diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/latex2e-help-texinfo/latex2e.texi |
Initial commit
Diffstat (limited to 'info/latex2e-help-texinfo/latex2e.texi')
-rw-r--r-- | info/latex2e-help-texinfo/latex2e.texi | 19044 |
1 files changed, 19044 insertions, 0 deletions
diff --git a/info/latex2e-help-texinfo/latex2e.texi b/info/latex2e-help-texinfo/latex2e.texi new file mode 100644 index 0000000000..d4f0726deb --- /dev/null +++ b/info/latex2e-help-texinfo/latex2e.texi @@ -0,0 +1,19044 @@ +\input texinfo +@c $Id: latex2e.texi 710 2018-10-14 14:32:52Z karl $ +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename latex2e.info +@set UPDATED October 2018 +@include common.texi +@settitle @LaTeX{}2e unofficial reference manual (@value{UPDATED}) +@comment %**end of header (This is for running Texinfo on a region.) + +@c latex 2.09 commands should all be present now, +@c xx but latex2e stuff is missing. +@c xx random list of a few of the missing items is at the end of this file +@c +@c xx ctan, distributions, components of TeX +@c xx classes and packages -- required, additional, useful; oberdiek; fonts +@c +@c xx merge permuted-index +@c xx merge latex-manual from savannah +@c xx merge display style math +@c xx JH explain nfss somewhere +@c xx JH expand BiBTeX +@c xx JH expand theorem, AMS math +@c xx JH something on code listings +@c xx JH ligatures +@c xx JH \xspace +@c xx JH \stretch +@c xx JH \mathstrut +@c xx JH \phantom https://tex.stackexchange.com/questions/4519/how-do-i-create-an-invisible-character +@c xx JH \baselineskip https://texfaq.org/FAQ-baselinepar +@c xx JH \contentsline, \@@dottedtocline? +@c xx JH more on \write18, beyond what's mentioned in Command line. +@c xx JH \numexpr, \dimexpr, \glueexpr, \muexpr +@c +@c xx The typeset source2e has an index with all kernel +@c xx commands, though some are internal and shouldn't be included. +@c xx classes.dtx et al. define additional commands. +@c xx See also http://ctan.org/pkg/macros2e. + +@copying +This document is an unofficial reference manual for @LaTeX{}, a +document preparation system, version of @value{UPDATED}. + +This manual was originally translated from @file{LATEX.HLP} v1.0a in the +VMS Help Library. The pre-translation version was written by +George@tie{}D. Greenwade of Sam Houston State University. The +@LaTeX{}@tie{}2.09 version was written by Stephen Gilmore. The +@LaTeX{}2e version was adapted from this by Torsten Martinsen. Karl +Berry made further updates and additions, and gratefully acknowledges +using @cite{Hypertext Help with @LaTeX{}}, by Sheldon Green, and +@cite{@LaTeX{} Command Summary} (for @LaTeX{}@tie{}2.09) by +L.@tie{}Botway and C.@tie{}Biemesderfer (published by the @TeX{} Users +Group as @cite{@TeX{}niques} number 10), as reference material. We also +gratefully acknowledge additional material appearing in +latex2e-reference by Martin Herbert Dietze. (From these references no +text was directly copied.) + +Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, +2014, 2015, 2016, 2017, 2018 Karl Berry.@* +Copyright 1988, 1994, 2007 Stephen Gilmore.@* +Copyright 1994, 1995, 1996 Torsten Martinsen. + +@comment start of License +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. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@comment end of License +@end copying + +@c Merge into one index (arbitrarily chosen to be the concept index). +@syncodeindex fn cp + +@dircategory TeX +@direntry +* LaTeX2e: (latex2e). Unofficial LaTeX reference manual. +@end direntry + +@tex +\global\hbadness=4444 % don't complain much +@end tex + +@titlepage +@title @LaTeX{}2e: An unofficial reference manual +@subtitle @value{UPDATED} +@author @url{@value{LTXREFMAN_HOME_PAGE}} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@shortcontents +@contents + +@c Best Effort Symbol +@iftex +@macro BES {utf8,math} +@math{\math\} +@end macro +@macro BESU {utf8,math} +@code{@backslashchar{}\math\} +@end macro +@end iftex +@ifnottex +@macro BES {utf8,math} +@U{\utf8\} +@end macro +@macro BESU {utf8,math} +@U{\utf8\} +@end macro +@end ifnottex +@macro EnvIndex {env} +@findex @r{environment}, @code{\env\} +@findex @code{\env\} @r{environment} + +@end macro +@macro PkgIndex {pkg} +@cindex @r{package}, @code{\pkg\} +@cindex @code{\pkg\} @r{package} + +@end macro + +@set NotInPlainTeX Not available in plain @TeX{}. +@set NeedsAMSSymb @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{amssymb} package. +@set NeedsSTIX @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{stix} package. + +@node Top +@top @LaTeX{}2e: An unofficial reference manual + +This document is an unofficial reference manual (version of +@value{UPDATED}) for @LaTeX{}2e, a document preparation system. + +@menu +* About this document:: Bug reporting, etc. +* Overview:: What is @LaTeX{}? +* Document classes:: Some of the various classes available. +* Fonts:: Italic, bold, typewriter, etc. +* Layout:: Controlling the page layout. +* Sectioning:: Parts, Chapters, Sections, etc. +* Cross references:: Automatic referencing. +* Environments:: Such as enumerate & itemize. +* Line breaking:: Influencing line breaks. +* Page breaking:: Influencing page breaks. +* Footnotes:: How to produce footnotes. +* Definitions:: Define your own commands, etc. +* Counters:: Internal counters used by @LaTeX{}. +* Lengths:: The length commands. +* Making paragraphs:: Paragraph commands. +* Math formulas:: How to create mathematical formulas. +* Modes:: Paragraph, Math or LR modes. +* Page styles:: Various styles of page layout. +* Spaces:: Horizontal and vertical space. +* Boxes:: Making boxes. +* Color:: Defining and using colors. +* Graphics:: Importing graphics from outside @LaTeX{}. +* Special insertions:: Inserting reserved and special characters. +* Splitting the input:: Dealing with big files by splitting. +* Front/back matter:: Tables of contents, glossaries, indexes. +* Letters:: The @code{letter} class. +* Terminal input/output:: User interaction. +* Command line:: System-independent command-line behavior. +* Document templates:: Starter templates for various document classes. +* Index:: General index. +@end menu + + +@node About this document +@chapter About this document + +@cindex home page for manual +This is an unofficial reference manual for the @LaTeX{}2e document +preparation system, which is a macro package for the @TeX{} +typesetting program (@pxref{Overview}). + +This document's home page is @url{@value{LTXREFMAN_HOME_PAGE}}. There +you can get the sources, subscribe to the mailing list or read its +archives, see other infrastructure, and get the current output in +various formats. In particular, the output comes in two web formats. +Probably the most convenient one, shown at @url{http://latexref.xyz/}, +has pages for each topic and so is good for a quick lookup; see also the +note there about easy-to-remember links. The other, shown at +@url{http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co}, +has all the information on single page. + +@cindex @LaTeX{} vs.@: @LaTeX{}2e +In this document, we will mostly just use `@LaTeX{}' rather than +`@LaTeX{}2e', since the previous version of @LaTeX{}@tie{}(2.09) was +frozen decades ago. + +@cindex unofficial nature of this manual +@cindex @LaTeX{} Project team +@findex @email{@value{LTXREFMAN_BUGS}} @r{email address} +@LaTeX{} is currently maintained by a group of volunteers +(@url{http://latex-project.org}). The official documentation written by +the @LaTeX{} project is available from their web site. This document is +completely unofficial and has not been reviewed by the @LaTeX{} +maintainers. +@cindex bug reporting +@cindex reporting bugs +Do not send bug reports or anything else about this document to them. +Instead, please send all comments to @email{@value{LTXREFMAN_BUGS}}. + +This document is a reference. There is a vast array of other sources +of information about @LaTeX{}, at all levels. Here are a few +introductions. + +@table @url +@item http://ctan.org/pkg/latex-doc-ptr +@findex latex-doc-ptr @r{document} +Two pages of recommended references to @LaTeX{} documentation. + +@item http://ctan.org/pkg/first-latex-doc +@findex first-latex-doc @r{document} +Writing your first document, with a bit of both text and math. + +@item http://ctan.org/pkg/usrguide +@findex usrguide @r{official documentation} +The guide for document authors that is maintained as part of @LaTeX{}. +Many other guides by many other people are also available, independent +of @LaTeX{} itself; one such is the next item: + +@item http://ctan.org/pkg/lshort +@findex lshort @r{document} +A short introduction to @LaTeX{}, translated to many languages. + +@item http://tug.org/begin.html +Introduction to the @TeX{} system, including @LaTeX{}, with further +references. + +@end table + + +@node Overview +@chapter Overview of @LaTeX{} + +@cindex overview of @LaTeX{} +@cindex basics of @LaTeX{} +@cindex Knuth, Donald E. +@cindex Lamport, Leslie +@cindex @LaTeX{} overview + +@LaTeX{} is a system for typesetting documents. It was originally +created by Leslie Lamport and is now maintained by a group of volunteers +(@url{http://latex-project.org}). It is widely used, particularly for +complex and technical documents, such as those involving mathematics. + +@cindex macro package, @LaTeX{} as +A @LaTeX{} user writes an input file containing text along with +interspersed commands, for instance commands describing how the text +should be formatted. It is implemented as a set of related commands +that interface with Donald@tie{}E. Knuth's @TeX{} typesetting program +(the technical term is that @LaTeX{} is a @dfn{macro package} for the +@TeX{} engine). The user produces the output document by giving that +input file to the @TeX{} engine. + +The term @LaTeX{} is also sometimes used to mean the language in which +the document is marked up, that is, to mean the set of commands +available to a @LaTeX{} user. + +@cindex Lamport @TeX{} +@cindex pronunciation +The name @LaTeX{} is short for ``Lamport @TeX{}''. It is pronounced +LAH-teck or LAY-teck, or sometimes LAY-tecks. Inside a document, +produce the logo with @code{\LaTeX}. Where use of the logo is not +sensible, such as in plain text, write it as @samp{LaTeX}. + +@menu +* Starting and ending:: The standard beginning and end of a document. +* Output files:: Files produced. +* @TeX{} engines:: Programs that can compile @TeX{} and @LaTeX{}. +* @LaTeX{} command syntax:: General syntax of @LaTeX{} commands. +* Environment:: Area of the source giving distinct behavior. +* CTAN:: Our repository. +@end menu + + +@node Starting and ending +@section Starting and ending + +@anchor{Starting & ending}@c old name +@cindex starting and ending +@cindex ending and starting +@cindex hello, world + +@LaTeX{} files have a simple global structure, with a standard beginning +and ending. This is a small example. + +@example +\documentclass@{article@} +\begin@{document@} +Hello, \LaTeX\ world. +\end@{document@} +@end example + +@noindent +Every @LaTeX{} document has a @code{\begin@{document@}} line and an +@code{\end@{document@}} line. + +@cindex document class, defined +@noindent +Here, the @samp{article} is the @dfn{document class}. It is implemented +in a file @file{article.cls}. You can use any document class on your +system. A few document classes are defined by @LaTeX{} itself, and vast +array of others are widely available. @xref{Document classes}. + +@cindex preamble, defined +You can include other @LaTeX{} commands between the +@code{\documentclass} and the @code{\begin@{document@}} commands. +This area is called the @dfn{preamble}. + +The @code{\begin@{document@}}, @code{\end@{document@}} pair defines an +@cindex environment +@dfn{environment}; the @samp{document} environment (and no others) is +required in all @LaTeX{} documents (@pxref{document}). @LaTeX{} make +available to you many environments that are documented here +(@pxref{Environments}). Many more are available to you from external +packages, most importantly those available at CTAN (@pxref{CTAN}). + +The following sections discuss how to produce PDF or other output from +a @LaTeX{} input file. + + +@node Output files +@section Output files + +@LaTeX{} produces a main output file and at least two auxiliary files. +The main output file's name ends in either @file{.dvi} or @file{.pdf}. + +@table @code +@item .dvi +@findex .dvi @r{file} +@findex latex @r{command} +@findex xdvi @r{command} +@findex dvips @r{command} +@findex dvipdfmx @r{command} +@findex dvitype @r{command} +@anchor{output files dvi} +If @LaTeX{} is invoked with the system command @command{latex} then it +produces a DeVice Independent file, with extension @file{.dvi}. You +can view this file with a command such as @command{xdvi}, or convert +it to a PostScript @code{.ps} file with @command{dvips} or to a +Portable Document Format @code{.pdf} file with @command{dvipdfmx}. +The contents of the file can be dumped in human-readable form with +@command{dvitype}. A vast array of other DVI utility programs are +available (@url{http://mirror.ctan.org/dviware}). + +@item .pdf +@findex .pdf @r{file} +@cindex pdf@TeX{} +@findex pdflatex @r{command} +@anchor{output files pdf} +If @LaTeX{} is invoked via the system command @command{pdflatex}, +among other commands (@pxref{@TeX{} engines}), then the main output is +a Portable Document Format (PDF) file. Typically this is a +self-contained file, with all fonts and images included. + +@end table + +@LaTeX{} also produces at least two additional files. + +@table @code +@item .log +@cindex transcript file +@cindex log file +@findex .log @r{file} +@anchor{output files log} +This transcript file contains summary information such as a list of +loaded packages. It also includes diagnostic messages and perhaps +additional information for any errors. + +@item .aux +@cindex auxiliary file +@findex .aux @r{file} +@cindex cross references, resolving +@cindex forward references, resolving +@cindex references, resolving forward +@anchor{output files aux} +Auxiliary information is used by @LaTeX{} for things such as +cross references. For example, the first time that @LaTeX{} finds a +forward reference---a cross reference to something that has not yet +appeared in the source---it will appear in the output as a doubled +question mark @code{??}. When the referred-to spot does eventually +appear in the source then @LaTeX{} writes its location information to +this @code{.aux} file. On the next invocation, @LaTeX{} reads the +location information from this file and uses it to resolve the +reference, replacing the double question mark with the remembered +location. + +@end table + +@findex .lof @r{file} +@cindex list of figures file +@findex .lot @r{file} +@cindex list of tables file +@findex .toc @r{file} +@cindex table of contents file +@cindex contents file +@LaTeX{} may produce yet more files, characterized by the filename +ending. These include a @code{.lof} file that is used to make a list of +figures, a @code{.lot} file used to make a list of tables, and a +@code{.toc} file used to make a table of contents (@pxref{Table of +contents etc.}). A particular class may create others; the list is +open-ended. + + +@node @TeX{} engines +@section @TeX{} engines + +@cindex engines, @TeX{} +@cindex implementations of @TeX{} +@cindex UTF-8 +@cindex Unicode input, native +@cindex TrueType fonts +@cindex OpenType fonts + +@LaTeX{} is defined to be a set of commands that are run by a @TeX{} +implementation (@pxref{Overview}). This section gives a terse +overview of the main programs (see also@tie{}@ref{Command line}). + +@table @code +@item latex +@itemx pdflatex +@cindex pdf@TeX{} engine +@findex etex @r{command} +@cindex e-@TeX{} +@anchor{tex engines latex} +In @TeX{} Live (@url{http://tug.org/texlive}), if @LaTeX{} is invoked +via either the system command @command{latex} or @command{pdflatex}, +then the pdf@TeX{} engine is run (@url{http://ctan.org/pkg/pdftex}). +When invoked as @command{latex}, the main output is a @file{.dvi} +file; as @command{pdflatex}, the main output is a @file{.pdf} file. + +pdf@TeX{} incorporates the e-@TeX{} extensions to Knuth's original +program (@url{http://ctan.org/pkg/etex}), including additional +programming features and bi-directional typesetting, and has plenty of +extensions of its own. e-@TeX{} is available on its own as the system +command @command{etex}, but this is plain @TeX{} (and produces +@file{.dvi}). + +In other @TeX{} distributions, @command{latex} may invoke e-@TeX{} +rather than pdf@TeX{}. In any case, the e-@TeX{} extensions can be +assumed to be available in @LaTeX{}. + +@item lualatex +@findex lualatex @r{command} +@cindex Lua@TeX{} +@anchor{tex engines lualatex} +If @LaTeX{} is invoked via the system command @command{lualatex}, the +Lua@TeX{} engine is run (@url{http://ctan.org/pkg/luatex}). This +program allows code written in the scripting language Lua +(@url{http://luatex.org}) to interact with @TeX{}'s typesetting. +Lua@TeX{} handles UTF-8 Unicode input natively, can handle OpenType +and TrueType fonts, and produces a @file{.pdf} file by default. +There is also @command{dvilualatex} to produce a @file{.dvi} file, +but this is rarely used. + +@item xelatex +@findex xelatex @r{command} +@cindex Xe@TeX{} +@findex .xdv @r{file} +@findex xdvipdfmx +@anchor{tex engines xelatex} +If @LaTeX{} is invoked with the system command @command{xelatex}, the +Xe@TeX{} engine is run (@url{http://tug.org/xetex}). Like Lua@TeX{}, +Xe@TeX{} natively supports UTF-8 Unicode and TrueType and OpenType +fonts, though the implementation is completely different, mainly using +external libraries instead of internal code. Xe@TeX{} produces a +@file{.pdf} file as output; it does not support DVI output. + +Internally, Xe@TeX{} creates an @code{.xdv} file, a variant of DVI, +and translates that to PDF using the (@code{x})@code{dvipdfmx} +program, but this process is automatic. The @code{.xdv} file is only +useful for debugging. + +@end table + +Other variants of @LaTeX{} and @TeX{} exist, e.g., to provide +additional support for Japanese and other languages ([u]p@TeX{}, +@url{http://ctan.org/pkg/ptex}, @url{http://ctan.org/pkg/uptex}). + + +@node @LaTeX{} command syntax +@section @LaTeX{} command syntax + +@cindex command syntax +@findex \ @r{character starting commands} +@findex [...] @r{for optional arguments} +@findex @{...@} @r{for required arguments} +In the @LaTeX{} input file, a command name starts with a backslash +character, @code{\}. The name itself then consists of either +(a)@tie{}a string of letters or (b)@tie{}a single non-letter. + +@LaTeX{} commands names are case sensitive so that @code{\pagebreak} +differs from @code{\Pagebreak} (the latter is not a standard command). +Most commands are lowercase, but in any event you must enter all +commands in the same case as they are defined. + +A command may be followed by zero, one, or more arguments. These +arguments may be either required or optional. Required arguments are +contained in curly braces, @code{@{...@}}. Optional arguments are +contained in square brackets, @code{[...]}. Generally, but not +universally, if the command accepts an optional argument, it comes +first, before any required arguments. + +Inside of an optional argument, to use the character close square +bracket@tie{}(@code{]}) hide it inside curly braces, as +in@tie{}@code{\item[closing bracket @{]@}]}. Similarly, if an optional +argument comes last, with no required argument after it, then to make +the first character of the following text be an open square bracket, +hide it inside curly braces. + +Some of @LaTeX{}'s commands are a @dfn{declaration}. Such a command +changes the value the meaning of some other command or parameter. For +instance, the @code{\mainmatter} declaration changes the typesetting of +page numbers from roman numerals to arabic (@pxref{\frontmatter & +\mainmatter & \backmatter}). + +@LaTeX{} has the convention that some commands have a @code{*} form that +is related to the form without a @code{*}, such as @code{\chapter} and +@code{\chapter*}. The exact difference in behavior varies from command +to command. + +This manual describes all accepted options and @code{*}-forms for the +commands it covers (barring unintentional omissions, a.k.a.@: bugs). + + +@node Environment +@section Environment + +Synopsis: + +@example +\begin@{@var{environment name}@} + ... +\end@{@var{environment name}@} +@end example + +An area of @LaTeX{} source, inside of which there is a distinct +behavior. For instance, for poetry in @LaTeX{} put the lines between +@code{\begin@{verse@}} and @code{\end@{verse@}}. + +@example +\begin@{verse@} + There once was a man from Nantucket \\ + ... +\end@{verse@} +@end example + +@xref{Environments} for a list of environments. Particularly notable is +that every @LaTeX{} document must have a @code{document} environment, +a @code{\begin@{document@} ... \end@{document@}} pair. + +The @var{environment name} at the beginning must exactly match that at +the end. This includes the case where @var{environment name} ends in a +star@tie{}(@code{*}); both the @code{\begin} and @code{\end} texts must +include the star. + +Environments may have arguments, including optional arguments. This +example produces a table. The first argument is optional (and causes +the table to be aligned on its top row) while the second argument is +required (it specifies the formatting of columns). + +@example +\begin@{tabular@}[t]@{r|l@} + ... rows of table ... +\end@{tabular@} +@end example + + +@node CTAN +@section CTAN: the Comprehensive @TeX{} Archive Network + +@cindex CTAN + +The Comprehensive @TeX{} Archive Network, CTAN, is the @TeX{} and +@LaTeX{} community's repository of free material. It is a set of +Internet sites around the world that offer material related to @LaTeX{} +for download. Visit CTAN on the web at @url{https://ctan.org}. + +This material is organized into packages, discrete bundles that +typically offer some coherent functionality and are maintained by one +person or a small number of people. For instance, many publishers have +a package that allows authors to format papers to that publisher's +specifications. + +In addition to the massive holdings, the web site offers features such +as search by name or by functionality. + +@cindex DANTE e.V. +@cindex mirrors of CTAN +CTAN is not a single site, but instead is a set of sites. One of the +sites is the core. This site actively manages the material, for +instance, by accepting uploads of new or updated packages. It is +hosted by the German @TeX{} group DANTE e.V. Other sites around the +world help out by mirroring, that is, automatically syncing their +collections with the core site and then in turn making their copies +publicly available. This gives users close to their location better +access and relieves the load on the core site. The list of mirrors is +at @url{https://ctan.org/mirrors}. + + +@node Document classes +@chapter Document classes + +@cindex document classes +@cindex classes of documents +@findex \documentclass + +The document's overall class is defined with this command, which is +normally the first command in a @LaTeX{} source file. + +@example +\documentclass[@var{options}]@{@var{class}@} +@end example + +@findex article @r{class} +@findex report @r{class} +@findex book @r{class} +@findex letter @r{class} +@findex slides @r{class} +The following document @var{class} names are built into @LaTeX{}. +(Many other document classes are available as separate packages; +@pxref{Overview}.) + +@table @code +@item article +@anchor{document classes article} +For a journal article, a presentation, and miscellaneous general use. + +@item book +@anchor{document classes book} +Full-length books, including chapters and possibly including front +matter, such as a preface, and back matter, such as an appendix +(@pxref{Front/back matter}). + +@item letter +@anchor{document classes letter} +Mail, optionally including mailing labels +(@pxref{Letters}). + +@item report +@anchor{document classes report} +For documents of length between an @code{article} and a @code{book}, +such as technical reports or theses, which may contain several chapters. + +@item slides +@anchor{document classes slides} +For slide presentations---rarely used today. In its place the +@code{beamer} package is perhaps the most prevalent (@pxref{beamer +template}). + +@end table + +Standard @var{options} are described in the next section. + +@menu +* Document class options:: Global options. +* Additional packages:: Bring in packages. +* Class and package construction:: Create new classes and packages. +@end menu + + +@node Document class options +@section Document class options + +@cindex document class options +@cindex options, document class +@cindex class options +@cindex global options + +You can specify @dfn{global options} or @dfn{class options} to the +@code{\documentclass} command by enclosing them in square brackets. To +specify more than one @var{option}, separate them with a comma. + +@example +\documentclass[@var{option1},@var{option2},...]@{@var{class}@} +@end example + +Here is the list of the standard class options. + +@findex 10pt @r{option} +@findex 11pt @r{option} +@findex 12pt @r{option} +All of the standard classes except @code{slides} accept the following +options for selecting the typeface size (default is @code{10pt}): + +@example +10pt 11pt 12pt +@end example + +@findex a4paper @r{option} +@findex a5paper @r{option} +@findex b5paper @r{option} +@findex executivepaper @r{option} +@findex legalpaper @r{option} +@findex letterpaper @r{option} +All of the standard classes accept these options for selecting the paper +size (these show height by width): + +@table @code +@item a4paper +210 by 297@dmn{mm} (about 8.25 by 11.75@tie{}inches) + +@item a5paper +148 by 210@dmn{mm} (about 5.8 by 8.3@tie{}inches) + +@item b5paper +176 by 250@dmn{mm} (about 6.9 by 9.8@tie{}inches) + +@item executivepaper +7.25 by 10.5@tie{}inches + +@item legalpaper +8.5 by 14@tie{}inches + +@item letterpaper +8.5 by 11@tie{}inches (the default) +@end table + +@findex \pdfpagewidth +@findex \pdfpageheight +@PkgIndex{geometry} +When using one of the engines pdf@LaTeX{}, Lua@LaTeX{}, or Xe@LaTeX{} +(@pxref{@TeX{} engines}), options other than @code{letterpaper} set +the print area but you must also set the physical paper size. One way +to do that is to put @code{\pdfpagewidth=\paperwidth} and +@code{\pdfpageheight=\paperheight} in your document's preamble. +@PkgIndex{geometry} +The @code{geometry} package provides flexible ways of setting the print +area and physical page size. + +@findex draft @r{option} +@findex final @r{option} +@findex fleqn @r{option} +@findex landscape @r{option} +@findex leqno @r{option} +@findex openbib @r{option} +@findex titlepage @r{option} +@findex notitlepage @r{option} +Miscellaneous other options: + +@table @code +@item draft +@itemx final +@cindex black boxes, omitting +Mark (@code{draft}) or do not mark (@code{final}) overfull boxes with a +black box in the margin; default is @code{final}. + +@item fleqn +@cindex flush left equations +@cindex centered equations +@cindex equations, flush left vs.@: centered +Put displayed formulas flush left; default is centered. + +@item landscape +@cindex landscape orientation +@cindex portrait orientation +Selects landscape format; default is portrait. + +@item leqno +@cindex left-hand equation numbers +@cindex right-hand equation numbers +@cindex equation numbers, left vs.@: right +Put equation numbers on the left side of equations; default is the right side. + +@item openbib +@cindex bibliography format, open +Use ``open'' bibliography format. + +@item titlepage +@itemx notitlepage +@cindex title page, separate or run-in +Specifies whether there is a separate page for the title information and +for the abstract also, if there is one. The default for the +@code{report} class is @code{titlepage}, for the other classes it is +@code{notitlepage}. +@end table + +The following options are not available with the @code{slides} class. + +@findex onecolumn @r{option} +@findex twocolumn @r{option} +@findex oneside @r{option} +@findex twoside @r{option} +@findex openright @r{option} +@findex openany @r{option} +@table @code +@item onecolumn +@itemx twocolumn +Typeset in one or two columns; default is @code{onecolumn}. + +@item oneside +@itemx twoside +@findex \evensidemargin +@findex \oddsidemargin +Selects one- or two-sided layout; default is @code{oneside}, except +that in the @code{book} class the default is @code{twoside}. + +For one-sided printing, the text is centered on the page. For two-sided +printing, the @code{\evensidemargin} (@code{\oddsidemargin}) parameter +determines the distance on even (odd) numbered pages between the left +side of the page and the text's left margin, with @code{\oddsidemargin} +being 40% of the difference between @code{\paperwidth} and +@code{\textwidth}, and @code{\evensidemargin} is the remainder. + +@item openright +@itemx openany +Determines if a chapter should start on a right-hand page; default is +@code{openright} for @code{book}, and @code{openany} for @code{report}. +@end table + +@findex clock @r{option to @code{slides} class} +The @code{slides} class offers the option @code{clock} for printing +the time at the bottom of each note. + + +@node Additional packages +@section Additional packages + +@cindex loading additional packages +@cindex packages, loading additional +@cindex additional packages, loading +@findex \usepackage +Load a package @var{pkg}, with the package options given in the comma-separated +list @var{options}, as here. + +@example +\usepackage[@var{options}]@{@var{pkg}@}. +@end example + +To specify more than one package you can separate them with a comma, +as in @code{\usepackage@{@var{pkg1},@var{pkg2},...@}}, or use multiple +@code{\usepackage} commands. + +@cindex global options +@cindex options, global +Any options given in the @code{\documentclass} command that are unknown +to the selected document class are passed on to the packages loaded with +@code{\usepackage}. + + +@node Class and package construction +@section Class and package construction + +@cindex document class commands +@cindex commands, document class +@cindex new class commands + +You can create new document classes and new packages. For instance, if +your memos must satisfy some local requirements, such as a +standard header for each page, then you could create a new class +@code{smcmemo.cls} and begin your documents with +@code{\documentclass@{smcmemo@}}. + +What separates a package from a document class is that the commands in a +package are useful across classes while those in a document class are +specific to that class. Thus, a command to set page headers is for a +package while a command to make the page headers say @code{Memo from the +SMC Math Department} is for a class. +@cindex class and package difference +@cindex difference between class and package + +Inside of a class or package file you can use the at-sign @code{@@} as a +character in command names without having to surround the code +containing that command with @code{\makeatletter} and +@code{\makeatother}. @xref{\makeatletter & \makeatother}. This allow +you to create commands that users will not accidentally redefine. +Another technique is to preface class- or package-specific commands with +some string to prevent your class or package from interfering with +others. For instance, the class @code{smcmemo} might have commands +@code{\smc@@tolist}, @code{\smc@@fromlist}, etc. + + +@menu +* Class and package structure:: Layout of the file. +* Class and package commands:: List of commands. +@end menu + + +@node Class and package structure +@subsection Class and package structure + +@cindex class and package structure +@cindex class file layout +@cindex package file layout +@cindex options, document class +@cindex options, package +@cindex class options +@cindex package options + +A class file or package file typically has four parts. +@enumerate +@item +In the @dfn{identification part}, the file says that it is a @LaTeX{} +package or class and describes itself, using the @code{\NeedsTeXFormat} +and @code{\ProvidesClass} or @code{\ProvidesPackage} commands. + +@item +The @dfn{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 @code{smcmemo} +class might be called with an option to read in a file with a list of +people for the to-head, as @code{\documentclass[mathto]@{smcmemo@}}, and +therefore needs to define a command +@code{\newcommand@{\setto@}[1]@{\def\@@tolist@{#1@}@}} used in that +file. + +@item +In the @dfn{handle options part} the class or package declares +and processes its options. Class options allow a user to start their +document as @code{\documentclass[@var{option list}]@{@var{class +name}@}}, to modify the behavior of the class. An example is when you +declare @code{\documentclass[11pt]@{article@}} to set the default +document font size. + +@item +Finally, in the @dfn{more declarations part} the class or package usually does +most of its work: declaring new variables, commands and fonts, and +loading other files. +@end enumerate + +Here is a starting class file, which should be saved as @file{stub.cls} +where @LaTeX{} can find it, for example in the same directory as the +@file{.tex} file. + +@example +\NeedsTeXFormat@{LaTeX2e@} +\ProvidesClass@{stub@}[2017/07/06 stub to start building classes from] +\DeclareOption*@{\PassOptionsToClass@{\CurrentOption@}@{article@}@} +\ProcessOptions\relax +\LoadClass@{article@} +@end example +@cindex class file example + +@noindent +It identifies itself, handles the class options via the default of +passing them all to the @code{article} class, and then loads the +@code{article} class to provide the basis for this class's code. + +For more, see the official guide for class and package writers, the +Class Guide, at +@url{http://www.latex-project.org/help/documentation/clsguide.pdf} (much +of the descriptions here derive from this document), or the tutorial +@url{https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf}. + + +@node Class and package commands +@subsection Class and package commands +@cindex class and package commands +@cindex commands, class and package + +These are the commands designed to help writers of classes or packages. + +@table @code +@item \AtBeginDvi@{specials@} +@findex \AtBeginDvi +Save in a box register things that are written to the @file{.dvi} file +at the beginning of the shipout of the first page of the document. + +@item \AtEndOfClass@{@var{code}@} +@item \AtEndOfPackage@{@var{code}@} +@findex \AtEndOfClass +@findex \AtEndOfPackage +Hook to insert @var{code} to be executed when @LaTeX{} finishes +processing the current class or package. You can use these hooks +multiple times; the @code{code} will be executed in the order that you +called it. See also @ref{\AtBeginDocument}. + +@item \CheckCommand@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@item \CheckCommand*@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@findex \CheckCommand +@findex \CheckCommand* +@cindex new command, check +Like @code{\newcommand} (@pxref{\newcommand & \renewcommand}) but does +not define @var{cmd}; instead it checks that the current definition of +@var{cmd} is exactly as given by @var{definition} and is or is not +@cindex long command +@dfn{long} as expected. A long command is a command that accepts +@code{\par} within an argument. The @var{cmd} command is expected to be +long with the unstarred version of @code{\CheckCommand}. Raises an +error when the check fails. This allows you to check before you start +redefining @code{cmd} yourself that no other package has already +redefined this command. + +@item \ClassError@{@var{class name}@}@{@var{error text}@}@{@var{help text}@} +@item \PackageError@{@var{package name}@}@{@var{error text}@}@{@var{help text}@} +@item \ClassWarning@{@var{class name}@}@{@var{warning text}@} +@item \PackageWarning@{@var{package name}@}@{@var{warning text}@} +@item \ClassWarningNoLine@{@var{class name}@}@{@var{warning text}@} +@item \PackageWarningNoLine@{@var{package name}@}@{@var{warning text}@} +@item \ClassInfo@{@var{class name}@}@{@var{info text}@} +@item \PackageInfo@{@var{package name}@}@{@var{info text}@} +@item \ClassInfoNoLine@{@var{class name}@}@{@var{info text}@} +@item \PackageInfoNoLine@{@var{package name}@}@{@var{info text}@} +@findex \ClassError +@findex \PackageError +@findex \ClassWarning +@findex \PackageWarning +@findex \ClassWarningNoLine +@findex \PackageWarningNoLine +@findex \ClassInfo +@findex \PackageInfo +@findex \ClassInfoNoLine +@findex \PackageInfoNoLine +Produce an error message, or warning or informational messages. + +For @code{\ClassError} and @code{\PackageError} the message is +@var{error text}, followed by @TeX{}'s @code{?} error prompt. If the +user then asks for help by typing @code{h}, they see the @var{help +text}. + +The four warning commands are similar except that they write +@var{warning text} on the screen with no error prompt. The four info +commands write @var{info text} only in the transcript file. The +@code{NoLine} versions do not show the number of the line generating the +message, while the other versions do show that number. + +To format the messages, including the @var{help text}: use +@code{\protect} to stop a command from expanding, get a line break with +@code{\MessageBreak}, and get a space with @code{\space} when a space +character does not allow it, like after a command. Note that @LaTeX{} +appends a period to the messages. + +@item \CurrentOption +@findex \CurrentOption +Expands to the name of the currently-being-processed option. Can only +be used within the @var{code} argument of either @code{\DeclareOption} +or @code{\DeclareOption*}. + +@item \DeclareOption@{@var{option}@}@{@var{code}@} +@item \DeclareOption*@{@var{code}@} +@findex \DeclareOption +@findex \DeclareOption* +@cindex class options +@cindex package options +@cindex options, class +@cindex options, package +Make an option available to a user to invoke in their +@code{\documentclass} command. For example, the @code{smcmemo} class +could have an option @code{\documentclass[logo]@{smcmemo@}} allowing +users to put the institutional logo on the first page. The class file +must contain @code{\DeclareOption@{logo@}@{@var{code}@}} (and later, +@code{\ProcessOptions}). + +If you request an option that has not been declared, by default this +will produce a warning like @code{Unused global option(s): [badoption].} +Change this behaviour with the starred version +@code{\DeclareOption*@{@var{code}@}}. For example, many classes extend +an existing class, using a declaration such as +@code{\LoadClass@{article@}}, and for passing extra options to the +underlying class use code such as this. + +@example +\DeclareOption*@{% +\PassOptionsToClass@{\CurrentOption@}@{article@}% +@} +@end example + +Another example is that the class @code{smcmemo} may allow users to keep +lists of memo recipients in external files. Then the user could invoke +@code{\documentclass[math]@{smcmemo@}} and it will read the file +@code{math.memo}. This code handles the file if it exists and otherwise +passes the option to the @code{article} class. + +@example +\DeclareOption*@{\InputIfFileExists@{\CurrentOption.memo@}@{@}@{% + \PassOptionsToClass@{\CurrentOption@}@{article@}@}@} +@end example + +@item \DeclareRobustCommand@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@item \DeclareRobustCommand*@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@findex \DeclareRobustCommand +@findex \DeclareRobustCommand* +@cindex new command, definition +Like @code{\newcommand} and @code{\newcommand*} (@pxref{\newcommand & +\renewcommand}) but these declare a robust command, even if some code +within the @var{definition} is fragile. (For a discussion of robust and +fragile commands @pxref{\protect}.) Use this command to define new +robust commands or to redefine existing commands and make them +robust. Unlike @code{\newcommand} these do not give an error if macro +@var{cmd} already exists; instead, a log message is put into the +transcript file if a command is redefined. + +Commands defined this way are a bit less efficient than those defined +using @code{\newcommand} so unless the command's data is fragile and the +command is used within a moving argument, use @code{\newcommand}. + +@PkgIndex{etoolbox} The @file{etoolbox} package offers the commands +@code{\newrobustcmd}, @code{\newrobustcmd*}, as well as the commands +@code{\renewrobustcmd}, @code{\renewrobustcmd*}, and the commands +@code{\providerobustcmd}, and @code{\providerobustcmd*}. These are +similar to @code{\newcommand}, @code{\newcommand*}, +@code{\renewcommand}, @code{\renewcommand*}, @code{\providecommand}, and +@code{\providecommand*}, but define a robust @var{cmd} with two +advantages as compared to @code{\DeclareRobustCommand}: +@enumerate +@item +They use the low-level e-@TeX{} protection mechanism rather than the +higher level @LaTeX{} @code{\protect} mechanism, so they do not incur +the slight loss of performance mentioned above, and +@item +They make the same distinction between @code{\new@dots{}}, +@code{\renew@dots{}}, and @code{\provide@dots{}}, as the standard +commands, so they do not just make a log message when you redefine +@var{cmd} that already exists, in that case you need to use either +@code{\renew@dots{}} or @code{\provide@dots{}} or you get an error. +@end enumerate + + +@item \IfFileExists@{@var{file name}@}@{@var{true code}@}@{@var{false code}@} +@item \InputIfFileExists@{@var{file name}@}@{@var{true code}@}@{@var{false code}@} +@findex \IfFileExists +@findex \InputIfFileExists +Execute @var{true code} if @LaTeX{} finds the file @file{@var{file +name}} or @var{false code} otherwise. In the first case it executing +@var{true code} and then inputs the file. Thus the command + +@example +\IfFileExists@{img.pdf@}@{% + \includegraphics@{img.pdf@}@}@{\typeout@{!! img.pdf not found@} +@end example + +@noindent +will include the graphic @file{img.pdf} if it is found and otherwise +give a warning. + +This command looks for the file in all search paths that @LaTeX{} uses, +not only in the current directory. To look only in the current +directory do something like @code{\IfFileExists@{./filename@}@{@var{true +code}@}@{@var{false code}@}}. If you ask for a filename without a +@code{.tex} extension then @LaTeX{} will first look for the file by +appending the @code{.tex}; for more on how @LaTeX{} handles file +extensions see @ref{\input}. + +@item \LoadClass[@var{options list}]@{@var{class name}@}[@var{release date}] +@item \LoadClassWithOptions@{@var{class name}@}[@var{release date}] +@findex \LoadClass +@findex \LoadClassWithOptions +Load a class, as with @code{\documentclass[@var{options +list}]@{@var{class name}@}[@var{release info}]}. An example is +@code{\LoadClass[twoside]@{article@}}. + +The @var{options list}, if present, is a comma-separated list. The +@var{release date} is optional. If present it must have the form +@var{YYYY/MM/DD}. +@c BTW, there are at-macros documented in macros2e.pdf to check the version +@c and do some actions conditionnally on version later or not to some +@c date. + +If you request a @var{release date} and the date of the package +installed on your system is earlier, then you get a warning on the +screen and in the log like this. + +@example +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. +@end example + +The command version @code{\LoadClassWithOptions} uses the list of +options for the current class. This means it ignores any options passed +to it via @code{\PassOptionsToClass}. This is a convenience command +that lets you build classes on existing ones, such as the standard +@code{article} class, without having to track which options were passed. + +@item \ExecuteOptions@{@var{options-list}@} +@findex \ExecuteOptions +For each option @var{option} in the @var{options-list}, in order, this command +executes the command @code{\ds@@@var{option}}. If this command is not +defined then that option is silently ignored. + +It can be used to provide a default option list before +@code{\ProcessOptions}. For example, if in a class file you want the +default to be 11pt fonts then you could specify +@code{\ExecuteOptions@{11pt@}\ProcessOptions\relax}. + +@item \NeedsTeXFormat@{@var{format}@}[@var{format date}] +@findex \NeedsTeXFormat +Specifies the format that this class must be run under. Often issued +as the first line of a class file, and most often used as: +@code{\NeedsTeXFormat@{LaTeX2e@}}. When a document using that class is +processed, the format name given here must match the format that is +actually being run (including that the @var{format} string is case +sensitive). If it does not match then execution stops with an error +like @samp{This file needs format `LaTeX2e' but this is `xxx'.} + +To specify a version of the format that you know to have certain +features, include the optional @var{format date} on which those features +were implemented. If present it must be in the form @code{YYYY/MM/DD}. +If the format version installed on your system is earlier than +@var{format date} then you get a warning like this. + +@example +You have requested release `2038/01/20' of LaTeX, but only +release `2016/02/01' is available. +@end example + +@item \OptionNotUsed +@findex \OptionNotUsed +Adds the current option to the list of unused options. Can only be used +within the @var{code} argument of either @code{\DeclareOption} or +@code{\DeclareOption*}. + +@c I cannot reproduce this behavior as it is documented in clsguide. +@c In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues +@c on the console a warning like @code{LaTeX Warning: Unused global +@c option(s): [unusedoption].} with the list of not-used options when it +@c reaches @code{\begin@{document@}}. + +@item \PassOptionsToClass@{@var{option list}@}@{@var{class name}@} +@item \PassOptionsToPackage@{@var{option list}@}@{@var{package name}@} +@findex \PassOptionsToClass +@findex \PassOptionsToPackage +Adds the options in the comma-separated list @var{option list} to the +options used by any future @code{\RequirePackage} or @code{\usepackage} +command for package @var{package name} or the class @var{class name}. + +The reason for these commands is: you may load a package any number of +times with no options but if you want options then you may only supply +them when you first load the package. Loading a package with options +more than once will get you an error like @code{Option clash for package +foo.} (@LaTeX{} throws an error even if there is no conflict between the +options.) + +If your own code is bringing in a package twice then you can collapse +that to once, for example replacing the two +@code{\RequirePackage[landscape]@{geometry@}} and +@code{\RequirePackage[margins=1in]@{geometry@}} with the single command +@code{\RequirePackage[landscape,margins=1in]@{geometry@}}. + +However, imagine that you are loading @file{firstpkg} and inside that +package it loads @file{secondpkg}, and you need the second package to be +loaded with option @code{draft}. Then before doing the first package +you must queue up the options for the second package, like this. + +@example +\PassOptionsToPackage@{draft@}@{secondpkg@} +\RequirePackage@{firstpkg@} +@end example + +@noindent +(If @code{firstpkg.sty} loads an option in conflict with what you want +then you may have to alter its source.) + +These commands are useful for general users as well as class and package +writers. For instance, suppose a user wants to load the @code{graphicx} +package with the option @code{draft} and also wants to use a class +@code{foo} that loads the @code{graphicx} package, but without that +option. The user could start their @LaTeX{} file with +@code{\PassOptionsToPackage@{draft@}@{graphicx@}\documentclass@{foo@}}. + +@item \ProcessOptions +@item \ProcessOptions*@var{\@@options} +@findex \ProcessOptions +@findex \ProcessOptions* +Execute the code for each option that the user has invoked. Include it +in the class file as @code{\ProcessOptions\relax} (because of the +existence of the starred command). + +Options come in two types. @dfn{Local options} have been specified for this +particular package in the @var{options} argument of +@code{\PassOptionsToPackage@{@var{options}@}}, +@code{\usepackage[@var{options}]}, or +@code{\RequirePackage[@var{options}]}. @dfn{Global options} are those given +by the class user in @code{\documentclass[@var{options}]} (If an option +is specified both locally and globally then it is local.) + +When @code{\ProcessOptions} is called for a package @file{pkg.sty}, the +following happens: +@enumerate +@item +For each option @var{option} so far declared +with @code{\DeclareOption}, it looks to see if that option is either a +global or a local option for @code{pkg}. If so then it executes the +declared code. This is done in the order in which these options were +given in @file{pkg.sty}. +@item +For each remaining local option, it executes the command +@code{\ds@@}@var{option} if it has been defined somewhere (other than by +a @code{\DeclareOption}); otherwise, it executes the default option code +given in @code{\DeclareOption*}. 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. +@end enumerate + +When @code{\ProcessOptions} is called for a class it works in the same +way except that all options are local, and the default @var{code} for +@code{\DeclareOption*} is @code{\OptionNotUsed} rather than an error. + +The starred version @code{\ProcessOptions*} 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. + +@item \ProvidesClass@{@var{class name}@}[@var{release date} @var{brief additional information}] +@item \ProvidesClass@{@var{class name}@}[@var{release date}] +@item \ProvidesPackage@{@var{package name}@}[@var{release date} @var{brief additional information}] +@item \ProvidesPackage@{@var{package name}@}[@var{release date}] +@findex \ProvidesClass +@findex \ProvidesPackage +Identifies the class or package, printing a message to the screen and +the log file. + +When you load a class or package, for example with +@code{\documentclass@{smcmemo@}} or @code{\usepackage@{test@}}, @LaTeX{} +inputs a file. If the name of the file does not match the class or +package name declared in it then you get a warning. Thus, if you invoke +@code{\documentclass@{smcmemo@}}, and the file @file{smcmemo.cls} has +the statement @code{\ProvidesClass@{xxx@}} then you get a warning like +@code{You have requested document class `smcmemo', but the document +class provides 'xxx'.} This warning does not prevent @LaTeX{} from +processing the rest of the class file normally. + +If you include the optional argument then you must include a date, +before any spaces, of the form @code{YYYY/MM/DD}. The rest of the +optional argument is free-form, although it traditionally identifies the +class, and is written to the screen during compilation and to the log +file. Thus, if your file @file{smcmemo.cls} contains the line +@code{\ProvidesClass@{smcmemo@}[2008/06/01 v1.0 SMC memo class]} and +your document's first line is @code{\documentclass@{smcmemo@}} then you +will see @code{Document Class: smcmemo 2008/06/01 v1.0 SMC memo class}. + +The date in the optional argument allows class and package users to ask +to be warned if the version of the class or package is earlier than +@var{release date}. For instance, a user could enter +@code{\documentclass@{smcmemo@}[2018/10/12]} or +@code{\usepackage@{foo@}[[2017/07/07]]} to require a class or package +with certain features by specifying that it must be released no earlier +than the given date. (Although, in practice package users only rarely +include a date, and class users almost never do.) + +@item \ProvidesFile@{@var{file name}@}[@var{additional information}] +@findex \ProvidesFile +Declare a file other than the main class and package files, such as +configuration files or font definition files. Put this command in that +file and you get in the log a string like @code{File: test.config +2017/10/12 config file for test.cls} for @var{file name} equal to +@samp{test.config} and @var{additional information} equal to +@samp{2017/10/12 config file for test.cls}. + +@item \RequirePackage[@var{option list}]@{@var{package name}@}[@var{release date}] +@item \RequirePackageWithOptions@{@var{package name}@}[@var{release date}] +@findex \RequirePackage +@findex \RequirePackageWithOptions +Load a package, like the command @code{\usepackage} (@pxref{Additional +packages}). The @LaTeX{} development team strongly recommends use of +these commands over Plain@tie{}@TeX{}'s @code{\input}; see the Class +Guide. An example is +@code{\RequirePackage[landscape,margin=1in]@{geometry@}}. + +The @var{option list}, if present, is a comma-separated list. The +@var{release date}, if present, must have the form @var{YYYY/MM/DD}. If +the release date of the package as installed on your system is earlier +than @var{release date} then you get a warning like @code{You have +requested, on input line 9, version `2017/07/03' of package jhtest, but +only version `2000/01/01' is available}. + +The @code{\RequirePackageWithOptions} version uses the list of options +for the current class. This means it ignores any options passed to it +via @code{\PassOptionsToClass}. This is a convenience command to allow +easily building classes on existing ones without having to track which +options were passed. + +The difference between @code{\usepackage} and @code{\RequirePackage} is +small. The @code{\usepackage} command is intended for the document file +while @code{\RequirePackage} is intended for package and class files. +Thus, using @code{\usepackage} before the @code{\documentclass} command +causes @LaTeX{} to give error like @code{\usepackage before +\documentclass}, but you can use @code{\RequirePackage} there. +@end table + + +@node Fonts +@chapter Fonts +@anchor{Typefaces}@c old name + +@cindex typefaces +@cindex fonts + +Two important aspects of selecting a @dfn{font} are specifying a size +and a style. The @LaTeX{} commands for doing this are described here. + +@menu +* Font styles:: Select roman, italics, etc. +* Font sizes:: Select point size. +* Low-level font commands:: Select encoding, family, series, shape. +@end menu + + +@node Font styles +@section Font styles + +@cindex font styles +@cindex type styles +@cindex styles of text + +The following type style commands are supported by @LaTeX{}. + +In the table below the listed commands, the @code{\text...} commands, +is used with an argument, as in @code{\textit@{@var{text}@}}. This is +the preferred form. But shown after it, in parenthesis, is the +corresponding declaration form, which is sometimes useful. This form +takes no arguments, as in @code{@{\itshape @var{text}@}}. The scope of +the declaration form lasts until the next type style command or the end +of the current group. In addition, each has an environment form such as +@code{\begin@{itshape@}...\end@{itshape@}}. + +These commands, in both the argument form and the declaration form, are +cumulative; for instance you can get bold sans serif by saying either of +@code{\sffamily\bfseries} or @code{\bfseries\sffamily}. + +@findex \nocorrlist +@findex \nocorr +One advantage of these commands is that they automatically insert italic +corrections if needed (@pxref{\/}). Specifically, they insert the +italic correction unless the following character is in the list +@code{\nocorrlist}, which by default consists of a period and a comma. +To suppress the automatic insertion of italic correction, use +@code{\nocorr} at the start or end of the command argument, such as +@code{\textit@{\nocorr text@}} or @code{\textsc@{text \nocorr@}}. + +@table @code +@item \textrm (\rmfamily) +@findex \textrm +@findex \rmfamily +Roman. + +@item \textit (\itshape) +@findex \textit +@findex \itshape +Italics. + +@item \textmd (\mdseries) +@findex \textmd +@findex \mdseries +Medium weight (default). + +@item \textbf (\bfseries) +@findex \textbf +@findex \bfseries +Boldface. + +@item \textup (\upshape) +@findex \textup +@findex \upshape +Upright (default). + +@item \textsl (\slshape) +@findex \textsl +@findex \slshape +Slanted. + +@item \textsf (\sffamily) +@findex \textsf +@findex \sffamily +Sans serif. + +@item \textsc (\scshape) +@findex \textsc +@findex \scshape +Small caps. + +@item \texttt (\ttfamily) +@findex \texttt +@findex \ttfamily +Typewriter. + +@item \textnormal (\normalfont) +@findex \textnormal +@findex \normalfont +Main document font. + +@end table + +@cindex emphasis +@findex \emph +Although it also changes fonts, the @code{\emph@{@var{text}@}} command +is semantic, for text to be emphasized, and should not be used as a +substitute for @code{\textit}. For example, @code{\emph@{@var{start +text} \emph@{@var{middle text}@} @var{end text}@}} will result in the +@var{start text} and @var{end text} in italics, but @var{middle text} +will be in roman. + +@LaTeX{} also provides the following commands, which unconditionally +switch to the given style, that is, are @emph{not} cumulative. They are +used as declarations: @code{@{\@var{cmd}...@}} instead of +@code{\@var{cmd}@{...@}}. + +(The unconditional commands below are an older version of font +switching. The earlier commands are an improvement in most +circumstances. But sometimes an unconditional font switch is precisely +what you want.) + +@ftable @code +@item \bf +@cindex bold font +Switch to bold face. + +@item \cal +@cindex script letters for math +@cindex calligraphic letters for math +Switch to calligraphic letters for math. + +@item \it +@cindex italic font +Italics. + +@item \rm +@cindex roman font +Roman. + +@item \sc +@cindex small caps font +Small caps. + +@item \sf +@cindex sans serif font +Sans serif. + +@item \sl +@cindex slanted font +@cindex oblique font +Slanted (oblique). + +@item \tt +@cindex typewriter font +@cindex monospace font +@cindex fixed-width font +Typewriter (monospace, fixed-width). + +@end ftable + +The @code{\em} command is the unconditional version of @code{\emph}. + +The following commands are for use in math mode. They are not +cumulative, so @code{\mathbf@{\mathit@{@var{symbol}@}@}} does not +create a boldface and italic @var{symbol}; instead, it will just be in +italics. This is because typically math symbols need consistent +typographic treatment, regardless of the surrounding environment. + +@table @code +@item \mathrm +@findex \mathrm +Roman, for use in math mode. + +@item \mathbf +@findex \mathbf +Boldface, for use in math mode. + +@item \mathsf +@findex \mathsf +Sans serif, for use in math mode. + +@item \mathtt +@findex \mathtt +Typewriter, for use in math mode. + +@item \mathit +@itemx (\mit) +Italics, for use in math mode. + +@item \mathnormal +@findex \mathnormal +For use in math mode, e.g., inside another type style declaration. + +@item \mathcal +@findex \mathcal +Calligraphic letters, for use in math mode. + +@end table + +@findex \mathversion +@cindex math, bold +@cindex bold math +In addition, the command @code{\mathversion@{bold@}} can be used for +switching to bold letters and symbols in +formulas. @code{\mathversion@{normal@}} restores the default. + +@findex \oldstylenums +@cindex numerals, old-style +@cindex old-style numerals +@cindex lining numerals +@PkgIndex{textcomp} +Finally, the command @code{\oldstylenums@{@var{numerals}@}} will typeset +so-called ``old-style'' numerals, which have differing heights and +depths (and sometimes widths) from the standard ``lining'' numerals, +which all have the same height as uppercase letters. @LaTeX{}'s +default fonts support this, and will respect @code{\textbf} (but not +other styles; there are no italic old-style numerals in Computer +Modern). Many other fonts have old-style numerals also; sometimes the +@code{textcomp} package must be loaded, and sometimes package options +are provided to make them the default. FAQ entry: +@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf}. + + +@node Font sizes +@section Font sizes + +@cindex font sizes +@cindex typeface sizes +@cindex sizes of text + +The following standard type size commands are supported by @LaTeX{}. +The table shows the command name and the corresponding actual font +size used (in points) with the @samp{10pt}, @samp{11pt}, and +@samp{12pt} document size options, respectively (@pxref{Document class +options}). + +@findex \tiny +@findex \scriptsize +@findex \footnotesize +@findex \small +@findex \normalsize +@findex \large +@findex \Large +@findex \LARGE +@findex \huge +@findex \Huge + +@multitable {@code{\normalsize} (default)@ @ } {24.88@ @ } {24.88@ @ } {24.88} +@headitem Command @tab @code{10pt} @tab @code{11pt} @tab @code{12pt} +@item @code{\tiny} +@tab 5 @tab 6 @tab 6 +@item @code{\scriptsize} +@tab 7 @tab 8 @tab 8 +@item @code{\footnotesize} +@tab 8 @tab 9 @tab 10 +@item @code{\small} +@tab 9 @tab 10 @tab 10.95 +@item @code{\normalsize} (default) +@tab 10 @tab 10.95 @tab 12 +@item @code{\large} +@tab 12 @tab 12 @tab 14.4 +@item @code{\Large} +@tab 14.4 @tab 14.4 @tab 17.28 +@item @code{\LARGE} +@tab 17.28 @tab 17.28 @tab 20.74 +@item @code{\huge} +@tab 20.74 @tab 20.74 @tab 24.88 +@item @code{\Huge} +@tab 24.88 @tab 24.88 @tab 24.88 +@end multitable + +The commands are listed here in declaration forms. You use them by +declaring them, as with this example. + +@example +\begin@{quotation@} \small + The Tao that can be named is not the eternal Tao. +\end@{quotation@} +@end example + +@noindent +The scope of the @code{\small} lasts until the end of the +@code{quotation} environment. It would also end at the next type style +command or the end of the current group, so you could enclose it in +extra curly braces @code{@{\small We are here, we are here, we are +here!@}}. You can instead use the environment form of these commands; +for instance, @code{\begin@{tiny@}...\end@{tiny@}}. + + +@node Low-level font commands +@section Low-level font commands + +@cindex low-level font commands +@cindex font commands, low-level + +These commands are primarily intended for writers of macros and +packages. The commands listed here are only a subset of the available +ones. +@c xx but it should be complete +@c xx something about ultimately reading ENCFAM.fd? + +@table @code +@anchor{low level font commands fontencoding} +@item \fontencoding@{@var{encoding}@} +@findex \fontencoding +Select the font encoding, the encoding of the output font. There are a +large number of valid encodings. The most common are @code{OT1}, +Knuth's original encoding for Computer Modern (the default), and +@code{T1}, also known as the Cork encoding, which has support for the +accented characters used by the most widespread European languages +(German, French, Italian, Polish and others), which allows @TeX{} to +hyphenate words containing accented letters. For more, see +@url{https://ctan.org/pkg/encguide}. + +@anchor{low level font commands fontfamily} +@item \fontfamily@{@var{family}@} +@findex \fontfamily +@cindex families, of fonts +@cindex font catalogue +Select the font family. The web page +@url{http://www.tug.dk/FontCatalogue/} provides one way to browse +through many of the fonts easily used with @LaTeX{}. Here are +examples of some common families. + +@multitable {font} {Computer Modern Typewriter more space} +@item @code{pag} +@tab Avant Garde +@item @code{fvs} +@tab Bitstream Vera Sans +@item @code{pbk} +@tab Bookman +@item @code{bch} +@tab Charter +@item @code{ccr} +@tab Computer Concrete +@item @code{cmr} +@tab Computer Modern +@item @code{cmss} +@tab Computer Modern Sans Serif +@item @code{cmtt} +@tab Computer Modern Typewriter +@item @code{pcr} +@tab Courier +@item @code{phv} +@tab Helvetica +@item @code{fi4} +@tab Inconsolata +@item @code{lmr} +@tab Latin Modern +@item @code{lmss} +@tab Latin Modern Sans +@item @code{lmtt} +@tab Latin Modern Typewriter +@item @code{pnc} +@tab New Century Schoolbook +@item @code{ppl} +@tab Palatino +@item @code{ptm} +@tab Times +@item @code{uncl} +@tab Uncial +@item @code{put} +@tab Utopia +@item @code{pzc} +@tab Zapf Chancery +@end multitable + + +@anchor{low level font commands fontseries} +@item \fontseries@{@var{series}@} +@findex \fontseries +@cindex series, of fonts +Select the font series. A @dfn{series} combines a @dfn{weight} and a +@dfn{width}. Typically, a font supports only a few of the possible +combinations. Some common combined series values include: + +@multitable {xx} {Medium (normal)xx} +@item @code{m} +@tab Medium (normal) +@item @code{b} +@tab Bold +@item @code{c} +@tab Condensed +@item @code{bc} +@tab Bold condensed +@item @code{bx} +@tab Bold extended +@end multitable + +@cindex weights, of fonts +The possible values for weight, individually, are: + +@multitable {xx} {Medium (normal) xx} +@item @code{ul} +@tab Ultra light +@item @code{el} +@tab Extra light +@item @code{l} +@tab Light +@item @code{sl} +@tab Semi light +@item @code{m} +@tab Medium (normal) +@item @code{sb} +@tab Semi bold +@item @code{b} +@tab Bold +@item @code{eb} +@tab Extra bold +@item @code{ub} +@tab Ultra bold +@end multitable + +@cindex widths, of fonts +The possible values for width, individually, are (the meaning and +relationship of these terms varies with individual typefaces): + +@multitable {xx} {Ultra condensed} +@item @code{uc} +@tab Ultra condensed +@item @code{ec} +@tab Extra condensed +@item @code{c} +@tab Condensed +@item @code{sc} +@tab Semi condensed +@item @code{m} +@tab Medium +@item @code{sx} +@tab Semi expanded +@item @code{x} +@tab Expanded +@item @code{ex} +@tab Extra expanded +@item @code{ux} +@tab Ultra expanded +@end multitable + +When forming the @var{series} string from the weight and width, drop the +@code{m} that stands for medium weight or medium width, unless both +weight and width are @code{m}, in which case use just one +(@samp{@code{m}}). + +@item \fontshape@{@var{shape}@} +@findex \fontshape +@cindex shapes, of fonts +@anchor{low level font commands fontshape} +Select font shape. Valid shapes are: + +@multitable {xx} {Slanted (oblique)xx} +@item @code{n} +@tab Upright (normal) +@item @code{it} +@tab Italic +@item @code{sl} +@tab Slanted (oblique) +@item @code{sc} +@tab Small caps +@item @code{ui} +@tab Upright italics +@item @code{ol} +@tab Outline +@end multitable + +The two last shapes are not available for most font families, and +small caps are often missing as well. + +@anchor{low level font commands fontsize} +@item \fontsize@{@var{size}@}@{@var{skip}@} +@findex \fontsize +@cindex font size +@findex \baselineskip +Set the font size and the line spacing. The unit of both parameters +defaults to points (@code{pt}). The line spacing is the nominal +vertical space between lines, baseline to baseline. It is stored in the +parameter @code{\baselineskip}. The default @code{\baselineskip} for +the Computer Modern typeface is 1.2 times the @code{\fontsize}. +Changing @code{\baselineskip} directly is inadvisable since its value is +reset every time a size change happens; see @code{\baselinestretch}, next. + +@anchor{low level font commands baselinestretch} +@item \baselinestretch +@findex \baselinestretch +@LaTeX{} multiplies the line spacing by the value of the +@code{\baselinestretch} parameter; the default factor is 1. A change +takes effect when @code{\selectfont} (see below) is called. You can +make a line skip change happen for the entire document, for instance +doubling it, by doing @code{\renewcommand@{\baselinestretch@}@{2.0@}} in +the preamble. + +@PkgIndex{setspace} +@cindex double spacing +However, the best way to double-space a document is to use the +@file{setspace} package. In addition to offering a number of spacing +options, this package keeps the line spacing single-spaced in places +where that is typically desirable, such as footnotes and figure +captions. See the package documentation. + +@anchor{low level font commands linespread} +@item \linespread@{@var{factor}@} +@findex \linespread +Equivalent to +@code{\renewcommand@{\baselinestretch@}@{@var{factor}@}}, and +therefore must be followed by @code{\selectfont} to have any effect. +Best specified in the preamble, or use the @code{setspace} package, as +just described. + +@anchor{low level font commands selectfont} +@item \selectfont +@findex \selectfont +The effects of the font commands described above do not happen until +@code{\selectfont} is called, as in +@code{\fontfamily@{@var{familyname}@}\selectfont}. It is often useful +to put this in a macro:@* +@code{\newcommand*@{\myfont@}@{\fontfamily@{@var{familyname}@}\selectfont@}}@* +(@pxref{\newcommand & \renewcommand}). + +@anchor{low level font commands usefont} +@item \usefont@{@var{enc}@}@{@var{family}@}@{@var{series}@}@{@var{shape}@} +@findex \usefont +The same as invoking @code{\fontencoding}, @code{\fontfamily}, +@code{\fontseries} and @code{\fontshape} with the given parameters, +followed by @code{\selectfont}. For example: + +@example +\usefont@{ot1@}@{cmr@}@{m@}@{n@} +@end example + +@end table + + +@node Layout +@chapter Layout + +@cindex layout commands + +Commands for controlling the general page layout. + +@menu +* \onecolumn:: Use one-column layout. +* \twocolumn:: Use two-column layout. +* \flushbottom:: Make all text pages the same height. +* \raggedbottom:: Allow text pages of differing height. +* Page layout parameters:: @code{\headheight} @code{\footskip}. +* Floats:: Figures, tables, etc. +@end menu + + +@node \onecolumn +@section @code{\onecolumn} + +@findex \onecolumn +@cindex one-column output + +Synopsis: + +@example +\onecolumn +@end example + +Start a new page and produce single-column output. If the document is +given the class option @code{onecolumn} then this is the default +behavior (@pxref{Document class options}). This command is fragile +(@pxref{\protect}). + + +@node \twocolumn +@section @code{\twocolumn} + +@findex \twocolumn +@cindex multicolumn text +@cindex two-column output + +Synopses: + +@example +\twocolumn +\twocolumn[@var{prelim one column text}] +@end example + +Start a new page and produce two-column output. If the document is given +the class option @code{twocolumn} then this is the default +(@pxref{Document class options}). This command is fragile +(@pxref{\protect}). + +If the optional @var{prelim one column text} argument +is present, it is typeset in one-column mode before the two-column +typesetting starts. + +These parameters control typesetting in two-column output: + +@ftable @code +@item \columnsep +@anchor{twocolumn columnsep} +The distance between columns. The default is 35pt. Change it with a +command such as @code{\setlength@{\columnsep@}@{40pt@}} You must change +it before the two column environment starts; in the preamble is a good +place. + +@item \columnseprule +@anchor{twocolumn columnseprule} +The width of the rule between columns. The rule appears halfway between +the two columns. The default is 0pt, meaning that there is no rule. +Change it with a command such as +@code{\setlength@{\columnseprule@}@{0.4pt@}}, before the two-column +environment starts. + +@item \columnwidth +@anchor{twocolumn columnwidth} +The width of a single column. In one-column mode this is equal to +@code{\textwidth}. In two-column mode by default @LaTeX{} sets the +width of each of the two columns to be half of @code{\textwidth} minus +@code{\columnsep}. + +@end ftable + +In a two-column document, the starred environments @code{table*} and +@code{figure*} are two columns wide, whereas the unstarred environments +@code{table} and @code{figure} take up only one column (@pxref{figure} +and @pxref{table}). @LaTeX{} places starred floats at the top of a page. +The following parameters control float behavior of two-column output. + +@ftable @code +@anchor{twocolumn dbltopfraction} +@item \dbltopfraction +The maximum fraction at the top of a two-column page that may be +occupied by two-column wide floats. The default is 0.7, meaning that +the height of a @code{table*} or @code{figure*} environment must not +exceed @code{0.7\textheight} . If the height of your starred float +environment exceeds this then you can take one of the following actions +to prevent it from floating all the way to the back of the document: + +@itemize @bullet +@item +Use the @code{[tp]} location specifier to tell LaTeX to try to put +the bulky float on a page by itself, as well as at the top of a page. + +@item +Use the @code{[t!]} location specifier to override the effect of +@code{\dbltopfraction} for this particular float. + +@item +Increase the value of @code{\dbltopfraction} to a suitably large number, +to avoid going to float pages so soon. +@end itemize + +You can redefine it, as with +@code{\renewcommand@{\dbltopfraction@}@{0.9@}}. + +@anchor{twocolumn dblfloatpagefraction} +@item \dblfloatpagefraction +For a float page of two-column wide floats, this is the minimum fraction +that must be occupied by floats, limiting the amount of blank space. +@LaTeX{}'s default is @code{0.5}. Change it with @code{\renewcommand}. + +@anchor{twocolumn dblfloatsep} +@item \dblfloatsep +On a float page of two-column wide floats, this length is the distance +between floats, at both the top and bottom of the page. The default is +@code{12pt plus2pt minus2pt} for a document set at @code{10pt} or +@code{11pt}, and @code{14pt plus2pt minus4pt} for a document set at +@code{12pt}. + +@anchor{twocolumn dbltextfloatsep} +@item \dbltextfloatsep +This length is the distance between a multi-column float at the top or +bottom of a page and the main text. The default is @code{20pt plus2pt +minus4pt}. + +@anchor{twocolumn dbltopnumber} +@item \dbltopnumber +On a float page of two-column wide floats, this counter gives the +maximum number of floats allowed at the top of the page. The @LaTeX{} +default is @code{2}. + +@end ftable + +@c From egreg at http://tex.stackexchange.com/a/142232/339 +This example uses @code{\twocolumn}'s optional argument of to create a +title that spans the two-column article: + +@example +\documentclass[twocolumn]@{article@} +\newcommand@{\authormark@}[1]@{\textsuperscript@{#1@}@} +\begin@{document@} +\twocolumn[@{% inside this optional argument goes one-column text + \centering + \LARGE The Title \\[1.5em] + \large Author One\authormark@{1@}, + Author Two\authormark@{2@}, + Author Three\authormark@{1@} \\[1em] + \normalsize + \begin@{tabular@}@{p@{.2\textwidth@}@@@{\hspace@{2em@}@}p@{.2\textwidth@}@} + \authormark@{1@}Department one &\authormark@{2@}Department two \\ + School one &School two + \end@{tabular@}\\[3em] % space below title part + @}] + +Two column text here. +@end example + + +@node \flushbottom +@section @code{\flushbottom} + +@findex \flushbottom + +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. + +If @TeX{} cannot satisfactorily stretch the vertical space in a page +then you get a message like @samp{Underfull \vbox (badness 10000) has +occurred while \output is active}. If you get that, one option is to +change to @code{\raggedbottom} (@pxref{\raggedbottom}). Alternatively, +you can adjust the @code{textheight} to make compatible pages, or you +can add some vertical stretch glue between lines or between paragraphs, +as in @code{\setlength@{\parskip@}@{0ex plus0.1ex@}}. Your last option +is to, in a final editing stage, adjust the height of individual pages +(@pxref{\enlargethispage}). + +The @code{\flushbottom} state is the default only if you select the +@code{twoside} document class option (@pxref{Document class options}). + + +@node \raggedbottom +@section @code{\raggedbottom} + +@findex \raggedbottom +@cindex stretch, omitting vertical + +Make all later pages the natural height of the material on that page; no +rubber vertical lengths will be stretched. Thus, in a two-sided +document the facing pages may be different heights. This command can go +at any point in the document body. See @ref{\flushbottom}. + +This is the default unless you select the @code{twoside} document class +option (@pxref{Document class options}). + + +@node Page layout parameters +@section Page layout parameters + +@cindex page layout parameters +@cindex parameters, page layout +@cindex layout, page parameters for +@cindex header, parameters for +@cindex footer, parameters for +@cindex running header and footer + +@ftable @code +@item \columnsep +@itemx \columnseprule +@itemx \columnwidth +@findex \columnsep +@findex \columnseprule +@findex \columnwidth +@anchor{page layout parameters columnsep} +@anchor{page layout parameters columnseprule} +@anchor{page layout parameters columnwidth} +The distance between the two columns, the width of a rule between the +columns, and the width of the columns, when the document class option +@code{twocolumn} is in effect (@pxref{Document class options}). +@xref{\twocolumn}. + +@item \headheight +@findex \headheight +@anchor{page layout parameters headheight} +Height of the box that contains the running head. The default in the +@code{article}, @code{report}, and @code{book} classes is @samp{12pt}, +at all type sizes. + +@item \headsep +@findex \headsep +@anchor{page layout parameters headsep} +Vertical distance between the bottom of the header line and the top of +the main text. The default in the @code{article} and @code{report} +classes is @samp{25pt}. In the @code{book} class the default is: if the +document is set at 10pt then it is @samp{0.25in}, and at 11pt and 12pt +it is @samp{0.275in}. + +@item \footskip +@findex \footskip +@anchor{page layout parameters footskip} +Distance from the baseline of the last line of text to the baseline of +the page footer. The default in the @code{article} and @code{report} +classes is @samp{30pt}. In the @code{book} class the default is: when +the type size is 10pt the default is @samp{0.35in}, while at 11pt it is +@samp{0.38in}, and at 12pt it is @samp{30pt}. + +@item \linewidth +@findex \linewidth +@anchor{page layout parameters linewidth} +Width of the current line, decreased for each nested @code{list} +(@pxref{list}). That is, the nominal value for @code{\linewidth} is to +equal @code{\textwidth} but for each nested list the @code{\linewidth} +is decreased by the sum of that list's @code{\leftmargin} and +@code{\rightmargin} (@pxref{itemize}). +@c The default varies with the font size, paper width, two-column mode, +@c etc. For an @code{article} document set in 10pt, the default is +@c @samp{345pt}, while in two-column mode that becomes @samp{229.5pt}. + +@item \marginparpush +@itemx \marginsep +@itemx \marginparwidth +@findex \marginparpush +@findex \marginsep +@findex \marginparwidth +@anchor{page layout parameters marginparpush} +@anchor{page layout parameters marginsep} +@anchor{page layout parameters marginparwidth} +The minimum vertical space between two marginal notes, the horizontal +space between the text body and the marginal notes, and the horizontal +width of the notes. + +Normally marginal notes appear on the outside of the page, but the +declaration @code{\reversemarginpar} changes that (and +@code{\normalmarginpar} changes it back). + +The defaults for @code{\marginparpush} in both @code{book} and +@code{article} classes are: @samp{7pt} if the document is set at 12pt, +and @samp{5pt} if the document is set at 11pt or 10pt. + +For @code{\marginsep}, in @code{article} class the default is +@samp{10pt} except if the document is set at 10pt and in two-column mode +where the default is @samp{11pt}. + +For @code{\marginsep} in @code{book} class the default is @samp{10pt} in +two-column mode and @samp{7pt} in one-column mode. + +For @code{\marginparwidth} in both @code{book} and @code{article} +classes, in two-column mode the default is 60% of @code{\paperwidth +@minus{} \textwidth}, while in one-column mode it is 50% of that +distance. + +@item \oddsidemargin +@itemx \evensidemargin +@findex \oddsidemargin +@findex \evensidemargin +@anchor{page layout parameters oddsidemargin} +@anchor{page layout parameters evensidemargin} +The @code{\oddsidemargin} is the extra distance between the left side of +the page and the text's left margin, on odd-numbered pages when the +document class option @code{twoside} is chosen and on all pages when +@code{oneside} is in effect. When @code{twoside} is in effect, on +even-numbered pages the extra distance on the left is +@code{evensidemargin}. + +@LaTeX{}'s default is that @code{\oddsidemargin} is 40% of the +difference between @code{\paperwidth} and @code{\textwidth}, and +@code{\evensidemargin} is the remainder. + +@item \paperheight +@findex \paperheight +@anchor{page layout parameters paperheight} +The height of the paper, as distinct from the height of the print area. +Normally set with a document class option, as in +@code{\documentclass[a4paper]@{article@}} (@pxref{Document class +options}). + +@item \paperwidth +@findex \paperwidth +@anchor{page layout parameters paperwidth} +The width of the paper, as distinct from the width of the print area. +Normally set with a document class option, as in +@code{\documentclass[a4paper]@{article@}} (@pxref{Document class +options}). + +@item \textheight +@findex \textheight +@anchor{page layout parameters textheight} +The normal vertical height of the page body. If the document is set at +a nominal type size of 10pt then for an @code{article} or @code{report} +the default is @samp{43\baselineskip}, while for a @code{book} it is +@samp{41\baselineskip}. At a type size of 11pt the default is +@samp{38\baselineskip} for all document classes. At 12pt it is +@samp{36\baselineskip} for all classes. + +@item \textwidth +@findex \textwidth +@anchor{page layout parameters textwidth} +The full horizontal width of the entire page body. For an +@code{article} or @code{report} document, the default is @samp{345pt} +when the chosen type size is 10pt, the default is @samp{360pt} at 11pt, +and it is @samp{390pt} at 12pt. For a @code{book} document, the default +is @samp{4.5in} at a type size of 10pt, and @samp{5in} at 11pt or 12pt. + +In multi-column output, @code{\textwidth} remains the width of the +entire page body, while @code{\columnwidth} is the width of one column +(@pxref{\twocolumn}). + +In lists (@pxref{list}), @code{\textwidth} remains the width of the +entire page body (and @code{\columnwidth} the width of the entire +column), while @code{\linewidth} may decrease for nested lists. + +Inside a minipage (@pxref{minipage}) or @code{\parbox} +(@pxref{\parbox}), all the width-related parameters are set to the +specified width, and revert to their normal values at the end of the +@code{minipage} or @code{\parbox}. + +@findex \hsize +@anchor{page layout parameters hsize} +@item \hsize +This entry is included for completeness: @code{\hsize} is the @TeX{} +primitive parameter used when text is broken into lines. It should not +be used in normal @LaTeX{} documents. + +@item \topmargin +@findex topmargin +@anchor{page layout parameters topmargin} +Space between the top of the @TeX{} page (one inch from the top of the +paper, by default) and the top of the header. The value is computed +based on many other parameters: @code{\paperheight @minus{} 2in @minus{} +\headheight @minus{} \headsep @minus{} \textheight @minus{} \footskip}, +and then divided by two. + +@item \topskip +@findex \topskip +@anchor{page layout parameters topskip} +Minimum distance between the top of the page body and the baseline of +the first line of text. For the standard classes, the default is the +same as the font size, e.g., @samp{10pt} at a type size of 10pt. + +@end ftable + + +@node Floats +@section Floats + +Some typographic elements, such as figures and tables, cannot be broken +across pages. They must be typeset outside of the normal flow of text, +for instance floating to the top of a later page. + +@LaTeX{} can have a number of different classes of floating material. +The default is the two classes, @code{figure} (@pxref{figure}) and +@code{table} (@pxref{table}), but you can create a new class with the +package @file{float}. + +Within any one float class @LaTeX{} always respects the order, so that +the first figure in a document source must be typeset before the second +figure. However, @LaTeX{} may mix the classes, so it can happen that +while the first table appears in the source before the first figure, it +appears in the output after it. + +The placement of floats is subject to parameters, given below, that +limit the number of floats that can appear at the top of a page, and +the bottom, etc. If so many floats are queued that the limits prevent +them all from fitting on a page then @LaTeX{} places what it can and +defers the rest to the next page. In this way, floats may end up +being typeset far from their place in the source. In particular, a +float that is big may migrate to the end of the document. In which +event, because all floats in a class must appear in sequential order, +every following float in that class also appears at the end. + +@cindex placement of floats +@cindex specifier, float placement +In addition to changing the parameters, for each float you can tweak +where the float placement algorithm tries to place it by using its +@var{placement} argument. The possible values are a sequence of the +letters below. The default for both @code{figure} and @code{table}, in +both @code{article} and @code{book} classes, is @code{tbp}. + +@table @code +@item t +(Top)---at the top of a text page. + +@item b +(Bottom)---at the bottom of a text page. (However, @code{b} is not +allowed for full-width floats (@code{figure*}) with double-column +output. To ameliorate this, use the @file{stfloats} or +@file{dblfloatfix} package, but see the discussion at caveats in the +FAQ: @url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat}. + +@item h +(Here)---at the position in the text where the @code{figure} environment +appears. However, @code{h} is not allowed by itself; @code{t} is +automatically added. + +@cindex here, putting floats +@PkgIndex{float} +To absolutely force a float to appear ``here'', you can +@code{\usepackage@{float@}} and use the @code{H} specifier which it +defines. For further discussion, see the FAQ entry at +@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere}. + +@item p +@cindex float page +(Page of floats)---on a separate @dfn{float page}, which is a page +containing no text, only floats. + +@item ! +Used in addition to one of the above; for this float only, @LaTeX{} +ignores the restrictions on both the number of floats that can appear +and the relative amounts of float and non-float text on the page. +The @code{!} specifier does @emph{not} mean ``put the float here''; +see above. + +@end table + +Note: the order in which letters appear in the @var{placement} argument +does not change the order in which @LaTeX{} tries to place the float; +for instance, @code{btp} has the same effect as @code{tbp}. All that +@var{placement} does is that if a letter is not present then the +algorithm does not try that location. Thus, @LaTeX{}'s default of +@code{tbp} is to try every location except placing the float where it +occurs in the source. + +To prevent @LaTeX{} from moving floats to the end of the document or a +chapter you can use a @code{\clearpage} command to start a new page and +insert all pending floats. If a pagebreak is undesirable then you can +use the @file{afterpage} package and issue +@code{\afterpage@{\clearpage@}}. This will wait until the current page +is finished and then flush all outstanding floats. + +@PkgIndex{flafter} +@LaTeX{} can typeset a float before where it appears in the source +(although on the same output page) if there is a @code{t} specifier in +the @var{placement} parameter. If this is not desired, and deleting +the @code{t} is not acceptable as it keeps the float from being placed +at the top of the next page, then you can prevent it by either using +the @file{flafter} package or using the command +@findex \suppressfloats +@code{\suppressfloats[t]}, which causes floats for the top position on +this page to moved to the next page. + +Parameters relating to fractions of pages occupied by float and +non-float text (change them with +@code{\renewcommand@{@var{parameter}@}@{@var{decimal between 0 and 1}@}}): + +@ftable @code +@item \bottomfraction +@findex \bottomfraction +@anchor{floats bottomfraction} +The maximum fraction of the page allowed to be occupied by floats at +the bottom; default @samp{.3}. + +@item \floatpagefraction +@findex \floatpagefraction +@anchor{floats floatpagefraction} +The minimum fraction of a float page that must be occupied by floats; +default @samp{.5}. + +@item \textfraction +@findex \textfraction +@anchor{floats textfraction} +Minimum fraction of a page that must be text; if floats take up too +much space to preserve this much text, floats will be moved to a +different page. The default is @samp{.2}. + +@item \topfraction +@findex \topfraction +@anchor{floats topfraction} +Maximum fraction at the top of a page that may be occupied before +floats; default @samp{.7}. +@end ftable + +Parameters relating to vertical space around floats (change them with a +command of the form @code{\setlength@{@var{parameter}@}@{@var{length +expression}@}}): + +@ftable @code +@item \floatsep +@findex \floatsep +@anchor{floats floatsep} +Space between floats at the top or bottom of a page; default +@samp{12pt plus2pt minus2pt}. + +@item \intextsep +@findex \intextsep +@anchor{floats intextsep} +Space above and below a float in the middle of the main text; default +@samp{12pt plus2pt minus2pt} for 10 point and 11 point documents, +and @samp{14pt plus4pt minus4pt} for 12 point documents. + +@item \textfloatsep +@findex \textfloatsep +@anchor{floats textfloatsep} +Space between the last (first) float at the top (bottom) of a page; +default @samp{20pt plus2pt minus4pt}. +@end ftable + +Counters relating to the number of floats on a page (change them with a +command of the form @code{\setcounter@{@var{ctrname}@}@{@var{natural +number}@}}): + +@ftable @code +@item bottomnumber +@findex bottomnumber +@anchor{floats bottomnumber} +Maximum number of floats that can appear at the bottom of a text page; +default 1. + +@item dbltopnumber +@findex dbltopnumber +@anchor{floats dbltopnumber} +Maximum number of full-sized floats that can appear at the top of a +two-column page; default 2. + +@item topnumber +@findex topnumber +@anchor{floats topnumber} +Maximum number of floats that can appear at the top of a text page; +default 2. + +@item totalnumber +@findex totalnumber +@anchor{floats totalnumber} +Maximum number of floats that can appear on a text page; default 3. +@end ftable + +The principal @TeX{}@tie{}FAQ entry relating to floats +@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats} contains +suggestions for relaxing @LaTeX{}'s default parameters to reduce the +problem of floats being pushed to the end. A full explanation of the +float placement algorithm is in Frank Mittelbach's article ``How to +influence the position of float environments like figure and table in +@LaTeX{}?'' +(@url{http://latex-project.org/papers/tb111mitt-float.pdf}). + + +@node Sectioning +@chapter Sectioning + +@cindex sectioning commands +@cindex part +@cindex chapter +@cindex section +@cindex subsection +@cindex paragraph +@cindex subparagraph +@findex \part +@findex \chapter +@findex \section +@findex \subsection +@findex \paragraph +@findex \subparagraph + +Structure your text into divisions: parts, chapters, sections, etc. All +sectioning commands have the same form, one of: + +@example +@var{sectioning-command}@{@var{title}@} +@var{sectioning-command}*@{@var{title}@} +@var{sectioning-command}[@var{toc-title}]@{@var{title}@} +@end example + +@noindent +For instance, declare the start of a subsection as with +@code{\subsection@{Motivation@}}. + +The table has each @var{sectioning-command} in @LaTeX{}. All are +available in all of @LaTeX{}'s standard document classes @code{book}, +@code{report}, and@tie{}@code{article}, except that @code{\chapter} is +not available in @code{article}. + +@multitable @columnfractions .25 .25 .40 +@headitem Sectioning unit @tab Command @tab Level +@item Part +@tab @code{\part} @tab -1 (@code{book}, @code{report}), 0 (@code{article}) +@item Chapter +@tab @code{\chapter} @tab 0 +@item Section +@tab @code{\section} @tab 1 +@item Subsection +@tab @code{\subsection} @tab 2 +@item Subsubsection +@tab @code{\subsubsection} @tab 3 +@item Paragraph +@tab @code{\paragraph} @tab 4 +@item Subparagraph +@tab @code{\subparagraph} @tab 5 +@end multitable + +@cindex @code{*}-form of sectioning commands +All these commands have a @code{*}-form that prints @var{title} as usual +but is not numbered and does not make an entry in the table of contents. +An example of using this is for an appendix in an @code{article} . The +input @code{\appendix\section@{Appendix@}} gives the output @samp{A +Appendix} (@pxref{\appendix}). You can lose the numbering@tie{}@samp{A} +by instead entering @code{\section*@{Appendix@}} (articles often omit a +table of contents and have simple page headers so the other differences +from the @code{\section} command may not matter). + +The section title @var{title} provides the heading in the main text, but +it may also appear in the table of contents and in the running head or +foot (@pxref{Page styles}). You may not want the same text in these +places as in the main text. All of these commands have an optional +argument @var{toc-title} for these other places. + +The level number in the table above determines which sectional units are +numbered, and which appear in the table of contents. If the sectioning +command's @var{level} is less than or equal to the value of the counter +@code{secnumdepth} then the titles for this sectioning command will be +numbered (@pxref{Sectioning/secnumdepth}). And, if @var{level} is less +than or equal to the value of the counter @code{tocdepth} then the table +of contents will have an entry for this sectioning unit +(@pxref{Sectioning/tocdepth}). + +@LaTeX{} expects that before you have a @code{\subsection} you will have +a @code{\section} and, in a book, that before a @code{\section} you will +have a @code{\chapter}. Otherwise you can get a something like a +subsection numbered @samp{3.0.1}. + +Two counters relate to the appearance of sectioning commands. + +@ftable @code +@item secnumdepth +@findex secnumdepth @r{counter} +@cindex section numbers, printing +@anchor{sectioning secnumdepth} +@anchor{Sectioning/secnumdepth} +Controls which sectioning commands are +numbered. Suppress numbering of sectioning at any depth greater than +@var{level} @code{\setcounter@{secnumdepth@}@{@var{level}@}} +(@pxref{\setcounter}). See the above table for the level numbers. For +instance, if the @code{secnumdepth} is 1 in an @code{article} then a +@code{\section@{Introduction@}} command will produce output like @samp{1 +Introduction} while @code{\subsection@{Discussion@}} will produce output +like @samp{Discussion}, without the number. @LaTeX{}'s default +@code{secnumdepth} is@tie{}3 in @file{article} class and @tie{}2 in the +@file{book} and @file{report} classes. + +@item tocdepth +@findex tocdepth @r{counter} +@cindex table of contents, sectioning numbers printed +@anchor{sectioning tocdepth} +@anchor{Sectioning/tocdepth} +Controls which sectioning units are listed in the table of contents. +The setting @code{\setcounter@{tocdepth@}@{@var{level}@}} makes the +sectioning units at @var{level} be the smallest ones listed +(@pxref{\setcounter}). See the above table for the level numbers. For +instance, if @code{tocdepth} is@tie{}1 then the table of contents will +list sections but not subsections. @LaTeX{}'s default +@code{secnumdepth} is@tie{}3 in @file{article} class and @tie{}2 in the +@file{book} and @file{report} classes. + +@end ftable + +@menu +* \part:: Start a part. +* \chapter:: Start a chapter. +* \section:: Start a section. +* \subsection:: Start a subsection. +* \subsubsection & \paragraph & \subparagraph:: Lower divisions. +* \appendix:: Start appendices. +* \frontmatter & \mainmatter & \backmatter:: The three parts of a book. +* \@@startsection:: Layout of sectional units. +@end menu + + +@node \part +@section @code{\part} + +@findex \part +@cindex part +@cindex sectioning, part + +Synopsis, one of: + +@example +\part@{@var{title}@} +\part*@{@var{title}@} +\part[@var{toc-title}]@{@var{title}@} +@end example + +Start a document part. The standard @LaTeX{} classes @code{book}, +@code{report}, and @code{article}, all have this command. + +This produces a document part, in a book. + +@example +\part@{VOLUME I \\ + PERSONAL MEMOIRS OF U.\ S.\ GRANT@} +\chapter@{ANCESTRY--BIRTH--BOYHOOD.@} +My family is American, and has been for generations, +in all its branches, direct and collateral. +@end example + +In each standard class the @code{\part} command outputs a part number +such as @samp{Part I}, alone on its line, in boldface, and in large +type. Then @LaTeX{} outputs @var{title}, also alone on its line, in +bold and in even larger type. In class @code{book}, the @LaTeX{} +default puts each part alone on its own page. If the book is two-sided +then @LaTeX{} will skip a page if needed to have the new part on an +odd-numbered page. In @code{report} it is again alone on a page, but +@LaTeX{} won't force it onto an odd-numbered page. In an @code{article} +@LaTeX{} does not put it on a fresh page, but instead outputs the part +number and part title onto the main document page. + +The @code{*}@tie{}form shows @var{title} +but it does not show the part number, does not increment the +@code{part} counter, and produces no table of contents entry. + +The optional argument @var{toc-title} will appear as the part title in +the table of contents (@pxref{Table of contents etc.}) and in running +headers (@pxref{Page styles}). If it is not present then @var{title} +will be there. This example puts a line break in @var{title} but leaves +out the break in the table of contents. + +@example +\part[Up from the bottom; my life]@{Up from the bottom\\ my life@} +@end example + +For determining which sectional units are numbered and which appear in +the table of contents, the level number of a part is@tie{}-1 +(@pxref{Sectioning/secnumdepth} and @pxref{Sectioning/tocdepth}). + +@PkgIndex{indentfirst} +In the class @code{article}, if a paragraph immediately follows the part +title then it is not indented. To get an indent you can use the package +@file{indentfirst}. + +@PkgIndex{titlesec} +One package to change the behavior of @code{\part} is @file{titlesec}. +See its documentation on CTAN. + + +@node \chapter +@section @code{\chapter} + +@findex \chapter +@cindex chapter + +Synopsis, one of: + +@example +\chapter@{@var{title}@} +\chapter*@{@var{title}@} +\chapter[@var{toc-title}]@{@var{title}@} +@end example + +Start a chapter. The standard @LaTeX{} classes @code{book} and +@code{report} have this command but @code{article} does not. + +This produces a chapter. + +@example +\chapter@{Loomings@} +Call me Ishmael. +Some years ago---never mind how long precisely---having little or no +money in my purse, and nothing particular to interest me on shore, I +thought I would sail about a little and see the watery part of +the world. +@end example + +The @LaTeX{} default starts each chapter on a fresh page, an +odd-numbered page if the document is two-sided. It produces a chapter +number such as @samp{Chapter 1} in large boldface type (the size is +@code{\huge}). It then puts @var{title} on a fresh line, in boldface +type that is still larger (size @code{\Huge}). It also increments the +@code{chapter} counter, adds an entry to the table of contents +(@pxref{Table of contents etc.}), and sets the running header +information (@pxref{Page styles}). + +The @code{*}@tie{}form shows @var{title} on a fresh line, in boldface. +But it does not show the chapter number, does not increment the +@code{chapter} counter, produces no table of contents entry, and does +not affect the running header. (If you use the page style +@code{headings} in a two-sided document then the header will be from the +prior chapter.) This example illustrates. + +@example +\chapter*@{Preamble@} +@end example + +The optional argument @var{toc-title} will appear as the chapter title +in the table of contents (@pxref{Table of contents etc.}) and in +running headers (@pxref{Page styles}). If it is not present then +@var{title} will be there. This shows the full name in the chapter +title, + +@example +\chapter[Weyl]@{Hermann Klaus Hugo (Peter) Weyl (1885--1955)@} +@end example + +@noindent +but only @samp{Weyl} on the contents page. This puts a line break in +the title but that doesn't work well with running headers so it omits +the break in the contents + +@example +\chapter[Given it all\\ my story]@{Given it all\\ my story@} +@end example + +For determining which sectional units are numbered and which appear in +the table of contents, the level number of a chapter is@tie{}0 +(@pxref{Sectioning/secnumdepth} and @pxref{Sectioning/tocdepth}). + +@PkgIndex{indentfirst} +The paragraph that follows the chapter title is not indented, as is a +standard typographical practice. To get an indent use the package +@file{indentfirst}. + +You can change what is shown for the chapter number. To change it to +something like @samp{Lecture 1}, put in the preamble either +@code{\renewcommand@{\chaptername@}@{Lecture@}} or this +(@pxref{\makeatletter & \makeatother}). + +@example +\makeatletter +\renewcommand@{\@@chapapp@}@{Lecture@} +\makeatother +@end example + +@PkgIndex{babel} +@noindent To make this change because of the primary language for +the document, see the package @file{babel}. + +In a two-sided document @LaTeX{} puts a chapter on odd-numbered page, if +necessary leaving an even-numbered page that is blank except for any +running headers. To make that page completely blank, +see@tie{}@ref{\clearpage & \cleardoublepage}. + +@PkgIndex{titlesec} +To change the behavior of the @code{\chapter} command, you can copy its +definition from the @LaTeX{} format file and make adjustments. But +there are also many packages on CTAN that address this. One is +@file{titlesec}. See its documentation, but the example below gives a +sense of what it can do. + +@example +\usepackage@{titlesec@} % in preamble +\titleformat@{\chapter@} + @{\Huge\bfseries@} % format of title + @{@} % label, such as 1.2 for a subsection + @{0pt@} % length of separation between label and title + @{@} % before-code hook +@end example + +@noindent +This omits the chapter number @samp{Chapter 1} from the page but unlike +@code{\chapter*} it keeps the chapter in the table of contents and the +running headers. + + +@node \section +@section @code{\section} + +@findex \section +@cindex section + +Synopsis, one of: + +@example +\section@{@var{title}@} +\section*@{@var{title}@} +\section[@var{toc-title}]@{@var{title}@} +@end example + +Start a section. The standard @LaTeX{} classes @code{article}, +@code{book}, and @code{report} all have this command. + +This produces a section. + +@example +In this Part we tend to be more interested in the function, +in the input-output behavior, +than in the details of implementing that behavior. + +\section@{Turing machines@} +Despite this desire to downplay implementation, +we follow the approach of A~Turing that the +first step toward defining the set of computable functions +is to reflect on the details of what mechanisms can do. +@end example + +For the standard @LaTeX{} classes @code{book} and @code{report} the +default output is like @samp{1.2 @var{title}} (for chapter@tie{}1, +section@tie{}2), alone on its line and flush left, in boldface and a +larger type (the type size is @code{\Large}). The same holds in +@code{article} except that there are no chapters in that class so it +looks like @samp{2 @var{title}}. + +The @code{*}@tie{}form shows @var{title}. +But it does not show the section number, does not increment the +@code{section} counter, produces no table of contents entry, and does +not affect the running header. (If you use the page style +@code{headings} in a two-sided document then the header will be from the +prior section.) + +The optional argument @var{toc-title} will appear as the section title +in the table of contents (@pxref{Table of contents etc.}) and in +running headers (@pxref{Page styles}). If it is not present then +@var{title} will be there. This shows the full name in the title of the +section, + +@example +\section[Elizabeth~II]@{Elizabeth the Second, + by the Grace of God of the United Kingdom, + Canada and Her other Realms and Territories Queen, + Head of the Commonwealth, Defender of the Faith.@} +@end example + +@noindent +but only @samp{Elizabeth II} on the contents page and in the headers. +This has a line break in @var{title} but that does not work with headers +so it is omitted from the contents and headers. + +@example +\section[Truth is, I cheated; my life story]@{Truth is, + I cheated\\my life story@} +@end example + +For determining which sectional units are numbered and which appear in +the table of contents, the level number of a section is@tie{}1 +(@pxref{Sectioning/secnumdepth} and @pxref{Sectioning/tocdepth}). + +@PkgIndex{indentfirst} +The paragraph that follows the section title is not indented, as is a +standard typographical practice. One way to get an indent is to use the +package @file{indentfirst}. + +@PkgIndex{titlesec} +In general, to change the behavior of the @code{\section} command, there +are a number of options. One is the @code{\@@startsection} command +(@pxref{\@@startsection}). There are also many packages on CTAN that +address this, including @file{titlesec}. See the documentation but the +example below gives a sense of what they can do. + +@c credit: egreg https://groups.google.com/forum/#!topic/comp.text.tex/tvc8oM5P4y4 +@example +\usepackage@{titlesec@} % in preamble +\titleformat@{\section@} + @{\normalfont\Large\bfseries@} % format of title + @{\makebox[1pc][r]@{\thesection\hspace@{1pc@}@}@} % label + @{0pt@} % length of separation between label and title + @{@} % before-code hook +\titlespacing*@{\section@} + @{-1pc@}@{18pt@}@{10pt@}[10pc] +@end example + +@noindent +That puts the section number in the margin. + + +@node \subsection +@section @code{\subsection} + +@findex \subsection +@cindex subsection + +Synopsis, one of: + +@example +\subsection@{@var{title}@} +\subsection*@{@var{title}@} +\subsection[@var{toc-title}]@{@var{title}@} +@end example + +Start a subsection. The standard @LaTeX{} classes @code{article}, +@code{book}, and @code{report} all have this command. + +This produces a subsection. + +@example +We will show that there are more functions than Turing machines and that +therefore some functions have no associated machine. + +\subsection@{Cardinality@} We will begin with two paradoxes that +dramatize the challenge to our intuition posed by comparing the sizes of +infinite sets. +@end example + +For the standard @LaTeX{} classes @code{book} and @code{report} the +default output is like @samp{1.2.3 @var{title}} (for chapter@tie{}1, +section@tie{}2, subsection@tie{}3), alone on its line and flush left, in +boldface and a larger type (the type size is @code{\large}). The same +holds in @code{article} except that there are no chapters in that class +so it looks like @samp{2.3 @var{title}}. + +The @code{*}@tie{}form shows @var{title}. +But it does not show the section number, does not increment the +@code{section} counter, and produces no table of contents entry. + +The optional argument @var{toc-title} will appear as the section title +in the table of contents (@pxref{Table of contents etc.}). If it is +not present then @var{title} will be there. This shows the full name in +the title of the section, + +@example +\subsection[$\alpha,\beta,\gamma$ paper]@{\textit@{The Origin of + Chemical Elements@} by R.A.~Alpher, H.~Bethe, and G.~Gamow@} +@end example + +@noindent +but only @samp{@BES{03B1,\alpha},@BES{03B2,\beta},@BES{03B3,\gamma} +paper} on the contents page. + +For determining which sectional units are numbered and which appear in +the table of contents, the level number of a subsection is@tie{}2 +(@pxref{Sectioning/secnumdepth} and @pxref{Sectioning/tocdepth}). + +@PkgIndex{indentfirst} +The paragraph that follows the subsection title is not indented, as is a +standard typographical practice. One way to get an indent is to use the +package @file{indentfirst}. + +@PkgIndex{titlesec} +There are a number of ways to change the behavior of the +@code{\subsection} command. One is the @code{\@@startsection} command +(@pxref{\@@startsection}). There are also many packages on CTAN that +address this, including @file{titlesec}. See the documentation but the +example below gives a sense of what they can do. + +@example +\usepackage@{titlesec@} % in preamble +\titleformat@{\subsection@}[runin] + @{\normalfont\normalsize\bfseries@} % format of the title + @{\thesubsection@} % label + @{0.6em@} % space between label and title + @{@} % before-code hook +@end example + +@noindent +That puts the subsection number and @var{title} in the first line of +text. + + +@node \subsubsection & \paragraph & \subparagraph + +@section @code{\subsubsection}, @code{\paragraph}, @code{\subparagraph} + +@findex \subsubsection +@cindex subsubsection +@findex \paragraph +@cindex paragraph +@findex \subparagraph +@cindex subparagraph + +Synopsis, one of: + +@example +\subsubsection@{@var{title}@} +\subsubsection*@{@var{title}@} +\subsubsection[@var{toc-title}]@{@var{title}@} +@end example + +@noindent +or one of: + +@example +\paragraph@{@var{title}@} +\paragraph*@{@var{title}@} +\paragraph[@var{toc-title}]@{@var{title}@} +@end example + +@noindent +or one of: + +@example +\subparagraph@{@var{title}@} +\subparagraph*@{@var{title}@} +\subparagraph[@var{toc-title}]@{@var{title}@} +@end example + +Start a subsubsection, paragraph, or subparagraph. The standard +@LaTeX{} classes @code{article}, @code{book}, and @code{report} all have +these commands, although they are not commonly used. + +This produces a subsubsection. + +@example +\subsubsection@{Piston ring compressors: structural performance@} +Provide exterior/interior wall cladding assemblies +capable of withstanding the effects of load and stresses from +consumer-grade gasoline engine piston rings. +@end example + +The default output of each of the three does not change over the +standard @LaTeX{} classes @code{article}, @code{book}, and +@code{report}. For @code{\subsubsection} the @var{title} is alone on +its line, in boldface and normal size type. For @code{\paragraph} the +@var{title} is inline with the text, not indented, in boldface and +normal size type. For @code{\subparagraph} the @var{title} is inline +with the text, with a paragraph indent, in boldface and normal size type +(Because an @code{article} has no chapters its subsubsections are +numbered and so it looks like @samp{1.2.3 @var{title}}, for +section@tie{}1, subsection@tie{}2, and subsubsection@tie{}3. The other +two divisions are not numbered.) + +The @code{*}@tie{}form shows @var{title}. But it does not increment the +associated counter and produces no table of contents entry (and does not +show the number for @code{\subsubsection}). + +The optional argument @var{toc-title} will appear as the division title +in the table of contents (@pxref{Table of contents etc.}). If it is +not present then @var{title} will be there. + +For determining which sectional units are numbered and which appear in +the table of contents, the level number of a subsubsection is@tie{}3, of +a paragraph is@tie{}4, and of a subparagraph is@tie{}5 +(@pxref{Sectioning/secnumdepth} and @pxref{Sectioning/tocdepth}). + +@PkgIndex{indentfirst} +The paragraph that follows the subsubsection title is not indented, as is a +standard typographical practice. One way to get an indent is to use the +package @file{indentfirst}. + +@PkgIndex{titlesec} +There are a number of ways to change the behavior of the these commands. +One is the @code{\@@startsection} command (@pxref{\@@startsection}). +There are also many packages on CTAN that address this, including +@file{titlesec}. See the documentation on CTAN. + + +@node \appendix + +@section @code{\appendix} + +@findex \appendix +@cindex appendix +@cindex appendices + +Synopsis: + +@example +\appendix +@end example + +This does not directly produce any output. But in a book or report it +declares that subsequent @code{\chapter} commands start an appendix. In +an article it does the same, for @code{\section} commands. It also +resets the @code{chapter} and @code{section} counters to@tie{}0 in a +book or report, and in an article resets the @code{section} and +@code{subsection} counters. + +In this book + +@example +\chapter@{One@} ... +\chapter@{Two@} ... + ... +\appendix +\chapter@{Three@} ... +\chapter@{Four@} ... +@end example + +@noindent +the first two will generate output numbered @samp{Chapter 1} and +@samp{Chapter 2}. After the @code{\appendix} the numbering will be +@samp{Appendix A} and @samp{Appendix B}. @xref{Larger book template} +for another example. + +@PkgIndex{appendix} The @file{appendix} package adds the command +@code{\appendixpage} to put a separate @samp{Appendices} in the document +body before the first appendix, and the command @code{\addappheadtotoc} +to do the same in the table of contents. You can reset the name +@samp{Appendix} with a command like +@code{\renewcommand@{\appendixname@}@{Specification@}}, as well as a +number of other features. See the documentation on CTAN. + + +@node \frontmatter & \mainmatter & \backmatter + +@section @code{\frontmatter}, @code{\mainmatter}, @code{\backmatter} + +@findex \frontmatter +@cindex book, front matter +@findex \mainmatter +@cindex book, main matter +@findex \backmatter +@cindex book, back matter +@cindex book, end matter + +Synopsis, one of: + +@example +\frontmatter +\mainmatter +\backmatter +@end example + +Format a @code{book} class document differently according to which part +of the document is being produced. All three commands are optional. + +Traditionally, a book's front matter contains such things as the title +page, an abstract, a table of contents, a preface, a list of notations, +a list of figures, and a list of tables. (Some of these front matter +pages, such as the title page, are traditionally not numbered.) The +back matter may contain such things as a glossary, notes, a +bibliography, and an index. + +The @code{\frontmatter} declaration makes the pages numbered in +lowercase roman, and makes chapters not numbered, although each +chapter's title appears in the table of contents; if you use other +sectioning commands here, use the @code{*}-version (@pxref{Sectioning}). +The @code{\mainmatter} changes the behavior back to the expected +version, and resets the page number. The @code{\backmatter} leaves the +page numbering alone but switches the chapters back to being not +numbered. @xref{Larger book template} for an example using the three. + + +@node \@@startsection +@section @code{\@@startsection} + +@findex \@@startsection +@cindex section, redefining + +Synopsis: + +@example +\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}@{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@} +@end example + +Used to help redefine the behavior of commands that start sectioning +divisions such as @code{\section} or @code{\subsection}. + +Note that the @file{titlesec} package makes manipulation of sectioning +easier. Further, while most requirements for sectioning commands can be +satisfied with @code{\@@startsection}, some cannot. For instance, in +the standard @LaTeX{} @code{book} and @code{report} classes the commands +@code{\chapter} and @code{\report} are not constructed in this way. To +make such a command you may want to use the @code{\secdef} command. +@c xx define, and make a cross reference to, secdef. + +Technically, @code{\@@startsection} has the form + +@example +\@@startsection@{@var{name}@} + @{@var{level}@} + @{@var{indent}@} + @{@var{beforeskip}@} + @{@var{afterskip}@} + @{@var{style}@}*[@var{toctitle}]@{@var{title}@} +@end example + +@noindent +so that issuing + +@example +\renewcommand@{\section@}@{\@@startsection@{@var{name}@} + @{@var{level}@} + @{@var{indent}@} + @{@var{beforeskip}@} + @{@var{afterskip}@} + @{@var{style}@}@} +@end example + +@noindent +redefines @code{\section} to have the form +@code{\section*[@var{toctitle}]@{@var{title}@}} (here too, the +star@tie{}@code{*} is optional). @xref{Sectioning}. This implies that +when you write a command like @code{\renewcommand@{section@}@{...@}}, +the @code{\@@startsection@{...@}} must come last in the definition. See +the examples below. + +@table @var + +@item name +@anchor{startsection name} +@anchor{\@@startsection/name} +Name of the counter used to number the sectioning header. This counter +must be defined separately. Most commonly this is either +@code{section}, @code{subsection}, or @code{paragraph}. Although in +those cases the counter name is the same as the sectioning command +itself, you don't have to use the same name. + +Then @code{\the}@var{name} displays the title number and +@code{\}@var{name}@code{mark} is for the page headers. See the third +example below. + +@item level +@anchor{startsection level} +@anchor{\@@startsection/level} +An integer giving the depth of the sectioning command. +@xref{Sectioning} for the list of standard level numbers. + +If @var{level} is less than or equal to the value of the counter +@code{secnumdepth} then titles for this sectioning command will be +numbered (@pxref{Sectioning/secnumdepth}). For instance, if +@code{secnumdepth} is 1 in an @code{article} then the command +@code{\section@{Introduction@}} will produce output like ``1 +Introduction'' while @code{\subsection@{Discussion@}} will produce +output like ``Discussion'', without the number prefix. + +If @var{level} is less than or equal to the value of the counter +@var{tocdepth} then the table of contents will have an entry for this +sectioning unit (@pxref{Sectioning/tocdepth}). For instance, in an +@code{article}, if @var{tocdepth} is 1 then the table of contents will +list sections but not subsections. + +@item indent +@anchor{startsection indent} +@anchor{\@@startsection/indent} +A length giving the indentation of all of the title lines with respect +to the left margin. To have the title flush with the margin use +@code{0pt}. A negative indentation such as @code{-\parindent} will move +the title into the left margin. + +@item beforeskip +@anchor{startsection beforeskip} +@anchor{\@@startsection/beforeskip} +The absolute value of this length is the amount of vertical space that +is inserted before this sectioning unit's title. This space will be +discarded if the sectioning unit happens to start at the top of a fresh +page. If this number is negative then the first paragraph following the +header is not indented, if it is non-negative then the first paragraph +is indented. (Note that the negative of @code{1pt plus 2pt minus 3pt} +is @code{-1pt plus -2pt minus -3pt}.) + +For example, if @var{beforeskip} is @code{-3.5ex plus -1ex minus -0.2ex} +then to start the new sectioning unit, @LaTeX{} will add about 3.5 times +the height of a letter x in vertical space, and the first paragraph in +the section will not be indented. Using a rubber length, with +@code{plus} and @code{minus}, is good practice here since it gives +@LaTeX{} more flexibility in making up the page (@pxref{Lengths}). + +The full accounting of the vertical space between the baseline of the +line prior to this sectioning unit's header and the baseline of the +header is that it is the sum of the @code{\parskip} of the text font, +the @code{\baselineskip} of the title font, and the absolute value of +the @var{beforeskip}. This space is typically rubber so it may stretch +or shrink. (If the sectioning unit starts on a fresh page so that the +vertical space is discarded then the baseline of the header text will be +where @LaTeX{} would put the baseline of the first text line on that +page.) + +@item afterskip +@anchor{startsection afterskip} +@anchor{\@@startsection/afterskip} +This is a length. If @var{afterskip} is non-negative then this is the +vertical space inserted after the sectioning unit's title header. If it +is negative then the title header becomes a run-in header, so that it +becomes part of the next paragraph. In this case the absolute value of +the length gives the horizontal space between the end of the title and +the beginning of the following paragraph. (Note that the negative of +@code{1pt plus 2pt minus 3pt} is @code{-1pt plus -2pt minus -3pt}.) + +As with @var{beforeskip}, using a rubber length, with @code{plus} and +@code{minus} components, is good practice here since it gives @LaTeX{} +more flexibility in putting together the page. + +If @code{afterskip} is non-negative then the full accounting of the +vertical space between the baseline of the sectioning unit's header and +the baseline of the first line of the following paragraph is that it is +the sum of the @code{\parskip} of the title font, the +@code{\baselineskip} of the text font, and the value of @var{after}. +That space is typically rubber so it may stretch or shrink. (Note that +because the sign of @code{afterskip} changes the sectioning unit +header's from standalone to run-in, you cannot use a negative +@code{afterskip} to cancel part of the @code{\parskip}.) + +@item style +@anchor{startsection style} +@anchor{\@@startsection/style} +Controls the styling of the title. See the examples below. Typical +commands to use here are @code{\centering}, @code{\raggedright}, +@code{\normalfont}, @code{\hrule}, or @code{\newpage}. The last command +in @var{style} may be one that takes one argument, such as +@code{\MakeUppercase} or @code{\fbox} that takes one argument. The +section title will be supplied as the argument to this command. For +instance, setting @var{style} to @code{\bfseries\MakeUppercase} would +produce titles that are bold and uppercase. +@end table + +These are @LaTeX{}'s defaults for the first three sectioning units that +are defined with @code{\@@startsection}, for the @file{article}, +@file{book}, and @file{report} classes. For section, the @var{level} is +1, the @var{indent} is 0@dmn{pt}, the @var{beforeskip} is @code{-3.5ex +plus -1ex minus -0.2ex}, the @var{afterskip} is @code{2.3ex plus 0.2ex}, +and the @var{style} is @code{\normalfont\Large\bfseries}. For +subsection, the @var{level} is 2, the @var{indent} is 0@dmn{pt}, the +@var{beforeskip} is @code{-3.25ex plus -1ex minus -0.2ex}, the +@var{afterskip} is @code{1.5ex plus 0.2ex}, and the @var{style} is +@code{\normalfont\large\bfseries}. For subsubsection, the @var{level} +is 3, the @var{indent} is 0@dmn{pt}, the @var{beforeskip} is +@code{-3.25ex plus -1ex minus -0.2ex}, the @var{afterskip} is +@code{1.5ex plus 0.2ex}, and the @var{style} is +@code{\normalfont\normalsize\bfseries}. + +Here are examples. They go either in a package or class file or in the +preamble of a @LaTeX{} document. If you put them in the preamble they +must go between a @code{\makeatletter} command and a +@code{\makeatother}. (Probably the error message @code{You can't use +`\spacefactor' in vertical mode.} means that you forgot this.) +@xref{\makeatletter & \makeatother}. + +This will put section titles in large boldface type, centered. It says +@code{\renewcommand} because @LaTeX{}'s standard classes have already +defined a @code{\section}. For the same reason it does not define a +@code{section} counter, or the commands @code{\thesection} and +@code{\l@@section}. + +@example +\renewcommand\section@{% + \@@startsection@{section@}% @ref{\@@startsection/name,@var{name},@var{name}} + @{1@}% @ref{\@@startsection/level,@var{level},@var{level}} + @{0pt@}% @ref{\@@startsection/indent,@var{indent},@var{indent}} + @{-3.5ex plus -1ex minus -.2ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}} + @{2.3ex plus.2ex@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}} + @{\centering\normalfont\Large\bfseries@}% @ref{\@@startsection/style,@var{style},@var{style}} + @} +@end example + +This will put @code{subsection} titles in small caps type, inline with the paragraph. + +@example +\renewcommand\subsection@{% + \@@startsection@{subsection@}% @ref{\@@startsection/name,@var{name},@var{name}} + @{2@}% @ref{\@@startsection/level,@var{level},@var{level}} + @{0em@}% @ref{\@@startsection/indent,@var{indent},@var{indent}} + @{-1ex plus 0.1ex minus -0.05ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}} + @{-1em plus 0.2em@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}} + @{\scshape@}% @ref{\@@startsection/style,@var{style},@var{style}} + @} +@end example + +The prior examples redefined existing sectional unit title commands. +This defines a new one, illustrating the needed counter and macros to +display that counter. + +@c From https://groups.google.com/forum/#!searchin/comp.text.tex/startsection%7Csort:relevance/comp.text.tex/sB-nTS-oL08/ZZeKYdG0llMJ +@example +\setcounter@{secnumdepth@}@{6@}% show counters this far down +\newcounter@{subsubparagraph@}[subparagraph]% counter for numbering +\renewcommand@{\thesubsubparagraph@}% how to display + @{\thesubparagraph.\@@arabic\c@@subsubparagraph@}% numbering +\newcommand@{\subsubparagraph@}@{\@@startsection + @{subsubparagraph@}% + @{6@}% + @{0em@}% + @{\baselineskip@}% + @{0.5\baselineskip@}% + @{\normalfont\normalsize@}@} +\newcommand*\l@@subsubparagraph@{\@@dottedtocline@{6@}@{10em@}@{5em@}@}% for toc +\newcommand@{\subsubparagraphmark@}[1]@{@}% for page headers +@end example + + +@node Cross references +@chapter Cross references + +@cindex cross references + +@cindex label +We often want something like @samp{See Theorem~31}. But by-hand typing +the 31 is poor practice. Instead you should write a @dfn{label} such as +@code{\label@{eq:GreensThm@}} and then @dfn{reference} it, as with +@code{See equation~\ref@{eq:GreensThm@}}. @LaTeX{} will automatically +work out the number, put it into the output, and will change that number +later if needed. + +@example +We will see this with Theorem~\ref@{th:GreensThm@}. % forward reference +... +\begin@{theorem@} \label@{th:GreensThm@} + ... +\end@{theorem@} +... +See Theorem~\ref@{th:GreensThm@} on page~\pageref@{th:GreensThm@}. +@end example + +@LaTeX{} tracks cross reference information in a file having the +extension @file{.aux} and with the same base name as the file containing +the @code{\label}. So if @code{\label} is in @file{calculus.tex} then +the information is in @file{calculus.aux}. @LaTeX{} puts the +information in that file every time it runs across a @code{\label}. + +@cindex forward reference +@cindex reference, forward +The behavior described in the prior paragraph results in a quirk that +happens when your document has a @dfn{forward reference}, a @code{\ref} +that appears before the associated @code{\label}. If this is the first +time that you are compiling the document then you will get @samp{LaTeX +Warning: Label(s) may have changed. Rerun to get cross references right} +and in the output the forward reference will appear as two question +marks@tie{}@samp{??}, in boldface. A similar thing happens if you +change some things so the references changes; you get the same warning +and the output contains the old reference information. In both cases, +resolve this by compiling the document a second time. + +@PkgIndex{cleveref} The @code{cleveref} package enhances @LaTeX{}'s +cross referencing features. You can arrange that if you enter +@code{\begin@{thm@}\label@{th:Nerode@}...\end@{thm@}} then +@code{\cref@{th:Nerode@}} will output @samp{Theorem 3.21}, without you +having to enter the ``Theorem.'' + +@menu +* \label:: Assign a symbolic name to a piece of text. +* \pageref:: Refer to a page number. +* \ref:: Refer to a section, figure or similar. +@end menu + + +@node \label +@section @code{\label} + +@findex \label + +Synopsis: + +@example +\label@{@var{key}@} +@end example + +Assign a reference number to @var{key}. In ordinary text +@code{\label@{@var{key}@}} assigns to @var{key} the number of the +current sectional unit. Inside an environment with numbering, such as a +@code{table} or @code{theorem} environment, @code{\label@{@var{key}@}} +assigns to @var{key} the number of that environment. Retrieve the +assigned number with the @code{\ref@{@var{key}@}} command +(@pxref{\ref}). + +A key name can consist of any sequence of letters, digits, or common +punctuation characters. Upper and lowercase letters are +distinguished, as usual. + +A common convention is to use labels consisting of a prefix and a suffix +separated by a colon or period. Thus, @code{\label@{fig:Post@}} is a +label for a figure with a portrait of Emil Post. This helps to avoid +accidentally creating two labels with the same name, and makes your +source more readable. Some commonly-used prefixes: + +@table @code +@item ch +for chapters + +@item sec +@itemx subsec +for lower-level sectioning commands + +@item fig +for figures + +@item tab +for tables + +@item eq +for equations +@end table + +In the auxiliary file the reference information is kept as the text of +a command of the form +@code{\newlabel@{@var{label}@}@{@{@var{currentlabel}@}@{@var{pagenumber}@}@}}. +Here @var{currentlabel} is the current value of the macro +@code{\@@currentlabel} that is usually updated whenever you call +@code{\refstepcounter@{@var{counter}@}}. + +Below, the key @code{sec:test} will get the number of the current +section and the key @code{fig:test} will get the number of the figure. +(Incidentally, put labels after captions in figures and tables.) + +@example +\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@}. +@end example + + +@node \pageref +@section @code{\pageref} + +@findex \pageref +@cindex cross referencing with page number +@cindex page number, cross referencing + +Synopsis: + +@example +\pageref@{@var{key}@} +@end example + +Produce the page number of the place in the text where the corresponding +@code{\label}@{@var{key}@} command appears. + +If there is no @code{\label@{@var{key}@}} then you get something like +@samp{LaTeX Warning: Reference `th:GrensThm' on page 1 undefined on +input line 11.} + +Below, the @code{\label@{eq:main@}} 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.) + +@example +The main result is formula~\ref@{eq:main@} on page~\pageref@{eq:main@}. + ... +\begin@{equation@} \label@{eq:main@} + \mathbf@{P@}=\mathbf@{NP@} +\end@{equation@} +@end example + + +@node \ref +@section @code{\ref} + +@findex \ref +@cindex cross referencing, symbolic +@cindex section number, cross referencing +@cindex equation number, cross referencing +@cindex figure number, cross referencing +@cindex footnote number, cross referencing + +Synopsis: + +@example +\ref@{@var{key}@} +@end example + +Produces the number of the sectional unit, +equation, footnote, figure, @dots{}, of the corresponding +@code{\label} command (@pxref{\label}). It does not produce any text, +such as the word `Section' or `Figure', just the bare number itself. + +If there is no @code{\label@{@var{key}@}} then you get something like +@samp{LaTeX Warning: Reference `th:GrensThm' on page 1 undefined on +input line 11.} + +In this example the @code{\ref@{popular@}} produces @samp{2}. Note that +it is a forward reference since it comes before @code{\label@{popular@}} +so this document would have to be compiled twice. + +@example +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@} +@end example + +@PkgIndex{cleveref} +The @file{cleveref} package includes text such as @samp{Theorem} in the +reference. See the documentation on CTAN. + + +@node Environments +@chapter Environments + +@cindex environments +@findex \begin +@findex \end + +@LaTeX{} provides many environments for delimiting certain behavior. +An environment begins with @code{\begin} and ends with @code{\end}, +like this: + +@example +\begin@{@var{environment-name}@} + ... +\end@{@var{environment-name}@} +@end example + +The @var{environment-name} at the beginning must exactly match that at +the end. For instance, the input +@code{\begin@{table*@}...\end@{table@}} will cause an error like: +@samp{! LaTeX Error: \begin@{table*@} on input line 5 ended by +\end@{table@}.} + +@cindex group, and environments +Environments are executed within a group. + +@menu +* abstract:: Produce an abstract. +* array:: Math arrays. +* center:: Centered lines. +* description:: Labelled lists. +* displaymath:: Formulas that appear on their own line. +* document:: Enclose the whole document. +* enumerate:: Numbered lists. +* eqnarray:: Sequences of aligned equations. +* equation:: Displayed equation. +* figure:: Floating figures. +* filecontents:: Writing multiple files from the source. +* flushleft:: Flushed left lines. +* flushright:: Flushed right lines. +* itemize:: Bulleted lists. +* letter:: Letters. +* list:: Generic list environment. +* math:: In-line math. +* minipage:: Miniature page. +* picture:: Picture with text, arrows, lines and circles. +* quotation & quote:: Include a quotation. +* tabbing:: Align text arbitrarily. +* table:: Floating tables. +* tabular:: Align text in columns. +* thebibliography:: Bibliography or reference list. +* theorem:: Theorems, lemmas, etc. +* titlepage:: For hand crafted title pages. +* verbatim:: Simulating typed input. +* verse:: For poetry and other things. +@end menu + + +@node abstract +@section @code{abstract} + +@EnvIndex{abstract} +@cindex abstracts + +Synopsis: + +@example +\begin@{abstract@} +... +\end@{abstract@} +@end example + +Produce an abstract, possibly of multiple paragraphs. This environment +is only defined in the @code{article} and @code{report} document classes +(@pxref{Document classes}). + +Using the example below in the @code{article} class produces a displayed +paragraph. Document class option @code{titlepage} causes the abstract +to be on a separate page (@pxref{Document class options}); this is the +default only in the @code{report} class. + +@example +\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@} +@end example + +The next example produces a one column abstract in a two column document (for +a more flexible solution, use the package @file{abstract}). + +@c Adopted from http://www.tex.ac.uk/FAQ-onecolabs.html +@example +\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.@} +@} +@end example + + +@node array +@section @code{array} + +@EnvIndex{array} +@cindex arrays, math + +Synopsis: + +@example +\begin@{array@}@{@var{cols}@} + @var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ + ... +\end@{array@} +@end example + +@noindent +or: + +@example +\begin@{array@}[@var{pos}]@{@var{cols}@} + @var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ + ... +\end@{array@} +@end example + +Produce a mathematical array. This environment can only be used in math +mode, and normally appears within a displayed mathematics environment +such as @code{equation} (@pxref{equation}). Inside of each row the +column entries are separated by an ampersand, (@code{&}). Rows are +terminated with double-backslashes (@pxref{\\}). + +This example shows a three by three array. + +@example +\begin@{equation*@} + \chi(x) = + \left| % vertical bar fence + \begin@{array@}@{ccc@} + x-a &-b &-c \\ + -d &x-e &-f \\ + -g &-h &x-i + \end@{array@} + \right| +\end@{equation*@} +@end example + +The required argument @var{cols} describes the number of columns, their +alignment, and the formatting of the intercolumn regions. For instance, +@code{\begin@{array@}@{rcl@}...\end@{array@}} gives three columns: the +first flush right, the second centered, and the third flush left. See +@ref{tabular} for the complete description of @var{cols} and of the +other common features of the two environments, including the optional +@var{pos} argument. + +There are two ways that @code{array} diverges from @code{tabular}. The +first is that @code{array} entries are typeset in math mode, in +textstyle (@pxref{Modes}) except if the @var{cols} definition specifies +the column with @code{p@{...@}}, which causes the entry to be typeset in +text mode. The second is that, instead of @code{tabular}'s parameter +@code{\tabcolsep}, @LaTeX{}'s intercolumn space in an @code{array} is +governed by +@findex \arraycolsep +@code{\arraycolsep}, which gives half the width between columns. The +default for this is @samp{5pt} so that between two columns comes +10@dmn{pt} of space. + +@PkgIndex{amsmath} +To obtain arrays with braces the standard is to use the @file{amsmath} +package. It comes with environments @code{pmatrix} for an array +surrounded by parentheses@tie{}@code{(...)}, @code{bmatrix} for an array +surrounded by square brackets@tie{}@code{[...]}, @code{Bmatrix} for an +array surrounded by curly braces@tie{}@code{@{...@}}, @code{vmatrix} for +an array surrounded by vertical bars@tie{}@code{|...|}, and +@code{Vmatrix} for an array surrounded by double vertical +bars@tie{}@code{||...||}, along with a number of other array constructs. + +@PkgIndex{amsmath} +The next example uses the @file{amsmath} package. + +@example +\usepackage@{amsmath@} % in preamble + +\begin@{equation@} + \begin@{vmatrix@}@{cc@} % array with vert lines + a &b \\ + c &d + \end@{vmatrix@}=ad-bc +\end@{equation@} +@end example + +@PkgIndex{array (package)} +@PkgIndex{dcolumn} +There are many packages concerning arrays. The @file{array} package has +many useful extensions, including more column types. The @file{dcolumn} +package adds a column type to center on a decimal point. For both see +the documentation on CTAN. + + +@node center +@section @code{center} + +@EnvIndex{center} +@cindex centering text, environment for + +Synopsis: + +@example +\begin@{center@} + @var{line1} \\ + @var{line2} \\ + ... +\end@{center@} +@end example + +Create a new paragraph consisting of a sequence of lines that are +centered within the left and right margins. Use +double-backslash, @code{\\}, to get a line break (@pxref{\\}). +@findex \\ @r{(for @code{center})} +If some text is too long to fit on a line then @LaTeX{} will insert line +breaks that avoid hyphenation and avoid stretching or shrinking any +interword space. + +This environment inserts space above and below the text body. See +@ref{\centering} to avoid such space, for example inside a @code{figure} +environment. + +This example produces three centered lines. There is extra vertical +space between the last two lines. + +@example +\begin@{center@} + A Thesis Submitted in Partial Fufillment \\ + of the Requirements of \\[0.5ex] + the School of Environmental Engineering +\end@{center@} +@end example + +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. + +@example +\begin@{center@} + My father considered that anyone who went to chapel and didn't drink + alcohol was not to be tolerated.\\ + I grew up in that belief. --Richard Burton +\end@{center@} +@end example + +A double backslash after the final line is optional. If present it +doesn't add any vertical space. + +In a two-column document the text is centered in a column, not in the +entire page. + +@menu +* \centering:: Declaration form of the @code{center} environment. +@end menu + + +@node \centering +@subsection @code{\centering} + +@findex \centering +@cindex centering text, declaration for + + +Synopsis: + +@example +@{\centering ... @} +@end example + +@noindent +or + +@example +\begin@{group@} + \centering ... +\end@{group@} +@end example + +Center the material in its scope. It is most often used inside an +environment such as @code{figure}, or in a @code{parbox}. + +This example's @code{\centering} declaration causes the graphic to be +horizontally centered. + +@example +\begin@{figure@} + \centering + \includegraphics[width=0.6\textwidth]@{ctan_lion.png@} + \caption@{CTAN Lion@} \label@{fig:CTANLion@} +\end@{figure@} +@end example + +@noindent +The scope of this @code{\centering} ends with the @code{\end@{figure@}}. + +Unlike the @code{center} environment, the @code{\centering} command does +not add vertical space above and below the text. That's its advantage +in the above example; there is not an excess of space. + +It also does not start a new paragraph; it simply changes how @LaTeX{} +formats paragraph units. If @code{ww @{\centering xx \\ yy@} zz} is +surrounded by blank lines then @LaTeX{} will create a paragraph whose +first line @samp{ww xx} is centered and whose second line, not centered, +contains @samp{yy zz}. Usually what is desired is for the scope of the +declaration to contain a blank line or the @code{\end} command of an +environment such as @code{figure} or @code{table} that ends the +paragraph unit. Thus, if @code{@{\centering xx \\ yy\par@} zz} is +surrounded by blank lines then it makes a new paragraph with two +centered lines @samp{xx} and @samp{yy}, followed by a new paragraph with +@samp{zz} that is formatted as usual. + + +@node description +@section @code{description} + +@EnvIndex{description} +@cindex labelled lists, creating +@cindex description lists, creating + +Synopsis: + +@example +\begin@{description@} + \item[@var{label of first item}] @var{text of first item} + \item[@var{label of second item}] @var{text of second item} + ... +\end@{description@} +@end example + +Environment to make a list of labeled items. Each item's @var{label} is +typeset in bold and is flush left, so that long labels continue into the +first line of the item text. There must be at least one item; having +none causes the @LaTeX{} error @samp{Something's wrong--perhaps a +missing \item}. + +This example shows the environment used for a sequence of definitions. + +@example +\begin@{definition@} + \item[lama] A priest. + \item[llama] A beast. +\end@{definition@} +@end example + +@noindent +The labels @samp{lama} and @samp{llama} are output in boldface, with the +left edge on the left margin. + +@findex \item +Start list items with the @code{\item} command (@pxref{\item}). Use the +optional labels, as in @code{\item[Main point]}, because there is +no sensible default. Following the @code{\item} is optional text, which +may contain multiple paragraphs. + +@cindex bold typewriter, avoiding +@cindex typewriter labels in lists +Since the labels are in bold style, if the label text calls for a font +change given in argument style (see @ref{Font styles}) then it will come +out bold. For instance, if the label text calls for typewriter with +@code{\item[\texttt@{label text@}]} then it will appear in bold +typewriter, if that is available. The simplest way around this, in this +example to get non-bold typewriter, is to use declarative style: +@code{\item[@{\tt label text@}]}. Similarly, get the standard roman +font with @code{\item[@{\rm label text@}]}. + +For other major @LaTeX{} labelled list environments, see @ref{itemize} +and @ref{enumerate}. Unlike those environments, nesting +@code{description} environments does not change the default label; it is +boldface and flush left at all levels. + +For information about list layout parameters, including the default +values, and for information about customizing list layout, see +@ref{list}. The package @file{enumitem} is useful for customizing +lists. + +This example changes the description labels to small caps. + +@example +\renewcommand@{\descriptionlabel@}[1]@{% + @{\hspace@{\labelsep@}\textsc@{#1@}@}@} +@end example + + +@node displaymath +@section @code{displaymath} +@c http://tex.stackexchange.com/questions/40492/what-are-the-differences-between-align-equation-and-displaymath + +@EnvIndex{displaymath} + +Synopsis: + +@example +\begin@{displaymath@} + @var{mathematical text} +\end@{displaymath@} +@end example + +Environment to typeset the math text on its own line, in display style +and centered. To make the text be flush-left use the global option +@code{fleqn}; see @ref{Document class options}. + +In the @code{displaymath} environment no equation number is added to the +math text. One way to get an equation number is to use the +@code{equation} environment (@pxref{equation}). + +@LaTeX{} will not break the @var{math text} across lines. + +@PkgIndex{amsmath} +Note that the @file{amsmath} package has significantly more extensive +displayed equation facilities. For example, there are a number of +ways in that package for having math text broken across lines. + +The construct @code{\[@var{math text}\]} is essentially a synonym for +@code{\begin@{displaymath@}@var{math text}\end@{displaymath@}} but the +latter is easier to work with in the source file; for instance, +searching for a square bracket may get false positives but the word +@code{displaymath} will likely be unique. (The construct +@code{$$@var{math text}$$} from Plain@tie{}@TeX{} is sometimes +mistakenly used as a synonym for @code{displaymath}. It is not a +synonym, because the @code{displaymath} environment checks that it isn't +started in math mode and that it ends in math mode begun by the matching +environment start, because the @code{displaymath} environment has +different vertical spacing, and because the @code{displaymath} +environment honors the @code{fleqn} option.) + +The output from this example is centered and alone on its line. + +@example +\begin@{displaymath@} + \int_1^2 x^2\,dx=7/3 +\end@{displaymath@} +@end example + +@noindent +Also, the integral sign is larger than the inline version +@code{\( \int_1^2 x^2\,dx=7/3 \)} produces. + + +@node document +@section @code{document} + +@EnvIndex{document} + +The @code{document} environment encloses the entire body of a document. +It is required in every @LaTeX{} document. @xref{Starting and ending}. + +@menu +* \AtBeginDocument:: Hook for commands at the start of the document. +* \AtEndDocument:: Hook for commands at the end of the document. +@end menu + + +@node \AtBeginDocument +@subsection @code{\AtBeginDocument} + +@findex \AtBeginDocument +@cindex beginning of document hook + +Synopsis: + +@example +\AtBeginDocument@{@var{code}@} +@end example + +Save @var{code} and execute it when @code{\begin@{document@}} is +executed, at the very end of the preamble. The code is executed after +the font selection tables have been set up, so the normal font for the +document is the current font. However, the code is executed as part of +the preamble so you cannot do any typesetting with it. + +You can issue this command more than once; the successive code lines +will be executed in the order that you gave them. + + +@node \AtEndDocument +@subsection @code{\AtEndDocument} + +@findex \AtEndDocument +@cindex end of document hook + +Synopsis: + +@example +\AtEndDocument@{@var{code}@} +@end example + +Save @var{code} and execute it near the end of the document. +Specifically, it is executed when @code{\end@{document@}} is executed, +before the final page is finished and before any leftover floating +environments are processed. If you want some of the code to be executed +after these two processes then include a @code{\clearpage} at the +appropriate point in @var{code}. + +You can issue this command more than once; the successive code lines +will be executed in the order that you gave them. + + +@node enumerate +@section @code{enumerate} + +@EnvIndex{enumerate} +@cindex lists of items, numbered + +Synopsis: + +@example +\begin@{enumerate@} + \item[@var{optional label of first item}] @var{text of first item} + \item[@var{optional label of second item}] @var{text of second item} + ... +\end@{enumerate@} +@end example + +Environment to produce a numbered list of items. The format of the +label numbering depends on the nesting level of this environment; see +below. The default top-level numbering is @samp{1.}, @samp{2.}, +etc. Each @code{enumerate} list environment must have at least one item; +having none causes the @LaTeX{} error @samp{Something's wrong--perhaps a +missing \item}. + +This example gives the first two finishers in the 1908 Olympic marathon. +As a top-level list the labels would come out as @samp{1.} and +@samp{2.}. + +@example +\begin@{enumerate@} + \item Johnny Hayes (USA) + \item Charles Hefferon (RSA) +\end@{enumerate@} +@end example + +@findex \item +Start list items with the @code{\item} command (@pxref{\item}). If you +give @code{\item} an optional argument by following it with square +brackets, as in @code{\item[Interstitial label]}, then the next item +will continue the interrupted sequence (@pxref{\item}). That is, you +will get labels like @samp{1.}, then @samp{Interstitial label}, then +@samp{2.}. Following the @code{\item} is optional text, which may +contain multiple paragraphs. + +Enumerations may be nested within other @code{enumerate} environments, +or within any paragraph-making environment such as @code{itemize} +(@pxref{itemize}), up to four levels deep. This gives @LaTeX{}'s +default for the format at each nesting level, where 1 is the top level, +the outermost level. + +@enumerate +@item arabic number followed by a period: @samp{1.}, @samp{2.},@tie{}@dots{} +@item lowercase letter inside parentheses: @samp{(a)}, @samp{(b)}@tie{}@dots{} +@item lowercase roman numeral followed by a period: @samp{i.}, @samp{ii.},@tie{}@dots{} +@item uppercase letter followed by a period: @samp{A.}, @samp{B.},@tie{}@dots{} +@end enumerate + +@findex \enumi +@findex \enumii +@findex \enumiii +@findex \enumiv +@anchor{enumerate enumi} +@anchor{enumerate enumii} +@anchor{enumerate enumiii} +@anchor{enumerate enumiv} +The @code{enumerate} environment uses the counters @code{\enumi} through +@code{\enumiv} (@pxref{Counters}). + +For other major @LaTeX{} labeled list environments, see +@ref{description} and @ref{itemize}. For information about list layout +parameters, including the default values, and for information about +customizing list layout, see @ref{list}. The package @file{enumitem} is +useful for customizing lists. + +@findex \labelenumi +@findex \labelenumii +@findex \labelenumiii +@findex \labelenumiv +@anchor{enumerate labelenumi} +@anchor{enumerate labelenumii} +@anchor{enumerate labelenumiii} +@anchor{enumerate labelenumiv} +To change the format of the label use @code{\renewcommand} +(@pxref{\newcommand & \renewcommand}) on the commands @code{\labelenumi} +through @code{\labelenumiv}. For instance, this first level list will be +labelled with uppercase letters, in boldface, and without a trailing +period. + +@findex \Alph @r{example} +@example +\renewcommand@{\labelenumi@}@{\textbf@{\Alph@{enumi@}@}@} +\begin@{enumerate@} + \item Shows as boldface A + \item Shows as boldface B +\end@{enumerate@} +@end example + +For a list of counter-labeling commands see @ref{\alph \Alph \arabic +\roman \Roman \fnsymbol}. + + +@node eqnarray +@section @code{eqnarray} + +@EnvIndex{eqnarray} +@cindex equations, aligning +@cindex aligning equations + +@cindex align @r{environment, from @code{amsmath}} +@cindex amsmath @r{package, replacing @code{eqnarray}} +@cindex Madsen, Lars +The @code{eqnarray} environment is obsolete. It has infelicities, +including spacing that is inconsistent with other mathematics elements. +(See ``Avoid eqnarray!''@: by Lars Madsen +@url{http://tug.org/TUGboat/tb33-1/tb103madsen.pdf}). New documents +should include the @file{amsmath} package and use the displayed +mathematics environments provided there, such as the @code{align} +environment. We include a description only for completeness and for +working with old documents. + +Synopsis: + +@example +\begin@{eqnarray@} + @var{first formula left} &@var{first formula middle} &@var{first formula right} \\ + ... +\end@{eqnarray@} +@end example + +@noindent +or + +@example +\begin@{eqnarray*@} + @var{first formula left} &@var{first formula middle} &@var{first formula right} \\ + ... +\end@{eqnarray*@} +@end example + +@findex \\ @r{(for @code{eqnarray})} +Display a sequence of equations or inequalities. The left and right +sides are typeset in display mode, while the middle is typeset in text +mode. + +It is similar to a three-column @code{array} environment, with items +within a row separated by an ampersand@tie{}(@code{&}), and with rows +separated by double backslash@tie{} @code{\\}). +@findex \\* @r{(for @code{eqnarray})} +The starred form of line break (@code{\\*}) can also be used to separate +equations, and will disallow a page break there (@pxref{\\}). + +@findex \nonumber +@cindex equation numbers, omitting +The unstarred form @code{eqnarray} places an equation number on every +line (using the @code{equation} counter), unless that line contains a +@code{\nonumber} command. The starred form @code{eqnarray*} omits +equation numbering, while otherwise being the same. + +@findex \lefteqn +The command @code{\lefteqn} is used for splitting long formulas across +lines. It typesets its argument in display style flush left in a box of +zero width. + +This example shows three lines. The first two lines make an inequality, +while the third line has not entry on the left side. + +@example +\begin@{eqnarray*@} + \lefteqn@{x_1+x_2+\cdots+x_n@} \\ + &\leq &y_1+y_2+\cdots+y_n \\ + &= &z+y_3+\cdots+y_n +\end@{eqnarray*@} +@end example + + +@node equation +@section @code{equation} + +@EnvIndex{equation} +@cindex equations, environment for +@cindex formulas, environment for + +Synopsis: + +@example +\begin@{equation@} + @var{mathematical text} +\end@{equation@} +@end example + +The same as a @code{displaymath} environment (@pxref{displaymath}) +except that @LaTeX{} puts an equation number flush to the right margin. +The equation number is generated using the @code{equation} counter. + +You should have no blank lines between @code{\begin@{equation@}} and +@code{\begin@{equation@}}, or @LaTeX{} will tell you that there is a +missing dollar sign. + +@PkgIndex{amsmath} +The package @file{amsmath} package has extensive displayed equation +facilities. New documents should include this package. + + +@node figure +@section @code{figure} + +@EnvIndex{figure} +@cindex inserting figures +@cindex figures, inserting + +Synopsis: + +@example +\begin@{figure@}[@var{placement}] + @var{figure body} + \caption[@var{loftitle}]@{@var{title}@} % optional + \label@{@var{label@}} % optional +\end@{figure@} +@end example + +@noindent +or: + +@example +\begin@{figure*@}[@var{placement}] + @var{figure body} + \caption[@var{loftitle}]@{@var{title}@} % optional + \label@{@var{label@}} % optional +\end@{figure*@} +@end example + +Figures are for material that is not part of the normal text. An +example is material that you cannot have split between two pages, such +as a graphic. Because of this, @LaTeX{} does not typeset figures in +sequence with normal text but instead ``floats'' them to a convenient +place, such as the top of a following page (@pxref{Floats}). + +The @var{figure body} can consist of imported graphics +(@pxref{Graphics}), or text, @LaTeX{} commands, etc. It is typeset in a +@code{parbox} of width @code{\textwidth}. + +The possible values of @var{placement} are @code{h} for @samp{here}, +@code{t} for @samp{top}, @code{b} for @samp{bottom}, and @code{p} for +@samp{on a separate page of floats}. For the effect of these options on +the float placement algorithm, see @ref{Floats}. + +The starred form @code{figure*} is used when a document is in +double-column mode (@pxref{\twocolumn}). It produces a figure that +spans both columns, at the top of the page. To add the possibility of +placing at a page bottom see the discussion of @var{placement} @code{b} +in @ref{Floats}. + +The label is optional; it is used for cross references (@pxref{Cross +references}). +@findex \caption +The optional @code{\caption} command specifies caption text for the +figure. By default it is numbered. If @var{loftitle} is present, it is +used in the list of figures instead of @var{title} (@pxref{Table of +contents etc.}). + +This example makes a figure out of a graphic. @LaTeX{} will place that +graphic and its caption at the top of a page or, if it is pushed to the +end of the document, on a page of floats. + +@example +\usepackage@{graphicx@} % in preamble + ... +\begin@{figure@}[t] + \centering + \includegraphics[width=0.5\textwidth]@{CTANlion.png@} + \caption@{The CTAN lion, by Duane Bibby@} +\end@{figure@} +@end example + + +@node filecontents +@section @code{filecontents}: Write an external file + +@EnvIndex{filecontents} +@EnvIndex{filecontents*} +@cindex external files, writing +@cindex writing external files + +Synopsis: + +@example +\begin@{filecontents@}@{@var{filename}@} + @var{text} +\end@{filecontents@} +@end example + +@noindent +or + +@example +\begin@{filecontents*@}@{@var{filename}@} + @var{text} +\end@{filecontents*@} +@end example + +Create a file named @var{filename} and fill it with @var{text}. The +unstarred version of the environment @code{filecontents} prefixes the +content of the created file with a header; see the example below. The +starred version @code{filecontents*} does not include the header. + +This environment can be used anywhere in the preamble, although it often +appears before the @code{\documentclass} command. It is typically used +when a source file requires a nonstandard style or class file. The +environment will write that file to the directory containing the source +and thus make the source file self-contained. Another use is to include +@code{bib} references in the file, again to make it self-contained. + +The environment checks whether a file of that name already exists and if +so, does not do anything. There is a @file{filecontents} package that +redefines the @code{filecontents} environment so that instead of doing +nothing in that case, it will overwrite the existing file. + +For example, this document + +@example +\documentclass@{article@} +\begin@{filecontents@}@{JH.sty@} +\newcommand@{\myname@}@{Jim Hef@{@}feron@} +\end@{filecontents@} +\usepackage@{JH@} +\begin@{document@} +Article by \myname. +\end@{document@} +@end example + +@noindent +produces this file @file{JH.sty}. + +@example +%% LaTeX2e file `JH.sty' +%% generated by the `filecontents' environment +%% from source `test' on 2015/10/12. +%% +\newcommand@{\myname@}@{Jim Hef@{@}feron@} +@end example + + +@node flushleft +@section @code{flushleft} + +@EnvIndex{flushleft} +@cindex left-justifying text, environment for +@cindex ragged right text, environment for + +Synopsis: + +@example +\begin@{flushleft@} + @var{line1} \\ + @var{line2} \\ + ... +\end@{flushleft@} +@end example + +@findex \\ @r{for @code{flushleft}} +An environment that creates a paragraph whose lines are flush to the +left-hand margin, and ragged right. If you have lines that are too long +then @LaTeX{} will linebreak them in a way that avoids hyphenation and +stretching or shrinking spaces. To force a new line use a double +backslash, @code{\\}. For the declaration form +see@tie{}@ref{\raggedright}. + +This creates a box of text that is at most 3 inches wide, with the text +flush left and ragged right. + +@example +\noindent\begin@{minipage@}@{3in@} +\begin@{flushleft@} + A long sentence that will be broken by \LaTeX@{@} + at a convenient spot. \\ + And, a fresh line forced by the double backslash. +\end@{flushleft@} +\end@{minipage@} +@end example + + +@menu +* \raggedright:: Declaration form of the @code{flushleft} environment. +@end menu + + +@node \raggedright +@subsection @code{\raggedright} + +@findex \raggedright +@cindex ragged right text +@cindex left-justifying text +@cindex justification, ragged right + +Synopses: + +@example +@{\raggedright ... @} +@end example + +@noindent +or + +@example +\begin@{@var{environment}@} \raggedright + ... +\end@{@var{environment}@} +@end example + +A declaration which causes lines to be flush to the left margin and +ragged right. It can be used inside an environment such as @code{quote} +or in a @code{parbox}. For the environment form +see@tie{}@ref{flushleft}. + +Unlike the @code{flushleft} environment, the @code{\raggedright} +command does not start a new paragraph; it only changes how @LaTeX{} +formats paragraph units. To affect a paragraph unit's format, the +scope of the declaration must contain the blank line or @code{\end} +command that ends the paragraph unit. + +Here @code{\raggedright} in each second column keeps @LaTeX{} from doing +very awkward typesetting to fit the text into the narrow column. Note +that @code{\raggedright} is inside the curly braces @code{@{...@}} to +delimit its effect. + +@example +\begin@{tabular@}@{rp@{2in@}@} + Team alpha &@{\raggedright This team does all the real work.@} \\ + Team beta &@{\raggedright This team ensures that the water + cooler is never empty.@} \\ +\end@{tabular@} +@end example + + +@node flushright +@section @code{flushright} + +@EnvIndex{flushright} +@cindex ragged left text, environment for +@cindex right-justifying text, environment for + +@example +\begin@{flushright@} + @var{line1} \\ + @var{line2} \\ + ... +\end@{flushright@} +@end example + +@findex \\ (for @code{flushright}) +An environment that creates a paragraph whose lines are flush to the +right-hand margin and ragged left. If you have lines that are too long +to fit the margins then @LaTeX{} will linebreak them in a way that +avoids hyphenation and stretching or shrinking spaces. To force a new +line use a double backslash, @code{\\}. For the declaration form +see@tie{}@ref{\raggedleft}. + +For an example related to this environment, see@tie{}@ref{flushleft}. + +@menu +* \raggedleft:: Declaration form of the @code{flushright} environment. +@end menu + + +@node \raggedleft +@subsection @code{\raggedleft} + +@findex \raggedleft +@cindex ragged left text +@cindex justification, ragged left +@cindex right-justifying text + +Synopses: + +@example +@{\raggedleft ... @} +@end example + +@noindent +or + +@example +\begin@{@var{environment}@} \raggedleft + ... +\end@{@var{environment}@} +@end example + +A declaration which causes lines to be flush to the right margin and +ragged left. It can be used inside an environment such as @code{quote} +or in a @code{parbox}. For the environment form +see@tie{}@ref{flushright}. + +Unlike the @code{flushright} environment, the @code{\raggedleft} +command does not start a new paragraph; it only changes how @LaTeX{} +formats paragraph units. To affect a paragraph unit's format, the +scope of the declaration must contain the blank line or @code{\end} +command that ends the paragraph unit. + +For an example related to this environment, see@tie{}@ref{\raggedright}. + + +@node itemize +@section @code{itemize} + +@EnvIndex{itemize} +@findex \item +@cindex lists of items +@cindex unordered lists +@cindex bulleted lists +@cindex bullet lists + +Synopsis: + +@example +\begin@{itemize@} + \item[@var{optional label of first item}] @var{text of first item} + \item[@var{optional label of second item}] @var{text of second item} + ... +\end@{itemize@} +@end example + +Produce a list that is unordered, sometimes called a bullet list. The +environment must have at least one @code{\item}; having none causes the +@LaTeX{} error @samp{Something's wrong--perhaps a missing \item}. + +This gives a two-item list. + +@example +\begin@{itemize@} + \item Pencil and watercolor sketch by Cassandra + \item Rice portrait +\end@{itemize@} +@end example + +@noindent +As a top-level list each label would come out as a bullet, @bullet{}. +The format of the labeling depends on the nesting level; see below. + +@findex \item +Start list items with the @code{\item} command (@pxref{\item}). If you +give @code{\item} an optional argument by following it with square +brackets, as in @code{\item[Optional label]}, then by default it will +appear in bold and be flush right, so it could extend into the left +margin. For labels that are flush left see the @ref{description} +environment. Following the @code{\item} is optional text, which may +contain multiple paragraphs. + +@findex \labelitemi +@findex \labelitemii +@findex \labelitemiii +@findex \labelitemiv +@anchor{itemize labelitemi} +@anchor{itemize labelitemii} +@anchor{itemize labelitemiii} +@anchor{itemize labelitemiv} +Itemized lists can be nested within one another, up to four levels deep. +They can also be nested within other paragraph-making environments, such +as @code{enumerate} (@pxref{enumerate}). The @code{itemize} environment +uses the commands @code{\labelitemi} through @code{\labelitemiv} to +produce the default label (this also uses the convention of lowercase +roman numerals at the end of the command names that signify the nesting +level). These are the default marks at each level. + +@enumerate +@item @bullet{} (bullet, from @code{\textbullet}) +@item @b{-@w{-}} (bold en-dash, from @code{\normalfont\bfseries\textendash}) +@item * (asterisk, from @code{\textasteriskcentered}) +@iftex +@item @math{\cdot} (centered dot, from @code{\textperiodcentered}) +@end iftex +@ifnottex +@item . (centered dot, rendered here as a period, from @code{\textperiodcentered}) +@end ifnottex +@end enumerate + +Change the labels with @code{\renewcommand}. For instance, this makes +the first level use diamonds. + +@example +\renewcommand@{\labelitemi@}@{$\diamond$@} +@end example + +@findex \leftmargin +@findex \leftmargini +@findex \leftmarginii +@findex \leftmarginiii +@findex \leftmarginiv +@findex \leftmarginv +@findex \leftmarginvi +@anchor{itemize leftmargin} +@anchor{itemize leftmargini} +@anchor{itemize leftmarginii} +@anchor{itemize leftmarginiii} +@anchor{itemize leftmarginiv} +@anchor{itemize leftmarginv} +@anchor{itemize leftmarginvi} +The distance between the left margin of the enclosing environment and +the left margin of the @code{itemize} list is determined by the +parameters @code{\leftmargini} through @code{\leftmarginvi}. (Note the +convention of using lowercase roman numerals a the end of the command +name to denote the nesting level.) The defaults are: @code{2.5em} in +level 1 (@code{2em} in two-column mode), @code{2.2em} in level 2, +@code{1.87em} in level 3, and @code{1.7em} in level 4, with smaller +values for more deeply nested levels. + +For other major @LaTeX{} labeled list environments, see +@ref{description} and @ref{enumerate}. For information about list +layout parameters, including the default values, and for information +about customizing list layout, see @ref{list}. The package +@file{enumitem} is useful for customizing lists. + +This example greatly reduces the margin space for outermost itemized +lists. + +@example +\setlength@{\leftmargini@}@{1.25em@} % default 2.5em +@end example + +@findex \parskip @r{example} +Especially for lists with short items, it may be desirable to elide +space between items. Here is an example defining an @code{itemize*} +environment with no extra spacing between items, or between paragraphs +within a single item (@code{\parskip} is not list-specific, +@pxref{\parindent & \parskip}): + +@example +\newenvironment@{itemize*@}% + @{\begin@{itemize@}% + \setlength@{\itemsep@}@{0pt@}% + \setlength@{\parsep@}@{0pt@}@}% + \setlength@{\parskip@}@{0pt@}@}% + @{\end@{itemize@}@} +@end example + + +@node letter +@section @code{letter} environment: writing letters + +@EnvIndex{letter} + +This environment is used for creating letters. @xref{Letters}. + + +@node list +@section @code{list} + +@EnvIndex{list} +@cindex lists of items, generic + +Synopsis: + +@example +\begin@{list@}@{@var{labeling}@}@{@var{spacing}@} + \item[@var{optional label of first item}] @var{text of first item} + \item[@var{optional label of second item}] @var{text of second item} + ... +\end@{list@} +@end example + +An environment for constructing lists. + +Note that this environment does not typically appear in the document +body. Most lists created by @LaTeX{} authors are the ones that come +standard: the @code{description}, @code{enumerate}, and @code{itemize} +environments (@pxref{description}, @ref{enumerate}, and @ref{itemize}). + +Instead, the @code{list} environment is most often used in macros. For +example, many standard @LaTeX{} environments that do not immediately +appear to be lists are in fact constructed using @code{list}, including +@code{quotation}, @code{quote}, and @code{center} (@pxref{quotation & +quote}, @pxref{center}). + +This uses the @code{list} environment to define a new custom +environment. + +@example +\newcounter@{namedlistcounter@} % number the items +\newenvironment@{named@} + @{\begin@{list@} + @{Item~\Roman@{namedlistcounter@}.@} % labeling + @{\usecounter@{namedlistcounter@} % set counter + \setlength@{\leftmargin@}@{3.5em@}@} % set spacing + @} + @{\end@{list@}@} + +\begin@{named@} + \item Shows as ``Item~I.'' + \item[Special label.] Shows as ``Special label.'' + \item Shows as ``Item~II.'' +\end@{named@} +@end example + +The mandatory first argument @var{labeling} specifies the default +labeling of list items. It can contain text and @LaTeX{} commands, as +above where it contains both @samp{Item} and @samp{\Roman@{...@}}. +@LaTeX{} forms the label by putting the @var{labeling} argument in a box +of width @code{\labelwidth}. If the label is wider than that, the +additional material extends to the right. When making an instance of a +list you can override the default labeling by giving @code{\item} an +optional argument by including square braces and the text, as in the +above @code{\item[Special label.]}; @pxref{\item}. + +The mandatory second argument @var{spacing} has a list of commands. +This list can be empty. A command that can go in here is +@code{\usecounter@{@var{countername}@}} (@pxref{\usecounter}). Use this +to tell @LaTeX{} to number the items using the given counter. The +counter will be reset to zero each time @LaTeX{} enters the environment, +and the counter is incremented by one each time @LaTeX{} encounters an +@code{\item} that does not have an optional argument. + +@findex \makelabel +@anchor{list makelabel} Another command that can go in @var{spacing} is +@code{\makelabel}, which constructs the label box. By default it puts +the contents flush right. Its only argument is the label, which it +typesets in LR mode (@pxref{Modes}). One example of changing its +definition is that to the above @code{named} example, before the +definition of the environment add +@code{\newcommand@{\namedmakelabel@}[1]@{\textsc@{#1@}@}}, and between +the @code{\setlength} command and the parenthesis that closes the +@var{spacing} argument also add @code{\let\makelabel\namedmakelabel}. +Then the items will be typeset in small caps. Similarly, changing the +second code line to @code{\let\makelabel\fbox} puts the labels inside a +framed box. Another example of the @code{\makelabel} command is below, +in the definition of the @code{redlabel} environment. + +Also often in @var{spacing} are commands to redefine the spacing for the +list. Below are the spacing parameters with their default values. +(Default values for derived environments such as @code{itemize} can be +different than the values shown here.) See also the figure that follows +the list. Each is a length (@pxref{Lengths}). The vertical spaces are +normally rubber lengths, with @code{plus} and @code{minus} components, +to give @TeX{} flexibility in setting the page. Change each with a +command such as @code{\setlength@{itemsep@}@{2pt plus1pt minus1pt@}}. +For some effects these lengths should be zero or negative. + +@ftable @code +@item \itemindent +@anchor{list itemindent} +Extra horizontal space indentation, beyond @code{leftmargin}, of the +first line each item. Its default value is @code{0pt}. + +@item \itemsep +@anchor{list itemsep} +Vertical space between items, beyond the @code{\parsep}. The defaults +for the first three levels in @LaTeX{}'s @samp{article}, @samp{book}, +and @samp{report} classes at 10 point size are: @code{4pt plus2pt +minus1pt}, @code{\parsep} (that is, @code{2pt plus1pt minus1pt}), and +@code{\topsep} (that is, @code{2pt plus1pt minus1pt}). The defaults at +11 point are: @code{4.5pt plus2pt minus1pt}, @code{\parsep} (that is, +@code{2pt plus1pt minus1pt}), and @code{topsep} (that is, @code{2pt +plus1pt minus1pt}). The defaults at 12 point are: @code{5pt plus2.5pt +minus1pt}, @code{\parsep} (that is, @code{2.5pt plus1pt minus1pt}), and +@code{\topsep} (that is, @code{2.5pt plus1pt minus1pt}). + +@item \labelsep +@anchor{list labelsep} +Horizontal space between the label and text of an item. +The default for @LaTeX{}'s @samp{article}, @samp{book}, +and @samp{report} classes is @code{0.5em}. + +@item \labelwidth +@anchor{list labelwidth} +Horizontal width. The box containing the label is nominally this wide. +If @code{\makelabel} returns text that is wider than this then the first +line of the item will be indented to make room for this extra material. +If @code{\makelabel} returns text of width less than or equal to +@code{\labelwidth} then @LaTeX{}'s default is that the label is typeset +flush right in a box of this width. + +The left edge of the label box is +@code{\leftmargin}+@code{\itemindent}-@code{\labelsep}-@code{\labelwidth} +from the left margin of the enclosing environment. + +The default for @LaTeX{}'s @samp{article}, @samp{book}, and +@samp{report} classes at the top level is +@code{\leftmargini}-@code{\labelsep}, (which is @code{2em} in one column +mode and @code{1.5em} in two column mode). At the second level it is +@code{\leftmarginii}-@code{\labelsep}, and at the third level it is +@code{\leftmarginiii}-@code{\labelsep}. These definitions make the +label's left edge coincide with the left margin of the enclosing +environment. + +@item \leftmargin +@anchor{list leftmargin} +Horizontal space between the left margin of the enclosing environment +(or the left margin of the page if this is a top-level list), and the +left margin of this list. It must be non-negative. + +In the standard @LaTeX{} document classes, a top-level list has this set +to the value of @code{\leftmargini}, while a list that is nested inside +a top-level list has this margin set to @code{\leftmarginii}. More +deeply nested lists get the values of @code{\leftmarginiii} through +@code{\leftmarginvi}. (Nesting greater than level five generates the +error message @samp{Too deeply nested}.) + +The defaults for the first three levels in @LaTeX{}'s @samp{article}, +@samp{book}, and @samp{report} classes are: @code{\leftmargini} is +@code{2.5em} (in two column mode, @code{2em}), @code{\leftmarginii} is +@code{2.2em}, and @code{\leftmarginiii} is @code{1.87em}. + +@item \listparindent +@anchor{list listparindent} +Horizontal space of additional line indentation, beyond +@code{\leftmargin}, for second and subsequent paragraphs within a list +item. A negative value makes this an ``outdent''. Its default value +is @code{0pt}. + +@item \parsep +@anchor{list parsep} +Vertical space between paragraphs within an item. In the @samp{book} +and @samp{article} classes The defaults for the first three levels in +@LaTeX{}'s @samp{article}, @samp{book}, and @samp{report} classes at 10 +point size are: @code{4pt plus2pt minus1pt}, @code{2pt plus1pt +minus1pt}, and @code{0pt}. The defaults at 11 point size are: +@code{4.5pt plus2pt minus1pt}, @code{2pt plus1pt minus1pt}, and +@code{0pt}. The defaults at 12 point size are: @code{5pt plus2.5pt +minus1pt}, @code{2.5pt plus1pt minus1pt}, and @code{0pt}. + +@item \partopsep +@anchor{list partopsep} +Vertical space added, beyond @code{\topsep}+@code{\parskip}, to the top +and bottom of the entire environment if the list instance is preceded by +a blank line. (A blank line in the @LaTeX{} source before the list +changes spacing at both the top and bottom of the list; whether the line +following the list is blank does not matter.) + +The defaults for the first three levels in @LaTeX{}'s @samp{article}, +@samp{book}, and @samp{report} classes at 10 point size are: @code{2pt +plus1 minus1pt}, @code{2pt plus1pt minus1pt}, and @code{1pt plus0pt +minus1pt}. The defaults at 11 point are: @code{3pt plus1pt minus1pt}, +@code{3pt plus1pt minus1pt}, and @code{1pt plus0pt minus1pt}). The +defaults at 12 point are: @code{3pt plus2pt minus3pt}, @code{3pt plus2pt +minus2pt}, and @code{1pt plus0pt minus1pt}. + +@item \rightmargin +@anchor{list rightmargin} +Horizontal space between the right margin of the list and the right +margin of the enclosing environment. Its default value is @code{0pt}. +It must be non-negative. + +@item \topsep +@anchor{list topsep} +Vertical space added to both the top and bottom of the list, in addition +to @code{\parskip} (@pxref{\parindent & \parskip}). The defaults for +the first three levels in @LaTeX{}'s @samp{article}, @samp{book}, and +@samp{report} classes at 10 point size are: @code{8pt plus2pt minus4pt}, +@code{4pt plus2pt minus1pt}, and @code{2pt plus1pt minus1pt}. The +defaults at 11 point are: @code{9pt plus3pt minus5pt}, @code{4.5pt +plus2pt minus1pt}, and @code{2pt plus1pt minus1pt}. The defaults at 12 +point are: @code{10pt plus4pt minus6pt}, @code{5pt plus2.5pt minus1pt}, +and @code{2.5pt plus1pt minus1pt}. + +@end ftable + +This shows the horizontal and vertical distances. + +@float +@image{latex2e-figures/list,3.21in,,,.png} +@end float + +The lengths shown are listed below. The key relationship is that the +right edge of the bracket for @var{h1} equals the right edge of the +bracket for @var{h4}, so that the left edge of the label box is at +@var{h3}+@var{h4}-(@var{h0}+@var{h1}). + +@table @var +@item v0 +@math{@code{@\topsep} + @code{@\parskip}} if +the list environment does not start a new paragraph, and +@code{\topsep}+@code{\parskip}+@code{\partopsep} if it does + +@item v1 +@code{\parsep} + +@item v2 +@code{\itemsep}+@code{\parsep} + +@item v3 +Same as @var{v0}. (This space is affected by whether a blank line +appears in the source above the environment; whether a blank line +appears in the source below the environment does not matter.) + +@item h0 +@code{\labelwidth} + +@item h1 +@code{\labelsep} + +@item h2 +@code{\listparindent} + +@item h3 +@code{\leftmargin} + +@item h4 +@code{\itemindent} + +@item h5 +@code{\rightmargin} + +@end table + +The list's left and right margins, shown above as @var{h3} and @var{h5}, +are with respect to the ones provided by the surrounding environment, or +with respect to the page margins for a top-level list. The line width +used for typesetting the list items is @code{\linewidth} (@pxref{Page +layout parameters}). For instance, set the list's left margin to be one +quarter of the distance between the left and right margins of the +enclosing environment with +@code{\setlength@{\leftmargin@}@{0.25\linewidth@}}. + +Page breaking in a list structure is controlled by the three +parameters below. For each, the @LaTeX{} default is +@code{-\@@lowpenalty}, that is, @code{-51}. Because it is negative, +it somewhat encourages a page break at each spot. Change it with, +e.g., @code{\@@beginparpenalty=9999}; a value of 10000 prohibits a +page break. + +@ftable @code +@item \@@beginparpenalty +@anchor{list beginparpenalty} +The page breaking penalty for breaking before the list (default @code{-51}). + +@item \@@itempenalty +@anchor{list itempenalty} +The page breaking penalty for breaking before a list item (default @code{-51}). + +@item \@@endparpenalty +@anchor{list endparpenalty} +The page breaking penalty for breaking after a list (default @code{-51}). + +@end ftable + +@PkgIndex{enumitem} +The package @code{enumitem} is useful for customizing lists. + +This example has the labels in red. They are numbered, and the left +edge of the label lines up with the left edge of the item text. +@xref{\usecounter}. + +@example +\usepackage@{color@} +\newcounter@{cnt@} +\newcommand@{\makeredlabel@}[1]@{\textcolor@{red@}@{#1.@}@} +\newenvironment@{redlabel@} + @{\begin@{list@} + @{\arabic@{cnt@}@} + @{\usecounter@{cnt@} + \setlength@{\labelwidth@}@{0em@} + \setlength@{\labelsep@}@{0.5em@} + \setlength@{\leftmargin@}@{1.5em@} + \setlength@{\itemindent@}@{0.5em@} % equals \labelwidth+\labelsep + \let\makelabel=\makeredlabel + @} + @} +@{\end@{list@} @} +@end example + +@menu +* \item:: An entry in a list. +* trivlist:: A restricted form of @code{list}. +@end menu + + +@node \item +@subsection @code{\item}: An entry in a list + +Synopsis: + +@example +\item text of item +@end example + +@noindent +or + +@example +\item[@var{optional-label}] text of item +@end example + +An entry in a list. The entries are prefixed by a label, whose default +depends on the list type. + +Because the optional label is surrounded by square brackets +@samp{[...]}, if you have an item whose text starts with @samp{[}, you +have to hide the bracket inside curly braces, as in: @code{\item +@{[@} is an open square bracket}; otherwise, @LaTeX{} will think it +marks the start of an optional label. + +Similarly, if the item does have the optional label and you need a +close square bracket inside that label, you must hide it in the same +way: @code{\item[Close square bracket, @{]@}]}. @xref{@LaTeX{} +command syntax}. + +In this example the enumerate list has two items that use the default +label and one that uses the optional label. + +@example +\begin@{enumerate@} + \item Moe + \item[sometimes] Shemp + \item Larry +\end@{enumerate@} +@end example + +The first item is labelled @samp{1.}, the second item is labelled +@samp{sometimes}, and the third item is labelled @samp{2.}. Because +of the optional label in the second item, the third item is not +labelled@tie{}@samp{3.}. + + +@node trivlist +@subsection @code{trivlist}: A restricted form of @code{list} + +Synopsis: + +@example +\begin@{trivlist@} + ... +\end@{trivlist@} +@end example + +A restricted version of the list environment, in which margins are not +indented and an @code{\item} without an optional argument produces no +text. It is most often used in macros, to define an environment where +the @code{\item} command as part of the environment's definition. For +instance, the @code{center} environment is defined essentially like +this: + +@example +\newenvironment@{center@} + @{\begin@{trivlist@}\centering\item\relax@} + @{\end@{trivlist@}@} +@end example + +Using @code{trivlist} in this way allows the macro to inherit some +common code: combining vertical space of two adjacent environments; +detecting whether the text following the environment should be +considered a new paragraph or a continuation of the previous one; +adjusting the left and right margins for possible nested list +environments. + +Specifically, @code{trivlist} uses the current values of the list +parameters (@pxref{list}), except that @code{\parsep} is set to the +value of @code{\parskip}, and @code{\leftmargin}, @code{\labelwidth}, +and @code{\itemindent} are set to zero. + +This example outputs the items as two paragraphs, except that (by +default) they have no paragraph indent and are vertically separated. + +@example +\begin@{trivlist@} +\item The \textit@{Surprise@} is not old; no one would call her old. +\item She has a bluff bow, lovely lines. +\end@{trivlist@} +@end example + + +@node math +@section @code{math} + +@EnvIndex{math} +@cindex in-line formulas + +Synopsis: + +@example +\begin@{math@} +@var{math} +\end@{math@} +@end example + +The @code{math} environment inserts given @var{math} material within +the running text. @code{\(...\)} and @code{$...$} are synonyms. +@xref{Math formulas}. + + +@node minipage +@section @code{minipage} + +@EnvIndex{minipage} +@cindex minipage, creating a + +Synopses: + +@example +\begin@{minipage@}@{@var{width}@} + @var{contents} +\end@{minipage@} +@end example + +@noindent +or + +@example +\begin@{minipage@}[@var{position}][@var{height}][@var{inner-pos}]@{@var{width}@} + @var{contents} +\end@{minipage@} +@end example + +Put @var{contents} into a box that is @var{width} wide. This is like a +small version of a page; it can contain its own footnotes, itemized +lists, etc. (There are some restrictions, including that it cannot have +floats.) This box will not be broken across pages. So @code{minipage} +is similar to @code{\parbox} (@pxref{\parbox}) but here you can have +paragraphs. + +This example will be 3@tie{}inches wide, and has two paragraphs. + +@example +\begin@{minipage@}@{3in@} + Stephen Kleene was a founder of the Theory of Computation. + + He was a student of Church, wrote three influential texts, + was President of the Association for Symbolic Logic, + and won the National Medal of Science. +\end@{minipage@} +@end example + +@noindent +See below for a discussion of the paragraph indent inside a +@code{minipage}. + +The required argument @var{width} is a rigid length (@pxref{Lengths}). +It gives the width of the box into which @var{contents} are typeset. + +There are three optional arguments, @var{position}, @var{height}, and +@var{inner-pos}. You need not include all three. For example, get the +default @var{position} and set the @var{height} with +@code{\begin@{minipage@}[c][2.54cm] @var{contents} \end@{minipage@}}. +(Get the natural height with an empty argument, @code{[]}.) + +The optional argument @var{position} governs how the @code{minipage} +vertically aligns with the surrounding material. + +@table @code +@item c +(synonym @code{m}) Default. Positions the @code{minipage} so its +vertical center lines up with the center of the adjacent text line (what +Plain @TeX{} calls @code{\vcenter}). + +@item t +Match the top line in the @code{minipage} with the baseline of the +surrounding text (Plain @TeX{}'s @code{\vtop}. + +@item b +Match the bottom line in the @code{minipage} with the baseline of the +surrounding text (Plain @TeX{}'s @code{\vbox}. +@end table + +To see the effects of these, contrast running this + +@example +---\begin@{minipage@}[c]@{0.25in@} + first\\ second\\ third +\end@{minipage@} +@end example + +@noindent +with the results of changing @code{c} to @code{b} or@tie{}@code{t}. + +The optional argument @var{height} is a rigid length (@pxref{Lengths}). +It sets the height of the @code{minipage}. You can enter any value +larger than, or equal to, or smaller than the @code{minipage}'s natural +height and @LaTeX{} will not give an error or warning. You can also set +it to a height of zero or a negative value. + +The final optional argument @var{inner-pos} controls the placement of +@var{content} inside the box. These are the possible values are (the +default is the value of @var{position}). + +@table @code +@item t +Place @var{content} at the top of the box. + +@item c +Place it in the vertical center. + +@item b +Place it at the box bottom. + +@item s +Stretch @var{contents} out vertically; it must contain vertically +stretchable space. + +@end table + +The @var{inner-pos} argument makes sense when the @var{height} option +is set to a value larger than the @code{minipage}'s natural height. To +see the effect of the options, run this example with the various choices +in place of @code{b}. + +@example +Text before +\begin@{center@} + ---\begin@{minipage@}[c][3in][b]@{0.25\textwidth@} + first\\ second\\ third + \end@{minipage@} +\end@{center@} +Text after +@end example + +@cindex indentation of paragraphs, in minipage +@cindex paragraph indentation, in minipage +@findex \parindent +By default paragraphs are not indented in a @code{minipage}. Change +that with a command such as @code{\setlength@{\parindent@}@{1pc@}} at +the start of @var{contents}. + +@cindex footnotes in figures +@cindex figures, footnotes in +Footnotes in a @code{minipage} environment are handled in a way that is +particularly useful for putting footnotes in figures or tables. A +@code{\footnote} or @code{\footnotetext} command puts the footnote at +the bottom of the minipage instead of at the bottom of the page, and it +uses the @code{\mpfootnote} counter instead of the ordinary +@code{footnote} counter (@pxref{Counters}). + +This puts the footnote at the bottom of the table, not the bottom of the +page. + +@example +\begin@{center@} % center the minipage on the line +\begin@{minipage@}@{2.5in@} + \begin@{center@} % center the table inside the minipage + \begin@{tabular@}@{ll@} + \textsc@{Monarch@} &\textsc@{Reign@} \\ \hline + Elizabeth II &63 years\footnote@{to date@} \\ + Victoria &63 years \\ + George III &59 years + \end@{tabular@} + \end@{center@} +\end@{minipage@} +\end@{center@} +@end example + +If you nest minipages then there is an oddness when using footnotes. +Footnotes appear at the bottom of the text ended by the next +@code{\end@{minipage@}} which may not be their logical place. + +This puts a table containing data side by side with a map graphic. They +are vertically centered. + +@example +\newcommand*@{\vcenteredhbox@}[1]@{\begin@{tabular@}@{@@@{@}c@@@{@}@}#1\end@{tabular@}@} + ... +\begin@{center@} + \vcenteredhbox@{\includegraphics[width=0.3\textwidth]@{nyc.png@}@} + \hspace@{0.1\textwidth@} + \begin@{minipage@}@{0.5\textwidth@} + \begin@{tabular@}@{r|l@} + \multicolumn@{1@}@{r@}@{Borough@} &Pop (million) \\ \hline + The Bronx &$1.5$ \\ + Brooklyn &$2.6$ \\ + Manhattan &$1.6$ \\ + Queens &$2.3$ \\ + Staten Island &$0.5$ + \end@{tabular@} + \end@{minipage@} +\end@{center@} +@end example + + +@node picture +@section @code{picture} + +@EnvIndex{picture} +@cindex creating pictures +@cindex pictures, creating + +Synopses: +@example +\begin@{picture@}(@var{width},@var{height}) + @var{picture commands} +\end@{picture@} +@end example + +@noindent +or + +@example +\begin@{picture@}(@var{width},@var{height})(@var{xoffset},@var{yoffset}) + @var{picture commands} +\end@{picture@} +@end example + +An environment to create simple pictures containing lines, arrows, +boxes, circles, and text. Note that while this environment is not +obsolete, new documents typically use much more powerful graphics +creation systems, such as @code{TikZ}, @code{PSTricks}, @code{MetaPost}, +or @code{Asymptote}. These are not covered in this document; see CTAN. + +This shows the parallelogram law for adding vectors. + +@findex \unitlength +@example +\setlength@{\unitlength@}@{1cm@} +\begin@{picture@}(6,6) % picture box will be 6cm wide by 6cm tall + \put(0,0)@{\vector(2,1)@{4@}@} % for every 2 over this vector goes 1 up + \put(2,1)@{\makebox(0,0)[l]@{\ first leg@}@} + \put(4,2)@{\vector(1,2)@{2@}@} + \put(5,4)@{\makebox(0,0)[l]@{\ second leg@}@} + \put(0,0)@{\line(1,1)@{6@}@} + \put(3,3)@{\makebox(0,0)[r]@{sum\ @}@} +\end@{picture@} +@end example + +You can also use this environment to place arbitrary material at an +exact location. + +@example +\usepackage@{color,graphicx@} % in preamble + ... +\begin@{center@} +\setlength@{\unitlength@}@{\textwidth@} +\begin@{picture@}(1,1) % leave space, \textwidth wide and tall + \put(0,0)@{\includegraphics[width=\textwidth]@{desertedisland.jpg@}@} + \put(0.25,0.35)@{\textcolor@{red@}@{X Treasure here@}@} +\end@{picture@} +\end@{center@} +@end example + +@noindent +The red@tie{}X will be precisely a quarter of the @code{\linewidth} from +the left margin, and @code{0.35\linewidth} up from the bottom. Another +example of this usage is to put similar code in the page header to get +repeat material on each of a document's pages. + +The @code{picture} environment has one required argument, a pair of +numbers (@var{width},@var{height}). Multiply these by the value +@code{\unitlength} to get the nominal size of the output, the space that +@LaTeX{} reserves on the output page. This nominal size need not be how +large the picture really is; @LaTeX{} will draw things from the picture +outside the picture's box. + +This environment also has an optional argument +(@var{xoffset},@var{yoffset}). It is used to shift the origin. Unlike +most optional arguments, this one is not contained in square brackets. +As with the required argument, it consists of two real numbers. +Multiply these by @code{\unitlength} to get the point at the lower-left +corner of the picture. + +For example, if @code{\unitlength} has been set to @code{1mm}, the +command + +@example +\begin@{picture@}(100,200)(10,20) +@end example + +@noindent +produces a box of width 100 millimeters and height 200 millimeters. The +picture's origin is the point (10mm,20mm) and so the lower-left corner +is there, and the upper-right corner is at (110mm,220mm). When you +first draw a picture you typically omit the optional argument, leaving +the origin at the lower-left corner. If you then want to modify your +picture by shifting everything, you can just add the appropriate +optional argument. + +@cindex position, in picture +Each @var{picture command} tells @LaTeX{} where to put something by +naming its position. A @dfn{position} is a pair such as @code{(2.4,-5)} +giving the x- and y-coordinates. A @dfn{coordinate} is a not a length, +it is a real number (it may have a decimal point or a minus sign). It +specifies a length in multiples of the unit length @code{\unitlength}, +so if @code{\unitlength} has been set to @code{1cm}, then the coordinate +2.54 specifies a length of 2.54 centimeters. + +@LaTeX{}'s default for @code{\unitlength} is @code{1pt}. it is a rigid +length (@pxref{Lengths}). Change it with the @code{\setlength} command +(@pxref{\setlength}). Make this change only outside of a @code{picture} +environment. + +Coordinates are given with respect to an origin, which is normally at +the lower-left corner of the picture. Note that when a position appears +as an argument, as with @code{\put(1,2)@{...@}}, it is not enclosed in +braces since the parentheses serve to delimit the argument. Also, +unlike in some computer graphics systems, larger y-coordinates are +further up the page. + +There are four ways to put things in a picture: @code{\put}, +@code{\multiput}, @code{\qbezier}, and @code{\graphpaper}. The most +often used is @code{\put}. This + +@example +\put(11.3,-0.3)@{...@} +@end example + +@noindent +places the object with its reference point at coordinates +@math{(11.3,-0.3)}. The reference points for various objects will be +described below. +@findex LR box +The @code{\put} command creates an @dfn{LR box} (@pxref{Modes}). +Anything that can go in an @code{\mbox} (@pxref{\mbox & \makebox}) can +go in the text argument of the @code{\put} command. The reference point +will be the lower left corner of the box. In this picture + +@example +\setlength@{\unitlength@}@{1cm@} +...\begin@{picture@}(1,1) + \put(0,0)@{\line(1,0)@{1@}@} + \put(0,0)@{\line(1,1)@{1@}@} +\end@{picture@} +@end example + +@noindent +the three dots are just slightly left of the point of the angle formed +by the two lines. (Also, @code{\line(1,1)@{1@}} does not call for a +line of length one; rather the line has a change in the x coordinate of +1.) + +The @code{\multiput}, @code{qbezier}, and @code{graphpaper} commands are +described below. + +This draws a rectangle with a wavy top, using @code{\qbezier} for +that curve. + +@example +\begin@{picture@}(3,1.5) + \put(0,0)@{\vector(1,0)@{8@}@} % x axis + \put(0,0)@{\vector(0,1)@{4@}@} % y axis + \put(2,0)@{\line(0,1)@{3@}@} % left side rectangle + \put(4,0)@{\line(0,1)@{3.5@}@} % right side + \qbezier(2,3)(2.5,2.9)(3,3.25) + \qbezier(3,3.25)(3.5,3.6)(4,3.5) + \thicklines % below here, lines are twice as thick + \put(2,3)@{\line(4,1)@{2@}@} + \put(4.5,2.5)@{\framebox@{Trapezoidal Rule@}@} +\end@{picture@} +@end example + +@menu +* \put:: Place an object at a specified place. +* \multiput:: Draw multiple instances of an object. +* \qbezier:: Draw a quadratic Bezier curve. +* \graphpaper:: Draw graph paper. +* \line:: Draw a straight line. +* \linethickness:: Set thickness of horizontal and vertical lines. +* \thinlines:: The default line thickness. +* \thicklines:: A heavier line thickness. +* \circle:: Draw a circle. +* \oval:: Draw an oval. +* \shortstack:: Make a stack of objects. +* \vector:: Draw a line with an arrow. +* \makebox (picture):: Draw a box of the specified size. +* \framebox (picture):: Draw a box with a frame around it. +* \frame:: Draw a frame around an object. +* \dashbox:: Draw a dashed box. +@end menu + + +@node \put +@subsection @code{\put} + +@findex \put + +Synopsis: + +@example +\put(@var{xcoord},@var{ycoord})@{@var{content}@} +@end example + +Place @var{content} at the coordinate (@var{xcoord},@var{ycoord}). See +the discussion of coordinates and @code{\unitlength} in @ref{picture}. +The @var{content} is processed in LR mode (@pxref{Modes}) so it cannot +contain line breaks. + +This includes the text into the @code{picture}. + +@example +\put(4.5,2.5)@{Apply the \textit@{unpoke@} move@} +@end example + +The reference point, the location (4.5,2.5), is the lower left of the +text, at the bottom left of the @samp{A}. + + +@node \multiput +@subsection @code{\multiput} + +@findex \multiput + +Synopsis: + +@example +\multiput(@var{x},@var{y})(@var{delta_x},@var{delta_y})@{@var{num-copies}@}@{@var{obj}@} +@end example + +Copy @var{obj} a total of @var{num-copies} times, with an increment of +@var{delta_x,delta_y}. The @var{obj} first appears at position +@math{(x,y)}, then at @math{(x+\delta_x,y+\delta_y)}, and so on. + +This draws a simple grid with every fifth line in bold (see also +@ref{\graphpaper}). + +@example +\begin@{picture@}(10,10) + \linethickness@{0.05mm@} + \multiput(0,0)(1,0)@{10@}@{\line(0,1)@{10@}@} + \multiput(0,0)(0,1)@{10@}@{\line(1,0)@{10@}@} + \linethickness@{0.5mm@} + \multiput(0,0)(5,0)@{3@}@{\line(0,1)@{10@}@} + \multiput(0,0)(0,5)@{3@}@{\line(1,0)@{10@}@} +\end@{picture@} +@end example + + +@node \qbezier +@subsection @code{\qbezier} + +@findex \qbezier + +Synopsis: + +@example +\qbezier(@var{x1},@var{y1})(@var{x2},@var{y2})(@var{x3},@var{y3}) +\qbezier[@var{num}](@var{x1},@var{y1})(@var{x2},@var{y2})(@var{x3},@var{y3}) +@end example + +Draw a quadratic Bezier curve whose control points are given by the +three required arguments @code{(@var{x1},@var{y1})}, +@code{(@var{x2},@var{y2})}, and @code{(@var{x3},@var{y3})}. That is, +the curve runs from @var{(x1,y1)} to @var{(x3,y3)}, is quadratic, and is +such that the tangent line at @var{(x1,y1)} passes through +@var{(x2,y2)}, as does the tangent line at @var{(x3,y3)}. + +This draws a curve from the coordinate (1,1) to (1,0). + +@example +\qbezier(1,1)(1.25,0.75)(1,0) +@end example + +@noindent +The curve's tangent line at (1,1) contains (1.25,0.75), as does the +curve's tangent line at (1,0). + +The optional argument @var{num} gives the number of calculated +intermediate points. The default is to draw a smooth curve whose +maximum number of points is @code{\qbeziermax} (change this value with +@code{\renewcommand}). + + +@node \graphpaper +@subsection @code{\graphpaper} + +@findex \graphpaper +Synopsis: + +@example +\graphpaper(@var{x_init},@var{y_init})(@var{x_dimen},@var{y_dimen}) +\graphpaper[@var{spacing}](@var{x_init},@var{y_init})(@var{x_dimen},@var{y_dimen}) +@end example + +Draw a coordinate grid. Requires the @code{graphpap} package. +The grid's origin is @code{(@var{x_init},@var{y_init})}. +Grid lines come every @var{spacing} units (the default is 10). +The grid extends @var{x_dimen} units to the right and @var{y_dimen} units up. +All arguments must be positive integers. + +This make a grid with seven vertical lines and eleven horizontal lines. + +@example +\usepackage@{graphpap@} % in preamble + ... +\begin@{picture@}(6,20) % in document body + \graphpaper[2](0,0)(12,20) +\end@{picture@} +@end example + +@noindent +The lines are numbered every ten units. + + +@node \line +@subsection @code{\line} + +@findex \line + +Synopsis: + +@example +\line(@var{x_run},@var{y_rise})@{@var{travel}@} +@end example + +Draw a line. It slopes such that it vertically rises @var{y_rise} for +every horizontal @var{x_run}. The @var{travel} is the total horizontal +change@tie{}--- it is not the length of the vector, it is the change in +@math{x}. In the special case of vertical lines, where +(@var{x_run},@var{y_rise})=(0,1), the @var{travel} gives the change in +@math{y}. + +This draws a line starting at coordinates (1,3). + +@example +\put(1,3)@{\line(2,5)@{4@}@} +@end example + +@noindent +For every over 2, this line will go up 5. Because @var{travel} +specifies that this goes over 4, it must go up@tie{}10. Thus its +endpoint is @math{(1,3)+(4,10)=(5,13)}. In particular, note that +@math{@var{travel}=4} is not the length of the line, it is the change in +@math{x}. + +The arguments @var{x_run} and @var{y_rise} are integers that can be +positive, negative, or zero. (If both are 0 then @LaTeX{} treats the +second as 1.) With +@code{\put(@var{x_init},@var{y_init})@{\line(@var{x_run},@var{y_rise})@{@var{travel}@}@}}, +if @var{x_run} is negative then the line's ending point has a first +coordinate that is less than @var{x_init}. If @var{y_rise} is negative +then the line's ending point has a second coordinate that is less than +@var{y_init}. + +If @var{travel} is negative then you get @code{LaTeX Error: Bad \line or +\vector argument.} + +@cindex @code{pict2e} package +@cindex graphics packages +@PkgIndex{pict2e} +@PkgIndex{TikZ} +@PkgIndex{PSTricks} +@PkgIndex{MetaPost} +@PkgIndex{Asymptote} +Standard @LaTeX{} can only draw lines with a limited range of slopes +because these lines are made by putting together line segments from +pre-made fonts. The two numbers @var{x_run} and @var{y_rise} must have +integer values from @minus{}6 through@tie{}6. Also, they must be +relatively prime, so that @var{(x_run,y_rise)} can be (2,1) but not +(4,2) (if you choose the latter then instead of lines you get sequences +of arrowheads; the solution is to switch to the former). To get lines +of arbitrary slope and plenty of other shapes in a system like +@code{picture}, see the package @file{pict2e} on CTAN. Another solution +is to use a full-featured graphics system such as @file{TikZ}, or +@file{PSTricks}, or @file{MetaPost}, or @file{Asymptote} + + +@node \linethickness +@subsection @code{\linethickness} + +@findex \linethickness + +Synopsis: + +@example +\linethickness@{@var{dim}@} +@end example + +Declares the thickness of subsequent horizontal and vertical lines in a +picture to be @var{dim}, which must be a positive length +(@pxref{Lengths}). It differs from @code{\thinlines} and +@code{\thicklines} in that it does not affect the thickness of slanted +lines, circles, or ovals. + + +@node \thinlines +@subsection @code{\thinlines} + +@findex \thinlines + +Declaration to set the thickness of subsequent lines, circles, and ovals +in a picture environment to be 0.4@dmn{pt}. This is the default +thickness, so this command is unnecessary unless the thickness has been +changed with either @ref{\linethickness} or @ref{\thicklines}. + + +@node \thicklines +@subsection @code{\thicklines} + +@findex \thicklines + +Declaration to set the thickness of subsequent lines, circles, and ovals +in a picture environment to be 0.8@dmn{pt}. See also +@ref{\linethickness} and @ref{\thinlines}. This command is illustrated +in the Trapezoidal Rule example of @ref{picture}. + + +@node \circle +@subsection @code{\circle} + +@findex \circle + +Synopsis: + +@example +\circle@{@var{diameter}@} +\circle*@{@var{diameter}@} +@end example + +Produces a circle with a diameter as close as possible to the specified +one. The @code{*}@tie{}form produces a filled-in circle. + +This draws a circle of radius 6, centered at @code{(5,7)}. + +@example +\put(5,7)@{\circle@{6@}@} +@end example + +The available radii for @code{circle} are, in points, the even +numbers from 2 to 20, inclusive. For @code{circle*} they are all the +integers from 1 to 15. + + +@node \oval +@subsection @code{\oval} + +@findex \oval + +Synopsis: + +@example +\oval(@var{width},@var{height}) +\oval(@var{width},@var{height})[@var{portion}] +@end example + +Produce a rectangle with rounded corners. The optional argument +@var{portion} allows you to produce only half or a quarter of the oval. +For half an oval take @var{portion} to be one of these. + +@table @code +@item t +top half +@item b +bottom half +@item r +right half +@item l +left half +@end table + +Produce only one quarter of the oval by setting @var{portion} to +@code{tr}, @code{br}, @code{bl}, or @code{tl}. + +This draws the top half of an oval that is 3 wide and 7 tall. + +@example +\put(5,7)@{\oval(3,7)[t]@} +@end example + +@noindent +The (5,7) is the center of the entire oval, not just the center of the +top half. + +These shapes are not ellipses. They are rectangles whose corners are +made with quarter circles. These circles have a maximum radius of +20@dmn{pt} (@pxref{\circle} for the sizes). Thus large ovals are just +boxes with a small amount of corner rounding. + + +@node \shortstack +@subsection @code{\shortstack} + +@findex \shortstack + +Synopsis: + +@example +\shortstack[@var{position}]@{@var{line 1} \\ ... @} +@end example + +Produce a vertical stack of objects. + +This labels the @math{y} axis. + +@example +\put(0,0)@{\vector(1,0)@{4@}@} % x axis +\put(0,0)@{\vector(0,1)@{2@}@} % y +\put(-0.25,2)@{\makebox[0][r]@{\shortstack[r]@{$y$\\ axis@}@}@} +@end example + +@noindent +For a short stack, the reference point is the lower left of the stack. +In the above example the @ref{\mbox & \makebox} puts the stack flush +right in a zero width box so in total the short stack sits slightly to +the left of the @math{y}@tie{}axis. + +The valid positions are: + +@table @code +@item r +Make objects flush right +@item l +Make objects flush left +@item c +Center objects (default) +@end table + +@findex \\ @r{(for @code{\shortstack} objects)} +Separate objects into lines with @code{\\}. These stacks are short in +that, unlike in a @code{tabular} or @code{array} environment, here the +rows are not spaced out to be of even heights. Thus, in +@code{\shortstack@{X\\o\\o\\X@}} the first and last rows are taller than +the middle two. You can adjust row heights either by putting in the +usual interline spacing with @code{\shortstack@{X\\ \strut o\\o\\X@}}, +or by hand, via an explicit zero-width box @code{\shortstack@{X \\ +\rule@{0pt@}@{12pt@} o\\o\\X@}} or by using @code{\\}'s optional +argument @code{\shortstack@{X\\[2pt] o\\o\\X@}}. + +The @code{\shortstack} command is also available outside the +@code{picture} environment. + + +@node \vector +@subsection @code{\vector} + +@findex \vector + +Synopsis: + +@example +\vector(@var{x_run},@var{y_rise})@{@var{travel}@} +@end example + +Draw a line ending in an arrow. The slope of that line is: it +vertically rises @var{y_rise} for every horizontal @var{x_run}. The +@var{travel} is the total horizontal change@tie{}--- it is not the +length of the vector, it is the change in @math{x}. In the special case +of vertical vectors, if (@var{x_run},@var{y_rise})=(0,1), then +@var{travel} gives the change in @math{y}. + +For an example see @ref{picture}. + +For elaboration on @var{x_run} and @var{y_rise} see @ref{\line}. As +there, the values of @var{x_run} and @var{y_rise} are limited. For +@code{\vector} you must chooses integers between @minus{}4 and 4, +inclusive. Also, the two you choose must be relatively prime. Thus, +@code{\vector(2,1)@{4@}} is acceptable but @code{\vector(4,2)@{4@}} is +not (if you use the latter then you get a sequence of arrowheads). + + +@node \makebox (picture) +@subsection @code{\makebox} (picture) + +@findex \makebox @r{(for @code{picture})} + +Synopsis: + +@example +\makebox(@var{rec-width},@var{rec-height})@{@var{text}@} +\makebox(@var{rec-width},@var{rec-height})[@var{position}]@{@var{text}@} +@end example + +Make a box to hold @var{text}. This command fits with the +@code{picture} environment, although you can use it outside of there, +because @var{rec-width} and @var{rec-height} are numbers specifying +distances in terms of the @code{\unitlength} (@pxref{picture}). This +command is similar to the normal @code{\makebox} command (@pxref{\mbox & +\makebox}) except here that you must specify the width and height. This +command is fragile (@pxref{\protect}). + +This makes a box of length 3.5 times @code{\unitlength} and height 4 +times @code{\unitlength}. + +@example +\put(1,2)@{\makebox(3.5,4)@{...@}@} +@end example + +The optional argument @code{@var{position}} specifies where in the box +the @var{text} appears. The default is to center it, both horizontally +and vertically. To place it somewhere else, use a string with one or +two of these letters. + +@table @code +@item t +Puts @var{text} the top of the box. + +@item b +Put @var{text} at the bottom. + +@item l +Put @var{text} on the left. + +@item r +Put @var{text} on the right. + +@end table + + +@node \framebox (picture) +@subsection @code{\framebox} (picture) + +@findex \framebox + +Synopsis: + +@example +\framebox(@var{rec-width},@var{rec-height})@{@var{text}@} +\framebox(@var{rec-width},@var{rec-height})[@var{position}]@{@var{text}@} +@end example + +This is the same as @ref{\makebox (picture)} except that it puts a frame +around the outside of the box that it creates. The reference point is +the bottom left corner of the frame. This command fits with the +@code{picture} environment, although you can use it outside of there, +because lengths are numbers specifying the distance in terms of the +@code{\unitlength} (@pxref{picture}). This command is fragile +(@pxref{\protect}). + +This example creates a frame 2.5@tie{}inches by 3@tie{}inches and puts +the text in the center. + +@example +\setlength@{\unitlength@}@{1in@} +\framebox(2.5,3)@{test text@} +@end example + +The required arguments are that the rectangle has overall width +@var{rect-width} units and height @var{rect-height} units. + +The optional argument @var{position} specifies the position of +@var{text}; see @ref{\makebox (picture)} for the values that it can +take. + +@findex \fboxrule +@findex \fboxsep +The rule has thickness @code{\fboxrule} and there is a blank space +@code{\fboxsep} between the frame and the contents of the box. + +For this command, you must specify the @var{width} and @var{height}. If +you want to just put a frame around some contents whose dimension is +determined in some other way then either use @code{\fbox} (@pxref{\fbox +& \framebox}) or @code{\frame} (@pxref{\frame}). + + +@node \frame +@subsection @code{\frame} + +@findex \frame + +Synopsis: + +@example +\frame@{@var{contents}@} +@end example + +Puts a rectangular frame around @var{contents}. The reference point is +the bottom left corner of the frame. In contrast to @code{\framebox} +(@pxref{\framebox (picture)}), this command puts no extra space is put +between the frame and the object. It is fragile (@pxref{\protect}). + + +@node \dashbox +@subsection @code{\dashbox} + +@findex \dashbox + +Synopsis: + +@example +\dashbox@{@var{dash-len}@}(@var{rect-width},@var{rect-height})@{@var{text}@} +\dashbox@{@var{dash-len}@}(@var{rect-width},@var{rect-height})[@var{position}]@{@var{text}@} +@end example + +Create a dashed rectangle around @var{text}. This command fits with the +@code{picture} environment, although you can use it outside of there, +because lengths are numbers specifying the distance in terms of the +@code{\unitlength} (@pxref{picture}). + +The required arguments are: dashes are @var{dash-len} units long, with +the same length gap, and the rectangle has overall width +@var{rect-width} units and height @var{rect-height} units. + +The optional argument @var{position} specifies the position of +@var{text}; see @ref{\makebox (picture)} for the values that it can +take. + +This shows that you can use non-integer value for @var{dash-len}. + +@example +\put(0,0)@{\dashbox@{0.1@}(5,0.5)@{My hovercraft is full of eels.@}@} +@end example + +@noindent +Each dash will be @code{0.1\unitlength} long, the box's width is +@code{5\unitlength} and its height is @code{0.5\unitlength}. + +As in that example, a dashed box looks best when @var{rect-width} and +@var{rect-height} are multiples of the @var{dash-len}. + + +@node quotation & quote +@section @code{quotation} & @code{quote} + +@EnvIndex{quotation} +@cindex quoted text with paragraph indentation, displaying +@cindex displaying quoted text with paragraph indentation +@cindex paragraph indentations in quoted text +@EnvIndex{quote} +@cindex quoted text without paragraph indentation, displaying +@cindex displaying quoted text without paragraph indentation +@cindex paragraph indentations in quoted text, omitting + +Synopsis: + +@example +\begin@{quotation@} + @var{text} +\end@{quotation@} +@end example + +@noindent +or + +@example +\begin@{quote@} + @var{text} +\end@{quote@} +@end example + +Include a quotation. Both environments indent margins on both sides by +@code{\leftmargin} and the text is right-justified. + +They differ in how they treat paragraphs. In the @code{quotation} +environment, paragraphs are indented by 1.5@dmn{em} and the space +between paragraphs is small, @code{0pt plus 1pt}. In the @code{quote} +environment, paragraphs are not indented and there is vertical space +between paragraphs (it is the rubber length @code{\parsep}). + +@example +\begin@{quotation@} \small\it + Four score and seven years ago + ... shall not perish from the earth. + \hspace@{1em plus 1fill@}---Abraham Lincoln +\end@{quotation@} +@end example + + +@node tabbing +@section @code{tabbing} + +@EnvIndex{tabbing} +@cindex tab stops, using +@cindex lining text up using tab stops +@cindex alignment via tabbing + +Synopsis: + +@example +\begin@{tabbing@} +@var{row1col1} \= @var{row1col2} ... \\ +@var{row2col1} \> @var{row2col2} ... \\ +... +\end@{tabbing@} +@end example + +Align text in columns, by setting tab stops and tabbing to them much as +was done on a typewriter. This is less often used than the environments +@code{tabular} (@pxref{tabular}) or @code{array} (@pxref{array}) because +in those the width of each column need not be constant and need not be +known in advance. + +This example has a first line where the tab stops are set to explicit +widths, ended by a @code{\kill} command (which is described below): + +@example +\begin@{tabbing@} +\hspace@{0.75in@} \= \hspace@{0.40in@} \= \hspace@{0.40in@} \kill +Ship \> Guns \> Year \\ +\textit@{Sophie@} \> 14 \> 1800 \\ +\textit@{Polychrest@} \> 24 \> 1803 \\ +\textit@{Lively@} \> 38 \> 1804 \\ +\textit@{Surprise@} \> 28 \> 1805 \\ +\end@{tabbing@} +@end example + +Both the @code{tabbing} environment and the more widely-used +@code{tabular} environment put text in columns. The most important +distinction is that in @code{tabular} the width of columns is +determined automatically by @LaTeX{}, while in @code{tabbing} the user +sets the tab stops. Another distinction is that @code{tabular} +generates a box, but @code{tabbing} can be broken across pages. +Finally, while @code{tabular} can be used in any mode, @code{tabbing} +can be used only in paragraph mode and it starts a new paragraph. + +A @code{tabbing} environment always starts a new paragraph, without +indentation. Moreover, as shown in the example above, there is no need +to use the starred form of the @code{\hspace} command at the beginning +of a tabbed row. The right margin of the @code{tabbing} environment is +the end of line, so that the width of the environment is +@code{\linewidth}. + +@cindex row, @r{tabbing} +The @code{tabbing} environment contains a sequence of @dfn{tabbed +rows}. The first tabbed row begins immediately after +@code{\begin@{tabbing@}} and each row ends with @code{\\} or +@code{\kill}. The last row may omit the @code{\\} and end with just +@code{\end@{tabbing@}}. + +At any point the @code{tabbing} environment has a current tab stop +pattern, a sequence of @math{@var{n} > 0} tab stops, numbered 0, 1, +etc. These create @var{n} corresponding columns. Tab stop@tie{}0 is +always the left margin, defined by the enclosing environment. Tab +stop number@tie{}@var{i} is set if it is assigned a horizontal +position on the page. Tab stop number@tie{}@var{i} can only be set if +all the stops 0, @dots{}, @math{i-1} have already been set; normally +later stops are to the right of earlier ones. + +By default any text typeset in a @code{tabbing} environment is typeset +ragged right and left-aligned on the current tab stop. Typesetting is +done in LR mode (@pxref{Modes}). + +The following commands can be used inside a @code{tabbing} environment. +They are all fragile (@pxref{\protect}). + +@ftable @code +@item \\ @r{(tabbing)} +End a tabbed line and typeset it. + +@item \= @r{(tabbing)} +Sets a tab stop at the current position. + +@item \> @r{(tabbing)} +@findex \> +Advances to the next tab stop. + +@item \< +Put following text to the left of the local margin (without changing +the margin). Can only be used at the start of the line. + +@item \+ +Moves the left margin of the next and all the +following commands one tab stop to the right, beginning tabbed line if +necessary. + +@item \- +Moves the left margin of the next and all the +following commands one tab stop to the left, beginning tabbed line if +necessary. + +@item \' @r{(tabbing)} +Moves everything that you have typed so far in the current column, i.e., +everything from the most recent @code{\>}, @code{\<}, @code{\'}, +@code{\\}, or @code{\kill} command, to the previous column and aligned +to the right, flush against the current column's tab stop. + +@item \` @r{(tabbing)} +Allows you to put text flush right against any tab stop, including tab +stop@tie{}0. However, it can't move text to the right of the last +column because there's no tab stop there. The @code{\`} command moves +all the text that follows it, up to the @code{\\} or +@code{\end@{tabbing@}} command that ends the line, to the right margin +of the @code{tabbing} environment. There must be no @code{\>} or +@code{\'} command between the @code{\`} and the @code{\\} or +@code{\end@{tabbing@}} command that ends the line. + +@item \a @r{(tabbing)} +@findex \a' @r{(acute accent in tabbing)} +@findex \a` @r{(grave accent in tabbing)} +@findex \a= @r{(macron accent in tabbing)} +In a @code{tabbing} environment, the commands @code{\=}, @code{\'} and +@code{\`} do not produce accents as usual (@pxref{Accents}). Instead, +use the commands @code{\a=}, @code{\a'} and @code{\a`}. + +@item \kill +Sets tab stops without producing text. Works just like @code{\\} except +that it throws away the current line instead of producing output for it. +Any @code{\=}, @code{\+} or @code{\-} commands in that line remain in +effect. + +@item \poptabs +@findex \poptabs +Restores the tab stop positions saved by the last @code{\pushtabs}. + +@item \pushtabs +Saves all current tab stop positions. Useful for temporarily changing +tab stop positions in the middle of a @code{tabbing} environment. + +@item \tabbingsep +Distance of the text moved by @code{\'} to left of current tab stop. + +@end ftable + +This example typesets a Pascal function: + +@example +\begin@{tabbing@} +function \= fact(n : integer) : integer;\\ + \> begin \= \+ \\ + \> if \= n > 1 then \+ \\ + fact := n * fact(n-1) \- \\ + else \+ \\ + fact := 1; \-\- \\ + end;\\ +\end@{tabbing@} +@end example + +@noindent +The output looks like this. + +@example +function fact(n : integer) : integer; + begin + if n > 1 then + fact := n * fact(n-1); + else + fact := 1; + end; +@end example + +@PkgIndex{algorithm2e} @PkgIndex{listings} @PkgIndex{minted} +@PkgIndex{fancyvrb} +@noindent +This example is just for illustration of the environment. To actually +typeset computer code in typewriter like this, a verbatim environment +(@pxref{verbatim}) would normally be best. For pretty-printed code, +there are quite a few packages, including @code{algorithm2e}, +@code{fancyvrb}, @code{listings}, and @code{minted}. + + +@node table +@section @code{table} + +@EnvIndex{table} +@cindex tables, creating +@cindex creating tables + +Synopsis: + +@example +\begin@{table@}[@var{placement}] + @var{table body} + \caption[@var{loftitle}]@{@var{title}@} % optional + \label@{@var{label@}} % also optional +\end@{table@} +@end example + +A class of floats (@pxref{Floats}). They cannot be split across pages +and so they are not typeset in sequence with the normal text but instead +are floated to a convenient place, such as the top of a following page. + +This example @code{table} environment contains a @code{tabular} + +@example +\begin@{table@} + \centering\small + \begin@{tabular@}@{ll@} + \multicolumn@{1@}@{c@}@{\textit@{Author@}@} + &\multicolumn@{1@}@{c@}@{\textit@{Piece@}@} \\ \hline + Bach &Cello Suite Number 1 \\ + Beethoven &Cello Sonata Number 3 \\ + Brahms &Cello Sonata Number 1 + \end@{tabular@} + \caption@{Top cello pieces@} + \label@{tab:cello@} +\end@{table@} +@end example + +@noindent +but you can put many different kinds of content in a @code{table}, +including text, @LaTeX{} commands, etc. + +For the possible values of @var{placement} and their effect on the +float placement algorithm, see @ref{Floats}. + +The table body is typeset in a @code{parbox} of width @code{\textwidth}. +It can contain text, commands, graphics, etc. + +The label is optional; it is used for cross references (@pxref{Cross +references}). +@findex \caption +The @code{\caption} command is also optional. It specifies caption text +for the table. By default it is numbered. If its optional +@var{lottitle} is present then that text is used in the list of tables +instead of @var{title} (@pxref{Table of contents etc.}). + +In this example the table and caption will float to the bottom of a page, +unless it is pushed to a float page at the end. + +@example +\begin@{table@}[b] + \centering + \begin@{tabular@}@{r|p@{2in@}@} \hline + One &The loneliest number \\ + Two &Can be as sad as one. + It's the loneliest number since the number one. + \end@{tabular@} + \caption@{Cardinal virtues@} + \label@{tab:CardinalVirtues@} +\end@{table@} +@end example + + +@node tabular +@section @code{tabular} + +@EnvIndex{tabular} +@cindex lines in tables +@cindex lining text up in tables + +Synopsis: + +@example +\begin@{tabular@}[@var{pos}]@{@var{cols}@} + @var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ + ... +\end@{tabular@} +@end example + +@noindent +or + +@example +\begin@{tabular*@}@{@var{width}@}[@var{pos}]@{@var{cols}@} + @var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ + ... +\end@{tabular*@} +@end example + +Produce a table, a box consisting of a sequence of horizontal rows. +Each row consists of items that are aligned vertically in columns. This +illustrates many of the features. + +@example +\begin@{tabular@}@{l|l@} + \textit@{Player name@} &\textit@{Career home runs@} \\ + \hline + Hank Aaron &755 \\ + Babe Ruth &714 +\end@{tabular@} +@end example + +@noindent +The output will have two left-aligned columns with a vertical bar +between them. This is specified in @code{tabular}'s argument +@code{@{l|l@}}. +@findex & +Put the entries into different columns by separating them with an +ampersand, @code{&}. The end of each row is marked with a double +backslash, @code{\\}. Put a horizontal rule below a row, after a double +backslash, with @code{\hline}. +@findex \\ @r{for @code{tabular}} +After the last row the @code{\\} is optional, unless an @code{\hline} +command follows to put a rule below the table. + +The required and optional arguments to @code{tabular} consist of: + +@table @var +@item pos +Optional. Specifies the table's vertical position. The default is to +align the table so its vertical center matches the baseline of the +surrounding text. There are two other possible alignments: @code{t} +aligns the table so its top row matches the baseline of the surrounding +text, and @code{b} aligns on the bottom row. + +This only has an effect if there is other text. In the common case of a +@code{tabular} alone in a @code{center} environment this option makes +no difference. + +@item cols +Required. Specifies the formatting of columns. It consists of a +sequence of the following specifiers, corresponding to the types of +column and intercolumn material. + +@table @code +@item l +A column of left-aligned items. + +@item r +A column of right-aligned items. + +@item c +A column of centered items. + +@item | +A vertical line the full height and depth of the environment. + +@item @@@{@var{text or space}@} +Insert @var{text or space} at this location in every row. The @var{text +or space} material is typeset in LR mode. This text is fragile +(@pxref{\protect}). + +If between two columns there is no @@-expression then @LaTeX{}'s +@code{book}, @code{article}, and @code{report} classes will put on +either side of each column a space of length @code{\tabcolsep}, which by +default is 6@dmn{pt}. That is, by default adjacent columns are +separated by 12@dmn{pt} (so @code{\tabcolsep} is misleadingly named +since it is only half of the separation between tabular columns). In +addition, a space of 6@dmn{pt} also comes before the first column and +after the final column, unless you put a @code{@@@{...@}} or @code{|} +there. + +If you override the default and use an @@-expression then @LaTeX{} does +not insert @code{\tabcolsep} so you must insert any desired space +yourself, as in @code{@@@{\hspace@{1em@}@}}. + +An empty expression @code{@@@{@}} will eliminate the space. In +particular, sometimes you want to eliminate the space before the first +column or after the last one, as in the example below where the +tabular lines need to lie on the left margin. + +@example +\begin@{flushleft@} + \begin@{tabular@}@{@@@{@}l@} + ... + \end@{tabular@} +\end@{flushleft@} +@end example + +The next example shows text, a decimal point between the columns, +arranged so the numbers in the table are aligned on it. + +@example +\begin@{tabular@}@{r@@@{$.$@}l@} + $3$ &$14$ \\ + $9$ &$80665$ +\end@{tabular@} +@end example + +@findex \extracolsep +An @code{\extracolsep@{@var{wd}@}} command in an @@-expression causes an +extra space of width @var{wd} to appear to the left of all subsequent +columns, until countermanded by another @code{\extracolsep}. Unlike +ordinary intercolumn space, this extra space is not suppressed by an +@@-expression. An @code{\extracolsep} command can be used only in an +@@-expression in the @code{cols} argument. Below, @LaTeX{} inserts the +right amount of intercolumn space to make the entire table 4 inches +wide. + +@example +\begin@{tabular*@}@{4in@}@{l@@@{\extracolsep@{\fill@}@}l@} + Seven times down, eight times up \ldots + &such is life! +\end@{tabular*@} +@end example + +To insert commands that are automatically executed before a given +column, load the @code{array} package and use the @code{>@{...@}} +specifier. +@c xx should fully explain array, tabularx, and all other base packages... + +@item p@{@var{wd}@} +Each item in the column is typeset in a parbox of width @var{wd}, as if +it were the argument of a @code{\parbox[t]@{wd@}@{...@}} command. + +A line break double backslash @code{\\} may not appear in the item, +except inside an environment like @code{minipage}, @code{array}, or +@code{tabular}, or inside an explicit @code{\parbox}, or in the scope of +a @code{\centering}, @code{\raggedright}, or @code{\raggedleft} +declaration (when used in a @code{p}-column element these declarations +must appear inside braces, as with @code{@{\centering .. \\ +..@}}). Otherwise @LaTeX{} will misinterpret the double backslash as +ending the row. Instead, to get a line break in there use +@code{\newline} (@pxref{\newline}). + +@item *@{@var{num}@}@{@var{cols}@} +Equivalent to @var{num} copies of @var{cols}, where @var{num} is a +positive integer and @var{cols} is a list of specifiers. Thus the +specifier @code{\begin@{tabular@}@{|*@{3@}@{l|r@}|@}} is equivalent to +the specifier @code{\begin@{tabular@}@{|l|rl|rl|r|@}}. Note that +@var{cols} may contain another @code{*}-expression. + +@end table + +@item width +Required for @code{tabular*}, not allowed for @code{tabular}. Specifies +the width of the @code{tabular*} environment. The space between columns +should be rubber, as with @code{@@@{\extracolsep@{\fill@}@}}, to allow +the table to stretch or shrink to make the specified width, or else you +are likely to get the @code{Underfull \hbox (badness 10000) in alignment +...} warning. + +@end table + +Parameters that control formatting: +@c xx defaults, own node (xref from array)? + +@ftable @code +@item \arrayrulewidth +@anchor{tabular arrayrulewidth} +A length that is the thickness of the rule created by @code{|}, +@code{\hline}, and @code{\vline} in the @code{tabular} and @code{array} +environments. The default is @samp{.4pt}. Change it as in +@code{\setlength@{\arrayrulewidth@}@{0.8pt@}}. + +@item \arraystretch +@anchor{tabular arraystrech} +A factor by which the spacing between rows in the @code{tabular} and +@code{array} environments is multiplied. The default is @samp{1}, for +no scaling. Change it as @code{\renewcommand@{\arraystretch@}@{1.2@}}. + +@item \doublerulesep +@anchor{tabular doublerulesep} +A length that is the distance between the vertical rules produced by the +@code{||} specifier. The default is @samp{2pt}. + +@item \tabcolsep +@anchor{tabular tabcolsep} +A length that is half of the space between columns. The default is +@samp{6pt}. Change it with @code{\setlength}. + +@end ftable + +The following commands can be used inside the body of a @code{tabular} +environment, the first two inside an entry and the second two between +lines: + +@menu +* \multicolumn:: Make an item spanning several columns. +* \vline:: Draw a vertical line. +* \cline:: Draw a horizontal line spanning some columns. +* \hline:: Draw a horizontal line spanning all columns. +@end menu + + +@node \multicolumn +@subsection @code{\multicolumn} + +@findex \multicolumn + +Synopsis: + +@example +\multicolumn@{@var{numcols}@}@{@var{cols}@}@{@var{text}@} +@end example + +Make an @code{array} or @code{tabular} entry that spans several columns. +The first argument @var{numcols} gives the number of columns to span. +The second argument @var{cols} specifies the formatting of the entry, +with @code{c} for centered, @code{l} for flush left, or @code{r} for +flush right. The third argument @var{text} gives the contents of that +entry. + +In this example, in the first row, the second and third columns are +spanned by the single heading @samp{Name}. + +@example +\begin@{tabular@}@{lccl@} + \textit@{ID@} &\multicolumn@{2@}@{c@}@{\textit@{Name@}@} &\textit@{Age@} \\ + \hline + 978-0-393-03701-2 &O'Brian &Patrick &55 \\ + ... +\end@{tabular@} +@end example + +What counts as a column is:@tie{}the column format specifier for the +@code{array} or @code{tabular} environment is broken into parts, where +each part (except the first) begins with @code{l}, @code{c}, @code{r}, +or@tie{}@code{p}. So from @code{\begin@{tabular@}@{|r|ccp@{1.5in@}|@}} +the parts are @code{|r|}, @code{c}, @code{c}, +and@tie{}@code{p@{1.5in@}|}. + +The @var{cols} argument overrides the @code{array} or @code{tabular} +environment's intercolumn area default adjoining this multicolumn +entry. To affect that area, this argument can contain vertical bars +@code{|} indicating the placement of vertical rules, and @code{@@@{...@}} +expressions. Thus if @var{cols} is @samp{|c|} 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. + +@example +\begin@{tabular@}@{|cc|c|c|@} + \multicolumn@{1@}@{r@}@{w@} % entry one + &\multicolumn@{1@}@{|r|@}@{x@} % entry two + &\multicolumn@{1@}@{|r@}@{y@} % entry three + &z % entry four +\end@{tabular@} +@end example + +@noindent +Before the first entry the output will not have a vertical rule because +the @code{\multicolumn} has the @var{cols} specifier @samp{r} with no +initial vertical bar. Between entry one and entry two there will be a +vertical rule; although the first @var{cols} does not have an ending +vertical bar, the second @var{cols} does have a starting one. Between +entry two and entry three there is a single vertical rule; despite that +the @var{cols} in both of the surrounding @code{multicolumn}'s call for +a vertical rule, you only get one rule. Between entry three and entry +four there is no vertical rule; the default calls for one but the +@var{cols} in the entry three @code{\multicolumn} leaves it out, and +that takes precedence. Finally, following entry four there is a +vertical rule because of the default. + +The number of spanned columns @var{numcols} can be 1. Besides giving +the ability to change the horizontal alignment, this also is useful to +override for one row the @code{tabular} definition's default intercolumn +area specification, including the placement of vertical rules. + +In the example below, in the @code{tabular} definition the first column +is specified to default to left justified but in the first row the entry +is centered with @code{\multicolumn@{1@}@{c@}@{\textsc@{Period@}@}}. +Also in the first row, the second and third columns are spanned by a +single entry with @code{\multicolumn@{2@}@{c@}@{\textsc@{Span@}@}}, +overriding the specification to center those two columns on the page +range en-dash. + +@example +\begin@{tabular@}@{l|r@@@{--@}l@} + \multicolumn@{1@}@{c@}@{\textsc@{Period@}@} + &multicolumn@{2@}@{c@}@{\textsc@{Span@}@} \\ \hline + Baroque &1600 &1760 \\ + Classical &1730 &1820 \\ + Romantic &1780 &1910 \\ + Impressionistic &1875 &1925 +\end@{tabular@} +@end example + +@noindent +Although the @code{tabular} specification by default puts a vertical +rule between the first and second columns, no such vertical rule appears +in the first row here. That's because there is no vertical bar in the +@var{cols} part of the first row's first @code{\multicolumn} command. + + +@node \vline +@subsection @code{\vline} + +@findex \vline +Draw a vertical line in a @code{tabular} or @code{array} environment +extending the full height and depth of an entry's row. Can also be +used in an @@-expression, although its synonym vertical +bar@tie{}@code{|} is more common. This command is rarely used in the +body of a table; typically a table's vertical lines are specified in +@code{tabular}'s @var{cols} argument and overridden as needed with +@code{\multicolumn} (@pxref{tabular}). + +The example below illustrates some pitfalls. In the first row's second +entry the @code{\hfill} moves the @code{\vline} to the left edge of the +cell. But that is different than putting it halfway between the two +columns, so between the first and second columns there are two vertical +rules, with the one from the @code{@{c|cc@}} specifier coming before the +one produced by the @code{\vline\hfill}. In contrast, the first row's +third entry shows the usual way to put a vertical bar between two +columns. In the second row, the @code{ghi} is the widest entry in its +column so in the @code{\vline\hfill} the @code{\hfill} has no effect and +the vertical line in that entry appears immediately next to the +@code{g}, with no whitespace. + +@example +\begin@{tabular@}@{c|cc@} + x &\vline\hfill y &\multicolumn@{1@}@{|r@}@{z@} \\ % row 1 + abc &def &\vline\hfill ghi % row 2 +\end@{tabular@} +@end example + + +@node \cline +@subsection @code{\cline} + +@findex \cline + +Synopsis: + +@example +\cline@{@var{i}-@var{j}@} +@end example + +In an @code{array} or @code{tabular} environment, draw a horizontal rule +beginning in column@tie{}@var{i} and ending in column@tie{}@var{j}. The +dash, @code{-}, must appear in the mandatory argument. To span a single +column use the number twice, as with @code{\cline@{2-2@}}. + +This example puts two horizontal lines between the first and second +rows, one line in the first column only, and the other spanning the +third and fourth columns. The two lines are side-by-side, at the same +height. + +@example +\begin@{tabular@}@{llrr@} + a &b &c &d \\ \cline@{1-1@} \cline@{3-4@} + e &f &g &h +\end@{tabular@} +@end example + + +@node \hline +@subsection @code{\hline} + +@findex \hline + +Draw a horizontal line the width of the enclosing @code{tabular} or +@code{array} environment. It's most commonly used to draw a line at the +top, bottom, and between the rows of a table. + +In this example the top of the table has two horizontal rules, one above +the other, that span both columns. The bottom of the table has a single +rule spanning both columns. Because of the @code{\hline}, the +@code{tabular} second row's line ending double backslash@tie{}@code{\\} +is required. + +@example +\begin@{tabular@}@{ll@} \hline\hline + Baseball &Red Sox \\ + Basketball &Celtics \\ \hline +\end@{tabular@} +@end example + + +@node thebibliography +@section @code{thebibliography} + +@EnvIndex{thebibliography} +@cindex bibliography, creating (manually) + +Synopsis: + +@example +\begin@{thebibliography@}@{@var{widest-label}@} + \bibitem[@var{label}]@{@var{cite_key@}} + ... +\end@{thebibliography@} +@end example + +Produce a bibliography or reference list. There are two ways to produce +bibliographic lists. This environment is suitable when you have only a +few references and can maintain the list by hand. @xref{Using BibTeX} +for a more sophisticated approach. + +This shows the environment with two entries. + +@example +This work is based on \cite@{latexdps@}. +Together they are \cite@{latexdps, texbook@}. + ... +\begin@{thebibliography@}@{9@} +\bibitem@{latexdps@} + Leslie Lamport. + \textit@{\LaTeX@{@}: a document preparation system@}. + Addison-Wesley, Reading, Massachusetts, 1993. +\bibitem@{texbook@} + Donald Ervin Knuth. + \textit@{The \TeX book@}. + Addison-Wesley, Reading, Massachusetts, 1983. +\end@{thebibliography@} +@end example + +@noindent +This styles the first reference as @samp{[1] Leslie ...}, and so that +@code{\cite@{latexdps@}} produces the matching @samp{... based on [1]}. +The second @code{\cite} produces @samp{[1, 2]}. You must compile the +document twice to resolve these references. + +The mandatory argument @var{widest-label} is text that, when typeset, is +as wide as the widest item label produced by the @code{\bibitem} +commands. The tradition is to use @code{9} for bibliographies with less +than 10 references, @code{99} for ones with less than 100, etc. + +The bibliographic list is headed by a title such as @samp{Bibliography}. +To change it there are two cases. In the @file{book} and @file{report} +classes, where the top level sectioning is @code{\chapter} and the +default title is @samp{Bibliography}, that title is in the macro +@code{\bibname}. For @file{article}, where the class's top level +sectioning is @code{\section} and the default is @samp{References}, the +title is in macro @code{\refname}. Change it by redefining the command, +as with @code{\renewcommand@{\refname@}@{Cited references@}} after +@code{\begin@{document@}}. + +@PkgIndex{babel} +Language support packages such as @file{babel} will automatically +redefine @code{\refname} or @code{\bibname} to fit the selected +language. + +@menu +* \bibitem:: Specify a bibliography item. +* \cite:: Refer to a bibliography item. +* \nocite:: Include an item in the bibliography. +* Using BibTeX:: Automatic generation of bibliographies. +@end menu + + +@node \bibitem +@subsection @code{\bibitem} + +@findex \bibitem + +Synopsis: + +@example +\bibitem@{@var{cite_key}@} +@end example + +@noindent +or + +@example +\bibitem[@var{label}]@{@var{cite_key}@} +@end example + +Generate an entry labeled by @var{label}. The default is for @LaTeX{} to +generates a number using the @code{enumi} counter. The @dfn{citation key} +@cindex citation key +@var{cite_key} is a string of +letters, numbers, and punctuation symbols (but not comma). + +@xref{thebibliography} for an example. + +The optional @var{label} changes the default label from an integer to the +given string. With this + +@example +\begin@{thebibliography@} +\bibitem[Lamport 1993]@{latexdps@} + Leslie Lamport. + \textit@{\LaTeX@{@}: a document preparation system@}. + Addison-Wesley, Reading, Massachusetts, 1993. +\bibitem@{texbook@} + Donald Ervin Knuth. + \textit@{The \TeX book@}. + Addison-Wesley, Reading, Massachusetts, 1983. +\end@{thebibliography@} +@end example + +@noindent +the first entry will be styled as @samp{[Lamport 1993] Leslie ...} (The +amount of horizontal space that @LaTeX{} leaves for the label depends on +the @var{widest-label} argument of the @code{thebibliography} +environment; see @ref{thebibliography}.) Similarly, @code{... based on +\cite@{latexdps@}} will produce @samp{... based on [Lamport 1994]}. + +If you mix @code{\bibitem} entries having a @var{label} with those that +do not then @LaTeX{} will number the unlabelled ones sequentially. In +the example above the @code{texbook} entry will appear as @samp{[1] +Donald ...}, despite that it is the second entry. + +If you use the same @var{cite_key} twice then you get @samp{LaTeX +Warning: There were multiply-defined labels}. + +Under the hood, @LaTeX{} remembers the @var{cite_key} and @var{label} +information because @code{\bibitem} writes it to the auxiliary file +@file{@var{filename}.aux}. For instance, the above example causes +@code{\bibcite@{latexdps@}@{Lamport, 1993@}} and +@code{\bibcite@{texbook@}@{1@}} to appear in that file. The @file{.aux} +file is read by the @code{\begin@{document@}} command and then the +information is available for @code{\cite} commands. This explains why +you need to run @LaTeX{} twice to resolve references: once to write it +out and once to read it in. + +Because of this two-pass algorithm, when you add a @code{\bibitem} or +change its @var{cite_key} you may get @samp{LaTeX Warning: Label(s) may +have changed. Rerun to get cross-references right}. Fix it by +recompiling. + + +@node \cite +@subsection @code{\cite} + +@findex \cite + +Synopsis: + +@example +\cite@{@var{keys}@} +@end example + +@noindent +or + +@example +\cite[@var{subcite}]@{@var{keys}@} +@end example + +Generate as output a citation to the references associated with +@var{keys}. The mandatory @var{keys} is a citation key, or a +comma-separated list of citation keys (@pxref{\bibitem}). + +This + +@example +The ultimate source is \cite@{texbook@}. + ... +\begin@{thebibliography@} +\bibitem@{texbook@} + Donald Ervin Knuth. + \textit@{The \TeX book@}. + Addison-Wesley, Reading, Massachusetts, 1983. +\end@{thebibliography@} +@end example + +@noindent +produces output like @samp{... source is [1]}. (You can change the +appearance of the citation with bibliography styles. More is in +@ref{Using BibTeX}.) + +The optional argument @var{subcite} is appended to the citation. For +example, @code{See 14.3 in \cite[p.~314]@{texbook@}} might produce +@samp{See 14.3 in [1, p.@tie{}314]}. + +In addition to what appears in the output, @code{\cite} writes +information to the auxiliary file @file{@var{filename}.aux}. For +instance, @code{\cite@{latexdps@}} writes @samp{\citation@{latexdps@}} +to that file. This information is used by Bib@TeX{} to include in your +reference list only those works that you have actually cited; see +@ref{\nocite} also. + +If @var{keys} is not in your bibliography information then you get +@samp{LaTeX Warning: There were undefined references}, and in the output +the citation shows as a boldface question mark between square brackets. +There are two possible causes. If you have mistyped something, as in +@code{\cite@{texbok@}} then you need to correct the spelling. On the +other hand, if you have just added or modified the bibliographic +information and so changed the @file{.aux} file (@pxref{\bibitem}) then +the fix may be to run @LaTeX{} again. + + +@node \nocite +@subsection @code{\nocite} + +@findex \nocite + +Synopsis: + +@example +@code{\nocite@{@var{keys}@}} +@end example + +Produces no output but writes @var{keys} to the auxiliary file +@file{@var{doc-filename}.aux}. + +The mandatory argument @var{keys} is a comma-separated list of one or +more citation keys (@pxref{\bibitem}). This information is used by +Bib@TeX{} to include these works in your reference list even though you +have not cited them (@pxref{\cite}). + + +@node Using BibTeX +@subsection Using Bib@TeX{} + +@cindex using Bib@TeX{} +@cindex bib@TeX{}, using +@cindex bibliography, creating (automatically) +@findex \bibliographystyle +@findex \bibliography + +As described in @code{thebibliography} (@pxref{thebibliography}), a +sophisticated approach to managing bibliographies is provided by the +Bib@TeX{} program. This is only an introduction; see the full +documentation on CTAN. + +With Bib@TeX{}, you don't use @code{thebibliography} +(@pxref{thebibliography}). Instead, include these lines. + +@example +\bibliographystyle@{@var{bibstyle}@} +\bibliography@{@var{bibfile1}, @var{bibfile2}, ...@} +@end example + +@noindent +The @var{bibstyle} refers to a file @file{@var{bibstyle}.bst}, which +defines how your citations will look. The standard @var{bibstyle}'s +distributed with Bib@TeX{} are: + +@table @code +@item alpha +Labels are formed from name of author and year of publication. +The bibliographic items are sorted alphabetically. +@item plain +Labels are integers. +Sort the bibliographic items alphabetically. +@item unsrt +Like @code{plain}, but entries are in order of citation. +@item abbrv +Like @code{plain}, but more compact labels. +@end table + +@noindent Many, many other Bib@TeX{} style files exist, +tailored to the demands of various publications. See CTAN's listing +@url{http://mirror.ctan.org/biblio/bibtex/contrib}. + +The @code{\bibliography} command is what actually produces the +bibliography. Its argument is a comma-separated list, referring to +files named @file{@var{bibfile1}.bib}, @file{@var{bibfile2}.bib}, +@dots{} These contain your database in Bib@TeX{} format. This shows a +typical couple of entries in that format. + +@example +@@book@{texbook, + title = @{The @{@{\TeX@}@}book@}, + author = @{D.E. Knuth@}, + isbn = @{0201134489@}, + series = @{Computers \& typesetting@}, + year = @{1983@}, + publisher = @{Addison-Wesley@} +@} +@@book@{sexbook, + author = @{W.H. Masters and V.E. Johnson@}, + title = @{Human Sexual Response@}, + year = @{1966@}, + publisher = @{Bantam Books@} +@} +@end example + +Only the bibliographic entries referred to via @code{\cite} and +@code{\nocite} will be listed in the document's bibliography. Thus you +can keep all your sources together in one file, or a small number of +files, and rely on Bib@TeX{} to include in this document only those that +you used. + + +@node theorem +@section @code{theorem} + +@EnvIndex{theorem} +@cindex theorems, typesetting + +Synopsis: + +@example +\begin@{theorem@} + @var{theorem body} +\end@{theorem@} +@end example + +Produces @samp{Theorem @var{n}} in boldface followed by @var{theorem +body} in italics. The numbering possibilities for @var{n} are described under +@code{\newtheorem} (@pxref{\newtheorem}). + +@example +\newtheorem@{lem@}@{Lemma@} % in preamble +\newtheorem@{thm@}@{Theorem@} + ... +\begin@{lem@} % in document body + text of lemma +\end@{lem@} + +The next result follows immediately. +\begin@{thm@}[Gauss] % put `Gauss' in parens after theorem head + text of theorem +\end@{thm@} +@end example + +@PkgIndex{amsmath} +@PkgIndex{amsthm} +Most new documents use the packages @code{amsthm} and @code{amsmath} +from the American Mathematical Society. Among other things these +packages include a large number of options for theorem environments, +such as styling options. + + +@node titlepage +@section @code{titlepage} + +@EnvIndex{titlepage} +@cindex making a title page +@cindex title pages, creating + +Synopsis: + +@example +\begin@{titlepage@} + ... text and spacing ... +\end@{titlepage@} +@end example + +Create a title page, a page with no printed page number or heading and +with succeeding pages numbered starting with page one. + +In this example all formatting, including vertical spacing, is left to +the author. + +@example +\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@} +@end example + +To instead produce a standard title page without a @code{titlepage} +environment, use @code{\maketitle} (@pxref{\maketitle}). + + +@node verbatim +@section @code{verbatim} + +@EnvIndex{verbatim} +@cindex verbatim text +@cindex simulating typed text +@cindex typed text, simulating +@cindex code, typesetting +@cindex computer programs, typesetting + +Synopsis: + +@example +\begin@{verbatim@} +@var{literal-text} +\end@{verbatim@} +@end example + +A paragraph-making environment in which @LaTeX{} produces as output +exactly what you type as input. For instance inside @var{literal-text} +the backslash@tie{}@code{\} character does not start commands, it +produces a printed @samp{\}, and carriage returns and blanks are taken +literally. The output appears in a monospaced typewriter-like font +(@code{\tt}). + +@example +\begin@{verbatim@} +Symbol swearing: %&$#?@!. +\end@{verbatim@} +@end example + +The only restriction on @code{literal-text} is that it cannot include +the string @code{\end@{verbatim@}}. + +@PkgIndex{cprotect} +You cannot use the verbatim environment in the argument to macros, for +instance in the argument to a @code{\section}. This is not the same as +commands being fragile (@pxref{\protect}), instead it just cannot appear +there. (But the @code{cprotect} package can help with this.) + +@PkgIndex{listings} +@PkgIndex{minted} +One common use of verbatim input is to typeset computer code. There are +packages that are an improvement the @code{verbatim} environment. For +instance, one improvement is to allow the verbatim inclusion of external +files, or parts of those files. Such packages include @code{listings}, +and @code{minted}. + +@PkgIndex{fancyvrb} +@PkgIndex{verbatimbox} +A package that provides many more options for verbatim environments is +@code{fancyvrb}. Another is @code{verbatimbox}. + +For a list of all the relevant packages, see CTAN. + +@menu +* \verb:: The macro form of the @code{verbatim} environment. +@end menu + + +@node \verb +@subsection @code{\verb} + +@findex \verb +@cindex verbatim text, inline + +Synopsis: + +@example +\verb @var{char} @var{literal-text} @var{char} +\verb* @var{char} @var{literal-text} @var{char} +@end example + +Typeset @var{literal-text} as it is input, including special characters +and spaces, using the typewriter (@code{\tt}) font. + +This example shows two different invocations of @code{\verb}. + +@example +This is \verb!literally! the biggest pumpkin ever. +And this is the best squash, \verb+literally!+ +@end example + +@noindent +The first @code{\verb} has its @var{literal-text} surrounded with +exclamation point, @code{!}. The second instead uses plus, @code{+}, +because the exclamation point is part of @code{literal-text}. + +The single-character delimiter @var{char} surrounds +@var{literal-text}@tie{}--- it must be the same character before and +after. No spaces come between @code{\verb} or @code{\verb*} and +@var{char}, or between @var{char} and @var{literal-text}, or between +@var{literal-text} and the second occurrence of @var{char} (the synopsis +shows a space only to distinguish one component from the other). The +delimiter must not appear in @var{literal-text}. The @var{literal-text} +cannot include a line break. + +@cindex visible space +The @code{*}-form differs only in that spaces are printed with a visible +space character. +@tex +(Namely, {\tt\char`\ }.) +@end tex + +The output from this will include a character showing the spaces. + +@example +The commands's first argument is \verb*!filename with extension! and ... +@end example + +@PkgIndex{url} +For typesetting Internet addresses, urls, the package @code{url} +provides an option that is better than the @code{\verb} command, since +it allows line breaks. + +@PkgIndex{listings} +@PkgIndex{minted} +For computer code there are many packages with advantages over +@code{\verb}. One is @file{listings}, another is @file{minted}. + +@PkgIndex{cprotect} +You cannot use @code{\verb} in the argument to a macro, for instance in +the argument to a @code{\section}. It is not a question of @code{\verb} +being fragile (@pxref{\protect}), instead it just cannot appear there. +(But the @code{cprotect} package can help with this.) + + +@node verse +@section @code{verse} + +@EnvIndex{verse} +@cindex poetry, an environment for + +Synopsis: + +@example +\begin@{verse@} + @var{line1} \\ + @var{line2} \\ + ... +\end@{verse@} +@end example + +An environment for poetry. + +Here are two lines from Shakespeare's Romeo and Juliet. + +@example +Then plainly know my heart's dear love is set \\ +On the fair daughter of rich Capulet. +@end example + +@findex \\ @r{for @code{verse}} +Separate the lines of each stanza with @code{\\}, and use one or more +blank lines to separate the stanzas. + +@example +\begin@{verse@} +\makebox[\linewidth][c]@{\textit@{Shut Not Your Doors@} ---Walt Whitman@} + \\[1\baselineskip] +Shut not your doors to me proud libraries, \\ +For that which was lacking on all your well-fill'd shelves, \\ +\qquad yet needed most, I bring, \\ +Forth from the war emerging, a book I have made, \\ +The words of my book nothing, the drift of it every thing, \\ +A book separate, not link'd with the rest nor felt by the intellect, \\ +But you ye untold latencies will thrill to every page. +\end@{verse@} +@end example + +@noindent +The output has margins indented on the left and the right, paragraphs +are not indented, and the text is not right-justified. + + +@node Line breaking +@chapter Line breaking + +@cindex line breaking +@cindex breaking lines + +The first thing @LaTeX{} does when processing ordinary text is to +translate your input file into a sequence of glyphs and spaces. To +produce a printed document, this sequence must be broken into lines +(and these lines must be broken into pages). + +@LaTeX{} usually does the line (and page) breaking in the text body for +you but in some environments you manually force line breaks. + +A common workflow is to get a final version of the document content +before taking a final pass through and considering line breaks (and page +breaks). This differs from word processing, where you are formatting +text as you input it. Putting these off until the end prevents a lot of +fiddling with breaks that will change anyway. + +@menu +* \\:: Start a new line. +* \obeycr & \restorecr:: Make each input line start a new output line. +* \newline:: Break the line +* \- (hyphenation):: Insert explicit hyphenation. +* \discretionary:: Explicit control of the hyphen character. +* \fussy & \sloppy:: Be more or less particular with line breaking. +* \hyphenation:: Tell @LaTeX{} how to hyphenate a word. +* \linebreak & \nolinebreak:: Forcing & avoiding line breaks. +@end menu + + +@node \\ +@section @code{\\} + +@findex \\ @r{force line break} +@cindex new line, starting +@cindex line break, forcing + +Synopsis, one of: + +@example +\\ +\\[@var{morespace}] +@end example + +@noindent +or one of: + +@example +\\* +\\*[@var{morespace}] +@end example + +End the current line. The optional argument @var{morespace} specifies +extra vertical space to be inserted before the next line. This is a +rubber length (@pxref{Lengths}) and can be negative. The text before +the line break is set at its normal length, that is, it is not stretched +to fill out the line width. This command is fragile (@pxref{\protect}). + +The starred form, @code{\\*}, tells @LaTeX{} not to start a new page +between the two lines, by issuing a @code{\nobreak}. + +@example +\title@{My story: \\[0.25in] + a tale of woe@} +@end example + +Explicit line breaks in the main text body are unusual in @LaTeX{}. In +particular, don't start new paragraphs with @code{\\}. Instead leave a +blank line between the two paragraphs. And don't put in a sequence of +@code{\\}'s to make vertical space. Instead use +@code{\vspace@{@var{length}@}}, or +@code{\leavevmode\vspace@{@var{length}@}}, or +@code{\vspace*@{@var{length}@}} if you want the space to not be thrown +out at the top of a new page (@pxref{\vspace}). + +The @code{\\} command is mostly used outside of the main flow of text +such as in a @code{tabular} or @code{array} environment or in an +equation environment. + +The @code{\\} command is a synonym for @code{\newline} +(@pxref{\newline}) under ordinary circumstances (an example of an +exception is the @code{p@{...@}} column in a @code{tabular} +environment; @pxref{tabular}). + +@c credit: David Carlisle https://tex.stackexchange.com/a/82666 +The @code{\\} command is a macro, and its definition changes by context +so that its definition in normal text, a @code{center} environment, a +@code{flushleft} environment, and a @code{tabular} are all different. +In normal text when it forces a linebreak it is essentially a shorthand +for @code{\newline}. It does not end horizontal mode or end the +paragraph, it just inserts some glue and penalties so that when the +paragraph does end a linebreak will occur at that point, with the short +line padded with white space. + +You get @samp{LaTeX Error: There's no line here to end} if you use +@code{\\} to ask for a new line, rather than to end the current line. +An example is if you have @code{\begin@{document@}\\} or, more likely, +something like this. + +@example +\begin@{center@} + \begin@{minipage@}@{0.5\textwidth@} + \\ + In that vertical space put your mark. + \end@{minipage@} +\end@{center@} +@end example + +@noindent +Fix it by replacing the double backslash with something like +@code{\vspace@{\baselineskip@}}. + + +@node \obeycr & \restorecr +@section @code{\obeycr} & @code{\restorecr} + +@findex \obeycr +@findex \restorecr +@cindex new line, output as input + +The @code{\obeycr} command makes a return in the input file (@samp{^^M}, +internally) the same as @code{\\}, followed by @code{\relax}. So each +new line in the input will also be a new line in the output. The +@code{\restorecr} command restores normal line-breaking behavior. + +This is not the way to show verbatim text or computer code. +@xref{verbatim} instead. + +With @LaTeX{}'s usual defaults, this + +@example +aaa +bbb + +\obeycr +ccc +ddd + eee + +\restorecr +fff +ggg + +hhh +iii +@end example + +@noindent +produces output like this. + +@example + aaa bbb + ccc +ddd +eee + +fff ggg + hhh iii +@end example + +@noindent +The indents are paragraph indents. + + +@node \newline +@section @code{\newline} + +@findex \newline +@cindex new line, starting (paragraph mode) + +In ordinary text, this ends a line in a way that does not right-justify +the line, so the prior text is not stretched. That is, in paragraph mode +(@pxref{Modes}), the @code{\newline} command is equivalent to +double-backslash (@pxref{\\}). This command is fragile +(@pxref{\protect}). + +However, the two commands are different inside a @code{tabular} or +@code{array} environment. In a column with a specifier producing a +paragraph box such as typically @code{p@{...@}}, @code{\newline} will +insert a line end inside of the column; that is, it does not break the +entire tabular row. To break the entire row use @code{\\} or its +equivalent @code{\tabularnewline}. + +This will print @samp{Name:} and @samp{Address:} as two lines in a +single cell of the table. + +@example +\begin@{tabular@}@{p@{1in@}@{\hspace@{2in@}@}p@{1in@}@} + Name: \newline Address: &Date: \\ \hline +\end@{tabular@} +@end example + +@noindent +The @samp{Date:} will be baseline-aligned with @samp{Name:}. + + +@node \- (hyphenation) +@section @code{\-} (discretionary hyphen) + +@findex \- @r{(hyphenation)} +@cindex hyphenation, forcing + +Tell @LaTeX{} that it may hyphenate the word at that point. When you +insert @code{\-} commands in a word, the word will only be hyphenated at +those points and not at any of the hyphenation points that @LaTeX{} +might otherwise have chosen. This command is robust (@pxref{\protect}). + +@LaTeX{} is good at hyphenating and usually finds most of the correct +hyphenation points, while almost never using an incorrect one. The +@code{\-} command is for exceptional cases. + +For example, @LaTeX{} does not ordinarily hyphenate words containing a +hyphen. Below, the long and hyphenated word means @LaTeX{} has to put +in unacceptably large spaces to set the narrow column. + +@example +\begin@{tabular@}@{rp@{1.75in@}@} + Isaac Asimov &The strain of + anti-intellectualism + % an\-ti-in\-tel\-lec\-tu\-al\-ism + has been a constant thread winding its way through our + political and cultural life, nurtured by + the false notion that democracy means that + `my ignorance is just as good as your knowledge'. +\end@{tabular@} +@end example + +@noindent +Commenting out the third line and uncommenting the fourth makes a much +better fit. + +The @code{\-} command only allows @LaTeX{} to break there, it does not +require that it break there. You can insist on a split with something +like @code{Hef-\linebreak feron}. Of course, if you later change the +text then this forced break may look very odd, so this approach requires +care. + + +@node \discretionary +@section @code{\discretionary} (generalized hyphenation point) +@cindex hyphenation, discretionary +@cindex discretionary hyphenation + +Synopsis: + +@example +\discretionary@{@var{pre-break}@}@{@var{post-break}@}@{@var{no-break}@} +@end example + +Handle word changes around hyphens. This command is not often used in +@LaTeX{} documents. + +If a line break occurs at the point where @code{\discretionary} appears +then @TeX{} puts @var{pre-break} at the end of the current line and puts +@var{post-break} at the start of the next line. If there is no line +break here then @TeX{} puts @var{no-break} + +In @samp{difficult} the three letters @code{ffi} form a ligature. But +@TeX{} can nonetheless break between the two f's with this. + +@example +di\discretionary@{f-@}@{fi@}@{ffi@}cult +@end example + +Note that users do not have to do this. It is typically handled +automatically by @TeX{}'s hyphenation algorithm. + + +@node \fussy & \sloppy +@section @code{\fussy} & @code{\sloppy} + +@findex \fussy +@findex \sloppy +@cindex line breaks, changing + +Declarations to make @TeX{} more picky or less picky about line +breaking. Declaring @code{\fussy} usually avoids too much space between +words, at the cost of an occasional overfull box. Conversely, +@code{\sloppy} avoids overfull boxes while suffering loose interword +spacing. + +The default is @code{\fussy}. Line breaking in a paragraph is +controlled by whichever declaration is current at the blank line, or +@code{\par}, or displayed equation ending that paragraph. So to affect +the line breaks, include that paragraph-ending material in the scope of +the command. + +@menu +* sloppypar:: Environment version of \sloppy command. +@end menu + + +@node sloppypar +@subsection @code{sloppypar} + +@findex sloppypar +@cindex sloppypar environment + +Synopsis: + +@example +\begin@{sloppypar@} + ... paragraphs ... +\end@{sloppypar@} +@end example + +Typeset the paragraphs with @code{\sloppy} in effect (@pxref{\fussy & +\sloppy}). Use this to locally adjust line breaking, to avoid +@samp{Overfull box} or @samp{Underfull box} errors. + +The example is simple. + +@example +\begin@{sloppypar@} + Her plan for the morning thus settled, she sat quietly down to her + book after breakfast, resolving to remain in the same place and the + same employment till the clock struck one; and from habitude very + little incommoded by the remarks and ejaculations of Mrs.\ Allen, + whose vacancy of mind and incapacity for thinking were such, that + as she never talked a great deal, so she could never be entirely + silent; and, therefore, while she sat at her work, if she lost her + needle or broke her thread, if she heard a carriage in the street, + or saw a speck upon her gown, she must observe it aloud, whether + there were anyone at leisure to answer her or not. +\end@{sloppypar@} +@end example + + +@node \hyphenation +@section @code{\hyphenation} + +@findex \hyphenation +@cindex hyphenation, defining + +Synopsis: + +@example +\hyphenation@{@var{word1} ...@} +@end example + +Declares allowed hyphenation points within the words in the list. The +words in that list are separated by spaces. Show permitted points for +hyphenation with a dash character, @code{-}. + +Here is an example: + +@example +\hyphenation@{hat-er il-lit-e-ra-ti tru-th-i-ness@} +@end example + +Use lowercase letters. @TeX{} will only hyphenate if the word matches +exactly. Multiple @code{\hyphenation} commands accumulate. + + +@node \linebreak & \nolinebreak +@section @code{\linebreak} & @code{\nolinebreak} + +@findex \linebreak +@findex \nolinebreak +@cindex line breaks, forcing +@cindex line breaks, preventing + +Synopses, one of: + +@example +\linebreak +\linebreak[@var{zero-to-four}] +@end example + +@noindent +or one of these. + +@example +\nolinebreak +\nolinebreak[@var{zero-to-four}] +@end example + +Encourage or discourage a line break. The optional @var{zero-to-four} +is an integer that allows you to soften the instruction. The default is +4, so that without the optional argument these commands entirely force +or prevent the break. But for instance, @code{\nolinebreak[1]} is a +suggestion that another place may be better. The higher the number, the +more insistent the request. Both commands are fragile +(@pxref{\protect}). + +Here we tell @LaTeX{} that a good place to put a linebreak is after the +standard legal text. + +@example +\boilerplatelegal@{@} \linebreak[2] +We especially encourage applications from members of traditionally +underrepresented groups. +@end example + +When you issue @code{\linebreak}, the spaces in the line are stretched +out so that it extends to the right margin. @xref{\\} +and@tie{}@ref{\newline} to have the spaces not stretched out. + + + +@node Page breaking +@chapter Page breaking + +@cindex page breaking +@cindex breaking pages + +Ordinarily @LaTeX{} automatically takes care of breaking output into +pages with its usual aplomb. But if you are writing commands, or +tweaking the final version of a document, then you may need to +understand how to influence its actions. + +@c credit: H Vogt https://tex.stackexchange.com/a/115563 +@LaTeX{}'s algorithm for splitting a document into pages is more complex +than just waiting until there is enough material to fill a page and +outputting the result. Instead, @LaTeX{} typesets more material than +would fit on the page and then chooses a break that is optimal in some +way (it has the smallest badness). An example of the advantage of this +approach is that if the page has some vertical space that can be +stretched or shrunk, such as with rubber lengths between paragraphs, +then @LaTeX{} can use that to avoid widow lines (where a new page starts +with the last line of a paragraph; @LaTeX{} can squeeze the extra line +onto the first page) and orphans (where the first line of paragraph is +at the end of a page; @LaTeX{} can stretch the material of the first +page so the extra line falls on the second page). Another example is +where @LaTeX{} uses available vertical shrinkage to fit on a page not +just the header for a new section but also the first two lines of that +section. + +But @LaTeX{} does not optimize over the entire document's set of page +breaks. So it can happen that the first page break is great but the +second one is lousy; to break the current page @LaTeX{} doesn't look as +far ahead as the next page break. So occasionally you may want to +influence page breaks while preparing a final version of a document. + +@xref{Layout} for more material that is relevant to page breaking. + +@menu +* \clearpage & \cleardoublepage:: Start a new page; eject floats. +* \newpage:: Start a new page. +* \enlargethispage:: Enlarge the current page a bit. +* \pagebreak & \nopagebreak:: Forcing & avoiding page breaks. +@end menu + + +@node \clearpage & \cleardoublepage +@section @code{\clearpage} & @code{\cleardoublepage} + +@findex \clearpage +@cindex flushing floats and starting a page +@cindex starting a new page and clearing floats +@findex \cleardoublepage +@cindex starting on a right-hand page + +Synopsis: + +@example +\clearpage +@end example + +@noindent +or + +@example +\cleardoublepage +@end example + +End the current page and output all of the pending floating figures and +tables (@pxref{Floats}). If there are too many floats to fit on the +page then @LaTeX{} will put in extra pages containing only floats. In +two-sided printing, @code{\cleardoublepage} also makes the next page of +content a right-hand page, an odd-numbered page, if necessary inserting +a blank page. The @code{\clearpage} command is robust while +@code{\cleardoublepage} is fragile (@pxref{\protect}). + +@LaTeX{}'s page breaks are optimized so ordinarily you only use this +command in a document body to polish the final version, or inside +commands. + +@c credit: https://www.tex.ac.uk/FAQ-reallyblank.html +The @code{\cleardoublepage} command will put in a blank page, but it +will have the running headers and footers. To get a really blank +page, use this command. + +@example +\let\origdoublepage\cleardoublepage +\newcommand@{\clearemptydoublepage@}@{% + \clearpage + @{\pagestyle@{empty@}\origdoublepage@}% +@} +@end example + +@noindent +If you want @LaTeX{}'s standard @code{\chapter} command to do this then +add the line @code{\let\cleardoublepage\clearemptydoublepage}. + +The command @code{\newpage} (@pxref{\newpage}) also ends the current +page, but without clearing pending floats. And, if @LaTeX{} is in +two-column mode then @code{\newpage} ends the current column while +@code{\clearpage} and @code{\cleardoublepage} end the current page. + + + +@node \newpage +@section @code{\newpage} + +@findex \newpage +@cindex new page, starting +@cindex starting a new page + +Synopsis: + +@example +\newpage +@end example + +End the current page. This command is robust (@pxref{\protect}). + +@LaTeX{}'s page breaks are optimized so ordinarily you only use this +command in a document body to polish the final version, or inside +commands. + +While the commands @code{\clearpage} and @code{\cleardoublepage} also +end the current page, in addition they clear pending floats +(@pxref{\clearpage & \cleardoublepage}). And, if @LaTeX{} is in +two-column mode then @code{\clearpage} and @code{\cleardoublepage} end +the current page, possibly leaving an empty column, while +@code{\newpage} only ends the current column. + +In contrast with @code{\pagebreak} (@pxref{\pagebreak & \nopagebreak}), +the @code{\newpage} command will cause the new page to start right where +requested. This + +@example +Four score and seven years ago our fathers brought forth on this +continent, +\newpage +\noindent a new nation, conceived in Liberty, and dedicated to the +proposition that all men are created equal. +@end example + +@noindent +makes a new page start after @samp{continent,} and the cut-off line is +not right justified. In addition, @code{\newpage} does not vertically +stretch out the page, as @code{\pagebreak} does. + + +@node \enlargethispage +@section @code{\enlargethispage} + +@findex \enlargethispage +@cindex enlarge current page + +Synopsis, one of: + +@example +\enlargethispage@{size@} +\enlargethispage*@{size@} +@end example + +Enlarge the @code{\textheight} for the current page. The required +argument @var{size} must be a rigid length (@pxref{Lengths}). It may be +positive or negative. This command is fragile (@pxref{\protect}). + +A common strategy is to wait until you have the final text of a +document, and then pass through it tweaking line and page breaks. This +command allows you some page size leeway. + +This will allow one extra line on the current page. + +@example +\enlargethispage@{\baselineskip@} +@end example + +The starred form @code{\enlargesthispage*} tries to squeeze the material +together on the page as much as possible, for the common use case of +getting one more line on the page. This is often used together with an +explicit @code{\pagebreak}. + + +@node \pagebreak & \nopagebreak +@section @code{\pagebreak} & @code{\nopagebreak} + +@findex \pagebreak +@findex \nopagebreak +@cindex page break, forcing +@cindex page break, preventing + +Synopses: + +@example +\pagebreak +\pagebreak[@var{zero-to-four}] +@end example + +@noindent +or + +@example +\nopagebreak +\nopagebreak[@var{zero-to-four}] +@end example + +Encourage or discourage a page break. The optional @var{zero-to-four} +is an integer that allows you to soften the request. The default is 4, +so that without the optional argument these commands entirely force or +prevent the break. But for instance @code{\nopagebreak[1]} suggests to +@LaTeX{} that another spot might be preferable. The higher the number, +the more insistent the request. Both commands are fragile +(@pxref{\protect}). + +@LaTeX{}'s page endings are optimized so ordinarily you only use this +command in a document body to polish the final version, or inside +commands. + +If you use these inside a paragraph, they apply to the point following +the line in which they appear. So this + +@example +Four score and seven years ago our fathers brought forth on this +continent, +\pagebreak +a new nation, conceived in Liberty, and dedicated to the proposition +that all men are created equal. +@end example + +@noindent +does not give a page break at @samp{continent,} but instead at +@samp{nation,} since that is where @LaTeX{} breaks that line. In +addition, with @code{\pagebreak} the vertical space on the page is +stretched out where possible so that it extends to the normal bottom +margin. This can look strange, and if @code{\flushbottom} is in effect +this can cause you to get @samp{Underfull \vbox (badness 10000) has +occurred while \output is active}. @xref{\newpage} for a command that +does not have these effects. + + +@node Footnotes +@chapter Footnotes + +@cindex footnotes, creating + +Place a footnote at the bottom of the current page, as here. + +@example +No@"{e}l Coward quipped that having to read a footnote is like having +to go downstairs to answer the door, while in the midst of making +love.\footnote@{% + I wouldn't know, I don't read footnotes.@} +@end example + +You can put multiple footnotes on a page. If the footnote text becomes +too long then it will flow to the next page. + +You can also produce footnotes by combining the @code{\footnotemark} and +the @code{\footnotetext} commands, which is useful in special +circumstances. + +To make bibliographic references come out as footnotes you need to +include a bibliographic style with that behavior (@pxref{Using BibTeX}). + +@menu +* \footnote:: Insert a footnote. +* \footnotemark:: Insert footnote mark only. +* \footnotetext:: Insert footnote text only. +* Footnotes in section headings:: Chapter or section titles. +* Footnotes in a table:: Table footnotes. +* Footnotes of footnotes:: Multiple classes of footnotes. +@end menu + + +@node \footnote +@section @code{\footnote} + +@findex \footnote + +Synopsis, one of: + +@example +\footnote@{@var{text}@} +\footnote[@var{number}]@{@var{text}@} +@end example + +Place a footnote @var{text} at the bottom of the current page. + +@example +There are over a thousand footnotes in Gibbon's +\textit@{Decline and Fall of the Roman Empire@}.\footnote@{% + After reading an early version with endnotes David Hume complained, + ``One is also plagued with his Notes, according to the present Method + of printing the Book'' and suggested that they ``only to be printed + at the Margin or the Bottom of the Page.''@} +@end example + +The optional argument @var{number} allows you to specify the number of +the footnote. If you use this then @LaTeX{} does not increment the +@code{footnote} counter. + +@cindex footnotes, symbols instead of numbers +@findex \fnsymbol@r{, and footnotes} +@findex \@@fnsymbol +By default, @LaTeX{} uses arabic numbers as footnote markers. Change +this with something like +@code{\renewcommand@{\thefootnote@}@{\fnsymbol@{footnote@}@}}, which +uses a sequence of symbols (@pxref{\alph \Alph \arabic \roman \Roman +\fnsymbol}). To make this change global put that in the preamble. If +you make the change local then you may want to reset the counter with +@code{\setcounter@{footnote@}@{0@}}. + +@LaTeX{} determines the spacing of footnotes with two parameters. + +@cindex footnote parameters +@cindex parameters, for footnotes + +@ftable @code +@item \footnoterule +@anchor{footnote footnoterule} +Produces the rule separating the main text on a page from the page's +footnotes. Default dimensions in the standard document classes (except +@code{slides}, where it does not appear) is: vertical thickness of +@code{0.4pt}, and horizontal size of @code{0.4\columnwidth} long. +Change the rule with something like this. + +@c Credit egreg: https://tex.stackexchange.com/a/21917 +@example +\renewcommand@{\footnoterule@}@{% Kerns avoid vertical space + \kern -3pt % This -3 is negative + \hrule width \textwidth height 1pt % of the sum of this 1 + \kern 2pt@} % and this 2 +@end example + +@item \footnotesep +@anchor{footnote footnotesep} +The height of the strut placed at the beginning of the footnote +(@pxref{\strut}). By default, this is set to the normal strut for +@code{\footnotesize} fonts (@pxref{Font sizes}), therefore there is no +extra space between footnotes. This is @samp{6.65pt} for @samp{10pt}, +@samp{7.7pt} for @samp{11pt}, and @samp{8.4pt} for @samp{12pt}. Change +it as with @code{\setlength@{\footnotesep@}@{11pt@}}. + +@end ftable + +The @code{\footnote} command is fragile (@pxref{\protect}). + +@LaTeX{}'s default puts many restrictions on where you can use a +@code{\footnote}; for instance, you cannot use it in an argument to a +sectioning command such as @code{\chapter} (it can only be used in outer +paragraph mode; @pxref{Modes}). There are some workarounds; see +following sections. + +@cindex Footnotes, in a minipage +@cindex mpfootnote counter +In a @code{minipage} environment the @code{\footnote} command uses the +@code{mpfootnote} counter instead of the @code{footnote} counter, so +they are numbered independently. They are shown at the bottom of the +environment, not at the bottom of the page. And by default they are +shown alphabetically. @xref{minipage} and @ref{Footnotes in a table}. + + +@node \footnotemark +@section @code{\footnotemark} + +@findex \footnotemark + +Synopsis, one of: + +@example +\footnotemark +\footnotemark[@var{number}] +@end example + +Put the current footnote mark in the text. To specify associated text +for the footnote see@tie{}@ref{\footnotetext}. The optional argument +@var{number} causes the command to use that number to determine the +footnote mark. This command can be used in inner paragraph mode +(@pxref{Modes}). + +If you use @code{\footnotemark} without the optional argument then it +increments the footnote counter but if you use the optional @var{number} +then it does not. The next example produces several consecutive footnote +markers referring to the same footnote. + +@example +The first theorem\footnote@{Due to Gauss.@} +and the second theorem\footnotemark[\value@{footnote@}] +and the third theorem.\footnotemark[\value@{footnote@}] +@end example + +If there are intervening footnotes then you must remember the value of the +common mark. This example gives the same institutional affiliation to +both the first and third authors (@code{\thanks} is a version of +@code{footnote}), by-hand giving the number of the footnote. + +@example +\title@{A Treatise on the Binomial Theorem@} +\author@{J Moriarty\thanks@{University of Leeds@} + \and A C Doyle\thanks@{Durham University@} + \and S Holmes\footnotemark[1]@} +\begin@{document@} +\maketitle +@end example + +This uses a counter to remember the footnote number. The third sentence +is followed by the same footnote marker as the first. + +@example +\newcounter@{footnoteValueSaver@} +All babies are illogical.\footnote@{% + Lewis Carroll.@}\setcounter@{footnoteValueSaver@}@{\value@{footnote@}@} +Nobody is despised who can manage a crocodile.\footnote@{% + Captain Hook.@} +Illogical persons are despised.\footnotemark[\value@{footnoteValueSaver@}] +Therefore, anyone who can manage a crocodile is not a baby. +@end example + +@PkgIndex{cleveref} +@PkgIndex{hyperref} +This example accomplishes the same by using the package @file{cleveref}. + +@c from SE user Jake http://tex.stackexchange.com/a/10116/339 +@example +\usepackage@{cleveref@}[2012/02/15] % in preamble +\crefformat@{footnote@}@{#2\footnotemark[#1]#3@} +... +The theorem is from Evers.\footnote@{\label@{fn:TE@}Tinker, Evers, 1994.@} +The corollary is from Chance.\footnote@{Evers, Chance, 1990.@} +But the key lemma is from Tinker.\cref@{fn:TE@} +@end example + +@PkgIndex{hyperref} +It will work with the package @file{hyperref}. + + +@node \footnotetext +@section @code{\footnotetext} + +@findex \footnotetext + +Synopsis, one of: + +@example +\footnotetext@{@var{text}@} +\footnotetext[@var{number}]@{@var{text}@} +@end example + +Place @var{text} at the bottom of the page as a footnote. It pairs with +@code{\footnotemark} (@pxref{\footnotemark}) and can come anywhere after +that command, but must appear in outer paragraph mode (@pxref{Modes}). +The optional argument @var{number} changes the number of the footnote +mark. + +@xref{\footnotemark} and@tie{}@ref{Footnotes in a table} for usage +examples. + + +@node Footnotes in section headings +@section Footnotes in section headings + +@cindex footnote, in section headings +@cindex table of contents, avoiding footnotes + +Putting a footnote in a section heading, as in: + +@example +\section@{Full sets\protect\footnote@{This material due to ...@}@} +@end example + +@noindent +causes the footnote to appear at the bottom of the page where the +section starts, as usual, but also at the bottom of the table of +contents, where it is not likely to be desired. The simplest way +to have it not appear on the table of contents is to use the optional +argument to @code{\section} + +@example +\section[Please]@{Please\footnote@{% + Don't footnote in chapter and section headers!@}@} +@end example + +@noindent +No @code{\protect} is needed in front of @code{\footnote} here because +what gets moved to the table of contents is the optional argument. + + +@node Footnotes in a table +@section Footnotes in a table + +@cindex footnote, in a table + +Inside a @code{tabular} or @code{array} environment the @code{\footnote} +command does not work; there is a footnote mark in the table cell but +the footnote text does not appear. The solution is to use a +@code{minipage} environment as here (@pxref{minipage}). + +@example +\begin@{center@} + \begin@{minipage@}@{\textwidth@} \centering + \begin@{tabular@}@{l|l@} + \textsc@{Ship@} &\textsc@{Book@} \\ \hline + \textit@{HMS Sophie@} &Master and Commander \\ + \textit@{HMS Polychrest@} &Post Captain \\ + \textit@{HMS Lively@} &Post Captain \\ + \textit@{HMS Surprise@} &A number of books\footnote@{% + Starting with HMS Surprise.@} + \end@{tabular@} + \end@{minipage@} +\end@{center@} +@end example + +Inside a @code{minipage}, footnote marks are lowercase letters. Change +that with something like +@code{\renewcommand@{\thempfootnote@}@{\arabic@{mpfootnote@}@}} +(@pxref{\alph \Alph \arabic \roman \Roman \fnsymbol}). + +The footnotes in the prior example appear at the bottom of the +@code{minipage}. To have them appear at the bottom of the main page, as +part of the regular footnote sequence, use the @code{\footnotemark} and +@code{\footnotetext} pair and make a new counter. + +@example +\newcounter@{mpFootnoteValueSaver@} +\begin@{center@} + \begin@{minipage@}@{\textwidth@} + \setcounter@{mpFootnoteValueSaver@}@{\value@{footnote@}@} \centering + \begin@{tabular@}@{l|l@} + \textsc@{Woman@} &\textsc@{Relationship@} \\ \hline + Mona &Attached\footnotemark \\ + Diana Villiers &Eventual wife \\ + Christine Hatherleigh Wood &Fiance\footnotemark + \end@{tabular@} + \end@{minipage@}% percent sign keeps footnote text close to minipage + \stepcounter@{mpFootnoteValueSaver@}% + \footnotetext[\value@{mpFootnoteValueSaver@}]@{% + Little is known other than her death.@}% + \stepcounter@{mpFootnoteValueSaver@}% + \footnotetext[\value@{mpFootnoteValueSaver@}]@{% + Relationship is unresolved in XXI.@} +\end@{center@} +@end example + +For a floating @code{table} environment (@pxref{table}), use the +@file{tablefootnote} package. + +@example +\usepackage@{tablefootnote@} % in preamble + ... +\begin@{table@} + \centering + \begin@{tabular@}@{l|l@} + \textsc@{Date@} &\textsc@{Campaign@} \\ \hline + 1862 &Fort Donelson \\ + 1863 &Vicksburg \\ + 1865 &Army of Northern Virginia\tablefootnote@{% + Ending the war.@} + \end@{tabular@} + \caption@{Forces captured by US Grant@} +\end@{table@} +@end example + +@noindent +The footnote appears at the page bottom and is numbered in sequence with +other footnotes. + + +@node Footnotes of footnotes +@section Footnotes of footnotes + +@cindex footnote, of a footnote + +@PkgIndex{bigfoot} +Particularly in the humanities, authors can have multiple classes of +footnotes, including having footnotes of footnotes. The package +@file{bigfoot} extends @LaTeX{}'s default footnote mechanism in many +ways, including allow these two, as in this example. + +@example +\usepackage@{bigfoot@} % in preamble +\DeclareNewFootnote@{Default@} +\DeclareNewFootnote@{from@}[alph] % create class \footnotefrom@{@} + ... +The third theorem is a partial converse of the +second.\footnotefrom@{% + First noted in Wilson.\footnote@{Second edition only.@}@} +@end example + + +@node Definitions +@chapter Definitions + +@cindex definitions + +@LaTeX{} has support for making new commands of many different kinds. + +@menu +* \newcommand & \renewcommand:: (Re)define a new command. +* \providecommand:: Define a new command, if name not used. +* \makeatletter & \makeatother:: Change the status of the at-sign character. +* \@@ifstar:: Define your own commands with *-variants. +* \newcounter:: Define a new counter. +* \newlength:: Define a new length. +* \newsavebox:: Define a new box. +* \newenvironment & \renewenvironment:: Define a new environment. +* \newtheorem:: Define a new theorem-like environment. +* \newfont:: Define a new font name. +* \protect:: Using tricky commands. +* \ignorespaces & \ignorespacesafterend:: Discard extra spaces. +@end menu + + +@node \newcommand & \renewcommand +@section @code{\newcommand} & @code{\renewcommand} + +@findex \newcommand +@cindex commands, defining new ones +@cindex commands, redefining +@cindex defining a new command +@cindex new commands, defining + +Synopses, one of: + +@example +\newcommand@{\@var{cmd}@}@{@var{defn}@} +\newcommand@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@} +\newcommand@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +\newcommand*@{\@var{cmd}@}@{@var{defn}@} +\newcommand*@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@} +\newcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +@end example + +@noindent +or one of these. + +@example +\renewcommand@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@} +\renewcommand@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@} +\renewcommand@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +\renewcommand*@{\@var{cmd}@}@{@var{defn}@} +\renewcommand*@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@} +\renewcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +@end example + +Define or redefine a command. See also the discussion of +@code{\DeclareRobustCommand} in @ref{Class and package commands}. +@cindex starred form, defining new commands +@cindex *-form, defining new commands +The starred form of these two requires that the arguments not contain +multiple paragraphs of text (in plain @TeX{} terms that it not be +@code{\long}). + +These are the parameters: + +@table @var +@item cmd + +Required; the command name. It must begin with a backslash, @code{\}, +and must not begin with the four letter string @code{\end}. For +@code{\newcommand}, it must not be already defined. For +@code{\renewcommand}, this name must already be defined. + +@item nargs +Optional; an integer from 0 to 9, specifying the number of arguments +that the command takes, including any optional argument. Omitting this +argument is the same as specifying 0, meaning that the command has no +arguments. If you redefine a command, the new version can have a +different number of arguments than the old version. + +@item optargdefault +Optional; if this argument is present then the first argument of +@code{\@var{cmd}} is optional, with default value @var{optargdefault} +(which may be the empty string). If this argument is not present then +@code{\@var{cmd}} does not take an optional argument. + +@cindex positional parameter +That is, if @code{\@var{cmd}} is used with square brackets, as in +@code{\@var{cmd}[@var{optval}]@{...@}...}, then within @var{defn} the +parameter@tie{}@code{#1} is set to the value of @var{optval}. On the +other hand, if @code{\@var{cmd}} is called without the square brackets +then within @var{defn} the parameter @code{#1} is set to the value of +@var{optargdefault}. In either case, the required arguments start with +@code{#2}. + +Omitting @code{[@var{optargdefault}]} is different from having the +square brackets with no contents, as in @code{[]}. The former sets +@code{#1} to the value of @var{optargdefault}; the latter sets @code{#1} +to the empty string. + +@item defn +Required; the text to be substituted for every occurrence of +@code{\@var{cmd}}. The parameters @code{#1}, @code{#2}, +... @code{#@var{nargs}} are replaced by the values that you supply when +you call the command (or by the default value if there is an optional +argument and you don't exercise the option). + +@end table + +@TeX{} ignores spaces in the source following an alphabetic control +sequence, as in @samp{\cmd }. If you actually want a space there, one +solution is to type @code{@{@}} after the command (@samp{\cmd@{@} }, and +another solution is to use an explicit control space (@samp{\cmd\ }). + +A simple example of defining a new command: +@code{\newcommand@{\RS@}@{Robin Smith@}} results in @code{\RS} being +replaced by the longer text. Redefining an existing command is similar: +@code{\renewcommand@{\qedsymbol@}@{@{\small QED@}@}}. + +If you try to define a command and the name has already been used then +you get something like @samp{LaTeX Error: Command \fred already +defined. Or name \end... illegal, see p.192 of the manual}. If you try +to redefine a command and the name has not yet been used then you get +something like @samp{LaTeX Error: \hank undefined}. + +Here the first command definition has no arguments, and the second has +one required argument. + +@example +\newcommand@{\student@}@{Ms~O'Leary@} +\newcommand@{\defref@}[1]@{Definition~\ref@{#1@}@} +@end example + +@noindent +Use the first as in @code{I highly recommend \student@{@} to you}. The +second has a variable, so that @code{\defref@{def:basis@}} expands to +@code{Definition~\ref@{def:basis@}}, which ultimately expands to +something like @samp{Definition~3.14}. + +Similarly, but with two required arguments: +@code{\newcommand@{\nbym@}[2]@{$#1 \times #2$@}} is invoked as +@code{\nbym@{2@}@{k@}}. + +This example has an optional argument. + +@example +\newcommand@{\salutation@}[1][Sir or Madam]@{Dear #1:@} +@end example + +@noindent +Then @code{\salutation} gives @samp{Dear Sir or Madam:} while +@code{\salutation[John]} gives @samp{Dear John:}. And +@code{\salutation[]} gives @samp{Dear :}. + +This example has an optional argument and two required arguments. + +@example +\newcommand@{\lawyers@}[3][company]@{#2, #3, and~#1@} +I employ \lawyers[Howe]@{Dewey@}@{Cheatem@}. +@end example + +@noindent +The output is @samp{I employ Dewey, Cheatem, and Howe}. The optional +argument, the @code{Howe}, is associated with @code{#1}, while +@code{Dewey} and @code{Cheatem} are associated with @code{#2} +and@tie{}@code{#3}. Because of the optional argument, +@code{\lawyers@{Dewey@}@{Cheatem@}} will give the output @samp{I employ +Dewey, Cheatem, and company}. + +The braces around @var{defn} do not define a group, that is, they do not +delimit the scope of the result of expanding @var{defn}. For example, +with @code{\newcommand@{\shipname@}[1]@{\it #1@}}, in this sentence, + +@example +The \shipname@{Monitor@} met the \shipname@{Merrimac@}. +@end example + +@noindent +the words @samp{met the} would incorrectly be in italics. The solution +is to put another pair of braces inside the definition: +@code{\newcommand@{\shipname@}[1]@{@{\it #1@}@}}. + + +@node \providecommand +@section @code{\providecommand} + +@findex \providecommand +@cindex commands, defining new ones +@cindex defining a new command +@cindex new commands, defining + +Synopses, one of: + +@example +\providecommand@{@var{cmd}@}@{@var{defn}@} +\providecommand@{@var{cmd}@}[@var{nargs}]@{@var{defn}@} +\providecommand@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +\providecommand*@{@var{cmd}@}@{@var{defn}@} +\providecommand*@{@var{cmd}@}[@var{nargs}]@{@var{defn}@} +\providecommand*@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +@end example + +Defines a command, as long as no command of this name already exists. +If no command of this name already exists then this has the same effect +as @code{\newcommand}. If a command of this name already exists then +this definition does nothing. This is particularly useful in a file +that may be loaded more than once, such as a style file. +@xref{\newcommand & \renewcommand} for the description of the arguments. + +This example + +@example +\providecommand@{\myaffiliation@}@{Saint Michael's College@} +\providecommand@{\myaffiliation@}@{Saint Michael's College@} +From \myaffiliation. +@end example + +@noindent +outputs @samp{From Saint Michael's College}. Unlike @code{\newcommand}, +the repeated use of @code{\providecommand} does not give an error. + + +@node \makeatletter & \makeatother +@section @code{\makeatletter} & @code{\makeatother} + +Synopsis: + +@example +\makeatletter + ... definition of commands with @@ in their name .. +\makeatother +@end example + +Use this pair when you redefine @LaTeX{} commands that are named with an +at-sign character@tie{}@samp{@code{@@}}. The @code{\makeatletter} +declaration makes the at-sign character have the category code of a +letter, code@tie{}11. The @code{\makeatother} declaration sets the +category code of the at-sign to code@tie{}12, its default value. + +As @TeX{} reads characters, it assigns each one a category code, or +@cindex catcode +@cindex character category code +@cindex category code, character +@dfn{catcode}. For instance, it assigns the backslash +character@tie{}@samp{@code{\}} the catcode@tie{}0. Command names +consist of a category@tie{}0 character, ordinarily backslash, followed +by letters, category@tie{}11 characters (except that a command name can +also consist of a category@tie{}0 character followed by a single +non-letter symbol). + +@LaTeX{}'s source code has the convention that some commands use +@code{@@} in their name. These commands are mainly intended for package +or class writers. The convention prevents authors who are just using a +package or class from accidentally replacing such a command with one of +their own, because by default the at-sign has catcode@tie{}12. + +The pair @code{\makeatletter} and @code{\makeatother} changes the +default code and then changes it back. Use them inside a @file{.tex} +file, in the preamble, when you are defining or redefining commands +named with @code{@@}, by having them surround your definition. Don't +use these inside @file{.sty} or @file{.cls} files since the +@code{\usepackage} and @code{\documentclass} commands already arrange +that the at-sign has the character code of a letter, catcode@tie{}11. + +@PkgIndex{macros2e} +For a comprehensive list of macros with an at-sign in their names see +@url{http://ctan.org/pkg/macros2e}. + +In this example the class file has a command +@code{\thesis@@universityname} that the user wants to change. These +three lines should go in the preamble, before the +@code{\begin@{document@}}. + +@example +\makeatletter +\renewcommand@{\thesis@@universityname@}@{Saint Michael's College@} +\makeatother +@end example + + +@node \@@ifstar +@section @code{\@@ifstar} + +@findex \@@ifstar +@cindex commands, star-variants +@cindex star-variants, commands + +Synopsis: + +@example +\newcommand@{\mycmd@}@{\@@ifstar@{\mycmd@@star@}@{\mycmd@@nostar@}@} +\newcommand@{\mycmd@@nostar@}[@var{nostar-num-args}]@{@var{nostar-body}@} +\newcommand@{\mycmd@@star@}[@var{star-num-args}]@{@var{star-body}@} +@end example + +Many standard @LaTeX{} environments or commands have a variant with the +same name but ending with a star character@tie{}@code{*}, an asterisk. +Examples are the @code{table} and @code{table*} environments and the +@code{\section} and @code{\section*} commands. + +When defining environments, following this pattern is straightforward +because @code{\newenvironment} and @code{\renewenvironment} allow the +environment name to contain a star. For commands the situation is more +complex. As in the synopsis above, there will be a user-called command, +given above as @code{\mycmd}, which peeks ahead to see if it is followed +by a star. For instance, @LaTeX{} does not really have a +@code{\section*} command; instead, the @code{\section} command peeks +ahead. This command does not accept arguments but instead expands to +one of two commands that do accept arguments. In the synopsis these two +are @code{\mycmd@@nostar} and @code{\mycmd@@star}. They could take the +same number of arguments or a different number, or no arguments at all. +As always, in a @LaTeX{} document a command using at-sign@tie{}@code{@@} +must be enclosed inside a @code{\makeatletter ... \makeatother} block +(@pxref{\makeatletter & \makeatother}). + +This example of @code{\@@ifstar} defines the command @code{\ciel} and a +variant @code{\ciel*}. Both have one required argument. A call to +@code{\ciel@{night@}} will return "starry night sky" while +@code{\ciel*@{blue@}} will return "starry not blue sky". + +@example +\newcommand*@{\ciel@@unstarred@}[1]@{starry #1 sky@} +\newcommand*@{\ciel@@starred@}[1]@{starry not #1 sky@} +\newcommand*@{\ciel@}@{\@@ifstar@{\ciel@@starred@}@{\ciel@@unstarred@}@} +@end example + +In the next example, the starred variant takes a different number of +arguments than the unstarred one. With this definition, Agent 007's +@code{``My name is \agentsecret*@{Bond@}, +\agentsecret@{James@}@{Bond@}.''} is equivalent to entering the commands +@code{``My name is \textsc@{Bond@}, \textit@{James@} textsc@{Bond@}.''} + +@example +\newcommand*@{\agentsecret@@unstarred@}[2]@{\textit@{#1@} \textsc@{#2@}@} +\newcommand*@{\agentsecret@@starred@}[1]@{\textsc@{#1@}@} +\newcommand*@{\agentsecret@}@{% + \@@ifstar@{\agentsecret@@starred@}@{\agentsecret@@unstarred@}@} +@end example + +There are two sometimes more convenient ways to accomplish the work of +@code{\@@ifstar}. The @file{suffix} package allows the construct +@code{\newcommand\mycommand@{@var{unstarred version}@}} followed by +@code{\WithSuffix\newcommand\mycommand*@{@var{starred version}@}}. And +@LaTeX{}3 has the @file{xparse} package that allows this code. + +@example +\NewDocumentCommand\foo@{s@}@{\IfBooleanTF#1 + @{@var{starred version}@}% + @{@var{unstarred version}@}% + @} +@end example + + +@node \newcounter +@section @code{\newcounter}: Allocating a counter + +@findex \newcounter +@cindex counters, defining new + +Synopsis, one of: + +@example +\newcounter@{@var{countername}@} +\newcounter@{@var{countername}@}[@var{supercounter}] +@end example + +Globally defines a new counter named @var{countername} and initialize it +to zero (@pxref{Counters}). + +The name @var{countername} must consist of letters only. It does not +begin with a backslash. This name must not already be in use by another +counter. + +When you use the optional argument @code{[@var{supercounter}]} then the +counter @var{countername} will be reset to zero whenever +@var{supercounter} is incremented. For example, ordinarily +@code{subsection} is numbered within @code{section} so that any time you +increment @var{section}, either with @code{\stepcounter} +(@pxref{\stepcounter}) or @code{\refstepcounter} +(@pxref{\refstepcounter}), then @LaTeX{} will reset @var{subsection} to +zero. + +This example + +@example +\newcounter@{asuper@} \setcounter@{asuper@}@{1@} +\newcounter@{asub@}[asuper] \setcounter@{asub@}@{3@} % Note `asuper' +The value of asuper is \arabic@{asuper@} and of asub is \arabic@{asub@}. +\stepcounter@{asuper@} +Now asuper is \arabic@{asuper@} while asub is \arabic@{asub@}. +@end example + +produces @samp{The value of asuper is 1 and that of asub is 3} and +@samp{Now asuper is 2 while asub is 0}. + +If the counter already exists, for instance by entering @code{asuper} +twice, then you get something like @samp{LaTeX Error: Command \c@@asuper +already defined. Or name \end... illegal, see p.192 of the manual.}. + +If you use the optional argument then the super counter must already +exist. Entering @code{\newcounter@{jh@}[lh]} when @code{lh} is not a +defined counter will get you @samp{LaTeX Error: No counter 'lh' +defined.} + + +@node \newlength +@section @code{\newlength} + +@findex \newlength +@cindex lengths, allocating new +@cindex rubber lengths, defining new +@cindex skip register, plain @TeX{} +@cindex glue register, plain @TeX{} + +Synopsis: + +@example +\newlength@{@var{arg}@} +@end example + +Allocate a new length register (@pxref{Lengths}). The required argument +@var{arg} must begin with a backslash, @code{\}. The new register holds +rubber lengths such as @code{72.27pt} or @code{1in plus.2in minus.1in} +(a @LaTeX{} length register is what plain @TeX{} calls a @code{skip} +register). The initial value is zero. The control sequence +@code{\@var{arg}} must not be already defined. + +An example: + +@example +\newlength@{\graphichgt@} +@end example + +If you forget the backslash then you get @samp{Missing control sequence +inserted}. If the command sequence already exists then you get +something like @samp{LaTeX Error: Command \graphichgt already defined. +Or name \end... illegal, see p.192 of the manual}. + + +@node \newsavebox +@section @code{\newsavebox} + +@findex \newsavebox +@cindex box, allocating new + +Synopsis: + +@example +\newsavebox@{\@var{cmd}@} +@end example + +Define \@var{cmd}, the string consisting of a backslash followed by +@var{cmd}, to refer to a new bin for storing material. These bins hold +material that has been typeset, to use multiple times or to measure or +manipulate (@pxref{Boxes}). The bin name \@var{cmd} is required, must +start with a backslash, \, and must not already be a defined command. +This command is fragile (@pxref{\protect}). + +This allocates a bin and then puts typeset material into it. + +@example +\newsavebox@{\logobox@} +\savebox@{\logobox@}@{LoGo@} +Our logo is \usebox@{\logobox@}. +@end example + +@noindent +The output is @samp{Our logo is LoGo}. + +If there is an already defined bin then you get something like +@samp{LaTeX Error: Command \logobox already defined. Or name +\end... illegal, see p.192 of the manual}. + +The allocation of a box is global. + + +@node \newenvironment & \renewenvironment +@section @code{\newenvironment} & @code{\renewenvironment} + +@findex \newenvironment +@findex \renewenvironment +@cindex environments, defining +@cindex defining new environments +@cindex redefining environments + +Synopses, one of: + +@example +\newenvironment@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@} +\newenvironment@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@} +\newenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@} +\newenvironment*@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@} +\newenvironment*@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@} +\newenvironment*@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@} +@end example + +@noindent +or one of these. + +@example +\renewenvironment@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@} +\renewenvironment@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@} +\renewenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@} +\renewenvironment*@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@} +\renewenvironment*@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@} +\renewenvironment*@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@} +@end example + +Define or redefine the environment @var{env}, that is, create the +construct @code{\begin@{@var{env}@} ... @var{body} ... \end@{@var{env}@}}. + +@cindex @code{*}-form of environment commands +The starred form of these commands requires that the arguments not +contain multiple paragraphs of text. However, the body of these +environments can contain multiple paragraphs. + +@table @var +@item env +Required; the environment name. It consists only of letters or the +@code{*} character, and thus does not begin with backslash, @code{\}. +It must not begin with the string @code{end}. For +@code{\newenvironment}, the name @var{env} must not be the name of an +already existing environment, and also the command @code{\@var{env}} +must be undefined. For @code{\renewenvironment}, @var{env} must be the +name of an existing environment. + +@item nargs +Optional; an integer from 0 to 9 denoting the number of arguments of +that the environment takes. When you use the environment these +arguments appear after the @code{\begin}, as in +@code{\begin@{@var{env}@}@{@var{arg1}@} ... @{@var{argn}@}}. Omitting +this is equivalent to setting it to 0; the environment will have no +arguments. When redefining an environment, the new version can have a +different number of arguments than the old version. + +@item optargdefault +Optional; if this is present then the first argument of the defined +environment is optional, with default value @var{optargdefault} (which +may be the empty string). If this is not in the definition then the +environment does not take an optional argument. + +That is, when @var{optargdefault} is present in the definition of the +environment then you can start the environment with square brackets, as +in @code{\begin@{@var{env}@}[@var{optval}]@{...@} ... \end@{@var{env}@}}. +In this case, within @var{begdefn} the parameter @code{#1} is set to the +value of @var{optval}. If you call @code{\begin@{@var{env}@}} without +square brackets, then within @var{begdefn} the parameter @code{#1} is +set to the value of the default @var{optargdefault}. In either case, +any required arguments start with @code{#2}. + +Omitting @code{[@var{myval}]} in the call is different than having the +square brackets with no contents, as in @code{[]}. The former results +in @code{#1} expanding to @var{optargdefault}; the latter results in +@code{#1} expanding to the empty string. + +@item begdef +Required; the text expanded at every occurrence of +@code{\begin@{@var{env}@}}. Within @var{begdef}, the parameters +@code{#1}, @code{#2}, ... @code{#@var{nargs}}, are replaced by the +values that you supply when you call the environment; see the examples +below. + +@item enddef +Required; the text expanded at every occurrence of +@code{\end@{@var{env}@}}. This may not contain any parameters, that is, +you cannot use @code{#1}, @code{#2}, etc., here (but see the final +example below). + +@end table + +All environments, that is to say the @var{begdef} code, the environment +body, and the @var{enddef} code, are processed within a group. Thus, in +the first example below, the effect of the @code{\small} is limited to +the quote and does not extend to material following the environment. + +If you try to define an environment and the name has already been used +then you get something like @samp{LaTeX Error: Command \fred already +defined. Or name \end... illegal, see p.192 of the manual}. If you try +to redefine an environment and the name has not yet been used then you +get something like @samp{LaTeX Error: Environment hank undefined.}. + +This example gives an environment like @LaTeX{}'s @code{quotation} +except that it will be set in smaller type. + +@example +\newenvironment@{smallquote@}@{% + \small\begin@{quotation@} +@}@{% + \end@{quotation@} +@} +@end example + +This has an argument, which is set in boldface at the start of a +paragraph. + +@example +\newenvironment@{point@}[1]@{% + \noindent\textbf@{#1@} +@}@{% +@} +@end example + +This one shows the use of a optional argument; it gives a quotation +environment that cites the author. + +@example +\newenvironment@{citequote@}[1][Shakespeare]@{% + \begin@{quotation@} + \noindent\textit@{#1@}: +@}@{% + \end@{quotation@} +@} +@end example + +@noindent +The author's name is optional, and defaults to @samp{Shakespeare}. In +the document, use the environment like this. + +@example +\begin@{citequote@}[Lincoln] + ... +\end@{citequote@} +@end example + +The final example shows how to save the value of an argument to use in +@var{enddef}, in this case in a box (@pxref{\sbox & \savebox}). + +@example +\newsavebox@{\quoteauthor@} +\newenvironment@{citequote@}[1][Shakespeare]@{% + \sbox\quoteauthor@{#1@}% + \begin@{quotation@} +@}@{% + \hspace@{1em plus 1fill@}---\usebox@{\quoteauthor@} + \end@{quotation@} +@} +@end example + + +@node \newtheorem +@section @code{\newtheorem} + +@findex \newtheorem +@cindex theorems, defining +@cindex defining new theorems + +@cindex theorem-like environment +@cindex environment, theorem-like +Synopses: + +@example +\newtheorem@{@var{name}@}@{@var{title}@} +\newtheorem@{@var{name}@}@{@var{title}@}[@var{numbered_within}] +\newtheorem@{@var{name}@}[@var{numbered_like}]@{@var{title}@} +@end example + +Define a new theorem-like environment. You can specify one of +@var{numbered_within} and @var{numbered_like}, or neither, but not both. + +The first form, @code{\newtheorem@{@var{name}@}@{@var{title}@}}, creates +an environment that will be labelled with @var{title}; see the first +example below. + +The second form, +@code{\newtheorem@{@var{name}@}@{@var{title}@}[@var{numbered_within}]}, +creates an environment whose counter is subordinate to the existing +counter @var{numbered_within}, so this counter will be reset when +@var{numbered_within} is reset. See the second example below. + +The third form +@code{\newtheorem@{@var{name}@}[@var{numbered_like}]@{@var{title}@}}, +with optional argument between the two required arguments, creates an +environment whose counter will share the previously defined counter +@var{numbered_like}. See the third example. + +This command creates a counter named @var{name}. In addition, unless +the optional argument @var{numbered_like} is used, inside of the +theorem-like environment the current @code{\ref} value will be that of +@code{\the@var{numbered_within}} (@pxref{\ref}). + +This declaration is global. It is fragile (@pxref{\protect}). + +Arguments: + +@table @var +@item name +The name of the environment. It is a string of letters. It must not +begin with a backslash, @code{\}. It must not be the name of an +existing environment, and the command name @code{\@var{name}} must not +already be defined. + +@item title +The text to be printed at the beginning of the environment, before the +number. For example, @samp{Theorem}. + +@item numbered_within +Optional; the name of an already defined counter, usually a sectional +unit such as @code{chapter} or @code{section}. When the +@var{numbered_within} counter is reset then the @var{name} environment's +counter will also be reset. + +If this optional argument is not used then the command +@code{\the@var{name}} is set to @code{\arabic@{@var{name}@}}. + +@item numbered_like +Optional; the name of an already defined theorem-like environment. The +new environment will be numbered in sequence with @var{numbered_like}. + +@end table + +Without any optional arguments the environments are numbered +sequentially. The example below has a declaration in the preamble that +results in @samp{Definition@tie{}1} and @samp{Definition@tie{}2} in the +output. + +@example +\newtheorem@{defn@}@{Definition@} +\begin@{document@} +\section@{...@} +\begin@{defn@} + First def +\end@{defn@} + +\section@{...@} +\begin@{defn@} + Second def +\end@{defn@} +@end example + +This example has the same document body as the prior one. But here +@code{\newtheorem}'s optional argument @var{numbered_within} is given as +@code{section}, so the output is like @samp{Definition@tie{}1.1} and +@samp{Definition@tie{}2.1}. + +@example +\newtheorem@{defn@}@{Definition@}[section] +\begin@{document@} +\section@{...@} +\begin@{defn@} + First def +\end@{defn@} + +\section@{...@} +\begin@{defn@} + Second def +\end@{defn@} +@end example + +In the next example there are two declarations in the preamble, the +second of which calls for the new @code{thm} environment to use the same +counter as @code{defn}. It gives @samp{Definition@tie{}1.1}, followed +by @samp{Theorem@tie{}2.1} and @samp{Definition@tie{}2.2}. + +@example +\newtheorem@{defn@}@{Definition@}[section] +\newtheorem@{thm@}[defn]@{Theorem@} +\begin@{document@} +\section@{...@} +\begin@{defn@} + First def +\end@{defn@} + +\section@{...@} +\begin@{thm@} + First thm +\end@{thm@} + +\begin@{defn@} + Second def +\end@{defn@} +@end example + + +@node \newfont +@section @code{\newfont} + +@findex \newfont +@cindex fonts, new commands for +@cindex defining new fonts + +@c @findex .fd @r{file} +This command is obsolete. This description is here only to help with old +documents. New documents should define fonts in families through the +New Font Selection Scheme which allows you to, for example, associate a +boldface with a roman (@pxref{Fonts}). +@c This is done either by using +@c @file{.fd} files or through the use of an engine that can access system +@c fonts such as Xe@LaTeX{} (@pxref{@TeX{} engines}). + +Synopsis: + +@example +\newfont@{\@var{cmd}@}@{@var{font description}@} +@end example + +Define a command @code{\@var{cmd}} that will change the current font. +The control sequence must not already be defined. It must begin with a +backslash, @code{\}. + +@cindex at clause, in font definitions +@cindex design size, in font definitions +The @var{font description} consists of a @var{fontname} and an optional +@dfn{at clause}. @LaTeX{} will look on your system for a file named +@file{@var{fontname}.tfm}. The at clause can have the form either +@code{at @var{dimen}} or @code{scaled @var{factor}}, where a +@var{factor} of @samp{1000} means no scaling. For @LaTeX{}'s purposes, +all this does is scale all the character and other font dimensions +relative to the font's design size, which is a value defined in the +@file{.tfm} file. + +This defines two equivalent fonts and typesets a few characters in each. + +@example +\newfont@{\testfontat@}@{cmb10 at 11pt@} +\newfont@{\testfontscaled@}@{cmb10 scaled 1100@} +\testfontat abc +\testfontscaled abc +@end example + + +@node \protect +@section @code{\protect} + +@findex \protect +@cindex fragile commands +@cindex robust commands + +All @LaTeX{} commands are either @dfn{fragile} or @dfn{robust}. A +fragile command can break when it is used in the argument to certain +other commands. Commands that contain data that @LaTeX{} writes to an +auxiliary file and re-reads later are fragile. This includes material +that goes into a table of contents, list of figures, list of tables, +etc. Fragile commands also include line breaks, any command that has an +optional argument, and many more. To prevent such commands from +breaking, one solution is to preceded them with the command +@code{\protect}. + +For example, when @LaTeX{} runs the @code{\section@{@var{section +name}@}} command it writes the @var{section name} text to the +@file{.aux} auxiliary file, moving it there for use elsewhere in the +document such as in the table of contents. Any argument that is +internally expanded by @LaTeX{} without typesetting it directly is +referred to as a +@cindex moving arguments +@dfn{moving argument}. A command is fragile if it can +expand during this process into invalid @TeX{} code. Some examples of +moving arguments are those that appear in the @code{\caption@{...@}} +command (@pxref{figure}), in the @code{\thanks@{...@}} command +(@pxref{\maketitle}), and in @@-expressions in the @code{tabular} and +@code{array} environments (@pxref{tabular}). + +If you get strange errors from commands used in moving arguments, try +preceding it with @code{\protect}. Every fragile commands must be +protected with their own @code{\protect}. + +Although usually a @code{\protect} command doesn't hurt, length +commands are robust and should not be preceded by a @code{\protect} +command. Nor can a @code{\protect} command be used in the argument to +@code{\addtocounter} or @code{\setcounter} command. + +In this example the @code{\caption} command gives a mysterious error +about an extra curly brace. Fix the problem by preceding each +@code{\raisebox} command with @code{\protect}. + +@example +\begin@{figure@} + ... + \caption@{Company headquarters of A\raisebox@{1pt@}@{B@}\raisebox@{-1pt@}@{C@}@} +\end@{figure@} +@end example + +In the next example the @code{\tableofcontents} command gives an error +because the @code{\(..\)} in the section title expands to illegal @TeX{} +in the @file{.toc} file. You can solve this by changing @code{\(..\)} +to @code{\protect\(..\protect\)}. + +@example +\begin@{document@} +\tableofcontents +... +\section@{Einstein's \( e=mc^2 \)@} +... +@end example + + +@node \ignorespaces & \ignorespacesafterend +@section @code{\ignorespaces & \ignorespacesafterend} + +@findex \ignorespaces +@findex \ignorespacesafterend +@cindex spaces, ignore around commands +@cindex commands, ignore spaces + +Synopsis: + +@example +\ignorespaces +@end example + +@noindent +or + +@example +\ignorespacesafterend +@end example + +Both commands cause @LaTeX{} to ignore spaces after the end of the +command up until the first non-space character. The first is a command +from Plain @TeX{}, and the second is @LaTeX{}-specific. + +The @code{ignorespaces} is often used when defining commands via +@code{\newcommand}, or @code{\newenvironment}, or @code{\def}. The +example below illustrates. It allows a user to show the points values +for quiz questions in the margin but it is inconvenient because, as +shown in the @code{enumerate} list, users must not put any space between +the command and the question text. + +@example +\newcommand@{\points@}[1]@{\makebox[0pt]@{\makebox[10em][l]@{#1~pts@}@} +\begin@{enumerate@} + \item\points@{10@}no extra space output here + \item\points@{15@} extra space between the number and the `extra' +\end@{enumerate@} +@end example + +@noindent +The solution is to change to this. + +@example +\newcommand@{\points@}[1]@{% + \makebox[0pt]@{\makebox[10em][l]@{#1~pts@}@}\ignorespaces@} +@end example + +A second example shows spaces being removed from the front of text. The +commands below allow a user to uniformly attach a title to names. But, +as given, if a title accidentally starts with a space then +@code{\fullname} will reproduce that. + +@example +\makeatletter +\newcommand@{\honorific@}[1]@{\def\@@honorific@{#1@}@} % remember title +\newcommand@{\fullname@}[1]@{\@@honorific~#1@} % put title before name +\makeatother +\begin@{tabular@}@{|l|@} +\honorific@{Mr/Ms@} \fullname@{Jones@} \\ % no extra space here +\honorific@{ Mr/Ms@} \fullname@{Jones@} % extra space before title +\end@{tabular@} +@end example + +@noindent +To fix this, change to +@code{\newcommand@{\fullname@}[1]@{\ignorespaces\@@honorific~#1@}}. + +The @code{\ignorespaces} is also often used in a @code{\newenvironment} +at the end of the @var{begin} clause, that is, as part of the second +argument, as in @code{\begin@{newenvironment@}@{@var{env +name}@}@{... \ignorespaces@}@{...@}}. + +To strip spaces off the end of an environment use +@code{\ignorespacesafterend}. An example is that this will show a much +larger vertical space between the first and second environments than +between the second and third. + +@example +\newenvironment@{eq@}@{\begin@{equation@}@}@{\end@{equation@}@} +\begin@{eq@} +e=mc^2 +\end@{eq@} +\begin@{equation@} +F=ma +\end@{equation@} +\begin@{equation@} +E=IR +\end@{equation@} +@end example + +Putting a comment character@tie{}@code{%} immediately after the +@code{\end@{eq@}} will make the vertical space disappear, but that is +inconvenient. The solution is to change to +@code{\newenvironment@{eq@}@{\begin@{equation@}@}@{\end@{equation@}\ignorespacesafterend@}}. + + +@node Counters +@chapter Counters + +@cindex counters, a list of +@cindex variables, a list of + +Everything @LaTeX{} numbers for you has a counter associated with +it. The name of the counter is often the same as the name of the +environment or command associated with the number, except that the +counter's name has no backslash@tie{}@code{\}. Thus, associated with +the @code{\chapter} command is the @code{chapter} counter that keeps +track of the chapter number. + +Below is a list of the counters used in @LaTeX{}'s standard document +classes to control numbering. + +@example +part paragraph figure enumi +chapter subparagraph table enumii +section page footnote enumiii +subsection equation mpfootnote enumiv +subsubsection +@end example + +The @code{mpfootnote} counter is used by the @code{\footnote} command +inside of a minipage (@pxref{minipage}). The counters @code{enumi} +through @code{enumiv} are used in the @code{enumerate} environment, for +up to four levels of nesting (@pxref{enumerate}). + +Counters can have any integer value but they are typically positive. + +New counters are created with @code{\newcounter}. @xref{\newcounter}. + + +@menu +* \alph \Alph \arabic \roman \Roman \fnsymbol:: Print value of a counter. +* \usecounter:: Use a specified counter in a list environment. +* \value:: Use the value of a counter in an expression. +* \setcounter:: Set the value of a counter. +* \addtocounter:: Add a quantity to a counter. +* \refstepcounter:: Add to a counter. +* \stepcounter:: Add to a counter, resetting subsidiary counters. +* \day & \month & \year:: Numeric date values. +@end menu + + +@node \alph \Alph \arabic \roman \Roman \fnsymbol +@section @code{\alph \Alph \arabic \roman \Roman \fnsymbol}: Printing counters + +@cindex counters, printing + +Print the value of a counter, in a specified style. For instance, if +the counter @var{counter} has the value 1 then a +@code{\alph@{@var{counter}@}} in your source will result in a lowercase +letter@tie{}a appearing in the output. + +All of these commands take a single counter as an argument, for +instance, @code{\alph@{enumi@}}. Note that the counter name does not +start with a backslash. + +@ftable @code +@item \alph@{@var{counter}@} +Print the value of @var{counter} in lowercase letters: `a', `b', +@enddots{} If the counter's value is less than 1 or more than 26 then +you get @samp{LaTeX Error: Counter too large.} + +@item \Alph@{@var{counter}@} +Print in uppercase letters: `A', `B', @enddots{} If the counter's value +is less than 1 or more than 26 then you get @samp{LaTeX Error: Counter +too large.} + +@item \arabic@{@var{counter}@} +Print in Arabic numbers such as @samp{5} or @samp{-2}. + +@item \roman@{@var{counter}@} +Print in lowercase roman numerals: `i', `ii', @enddots{} If the +counter's value is less than 1 then you get no warning or error but +@LaTeX{} does not print anything in the output. + +@item \Roman@{@var{counter}@} +Print in uppercase roman numerals: `I', `II', @enddots{} If the +counter's value is less than 1 then you get no warning or error but +@LaTeX{} does not print anything in the output. + +@item \fnsymbol@{@var{counter}@} +Prints the value of @var{counter} using a sequence of nine symbols that +are traditionally used for labeling footnotes. The value of +@var{counter} should be between@tie{}1 and@tie{}9, inclusive. If the +counter's value is less than 0 or more than 9 then you get @samp{LaTeX +Error: Counter too large}, while if it is 0 then you get no error or +warning but @LaTeX{} does not output anything. + +Here are the symbols: + +@multitable @columnfractions .10 .30 .30 .30 +@headitem Number@tab Name@tab Command@tab Symbol +@item +1@tab asterisk@tab@code{\ast}@tab@iftexthenelse{@math{\ast},*} +@item +2@tab dagger@tab@code{\dagger}@tab@BES{2020,\dagger} +@item +3@tab ddagger@tab@code{\ddagger}@tab@BES{2021,\ddagger} +@item +4@tab section-sign@tab@code{\S}@tab@BES{00A7,\S} +@item +5@tab paragraph-sign@tab@code{\P}@tab@BES{00B6,\P} +@item +6@tab double-vert@tab@code{\parallel}@tab@BES{2016,\parallel} +@item +7@tab double-asterisk@tab@code{\ast\ast}@tab@iftexthenelse{@math{\ast\ast},**} +@item +8@tab + double-dagger@tab@code{\dagger\dagger}@tab@BES{2020,\dagger}@BES{2020,\dagger} +@item +9@tab + double-ddagger@tab@code{\ddagger\ddagger}@tab@BES{2021,\ddagger}@BES{2021,\ddagger} +@end multitable + +@end ftable + + +@node \usecounter +@section @code{\usecounter} + +@findex \usecounter +@cindex list items, specifying counter +@cindex numbered items, specifying counter + +Synopsis: + +@example +\usecounter@{@var{counter}@} +@end example + +Used in the second argument of the @code{list} environment +(@pxref{list}), this declares that list items will be numbered by +@var{counter}. It initializes @var{counter} to zero, and arranges that +when @code{\item} is called without its optional argument then +@var{counter} is incremented by @code{\refstepcounter}, making its value +be the current @code{ref} value (@pxref{\ref}). This command is fragile +(@pxref{\protect}). + +Put in the document preamble, this example makes a new list environment +enumerated with @var{testcounter}: + +@example +\newcounter@{testcounter@} +\newenvironment@{test@}@{% + \begin@{list@}@{@}@{% + \usecounter@{testcounter@} + @} +@}@{% + \end@{list@} +@} +@end example + + +@node \value +@section @code{\value} + +@findex \value +@cindex counters, getting value of + +Synopsis: + +@example +\value@{@var{counter}@} +@end example + +Expands to the value of the counter @var{counter}. (Note that the name +of a counter does not begin with a backslash.) + +This example outputs @samp{Test counter is@tie{}6. Other counter +is@tie{}5.}. + +@example +\newcounter@{test@} \setcounter@{test@}@{5@} +\newcounter@{other@} \setcounter@{other@}@{\value@{test@}@} +\addtocounter@{test@}@{1@} + +Test counter is \arabic@{test@}. +Other counter is \arabic@{other@}. +@end example + +The @code{\value} command is not used for typesetting the value of the +counter. For that, see @ref{\alph \Alph \arabic \roman \Roman \fnsymbol}. + +It is often used in @code{\setcounter} or @code{\addtocounter} but +@code{\value} can be used anywhere that @LaTeX{} expects a number, such +as in @code{\hspace@{\value@{foo@}\parindent@}}. It must not be +preceded by @code{\protect} (@pxref{\protect}). + +This example inserts @code{\hspace@{4\parindent@}}. + +@example +\setcounter@{myctr@}@{3@} \addtocounter@{myctr@}@{1@} +\hspace@{\value@{myctr@}\parindent@} +@end example + + +@node \setcounter +@section @code{\setcounter} + +@findex \setcounter +@cindex counters, setting +@cindex setting counters + +Synopsis: + +@example +\setcounter@{@var{counter}@}@{@var{value}@} +@end example + +Globally set the counter @var{counter} to have the value of the +@var{value} argument, which must be an integer. Thus, you can set a +counter's value as @code{\setcounter@{section@}@{5@}}. Note that the +counter name does not start with a backslash. + +In this example if the counter @code{theorem} has value 12 then the +second line will print @samp{XII}. + +@example +\setcounter@{exercise@}@{\value@{theorem@}@} +Here it is in Roman: \Roman@{exercise@}. +@end example + + +@node \addtocounter +@section @code{\addtocounter} + +@findex \addtocounter + +Synopsis: + +@example +\addtocounter@{@var{counter}@}@{@var{value}@ +@end example + +Globally increment @var{counter} by the amount specified by the +@var{value} argument, which may be negative. + +In this example the section value appears as @samp{VII}. + +@example +\setcounter@{section@}@{5@} +\addtocounter@{section@}@{2@} +Here it is in Roman: \Roman@{section@}. +@end example + + +@node \refstepcounter +@section @code{\refstepcounter} + +@findex \refstepcounter + +Synopsis: + +@example +\refstepcounter@{@var{counter}@} +@end example + +Globally increments the value of @var{counter} by one, as does +@code{\stepcounter} (@pxref{\stepcounter}). The difference is that this +command resets the value of any counter numbered within it. (For the +definition of ``counters numbered within'', @pxref{\newcounter}.) + +In addition, this command also defines the current @code{\ref} value +to be the result of @code{\thecounter}. + +While the counter value is set globally, the @code{\ref} value is set +locally, i.e., inside the current group. + + +@node \stepcounter +@section @code{\stepcounter} + +@findex \stepcounter + +Synopsis: + +@example +\stepcounter@{@var{counter}@} +@end example + +Globally adds one to @var{counter} and resets all counters numbered +within it. (For the definition of ``counters numbered within'', +@pxref{\newcounter}.) + +This command differs from @code{\refstepcounter} in that this one does +not influence references@tie{}--- it does not define the current +@code{\ref} value to be the result of @code{\thecounter} +(@pxref{\refstepcounter}). + + +@node \day & \month & \year +@section @code{\day} & @code{\month} & @code{\year} + +@findex \day +@findex \month +@findex \year + +@LaTeX{} defines the counter @code{\day} for the day of the month +(nominally with value between 1 and 31), @code{\month} for the month of +the year (nominally with value between 1 and 12), and year @code{\year}. +When @TeX{} starts up, they are set from the current values on the +system. The related command @code{\today} produces a string +representing the current day (@pxref{\today}). + +They counters are not updated as the job progresses so in principle they +could be incorrect by the end. In addition, @TeX{} does no sanity +check: + +@example +\day=-2 \month=13 \year=-4 \today +@end example + +@noindent +gives no error or warning and results in the output @samp{-2, -4} (the +bogus month value produces no output). + + +@node Lengths +@chapter Lengths + +@cindex lengths, defining and using + +A @dfn{length} is a measure of distance. Many @LaTeX{} commands take a +length as an argument. + +Lengths come in two types. A @dfn{rigid length} such as @code{10pt} +does not contain a @code{plus} or @code{minus} component. (Plain @TeX{} +calls this a @dfn{dimen}.) A @dfn{rubber length} (what Plain @TeX{} +calls a @dfn{skip}) such as as with @code{1cm plus0.05cm minus0.01cm} +can contain either or both of those components. In that rubber length, +the @code{1cm} is the @dfn{natural length} while the other two, the +@code{plus} and @code{minus} components, allow @TeX{} to stretch or +shrink the length to optimize placement. + +The illustrations below use these two commands. + +@example +% make a black bar 10pt tall and #1 wide +\newcommand@{\blackbar@}[1]@{\rule@{#1@}@{10pt@}@} + +% Make a box around #2 that is #1 wide (excluding the border) +\newcommand@{\showhbox@}[2]@{% + \fboxsep=0pt\fbox@{\hbox to #1@{#2@}@}@} +@end example + +@noindent +This example uses those commands to show a black bar 100@tie{}points +long between @samp{XXX} and @samp{YYY}. This length is rigid. + +@example +XXX\showhbox@{100pt@}@{\blackbar@{100pt@}@}YYY +@end example + +As for rubber lengths, shrinking is simpler one: with @code{1cm minus +0.05cm}, the natural length is 1@dmn{cm} but @TeX{} can shrink it down +as far as 0.95@dmn{cm}. Beyond that, @TeX{} refuses to shrink any more. +Thus, below the first one works fine, producing a space of +98@tie{}points between the two bars. + +@example +XXX\showhbox@{300pt@}@{% + \blackbar@{101pt@}\hspace@{100pt minus 2pt@}\blackbar@{101pt@}@}YYY + +XXX\showhbox@{300pt@}@{% + \blackbar@{105pt@}\hspace@{100pt minus 1pt@}\blackbar@{105pt@}@}YYY +@end example + +@noindent +But the second one gets a warning like @samp{Overfull \hbox (1.0pt too +wide) detected at line 17}. In the output the first @samp{Y} is +overwritten by the end of the black bar, because the box's material is +wider than the 300@dmn{pt} allocated, as @TeX{} has refused to shrink +the total to less than 309@tie{}points. + +Stretching is like shrinking except that if @TeX{} is asked to stretch +beyond the given amount, it will do it. Here the first line is fine, +producing a space of 110@tie{}points between the bars. + +@example +XXX\showhbox@{300pt@}@{% + \blackbar@{95pt@}\hspace@{100pt plus 10pt@}\blackbar@{95pt@}@}YYY + +XXX\showhbox@{300pt@}@{% + \blackbar@{95pt@}\hspace@{100pt plus 1pt@}\blackbar@{95pt@}@}YYY +@end example + +@noindent +In the second line @TeX{} needs a stretch of 10@tie{}points and only +1@tie{}point was specified. @TeX{} stretches the space to the required +length but it gives you a warning like @samp{Underfull \hbox (badness +10000) detected at line 22}. (We won't discuss badness.) + +You can put both stretch and shrink in the same length, as in +@code{1ex plus 0.05ex minus 0.02ex}. + +If @TeX{} is setting two or more rubber lengths then it allocates the +stretch or shrink in proportion. + +@example +XXX\showhbox@{300pt@}@{% + \blackbar@{100pt@}% left + \hspace@{0pt plus 50pt@}\blackbar@{80pt@}\hspace@{0pt plus 10pt@}% middle + \blackbar@{100pt@}@}YYY % right +@end example + +@noindent +The left and right bars take up 100@tie{}points, so the middle needs +another 100. The middle bar is 80@tie{}points so the two +@code{\hspace}'s must stretch 20@tie{}points. Because the two are +@code{plus 50pt} and @code{plus 10pt}, @TeX{} gets 5/6 of the stretch +from the first space and 1/6 from the second. + +The @code{plus} or @code{minus} component of a rubber length can contain +a @dfn{fill} component, as in @code{1in plus2fill}. This gives the +length infinite stretchability or shrinkability so that @TeX{} could set +it to any distance. Here the two figures will be equal-spaced across +the page. + +@example +\begin@{minipage@}@{\linewidth@} + \hspace@{0pt plus 1fill@}\includegraphics@{godel.png@}% + \hspace@{0pt plus 1fill@}\includegraphics@{einstein.png@}% + \hspace@{0pt plus 1fill@} +\end@{minipage@} +@end example + +@TeX{} actually has three levels of infinity for glue components: +@code{fil}, @code{fill}, and @code{filll}. The later ones are more +infinite than the earlier ones. Ordinarily document authors only use +the middle one (@pxref{\hfill} and @pxref{\vfill}). + +Multiplying a rubber length by a number turns it into a rigid length, so +that after @code{\setlength@{\ylength@}@{1in plus 0.2in@}} and +@code{\setlength@{\zlength@}@{3\ylength@}} then the value of +@code{\zlength} is @code{3in}. + +@menu +* Units of length:: The units that @LaTeX{} knows. +* \setlength:: Set the value of a length. +* \addtolength:: Add a quantity to a length. +* \settodepth:: Set a length to the depth of something. +* \settoheight:: Set a length to the height of something. +* \settowidth:: Set a length to the width of something. +@c * Predefined lengths:: Lengths that are, like, predefined. +@end menu + + +@node Units of length +@section Units of length + +@cindex units, of length + +@TeX{} and @LaTeX{} know about these units both inside and outside of +math mode. + +@table @code +@item pt +@findex pt +@cindex Point +@anchor{units of length pt} +Point, 1/72.27 inch. The conversion to metric units, to two decimal +places, is 1@dmn{point} = 2.85@dmn{mm} = 28.45@dmn{cm}. + +@item pc +@cindex pica +@findex pc +@anchor{units of length pc} +Pica, 12 pt + +@item in +@findex in +@findex inch +@anchor{units of length in} +Inch, 72.27 pt + +@item bp +@findex bp +@cindex Big point +@anchor{units of length bp} +Big point, 1/72 inch. This length is the definition of a point in +PostScript and many desktop publishing systems. + +@item cm +@cindex Centimeter +@findex cm +@anchor{units of length cm} +Centimeter + +@item mm +@cindex Millimeter +@findex mm +@anchor{units of length mm} +Millimeter + +@item dd +@cindex Didot point +@findex dd +@anchor{units of length dd} +Didot point, 1.07 pt + +@item cc +@cindex Cicero +@findex cc +@anchor{units of length cc} +Cicero, 12 dd + +@item sp +@cindex Scaled point +@findex sp +@anchor{units of length sp} +Scaled point, 1/65536 pt + +@end table + +@cindex ex +@cindex x-height +@findex ex +@cindex m-width +@cindex em +@findex em +@anchor{Lengths/em} +@anchor{Lengths/en} +@anchor{Lengths/ex} +@anchor{units of length em} +@anchor{units of length en} +@anchor{units of length ex} +Two other lengths that are often used are values set by the designer of +the font. The x-height of the current font @dfn{ex}, traditionally the +height of the lowercase letter x, is often used for vertical +lengths. Similarly @dfn{em}, traditionally the width of the capital +letter M, is often used for horizontal lengths (there is also +@code{\enspace}, which is @code{0.5em}). Use of these can help make a +definition work better across font changes. For example, a definition +of the vertical space between list items given as +@code{\setlength@{\itemsep@}@{1ex plus 0.05ex minus 0.01ex@}} is more +likely to still be reasonable if the font is changed than a definition +given in points. + +@cindex mu, math unit +@findex mu +In math mode, many definitions are expressed in terms of the math unit +@dfn{mu} given by 1 em = 18 mu, where the em is taken from the current +math symbols family. @xref{Spacing in math mode}. + + +@node \setlength +@section @code{\setlength} + +@findex \setlength +@cindex lengths, setting + +Synopsis: + +@example +\setlength@{@var{len}@}@{@var{amount}@} +@end example + +Set the length @var{len} to @var{amount}. The length name @var{len} +must begin with a backslash, @code{\}. The @code{amount} can be a +rubber length (@pxref{Lengths}). It can be positive, negative or zero, +and can be in any units that @LaTeX{} understands (@pxref{Units of +length}). + +Below, with @LaTeX{}'s defaults the first paragraph will be indented +while the second will not. + +@example +I told the doctor I broke my leg in two places. + +\setlength@{\parindent@}@{0em@} +He said stop going to those places. +@end example + +If you did not declare @var{len} with @code{\newlength}, for example if +you mistype the above as +@code{\newlength@{\specparindent@}\setlength@{\sepcparindent@}@{...@}}, +then you get an error like @samp{Undefined control sequence. <argument> +\sepcindent}. If you omit the backslash at the start of the length name +then you get an error like @samp{Missing number, treated as zero. <to be +read again> \relax l.19 \setlength@{specparindent@}@{0.6\parindent@}} + + +@node \addtolength +@section @code{\addtolength} + +@findex \addtolength +@cindex lengths, adding to + +Synopsis: + +@example +\addtolength@{@var{len}@}@{@var{amount}@} +@end example + +Increment the length @var{len} by @var{amount}. The length name +@var{len} begins with a backslash, @code{\}. The @code{amount} is a +rubber length (@pxref{Lengths}). It can be positive, negative or zero, +and can be in any units that @LaTeX{} understands (@pxref{Units of +length}). + +Below, if @code{\parskip} starts with the value @code{0pt plus 1pt} + +@example +Doctor: how is the boy who swallowed the silver dollar? +\addtolength@{\parskip@}@{1pt@} + +Nurse: no change. +@end example + +@noindent +then it has the value @code{1pt plus 1pt} for the second paragraph. + +If you did not declare the length @var{len} with @code{\newlength}, if +for example you mistype the above as +@code{\addtolength@{\specparindent@}@{0.6\praindent@}}, then you get +something like @samp{Undefined control sequence. <argument> \praindent}. +If you leave off the backslash at the start of @var{len}, as in +@code{\addtolength@{parindent@}@{1pt@}}, then you get something like +@samp{You can't use `the letter p' after \advance}. + + +@node \settodepth +@section @code{\settodepth} + +@findex \settodepth + +Synopsis: + +@example +\settodepth@{@var{len}@}@{@var{text}@} +@end example + +Set the length @var{len} to the depth of box that @LaTeX{} gets on +typesetting the @var{text} argument. The length name @var{len} must +begin with a backslash, @code{\}. + +This will show how low the character descenders go. + +@example +\newlength@{\alphabetdepth@} +\settodepth@{\alphabetdepth@}@{abcdefghijklmnopqrstuvwxyz@} +\the\alphabetdepth +@end example + +If you did not set aside the length @var{len}, if for example you +mistype the above as @code{\settodepth@{\aplhabetdepth@}@{abc...@}}, +then you get something like @samp{Undefined control sequence. <argument> +\aplhabetdepth}. If you leave the backslash out of @var{len}, as in +@code{\settodepth@{alphabetdepth@}@{...@}} then you get something like +@samp{Missing number, treated as zero. <to be read again> \setbox}. + + +@node \settoheight +@section @code{\settoheight} + +@findex \settoheight + +Synopsis: + +@example +\settoheight@{@var{len}@}@{text@} +@end example + +Sets the length @var{len} to the height of box that @LaTeX{} gets on +typesetting the @code{text} argument. The length name @var{len} must +begin with a backslash, @code{\}. + +This will show how high the characters go. + +@example +\newlength@{\alphabetheight@} +\settoheight@{\alphabetheight@}@{abcdefghijklmnopqrstuvwxyz@} +\the\alphabetheight +@end example + +If no such length @var{len} has been declared with @code{\newlength}, if +for example you mistype as +@code{\settoheight@{\aplhabetheight@}@{abc...@}}, then you get something +like @samp{Undefined control sequence. <argument> \alphabetheight}. If +you leave the backslash out of @var{len}, as in +@code{\settoheight@{alphabetheight@}@{...@}} then you get something like +@samp{Missing number, treated as zero. <to be read again> \setbox}. + + +@node \settowidth +@section @code{\settowidth} + +@findex \settowidth + +Synopsis: + +@example +\settowidth@{@var{len}@}@{@var{text}@} +@end example + +Set the length @var{len} to the width of the box that @LaTeX{} gets on +typesetting the @var{text} argument. The length name @var{len} must +begin with a backslash, @code{\}. + +This measures the width of the lowercase ASCII alphabet. + +@example +\newlength@{\alphabetwidth@} +\settowidth@{\alphabetwidth@}@{abcdefghijklmnopqrstuvwxyz@} +\the\alphabetwidth +@end example + +If no such length @var{len} has been set aside, if for example you +mistype the above as @code{\settowidth@{\aplhabetwidth@}@{abc...@}}, +then you get something like @samp{Undefined control sequence. <argument> +\aplhabetwidth}. If you leave the backslash out of @var{len}, as in +@code{\settoheight@{alphabetwidth@}@{...@}} then you get something like +@samp{Missing number, treated as zero. <to be read again> \setbox}. + + +@node Making paragraphs +@chapter Making paragraphs + +@cindex making paragraphs +@cindex paragraphs + +To start a paragraph, just type some text. To end the current +paragraph, put an empty line. This is three paragraphs, separated by +two empty lines. + +@example +It is a truth universally acknowledged, that a single man in possession +of a good fortune, must be in want of a wife. + +However little known the feelings or views of such a man may be on his +first entering a neighbourhood, this truth is so well fixed in the minds +of the surrounding families, that he is considered the rightful property +of some one or other of their daughters. + +``My dear Mr. Bennet,'' said his lady to him one day, +``have you heard that Netherfield Park is let at last?'' +@end example + +The separator lines must be empty, including not containing a comment +character, @code{%}. + +Once @LaTeX{} has gathered all of a paragraph's contents it divides that +content into lines in a way that is optimized over the entire paragraph +(@pxref{Line breaking}). + +There are places where a new paragraph is not permitted. Don't put a +blank line in math mode (@pxref{Modes}); here the line before the +@code{\end@{equation@}} + +@example +\begin@{equation@} + 2^@{|S|@} > |S| + +\end@{equation@} +@end example + +@noindent +will get you the error @samp{Missing $ inserted}. Similarly, the blank +line in this @code{section} argument + +@example +\section@{aaa + +bbb@} +@end example + +@noindent +gets @samp{Runaway argument? @{aaa ! Paragraph ended before \@@sect was +complete}. + + +@menu +* \par:: End the current paragraph. +* \indent & \noindent:: Go into horizontal mode, possibly with an indent. +* \parindent & \parskip:: Space added before paragraphs. +* Marginal notes:: Put remarks in the margin. +@end menu + + +@node \par +@section @code{\par} + +@findex \par +@cindex paragraph, ending + +Synopsis (note that while reading the input @TeX{} converts two +consecutive newlines to a @code{\par}): + +@example +\par +@end example + +End the current paragraph. The usual way to separate paragraphs is with +a blank line but the @code{\par} command is entirely equivalent. This +command is robust (@pxref{\protect}). + +This example uses @code{\par} rather than a blank line simply for +readability. + +@example +\newcommand@{\syllabusLegalese@}@{% + \whatCheatingIs\par\whatHappensWhenICatchYou@} +@end example + +In LR mode or a vertical mode the @code{\par} command does nothing but +it terminates paragraph mode, switching @LaTeX{} to vertical mode +(@pxref{Modes}). + +You cannot use the @code{\par} command in a math mode. You also cannot +use it in the argument of many commands, such as the @code{\section} +command (@pxref{Making paragraphs} and @ref{\newcommand & +\renewcommand}). + +The @code{\par} command is not the same as the @code{\paragraph} +command. The latter is, like @code{\section} or @code{\subsection}, a +sectioning unit used by the standard @LaTeX{} documents +(@pxref{\subsubsection & \paragraph & \subparagraph}). + +The @code{\par} command is not the same as @code{\newline} or the line +break double backslash, @code{\\}. The difference is that @code{\par} +ends the paragraph, not just the line, and also triggers the addition of +the between-paragraph vertical space @code{\parskip} (@pxref{\parindent +& \parskip}). + +The output from this example + +@example +xyz + +\setlength@{\parindent@}@{3in@} +\setlength@{\parskip@}@{5in@} +\noindent test\indent test1\par test2 +@end example + +@noindent +is: after @samp{xyz} there is a vertical skip of 5@tie{}inches and then +@samp{test} appears, aligned with the left margin. On the same line, +there is an empty horizontal space of 3@tie{}inches and then +@samp{test1} appears. Finally. there is a vertical space of +5@tie{}inches, followed by a fresh paragraph with a paragraph indent of +3@tie{}inches, and then @LaTeX{} puts the text @samp{test2}. + + +@node \indent & \noindent +@section @code{\indent} & @code{\noindent} + +@findex \indent +@findex \noindent +@findex \parindent +@cindex indent, forcing + +Synopsis: + +@example +\indent +@end example + +@noindent or + +@example +\noindent +@end example + +Go into horizontal mode (@pxref{Modes}). The @code{\indent} command +first outputs an empty box whose width is @code{\parindent}. These +commands are robust (@pxref{\protect}). + +Ordinarily you create a new paragraph by putting in a blank line. +@xref{\par} for the difference between this command and @code{\par}. To +start a paragraph without an indent, or to continue an interrupted +paragraph, use @code{\noindent}. + +In the middle of a paragraph the @code{\noindent} command has no effect, +because @LaTeX{} is already in horizontal mode there. The +@code{\indent} command's only effect is to output a space. + +This example starts a fresh paragraph. + +@example +... end of the prior paragraph. + +\noindent This paragraph is not indented. +@end example + +@noindent +and this continues an interrupted paragraph. + +@example +The data + +\begin@{center@} + \begin@{tabular@}@{rl@} ... \end@{tabular@} +\end@{center@} + +\noindent shows this clearly. +@end example + +To omit indentation in the entire document put +@code{\setlength@{\parindent@}@{0pt@}} in the preamble. If you do that, +you may want to also set the length of spaces between paragraphs, +@code{\parskip} (@pxref{\parindent & \parskip}). + +@PkgIndex{indentfirst} +Default @LaTeX{} styles have the first paragraph after a section that is +not indented, as is traditional typesetting in English. To change that, +look on CTAN for the package @code{indentfirst}. + + +@node \parindent & \parskip +@section @code{\parindent} & @code{\parskip} + +@findex \parindent +@findex \parskip +@cindex paragraph indentation +@cindex vertical space before paragraphs + +Synopsis: + +@example +\setlength@{\parskip@}@{@var{horizontal len}@} +\setlength@{\parinden@}@{@var{vertical len}@} +@end example + +Both are a rubber lengths (@pxref{Lengths}). They give the indentation +of ordinary paragraphs, not paragraphs inside minipages +(@pxref{minipage}), and the vertical space between paragraphs. + +This, put in the preamble, + +@example +\setlength@{\parindent@}@{0em@} +\setlength@{\parskip@}@{1ex@} +@end example + +@noindent +arranges that the document will have paragraphs that are not indented, +but instead are vertically separated by about the height of a lowercase +@samp{x}. + +In standard @LaTeX{} documents, the default value for @code{\parindent} +in one-column documents is @code{15pt} when the default text size is +@code{10pt} , @code{17pt} for @code{11pt}, and @code{1.5em} for +@code{12pt}. In two-column documents it is @code{1em}. The default +value for @code{\parskip} in @LaTeX{}'s standard document styles is +@code{0pt plus1pt}. + + +@node Marginal notes +@section Marginal notes + +@cindex marginal notes +@cindex notes in the margin +@cindex remarks in the margin +@findex \marginpar + +Synopsis, one of: + +@example +\marginpar@{@var{right}@} +\marginpar[@var{left}]@{@var{right}@} +@end example + +Create a note in the margin. The first line of the note will have the +same baseline as the line in the text where the @code{\marginpar} +occurs. + +The margin that @LaTeX{} uses for the note depends on the current layout +(@pxref{Document class options}) and also on @code{\reversemarginpar} +(see below). If you are using one-sided layout (document option +@code{oneside}) then it goes in the right margin. If you are using +two-sided layout (document option @code{twoside}) then it goes in the +outside margin. If you are in two-column layout (document option +@code{twocolumn}) then it goes in the nearest margin. + +@findex \reversemarginpar +@findex \normalmarginpar +If you declare @code{\reversemarginpar} then @LaTeX{} will place +subsequent marginal notes in the opposite margin to that given in the +prior paragraph. Revert that to the default position with +@code{\normalmarginpar}. + +When you specify the optional argument @var{left} then it is used for +a note in the left margin, while the mandatory argument @var{right} is +used for a note in the right margin. + +Normally, a note's first word will not be hyphenated. You can enable +hyphenation there by beginning @var{left} or @var{right} with +@code{\hspace@{0pt@}}. + +These parameters affect the formatting of the note: + +@ftable @code +@item \marginparpush +@anchor{marginal notes marginparpush} +Minimum vertical space between notes; default @samp{7pt} for +@samp{12pt} documents, @samp{5pt} else. + +@item \marginparsep +@anchor{marginal notes marginparsep} +Horizontal space between the main text and the note; default +@samp{11pt} for @samp{10pt} documents, @samp{10pt} else. + +@item \marginparwidth +@anchor{marginal notes marginparwidth} +Width of the note itself; default for a one-sided @samp{10pt} document +is @samp{90pt}, @samp{83pt} for @samp{11pt}, and @samp{68pt} for +@samp{12pt}; @samp{17pt} more in each case for a two-sided document. +In two column mode, the default is @samp{48pt}. + +@end ftable + +The standard @LaTeX{} routine for marginal notes does not prevent +notes from falling off the bottom of the page. +@c @TeX{} FAQ entry on this topic (xx when there): +@c @url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=marginparside}. +@c (+marginfix) + + +@node Math formulas +@chapter Math formulas + +@cindex math formulas +@cindex formulas, math +@cindex math mode, entering +@EnvIndex{math} +@EnvIndex{displaymath} +@EnvIndex{equation} + +Produce mathematical text by putting @LaTeX{} into math mode or display +math mode (@pxref{Modes}). This example shows both. + +@example +The wave equation for \( u \) is +\begin@{displaymath@} + \frac@{\partial^2u@}@{\partial t^2@} = c^2\nabla^2u +\end@{displaymath@} +where \( \nabla^2 \) is the spatial Laplacian and \( c \) is constant. +@end example + +@noindent +Math mode is for inline mathematics. In the above example it is invoked +by the starting @code{\(} and finished by the matching ending @code{\)}. +Display math mode is for displayed equations and here is invoked by the +@code{displaymath} environment. Note that any mathematical text +whatever, including mathematical text consisting of just one character, +is handled in math mode. + +When in math mode or display math mode, @LaTeX{} handles many aspects of +your input text differently than in other text modes. For example, + +@example +contrast x+y with \( x+y \) +@end example + +@noindent +in math mode the letters are in italics and the spacing around the plus +sign is different. + +There are three ways to make inline formulas, to put @LaTeX{} in math +mode. + +@example +\( @var{mathematical material} \) +$ @var{mathematical material} $ +\begin@{math@} @var{mathematical material} \end@{math@} +@end example + +@noindent +The first form is preferred and the second is quite common, but the +third form is rarely used. You can sometimes use one and sometimes +another, as in @code{\(x\) and $y$}. You can use these in paragraph +mode or in LR mode (@pxref{Modes}). + +To make displayed formulas, put @LaTeX{} into display math mode with +either: + +@example +\begin@{displaymath@} + @var{mathematical material} +\end@{displaymath@} +@end example + +@noindent +or + +@example +\begin@{equation@} + @var{mathematical material} +\end@{equation@} +@end example + +@noindent +(@pxref{displaymath}, @pxref{equation}). The only difference is that +with the @code{equation} environment, @LaTeX{} puts a formula number +alongside the formula. The construct @code{\[ @var{math} \]} is +equivalent to @code{\begin@{displaymath@} @var{math} +\end@{displaymath@}}. These environments can only be used in paragraph +mode (@pxref{Modes}). + +@findex \displaystyle +The two mathematics modes are similar, but there are some differences. +One involves the placement of subscripts and superscripts; in display +math mode they are further apart and in inline math mode they are closer +together. + +Sometimes you want the display math typographical treatment to happen in +the inline math mode. For this, the @code{\displaystyle} declaration +forces the size and style of the formula to be that of +@code{displaymath}. Thus @code{\(\displaystyle \sum_@{n=0@}^\infty +x_n\)} will have the limits above and below the summation sign, not next +to it. Another example is that + +@example +\begin@{tabular@}@{r|cc@} + \textsc@{Name@} &\textsc@{Series@} &\textsc@{Sum@} \\ \hline + Arithmetic &\( a+(a+b)+(a+2b)+\cdots+(a+(n-1)b) \) + &\( na+(n-1)n\cdot\frac@{b@}@{2@}\) \\ + Geometric &\( a+ab+ab^2+\cdots+ab^@{n-1@} \) + &\(\displaystyle a\cdot\frac@{1-b^n@}@{1-b@}\) \\ +\end@{tabular@} +@end example + +@noindent +because it has no @code{\displaystyle}, the @samp{Arithmetic} line's +fraction will be scrunched. But, because of its @code{\displaystyle}, +the @samp{Geometric} line's fraction will be easy to read, with +characters the same size as in the rest of the line. + +@PkgIndex{amsmath} +@PkgIndex{amsfonts} +@PkgIndex{mathtools} +The American Mathematical Society has made freely available a set of +packages that greatly expand your options for writing mathematics, +@file{amsmath} and @file{amssymb} (also be aware of the @file{mathtools} +package that is an extension to, and loads, @file{amsmath}). New +documents that will have mathematical text should use these packages. +Descriptions of these packages is outside the scope of this document; +see their documentation on CTAN. + +@menu +* Subscripts & superscripts:: Also known as exponent or index. +* Math symbols:: Various mathematical squiggles. +* Math functions:: Math function names like sin and exp. +* Math accents:: Accents in math. +* Over- and Underlining:: Things over or under formulas. +* Spacing in math mode:: Thick, medium, thin, and negative spaces. +* Math miscellany:: Stuff that doesn't fit anywhere else. +@end menu + + +@node Subscripts & superscripts +@section Subscripts & superscripts + +@cindex superscript +@cindex subscript +@cindex exponent +@findex _ +@findex ^ + +Synopsis (in math mode or display math mode), one of: + +@example +@var{base}^@var{exp} +@var{base}^@{@var{exp}@} +@end example + +@noindent +or, one of: + +@example +@var{base}_@var{exp} +@var{base}_@{@var{exp}@} +@end example + +Make @var{exp} appear as a superscript of @var{base} (with the caret +character,@tie{}@code{^}) or a subscript (with +underscore,@tie{}@code{_}). + +In this example the @code{0}'s and @code{1}'s are subscripts while the +@code{2}'s are superscripts. + +@example +\( (x_0+x_1)^2 \leq (x_0)^2+(x_1)^2 \) +@end example + +To have the subscript or superscript contain more than one character, +surround the expression with curly braces, as in @code{e^@{-2x@}}. +This example's fourth line shows curly braces used to group an expression +for the exponent. + +@example +\begin@{displaymath@} + (3^3)^3=27^3=19\,683 + \qquad + 3^@{(3^3)@}=3^@{27@}=7\,625\,597\,484\,987 +\end@{displaymath@} +@end example + +@LaTeX{} knows how to handle a superscript on a superscript, or a +subscript on a subscript, or supers on subs, or subs on supers. So, +expressions such as @code{e^@{x^2@}} and @code{x_@{i_0@}} give correct +output. Note the use in those expressions of curly braces to give the +@var{base} a determined @var{exp}. If you enter @code{\(3^3^3\)} then +you get @samp{Double superscript}. + +@LaTeX{} does the right thing when something has both a subscript and a +superscript. In this example the integral has both. They come out in +the correct place without any author intervention. + +@example +\begin@{displaymath@} + \int_@{x=a@}^b f'(x)\,dx = f(b)-f(a) +\end@{displaymath@} +@end example + +@noindent +Note the parentheses around @code{x=a} to make the entire expression a +subscript. + +To put a superscript or subscript before a symbol, use a construct like +@code{@{@}_t K^2}. The empty curly braces @code{@{@}} give the +subscript something to attach to and keeps it from accidentally +attaching to a prior symbols. + +Using the subscript or superscript command outside of math mode or +display math mode, as in @code{the expression x^2}, will get you +the error @samp{Missing $ inserted}. + +@PkgIndex{mhchem} +A common reason to want subscripts outside of a mathematics mode is to +typeset chemical formulas. There are packages for that such as +@file{mhchem}; see CTAN. + + +@node Math symbols +@section Math symbols + +@cindex math symbols +@cindex symbols, math +@cindex greek letters + +@PkgIndex{symbols} + +@LaTeX{} provides almost any mathematical or technical symbol that +anyone uses. For example, if you include @code{$\pi$} in your source, +you will get the pi symbol @BES{03C0,\pi}. See the @file{Comprehensive +@LaTeX{} Symbol List} at +@url{https://ctan.org/tex-archive/info/symbols/comprehensive/}. + +Here is a list of commonly-used symbols. It is by no means exhaustive. +Each symbol is described with a short phrase, and its symbol class, +which determines the spacing around it, is given in parenthesis. Unless +said otherwise, the commands for these symbols can be used only in math +mode. To redefine a command so that it can be used whatever the current +mode, see @ref{\ensuremath}. + +@c xx Add Negation: for negations of relevant symbols +@c Useful: http://www.w3.org/TR/WD-math-970515/section6.html + +@ftable @code +@item \| +@BES{2225,\|} Parallel (relation). Synonym:@tie{}@code{\parallel}. + +@item \aleph +@BES{2135,\aleph} Aleph, transfinite cardinal (ordinary). + +@item \alpha +@BES{03B1,\alpha} Lowercase Greek letter alpha (ordinary). + +@item \amalg +@BES{2A3F,\amalg} Disjoint union (binary) + +@item \angle +@BES{2220,\angle} Geometric angle (ordinary). Similar: less-than +sign@tie{}@code{<} and angle bracket@tie{}@code{\langle}. + +@item \approx +@BES{2248,\approx} Almost equal to (relation). + +@item \ast +@BES{2217,\ast} Asterisk operator, convolution, six-pointed +(binary). Synonym:@tie{}@code{*}, which is often a superscript or +subscript, as in the Kleene star. Similar:@tie{}@code{\star}, which is +five-pointed, and is sometimes used as a general binary operation, and +sometimes reserved for cross-correlation. + +@item \asymp +@BES{224D,\asymp} Asymptotically equivalent (relation). + +@item \backslash +\ Backslash (ordinary). Similar: set minus@tie{}@code{\setminus}, and +@code{\textbackslash} for backslash outside of math mode. + +@item \beta +@BES{03B2,\beta} Lowercase Greek letter beta (ordinary). + +@item \bigcap +@BES{22C2,\bigcap} Variable-sized, or n-ary, intersection (operator). Similar: +binary intersection@tie{}@code{\cap}. + +@item \bigcirc +@BES{26AA,\bigcirc} Circle, larger (binary). Similar: function +composition@tie{}@code{\circ}. +@c bb Best unicode symbol for this? + +@item \bigcup +@BES{22C3,\bigcup} Variable-sized, or n-ary, union (operator). Similar: binary +union@tie{}@code{\cup}. + +@item \bigodot +@BES{2A00,\bigodot} Variable-sized, or n-ary, circled dot operator (operator). + +@item \bigoplus +@BES{2A01,\bigoplus} Variable-sized, or n-ary, circled plus operator (operator). + +@item \bigotimes +@BES{2A02,\bigotimes} Variable-sized, or n-ary, circled times operator (operator). + +@item \bigtriangledown +@BES{25BD,\bigtriangledown} Variable-sized, or n-ary, open triangle pointing down +(operator). + +@item \bigtriangleup +@BES{25B3,\bigtriangleup} Variable-sized, or n-ary, open triangle pointing up (operator). + +@item \bigsqcup +@BES{2A06,\bigsqcup} Variable-sized, or n-ary, square union (operator). + +@item \biguplus +@BES{2A04,\biguplus} Variable-sized, or n-ary, union operator with a plus +(operator). (Note that the name has only one p.) + +@item \bigvee +@BES{22C1,\bigvee} Variable-sized, or n-ary, logical-and (operator). + +@item \bigwedge +@BES{22C0,\bigwedge} Variable-sized, or n-ary, logical-or (operator). + +@item \bot +@BES{22A5,} Up tack, bottom, least element of a partially ordered +set, or a contradiction (ordinary). See also@tie{}@code{\top}. + +@item \bowtie +@BES{22C8,\bowtie} Natural join of two relations (relation). + +@item \Box +@BES{25A1,} Modal operator for necessity; square open box +(ordinary). @value{NeedsAMSSymb} +@c bb Best Unicode equivalent? + +@item \bullet +@cindex bullet symbol +@BES{2022,\bullet} Bullet (binary). Similar: multiplication +dot@tie{}@code{\cdot}. + +@item \cap +@BES{2229,\cap} Intersection of two sets (binary). Similar: variable-sized +operator@tie{}@code{\bigcap}. + +@item \cdot +@BES{22C5,\cdot} Multiplication (binary). Similar: Bullet +dot@tie{}@code{\bullet}. + +@item \chi +@BES{03C7,\chi} Lowercase Greek chi (ordinary). + +@item \circ +@BES{2218,\circ} Function composition, ring operator (binary). Similar: +variable-sized operator@tie{}@code{\bigcirc}. + +@item \clubsuit +@BES{2663,\clubsuit} Club card suit (ordinary). + +@item \complement +@BES{2201,} Set complement, used as a superscript as in +@code{$S^\complement$} (ordinary). @value{NeedsAMSSymb} Also used: +@code{$S^@{\mathsf@{c@}@}$} or@tie{}@code{$\bar@{S@}$}. + +@item \cong +@BES{2245,\cong} Congruent (relation). + +@item \coprod +@BES{2210,\coprod} Coproduct (operator). + +@item \cup +@BES{222A,\cup} Union of two sets (binary). Similar: variable-sized +operator@tie{}@code{\bigcup}. + +@item \dagger +@BES{2020,\dagger} Dagger relation (binary). + +@item \dashv +@BES{22A3,\dashv} Dash with vertical, reversed turnstile (relation). Similar: +turnstile@tie{}@code{\vdash}. + +@item \ddagger +@BES{2021,\ddagger} Double dagger relation (binary). + +@item \Delta +@BES{0394,\Delta} Greek uppercase delta, used for increment (ordinary). + +@item \delta +@BES{03B4,\delta} Greek lowercase delta (ordinary). + +@item \Diamond +@BES{25C7,} Large diamond operator (ordinary). @value{NeedsAMSSymb} + +@item \diamond +@BES{22C4,\diamond} Diamond operator (binary). Similar: large +diamond@tie{}@code{\Diamond}, circle bullet@tie{}@code{\bullet}. + +@item \diamondsuit +@BES{2662,\diamondsuit} Diamond card suit (ordinary). + +@item \div +@BES{00F7,\div} Division sign (binary). + +@item \doteq +@BES{2250,\doteq} Approaches the limit (relation). Similar: geometrically equal +to@tie{}@code{\Doteq}. + +@item \downarrow +@BES{2193,\downarrow} Down arrow, converges (relation). Similar: +@code{\Downarrow} double line down arrow. + +@item \Downarrow +@BES{21D3,\Downarrow} Double line down arrow (relation). Similar: +@code{\downarrow} single line down arrow. + +@item \ell +@BES{2113,\ell} Lowercase cursive letter l (ordinary). + +@item \emptyset +@BES{2205,\emptyset} Empty set symbol (ordinary). The variant form is +@code{\varnothing}. +@c bb Why Unicode has \revemptyset but no \emptyset? + +@item \epsilon +@BES{03F5,\epsilon} Lowercase lunate epsilon (ordinary). Similar to +Greek text letter. More widely used in mathematics is the script small +letter epsilon @code{\varepsilon}@tie{}@BES{03B5,\varepsilon}. Related: +the set membership relation @code{\in}@tie{}@BES{2208,\in}. +@c src: David Carlisle http://tex.stackexchange.com/a/98018/339 and +@c Unicode referenced there asserts varepsilon is much more widely used. + +@item \equiv +@BES{2261,\equiv} Equivalence (relation). + +@item \eta +@BES{03B7,\eta} Lowercase Greek letter (ordinary). + +@item \exists +@BES{2203,\exists} Existential quantifier (ordinary). + +@item \flat +@BES{266D,\flat} Musical flat (ordinary). + +@item \forall +@BES{2200,\forall} Universal quantifier (ordinary). + +@item \frown +@BES{2322,\frown} Downward curving arc (ordinary). + +@item \Gamma +@BES{0393,\Gamma} uppercase Greek letter (ordinary). + +@item \gamma +@BES{03B3,\gamma} Lowercase Greek letter (ordinary). + +@item \ge +@BES{2265,\ge} Greater than or equal to (relation). This is a synonym +for@tie{}@code{\geq}. + +@item \geq +@BES{2265,\geq} Greater than or equal to (relation). This is a synonym +for@tie{}@code{\ge}. + +@item \gets +@BES{2190,\gets} Is assigned the value (relation). +Synonym:@tie{}@code{\leftarrow}. + +@item \gg +@BES{226B,\gg} Much greater than (relation). Similar: much less +than@tie{}@code{\ll}. + +@item \hbar +@BES{210F,\hbar} Planck constant over two pi (ordinary). + +@item \heartsuit +@BES{2661,\heartsuit} Heart card suit (ordinary). + +@item \hookleftarrow +@BES{21A9,\hookleftarrow} Hooked left arrow (relation). + +@item \hookrightarrow +@BES{21AA,\hookrightarrow} Hooked right arrow (relation). + +@item \iff +@BES{27F7,\iff} If and only if (relation). It is @code{\Longleftrightarrow} +with a @code{\thickmuskip} on either side. + +@item \Im +@BES{2111,\Im} Imaginary part (ordinary). See: real part@tie{}@code{\Re}. + +@item \imath +@cindex dotless i, math +Dotless i; used when you are putting an accent on an i (@pxref{Math +accents}). + +@item \in +@BES{2208,\in} Set element (relation). See also: lowercase lunate +epsilon@tie{}@code{\epsilon}@BES{03F5,\epsilon} and small letter script +epsilon@tie{}@code{\varepsilon}. + +@item \infty +@BES{221E,\infty} Infinity (ordinary). + +@item \int +@BES{222B,\int} Integral (operator). + +@item \iota +@BES{03B9,\iota} Lowercase Greek letter (ordinary). + +@item \Join +@BES{2A1D,} Condensed bowtie symbol (relation). Not available in Plain +@TeX{}. + +@item \jmath +@cindex dotless j, math +Dotless j; used when you are putting an accent on a j (@pxref{Math +accents}). + +@item \kappa +@BES{03BA,\kappa} Lowercase Greek letter (ordinary). + +@item \Lambda +@BES{039B,\Lambda} uppercase Greek letter (ordinary). + +@item \lambda +@BES{03BB,\lambda} Lowercase Greek letter (ordinary). + +@item \land +@BES{2227,\land} Logical and (binary). This is a synonym for @code{\wedge}. +See also logical or@tie{}@code{\lor}. + +@item \langle +@BES{27E8,\langle} Left angle, or sequence, bracket (opening). Similar: +less-than@tie{}@code{<}. Matches@tie{}@code{\rangle}. + +@item \lbrace +@BES{007B,\lbrace} Left curly brace +(opening). Synonym:@tie{}@code{\@{}. Matches@tie{}@code{\rbrace}. + +@item \lbrack +@BES{005B,\lbrack} Left square bracket (opening). +Synonym:@tie{}@code{[}. Matches@tie{}@code{\rbrack}. + +@item \lceil +@BES{2308,\lceil} Left ceiling bracket, like a square bracket but with the bottom +shaved off (opening). Matches@tie{}@code{\rceil}. + +@item \le +@BES{2264,\le} Less than or equal to (relation). This is a synonym +for@tie{}@code{\leq}. + +@item \leadsto +@BES{21DD,} Squiggly right arrow (relation). @value{NeedsAMSSymb} +To get this symbol outside of math mode you can put +@code{\newcommand*@{\Leadsto@}@{\ensuremath@{\leadsto@}@}} in the +preamble and then use @code{\Leadsto} instead. +@c bb Best Unicode equivalent? + +@item \Leftarrow +@BES{21D0,\Leftarrow} Is implied by, double-line left arrow (relation). Similar: +single-line left arrow@tie{}@code{\leftarrow}. + +@item \leftarrow +@BES{2190,\leftarrow} Single-line left arrow (relation). +Synonym:@tie{}@code{\gets}. Similar: double-line left +arrow@tie{}@code{\Leftarrow}. + +@item \leftharpoondown +@BES{21BD,\leftharpoondown} Single-line left harpoon, barb under bar (relation). + +@item \leftharpoonup +@BES{21BC,\leftharpoonup} Single-line left harpoon, barb over bar (relation). + +@item \Leftrightarrow +@BES{21D4,\Leftrightarrow} Bi-implication; double-line double-headed arrow (relation). +Similar: single-line double headed arrow@tie{}@code{\leftrightarrow}. + +@item \leftrightarrow +@BES{2194,\leftrightarrow} Single-line double-headed arrow (relation). Similar: +double-line double headed arrow@tie{}@code{\Leftrightarrow}. + +@item \leq +@BES{2264,\leq} Less than or equal to (relation). This is a synonym +for@tie{}@code{\le}. + +@item \lfloor +@BES{230A,\lfloor} Left floor bracket (opening). Matches:@tie{}@code{\floor}. + +@item \lhd +@BES{25C1,} Arrowhead, that is, triangle, pointing left (binary). +@value{NeedsAMSSymb} For the normal subgroup symbol you should load +@file{amssymb} and use@tie{}@code{\vartriangleleft} (which is a relation +and so gives better spacing). + +@item \ll +@BES{226A,\ll} Much less than (relation). Similar: much greater +than@tie{}@code{\gg}. + +@item \lnot +@BES{00AC,\lnot} Logical negation (ordinary). Synonym:@tie{}@code{\neg}. + +@item \longleftarrow +@BES{27F5,\longleftarrow} Long single-line left arrow (relation). Similar: long +double-line left arrow@tie{}@code{\Longleftarrow}. + +@item \longleftrightarrow +@BES{27F7,\longleftrightarrow} Long single-line double-headed arrow (relation). Similar: long +double-line double-headed arrow@tie{}@code{\Longleftrightarrow}. + +@item \longmapsto +@BES{27FC,\longmapsto} Long single-line left arrow starting with vertical bar +(relation). Similar: shorter version@tie{}@code{\mapsto}. + +@item \longrightarrow +@BES{27F6,\longrightarrow} Long single-line right arrow (relation). Similar: long +double-line right arrow@tie{}@code{\Longrightarrow}. + +@item \lor +@BES{2228,\lor} Logical or (binary). Synonym: wedge@tie{}@code{\wedge}. + +@item \mapsto +@BES{21A6,\mapsto} Single-line left arrow starting with vertical bar (relation). +Similar: longer version@tie{}@code{\longmapsto}. + +@item \mho +@BES{2127,} Conductance, half-circle rotated capital omega (ordinary). +@value{NeedsAMSSymb} + +@item \mid +@BES{2223,\mid} Single-line vertical bar (relation). A typical use of +@code{\mid} is for a set @code{\@{\, x \mid x\geq 5 \,\@}}. + +Similar: @code{\vert} and@tie{}@code{|} produce the same single-line +vertical bar symbol but without any spacing (they fall in class +ordinary) and you should not use them as relations but instead only as +ordinals, i.e., footnote symbols. For absolute value, see the entry +for@tie{}@code{\vert} and for norm see the entry for@tie{}@code{\Vert}. + +@item \models +@BES{22A8,\models} Entails, or satisfies; double turnstile, short double dash +(relation). Similar: long double dash@tie{}@code{\vDash}. + +@item \mp +@BES{2213,\mp} Minus or plus (relation). + +@item \mu +@BES{03BC,\mu} Lowercase Greek letter (ordinary). + +@item \nabla +@BES{2207,\nabla} Hamilton's del, or differential, operator (ordinary). + +@item \natural +@BES{266E,\natural} Musical natural notation (ordinary). + +@item \ne +@BES{2260,\ne} Not equal (relation). Synonym:@tie{}@code{\neq}. + +@item \nearrow +@BES{2197,\nearrow} North-east arrow (relation). + +@item \neg +@BES{00AC,\neg} Logical negation (ordinary). +Synonym:@tie{}@code{\lnot}. Sometimes instead used for +negation:@tie{}@code{\sim}. + +@item \neq +@BES{2260,\neq} Not equal (relation). Synonym:@tie{}@code{\ne}. + +@item \ni +@BES{220B,\ni} Reflected membership epsilon; has the member +(relation). Synonym:@tie{}@code{\owns}. Similar: is a member +of@tie{}@code{\in}. + +@item \not +@c the "@ "s put in spaces so the not slash doesn't hit the next char. +@BES{0020,\not}@ @ @ @ Long solidus, or slash, used to overstrike a +following operator (relation). + +Many negated operators are available that don't require @code{\not}, +particularly with the @file{amssymb} package. For example, @code{\notin} +is typographically preferable to @code{\not\in}. + +@item \notin +@BES{2209,\notin} Not an element of (relation). Similar: not subset +of@tie{}@code{\nsubseteq}. + +@item \nu +@BES{03BD,\nu} Lowercase Greek letter (ordinary). + +@item \nwarrow +@BES{2196,\nwarrow} North-west arrow (relation). + +@item \odot +@BES{2299,\odot} Dot inside a circle (binary). Similar: variable-sized +operator@tie{}@code{\bigodot}. + +@item \oint +@BES{222E,\oint} Contour integral, integral with circle in the middle +(operator). + +@item \Omega +@BES{03A9,\Omega} uppercase Greek letter (ordinary). + +@item \omega +@BES{03C9,\omega} Lowercase Greek letter (ordinary). + +@item \ominus +@BES{2296,\ominus} Minus sign, or dash, inside a circle (binary). + +@item \oplus +@BES{2295,\oplus} Plus sign inside a circle (binary). Similar: variable-sized +operator@tie{}@code{\bigoplus}. + +@item \oslash +@BES{2298,\oslash} Solidus, or slash, inside a circle (binary). + +@item \otimes +@BES{2297,\otimes} Times sign, or cross, inside a circle (binary). Similar: +variable-sized operator@tie{}@code{\bigotimes}. + +@item \owns +@BES{220B,\owns} Reflected membership epsilon; has the member +(relation). Synonym:@tie{}@code{\ni}. Similar: is a member +of@tie{}@code{\in}. + +@item \parallel +@BES{2225,\parallel} Parallel (relation). Synonym:@tie{}@code{\|}. + +@item \partial +@BES{2202,\partial} Partial differential (ordinary). + +@item \perp +@BES{27C2,\perp} Perpendicular (relation). Similar:@tie{}@code{\bot} uses the +same glyph but the spacing is different because it is in the class +ordinary. + +@item \phi +@BES{03D5,\phi} Lowercase Greek letter (ordinary). The variant form is +@code{\varphi}@tie{}@BES{03C6,\varphi}. + +@item \Pi +@BES{03A0,\Pi} uppercase Greek letter (ordinary). + +@item \pi +@BES{03C0,\pi} Lowercase Greek letter (ordinary). The variant form is +@code{\varpi}@tie{}@BES{03D6,\varpi}. + +@item \pm +@BES{00B1,\pm} Plus or minus (binary). + +@item \prec +@BES{227A,\prec} Precedes (relation). Similar: less than@tie{}@code{<}. + +@item \preceq +@BES{2AAF,\preceq} Precedes or equals (relation). Similar: less than or +equals@tie{}@code{\leq}. + +@item \prime +@BES{2032,\prime} Prime, or minute in a time expression (ordinary). +Typically used as a superscript: @code{$f^\prime$}; @code{$f^\prime$} +and @code{$f'$} produce the same result. An advantage of the second +is that @code{$f'''$} produces the desired symbol, that is, the same +result as @code{$f^@{\prime\prime\prime@}$}, but uses rather less +typing. You can only use @code{\prime} in math mode. Using the right +single quote@tie{}@code{'} in text mode produces a different character +(apostrophe). + +@item \prod +@BES{220F,\prod} Product (operator). + +@item \propto +@BES{221D,\propto} Is proportional to (relation) + +@item \Psi +@BES{03A8,\Psi} uppercase Greek letter (ordinary). + +@item \psi +@BES{03C8,\psi} Lowercase Greek letter (ordinary). + +@item \rangle +@BES{27E9,\rangle} Right angle, or sequence, bracket (closing). +Similar: greater than@tie{}@code{>}. Matches:@code{\langle}. + +@item \rbrace +@BES{007D,\rbrace} Right curly brace +(closing). Synonym:@tie{}@code{\@}}. Matches@tie{}@code{\lbrace}. + +@item \rbrack +@BES{005D,\rbrack} Right square bracket +(closing). Synonym:@tie{}@code{]}. Matches@tie{}@code{\lbrack}. + +@item \rceil +@BES{2309,\rceil} Right ceiling bracket (closing). Matches@tie{}@code{\lceil}. + +@item \Re +@BES{211C,\Re} Real part, real numbers, cursive capital R (ordinary). Related: +double-line, or blackboard bold, R@tie{}@code{\mathbb@{R@}}; to access +this, load the @file{amsfonts} package. + +@item \restriction +@BES{21BE,} Restriction of a function (relation). Synonym: +@code{\upharpoonright}. @value{NeedsAMSSymb} + +@item \revemptyset +@BES{29B0,} Reversed empty set symbol (ordinary). Related: +@code{\varnothing}. @value{NeedsSTIX} + +@item \rfloor +@BES{230B,\rfloor} Right floor bracket, a right square bracket with the top cut +off (closing). Matches@tie{}@code{\lfloor}. + +@item \rhd +@BES{25C1,} Arrowhead, that is, triangle, pointing right (binary). +@value{NeedsAMSSymb} For the normal subgroup symbol you should instead +load @file{amssymb} and use@tie{}@code{\vartriangleright} (which is a +relation and so gives better spacing). + +@item \rho +@BES{03C1,\rho} Lowercase Greek letter (ordinary). The variant form is +@code{\varrho}@tie{}@BES{03F1,\varrho}. + +@item \Rightarrow +@BES{21D2,\Rightarrow} Implies, right-pointing double line arrow +(relation). Similar: right single-line arrow@tie{}@code{\rightarrow}. + +@item \rightarrow +@BES{2192,\rightarrow} Right-pointing single line arrow (relation). +Synonym:@tie{}@code{\to}. Similar: right double line +arrow@tie{}@code{\Rightarrow}. + +@item \rightharpoondown +@BES{21C1,\rightharpoondown} Right-pointing harpoon with barb below +the line (relation). + +@item \rightharpoonup +@BES{21C0,\rightharpoonup} Right-pointing harpoon with barb above the +line (relation). + +@item \rightleftharpoons +@BES{21CC,\rightleftharpoons} Right harpoon up above left harpoon down +(relation). + +@item \searrow +@BES{2198,\searrow} Arrow pointing southeast (relation). + +@item \setminus +@BES{29F5,\setminus} Set difference, reverse solidus or reverse slash, +like \ (binary). Similar: backslash@tie{}@code{\backslash} and also +@code{\textbackslash} outside of math mode. + +@item \sharp +@BES{266F,\sharp} Musical sharp (ordinary). + +@item \Sigma +@BES{03A3,\Sigma} uppercase Greek letter (ordinary). + +@item \sigma +@BES{03C3,\sigma} Lowercase Greek letter (ordinary). The variant form is +@code{\varsigma}@tie{}@BES{03C2,\varsigma}. + +@item \sim +@BES{223C,\sim} Similar, in a relation (relation). + +@item \simeq +@BES{2243,\simeq} Similar or equal to, in a relation (relation). + +@item \smallint +@BES{222B,\smallint} Integral sign that does not change to a larger size in a +display (operator). + +@item \smile +@BES{2323,\smile} Upward curving arc, smile (ordinary). + +@item \spadesuit +@BES{2660,\spadesuit} Spade card suit (ordinary). + +@item \sqcap +@BES{2293,\sqcap} Square intersection symbol (binary). Similar: +intersection@tie{}@code{cap}. + +@item \sqcup +@BES{2294,\sqcup} Square union symbol (binary). Similar: +union@tie{}@code{cup}. Related: variable-sized +operator@tie{}@code{\bigsqcup}. + +@item \sqsubset +@BES{228F,} Square subset symbol (relation). Similar: +subset@tie{}@code{\subset}. @value{NeedsAMSSymb} + +@item \sqsubseteq +@BES{2291,\sqsubseteq} Square subset or equal symbol (binary). Similar: subset or +equal to@tie{}@code{\subseteq}. + +@item \sqsupset +@BES{2290,} Square superset symbol (relation). Similar: +superset@tie{}@code{\supset}. @value{NeedsAMSSymb} + +@item \sqsupseteq +@BES{2292,\sqsupseteq} Square superset or equal symbol (binary). +Similar: superset or equal@tie{}@code{\supseteq}. + +@item \star +@BES{22C6,\star} Five-pointed star, sometimes used as a general binary +operation but sometimes reserved for cross-correlation (binary). +Similar: the synonyms asterisk@tie{}@code{*} and @code{\ast}, which +are six-pointed, and more often appear as a superscript or subscript, +as with the Kleene star. + +@item \subset +@BES{2282,\subset} Subset (occasionally, is implied by) (relation). + +@item \subseteq +@BES{2286,\subseteq} Subset or equal to (relation). + +@item \succ +@BES{227B,\succ} Comes after, succeeds (relation). Similar: is less +than@tie{}@code{>}. + +@item \succeq +@BES{2AB0,\succeq} Succeeds or is equal to (relation). Similar: less +than or equal to@tie{}@code{\leq}. + +@item \sum +@BES{2211,\sum} Summation (operator). Similar: Greek capital +sigma@tie{}@code{\Sigma}. + +@item \supset +@BES{2283,\supset} Superset (relation). + +@item \supseteq +@BES{2287,\supseteq} Superset or equal to (relation). + +@item \surd +@BES{221A,\surd} Radical symbol (ordinary). The @LaTeX{} command +@code{\sqrt@{...@}} typesets the square root of the argument, with a bar +that extends to cover the argument. + +@item \swarrow +@BES{2199,\swarrow} Southwest-pointing arrow (relation). + +@item \tau +@BES{03C4,\tau} Lowercase Greek letter (ordinary). + +@item \theta +@BES{03B8,\theta} Lowercase Greek letter (ordinary). The variant form is +@code{\vartheta}@tie{}@BES{03D1,\vartheta}. + +@item \times +@BES{00D7,\times} Primary school multiplication sign (binary). See +also@tie{}@code{\cdot}. + +@item \to +@BES{2192,\to} Right-pointing single line arrow (relation). +Synonym:@tie{}@code{\rightarrow}. + +@item \top +@BES{22A4,} Top, greatest element of a partially ordered set +(ordinary). See also@tie{}@code{\bot}. + +@item \triangle +@BES{25B3,\triangle} Triangle (ordinary). + +@item \triangleleft +@BES{25C1,\triangleleft} Not-filled triangle pointing left +(binary). Similar:@tie{}@code{\lhd}. For the normal subgroup symbol you +should load @file{amssymb} and use@tie{}@code{\vartriangleleft} (which +is a relation and so gives better spacing). + +@item \triangleright +@BES{25B7,\triangleright} Not-filled triangle pointing right +(binary). For the normal subgroup symbol you should instead load +@file{amssymb} and use@tie{}@code{\vartriangleright} (which is a +relation and so gives better spacing). + +@item \unlhd +@BES{22B4,} Left-pointing not-filled underlined arrowhead, that is, +triangle, with a line under (binary). @value{NeedsAMSSymb} For the +normal subgroup symbol load @file{amssymb} and +use@tie{}@code{\vartrianglelefteq} (which is a relation and so gives +better spacing). + +@item \unrhd +@BES{22B5,} Right-pointing not-filled underlined arrowhead, that is, +triangle, with a line under (binary). @value{NeedsAMSSymb} For the +normal subgroup symbol load @file{amssymb} and +use@tie{}@code{\vartrianglerighteq} (which is a relation and so gives +better spacing). + +@item \Uparrow +@BES{21D1,\Uparrow} Double-line upward-pointing arrow +(relation). Similar: single-line up-pointing +arrow@tie{}@code{\uparrow}. + +@item \uparrow +@BES{2191,\uparrow} Single-line upward-pointing arrow, diverges +(relation). Similar: double-line up-pointing +arrow@tie{}@code{\Uparrow}. + +@item \Updownarrow +@BES{21D5,\Updownarrow} Double-line upward-and-downward-pointing arrow +(relation). Similar: single-line upward-and-downward-pointing +arrow@tie{}@code{\updownarrow}. + +@item \updownarrow +@BES{2195,\updownarrow} Single-line upward-and-downward-pointing arrow +(relation). Similar: double-line upward-and-downward-pointing +arrow@tie{}@code{\Updownarrow}. + +@item \upharpoonright +@BES{21BE,} Up harpoon, with barb on right side +(relation). Synonym:@tie{}@code{@backslashchar{}restriction}. +@value{NeedsAMSSymb} + +@item \uplus +@BES{228E,\uplus} Multiset union, a union symbol with a plus symbol in +the middle (binary). Similar: union@tie{}@code{\cup}. Related: +variable-sized operator@tie{}@code{\biguplus}. + +@item \Upsilon +@BES{03A5,\Upsilon} uppercase Greek letter (ordinary). + +@item \upsilon +@BES{03C5,\upsilon} Lowercase Greek letter (ordinary). + +@item \varepsilon +@BES{03B5,\varepsilon} Small letter script epsilon (ordinary). This is +more widely used in mathematics than the non-variant lunate epsilon form +@code{\epsilon}@tie{}@BES{03F5,\epsilon}. Related: set +membership@tie{}@code{\in}. + +@item \vanothing +@BES{2205,} Empty set symbol. Similar: @code{\emptyset}. Related: +@code{\revemptyset}. @value{NeedsAMSSymb} + +@item \varphi +@BES{03C6,\varphi} Variant on the lowercase Greek letter (ordinary). +The non-variant form is @code{\phi}@tie{}@BES{03D5,\phi}. + +@item \varpi +@BES{03D6,\varpi} Variant on the lowercase Greek letter (ordinary). +The non-variant form is @code{\pi}@tie{}@BES{03C0,\pi}. + +@item \varrho +@BES{03F1,\varrho} Variant on the lowercase Greek letter (ordinary). +The non-variant form is @code{\rho}@tie{}@BES{03C1,\rho}. + +@item \varsigma +@BES{03C2,\varsigma} Variant on the lowercase Greek letter +(ordinary). The non-variant form is +@code{\sigma}@tie{}@BES{03C3,\sigma}. + +@item \vartheta +@BES{03D1,\vartheta} Variant on the lowercase Greek letter +(ordinary). The non-variant form is +@code{\theta}@tie{}@BES{03B8,\theta}. + +@item \vdash +@BES{22A2,\vdash} Provable; turnstile, vertical and a dash +(relation). Similar: turnstile rotated a +half-circle@tie{}@code{\dashv}. + +@item \vee +@BES{2228,\vee} Logical or; a downwards v shape (binary). Related: +logical and@tie{}@code{\wedge}. Similar: variable-sized +operator@tie{}@code{\bigvee}. + +@item \Vert +@BES{2016,\Vert} Vertical double bar (ordinary). Similar: vertical single +bar@tie{}@code{\vert}. + +For a norm symbol, you can use the @file{mathtools} package and put in +your preamble +@code{\DeclarePairedDelimiter\norm@{\lVert@}@{\rVert@}}. This gives you +three command variants for double-line vertical bars that are correctly +horizontally spaced: if in the document body you write the starred +version @code{$\norm*@{M^\perp@}$} then the height of the vertical bars +will match the height of the argument, whereas with +@code{\norm@{M^\perp@}} the bars do not grow with the height of the +argument but instead are the default height, and @code{\norm[@var{size +command}]@{M^\perp@}} also gives bars that do not grow but are set to +the size given in the @var{size command}, e.g., @code{\Bigg}. + +@item \vert +@BES{007C,\vert} Single line vertical bar (ordinary). Similar: double-line +vertical bar@tie{}@code{\Vert}. For such that, as in the definition of a +set, use@tie{}@code{\mid} because it is a relation. + +For absolute value you can use the @file{mathtools} package and in your +preamble put +@code{\DeclarePairedDelimiter\abs@{\lvert@}@{\rvert@}}. This gives you +three command variants for single-line vertical bars that are correctly +horizontally spaced: if in the document body you write the starred +version @code{$\abs*@{\frac@{22@}@{7@}@}$} then the height of the +vertical bars will match the height of the argument, whereas with +@code{\abs@{\frac@{22@}@{7@}@}} the bars do not grow with the height of +the argument but instead are the default height, and +@code{\abs[@var{size command}]@{\frac@{22@}@{7@}@}} also gives bars that +do not grow but are set to the size given in the @var{size command}, +e.g., @code{\Bigg}. + +@item \wedge +@BES{2227,\wedge} Logical and (binary). Synonym:@tie{}@code{\land}. See also +logical or @code{\vee}. Similar: variable-sized +operator@tie{}@code{\bigwedge}. + +@item \wp +@BES{2118,\wp} Weierstrass p (ordinary). + +@item \wr +@BES{2240,\wr} Wreath product (binary). + +@item \Xi +@BES{039E,\Xi} uppercase Greek letter (ordinary). + +@item \xi +@BES{03BE,\xi} Lowercase Greek letter (ordinary). + +@item \zeta +@BES{03B6,\zeta} Lowercase Greek letter (ordinary). + +@end ftable + +The following symbols are most often used in plain text but @LaTeX{} +provides versions to use in mathematical text. + +@ftable @code +@item \mathdollar +Dollar sign in math mode: $. + +@item \mathparagraph +Paragraph sign (pilcrow) in math mode, @BES{00B6,\P}. + +@item \mathsection +Section sign in math mode @BES{00A7,\S}. + +@item \mathsterling +Sterling sign in math mode: @pounds{}. + +@item \mathunderscore +Underscore in math mode: _. + +@end ftable + +@menu +* Blackboard bold:: Doublestruck characters. +* Calligraphic:: Cursive characters. +* \boldmath & \unboldmath:: Symbols in boldface. +* Dots:: Ellipses, etc. +@end menu + + +@node Blackboard bold +@subsection Blackboard bold + +@cindex blackboard bold +@cindex doublestruck + +Synopsis: + +@example +\usepackage@{amssymb@} % in preamble + ... +\mathbb@{@var{uppercase-letter}@} +@end example + +Provide blackboard bold symbols, sometimes also known as doublestruck +letters, used to denote number sets such as the natural numbers, the +integers, etc. + +Here + +@example +\( \forall n \in \mathbb@{N@}, n^2 \geq 0 \) +@end example + +@noindent +the @code{\mathbb@{N@}} gives blackboard bold symbol @BES{2115,} +representing the natural numbers. + +If you use other than an uppercase letter then you do not get an error +but you get strange results, including unexpected characters. + +There are packages that give access to symbols other than just the +capital letters; look on CTAN. + + +@node Calligraphic +@subsection Calligraphic + +@cindex calligraphic fonts +@cindex script fonts +@cindex fonts, script + +Synopsis: + +@example +\mathcal@{@var{uppercase-letters}@} +@end example + +Use a script-like font. + +In this example the graph identifier is output in a cursive font. + +@example +Let the graph be \( \mathcal@{G@} \). +@end example + +If you use something other than an uppercase letter then you do not get +an error. Instead you get unexpected output. For instance, +@code{\mathcal@{g@}} outputs a close curly brace symbol, while +@code{\mathcal@{+@}} outputs a plus sign. + + +@node \boldmath & \unboldmath +@subsection @code{\boldmath} & @code{\unboldmath} + +@cindex boldface mathematics +@cindex symbols, boldface +@findex \boldmath +@findex \unboldmath + +Synopsis (used in paragraph mode or LR mode): + +@example +\boldmath \( @var{math} \) +@end example + +@noindent +or + +@example +\unboldmath \( @var{math} \) +@end example + +@findex \boldmath +@findex \unboldmath +Declarations to change the letters and symbols in @var{math} to be in +a bold font, or to countermand that and bring back the regular +(non-bold) default. They must be used when not in math mode or display +math mode (@pxref{Modes}). Both commands are fragile +(@pxref{\protect}). + +In this example each @code{\boldmath} command takes place inside an +@code{\mbox}, + +@example +we have $\mbox@{\boldmath \( v \)@} = 5\cdot\mbox@{\boldmath \( u \)$@}$ +@end example + +@noindent +which means @code{\boldmath} is only called in a text mode, here LR +mode, and explains why @LaTeX{} must switch to math mode to set @code{v} +and @code{u}. + +If you use either command inside math mode, as with @code{Trouble: \( +\boldmath x \)}, then you get something like @samp{LaTeX Font Warning: +Command \boldmath invalid in math mode on input line 11} and @samp{LaTeX +Font Warning: Command \mathversion invalid in math mode on input line +11}. + +@PkgIndex{bm} +There are many issues with @code{\boldmath}. New documents should use +the @file{bm} package provided by the @LaTeX{} Project team. A complete +description is outside the scope of this document (see the full +documentation on CTAN) but even this small example + +@example +\usepackage@{bm@} % in preamble +... +we have $\bm@{v@} = 5\cdot\bm@{u@}$ +@end example + +@noindent +shows that it is an improvement over @code{\boldmath}. + + +@node Dots +@subsection Dots, horizontal or vertical + +@cindex ellipses +@cindex dots + +Ellipses are the three dots (usually three) indicating that a pattern +continues. + +@example +\begin@{array@}@{cccc@} + a_@{0,0@} &a_@{0,1@} &a_@{0,2@} &\ldots \\ + a_@{1,0@} &\ddots \\ + \vdots +\end@{array@} +@end example + +@LaTeX{} provides these. + +@ftable @code +@anchor{ellipses cdots} +@item \cdots +Horizontal ellipsis with the dots raised to the center of the line, as +in @BES{22EF,\cdots}. Used as: @code{\( a_0\cdot a_1\cdots a_@{n-1@} +\)}. + +@anchor{ellipses ddots} +@item \ddots +Diagonal ellipsis, @BES{22F1,\ddots}. See the above array example for a +usage. + +@anchor{ellipses ldots} +@item \ldots +Ellipsis on the baseline, @BES{2026,\ldots}. Used as: @code{\( +x_0,\ldots x_@{n-1@} \)}. Another example is the above array example. A +synonym is @code{\mathellipsis}. A synonym from the @file{amsmath} +package is @code{\hdots}. + +You can also use this command outside of mathematical text, as in +@code{The gears, brakes, \ldots@{@} are all broken}. (In a paragraph +mode or LR mode a synonym for @code{\ldots} is @code{\dots}.) + +@anchor{ellipses vdots} +@item \vdots +Vertical ellipsis, @BES{22EE,\vdots}. See the above array example for a +usage. + +@end ftable + +@PkgIndex{amsmath} +The @file{amsmath} package has the command @code{\dots} to semantically +mark up ellipses. This example produces two different-looking outputs +for the first two uses of the @code{\dots} command. + +@example +\usepackage@{amsmath@} % in preamble + ... +Suppose that \( p_0, p_1, \dots, p_@{n-1@} \) lists all of the primes. +Observe that \( p_0\cdot p_1 \dots \cdot p_@{n-1@} +1 \) is not a + multiple of any \( p_i \). +Conclusion: there are infinitely many primes \( p_0, p_1, \dotsc \). +@end example + +@noindent +In the first line @LaTeX{} looks to the comma following @code{\dots} to +determine that it should output an ellipsis on the baseline. The second +line has a @code{\cdot} following @code{\dots} so @LaTeX{} outputs an +ellipsis that is on the math axis, vertically centered. However, the +third usage has no follow-on character so you have to tell @LaTeX{} what +to do. You can use one of the commands: @code{\dotsc} if you need the +ellipsis appropriate for a comma following, @code{\dotsb} if you need +the ellipses that fits when the dots are followed by a binary operator +or relation symbol, @code{\dotsi} for dots with integrals, or +@code{\dotso} for others. + + +@node Math functions +@section Math functions + +@cindex math functions +@cindex functions, math + +These commands produce roman function names in math mode with proper +spacing. + +@ftable @code +@item \arccos +Inverse cosine +@iftex +@math{\arccos} +@end iftex + +@item \arcsin +Inverse sine +@iftex +@math{\arcsin} +@end iftex + +@item \arctan +Inverse tangent +@iftex +@math{\arctan} +@end iftex + +@item \arg +Angle between the real axis and a point in the complex plane +@iftex +@math{\arg} +@end iftex + +@item \bmod +Binary modulo operator, used as in @code{\( 5\bmod 3=2 \)} +@iftex +@math{5 \bmod 3} +@end iftex + +@item \cos +Cosine +@iftex +@math{\cos} +@end iftex + +@item \cosh +Hyperbolic cosine +@iftex +@math{\cosh} +@end iftex + +@item \cot +Cotangent +@iftex +@math{\cot} +@end iftex + +@item \coth +Hyperbolic cotangent +@iftex +@math{\coth} +@end iftex + +@item \csc +Cosecant +@iftex +@math{\csc} +@end iftex + +@item \deg +Degrees +@iftex +@math{\deg} +@end iftex + +@item \det +Determinant +@iftex +@math{\det} +@end iftex + +@item \dim +Dimension +@iftex +@math{\dim} +@end iftex + +@item \exp +Exponential +@iftex +@math{\exp} +@end iftex + +@item \gcd +Greatest common divisor +@iftex +@math{\gcd} +@end iftex + +@item \hom +Homomorphism +@iftex +@math{\hom} +@end iftex + +@item \inf +Infinum +@iftex +@math{\inf} +@end iftex + +@item \ker +Kernel +@iftex +@math{\ker} +@end iftex + +@item \lg +Base 2 logarithm +@iftex +@math{\lg} +@end iftex + +@item \lim +Limit +@iftex +@math{\lim} +@end iftex + +@item \liminf +Limit inferior +@iftex +@math{\liminf} +@end iftex + +@item \limsup +Limit superior +@iftex +@math{\limsup} +@end iftex + +@item \ln +Natural logarithm +@iftex +@math{\ln} +@end iftex + +@item \log +Logarithm +@iftex +@math{\log} +@end iftex + +@item \max +Maximum +@iftex +@math{\max} +@end iftex + +@item \min +Minimum +@iftex +@math{\min} +@end iftex + +@item \pmod +Parenthesized modulus, as used in @code{\( 5\equiv 2\pmod 3 \)} +@iftex +@math{5\equiv 2\pmod 3} +@end iftex + +@item \Pr +Probability +@iftex +@math{\Pr} +@end iftex + +@item \sec +Secant +@iftex +@math{\sec} +@end iftex + +@item \sin +Sine +@iftex +@math{\sin} +@end iftex + +@item \sinh +Hyperbolic sine +@iftex +@math{\sinh} +@end iftex + +@item \sup +@iftex +Supremum +@iftex +@math{\mathop {\rm sup}} +@end iftex +@ifnottex +sup +@end ifnottex +@c don't try to use \sup with dvi/pdf output since that turned into a +@c Texinfo command and it's not worth hassling with different versions +@c when it's just three roman letters anyway. + +@item \tan +Tangent +@iftex +@math{\tan} +@end iftex + +@item \tanh +Hyperbolic tangent +@iftex +@math{\tanh} +@end iftex + +@end ftable + +@PkgIndex{amsmath} +The @file{amsmath} package adds improvements on some of these, and also +allows you to define your own. The full documentation is on CTAN, but +briefly, you can define an identity operator with +@code{\DeclareMathOperator@{\identity@}@{id@}} that is like the ones +above but prints as @samp{id}. The starred form +@code{\DeclareMathOperator*@{\op@}@{op@}} sets any limits above and +below, as is traditional with @code{\lim}, @code{\sup}, or @code{\max}. + + +@node Math accents +@section Math accents + +@cindex math accents +@cindex accents, mathematical + +@LaTeX{} provides a variety of commands for producing accented letters +in math. These are different from accents in normal text +(@pxref{Accents}). + +@ftable @code +@item \acute +@cindex acute accent, math +Math acute accent +@iftex +@math{\acute{x}}. +@end iftex + +@item \bar +@cindex bar-over accent, math +@cindex macron accent, math +Math bar-over accent +@iftex +@math{\bar{x}} +@end iftex + +@item \breve +@cindex breve accent, math +Math breve accent +@iftex +@math{\breve{x}} +@end iftex + +@item \check +@cindex check accent, math +@cindex h@'a@v{c}ek accent, math +Math h@'a@v{c}ek (check) accent +@iftex +@math{\check{x}} +@end iftex + +@item \ddot +@cindex double dot accent, math +Math dieresis accent +@iftex +@math{\ddot{x}} +@end iftex + +@item \dot +@cindex overdot accent, math +@cindex dot over accent, math +Math dot accent +@iftex +@math{\dot{x}} +@end iftex + +@item \grave +@cindex grave accent, math +Math grave accent +@iftex +@math{\grave{x}} +@end iftex + +@item \hat +@cindex hat accent, math +@cindex circumflex accent, math +Math hat (circumflex) accent +@iftex +@math{\hat{x}} +@end iftex + +@item \mathring +@cindex ring accent, math +Math ring accent @c don't bother implementing in texinfo +@iftex +@ringaccent{x} +@end iftex + +@item \tilde +@cindex tilde accent, math +Math tilde accent +@iftex +@math{\tilde{x}} +@end iftex + +@item \vec +@cindex vector symbol, math +Math vector symbol +@iftex +@math{\vec{x}} +@end iftex + +@item \widehat +@cindex wide hat accent, math +Math wide hat accent +@iftex +@math{\widehat{x+y}} +@end iftex + +@item \widetilde +@cindex wide tilde accent, math +Math wide tilde accent +@iftex +@math{\widetilde{x+y}} +@end iftex + +@end ftable + +When you are putting an accent on an i or a j, the tradition is to use +one without a dot, @code{\imath} or @code{jmath} (@pxref{Math symbols}). + + +@node Over- and Underlining +@section Over- and Underlining + +@cindex overlining +@cindex underlining + +@LaTeX{} provides commands for making overlines or underlines, or +putting braces over or under some material. + +@ftable @code + +@item \underline@{@var{text}@} +Underline @var{text}. Works inside math mode, and outside. +@ifset HAS-MATH +The result of @code{\underline@{xyz@}} is @math{\underline{xyz}}. +@end ifset +The line is always completely below the text, taking account of +descenders, so in @code{\(\underline@{y@}\)} the line is lower than in +@code{\(\underline@{x@}\)}. This command is fragile (@pxref{\protect}). + +@PkgIndex{ulem} +Note that the package @file{ulem} does text mode underlining and allows +line breaking as well as a number of other features. See the +documentation on CTAN. See also@tie{}@ref{\hrulefill & \dotfill} for +producing a line, for such things as a signature. + +@item \overline@{@var{text}@} +Put a horizontal line over @var{text}. Works inside math mode, and +outside. For example, @code{\overline@{x+y@}}. +@ifset HAS-MATH +The result looks like: @math{\overline{x+y}}. +@end ifset +Note that this differs from the command @code{\bar} (@pxref{Math +accents}). + +@item \underbrace@{@var{math}@} +Put a brace under @var{math}. For example, this +@code{(1-\underbrace@{1/2)+(1/2@}-1/3)} emphasizes the telescoping part. +@ifset HAS-MATH +The result looks like this: @math{(1-\underbrace{1/2)+(1/2}-1/3)}. +@end ifset +Attach text to the brace by using subscript, @code{_}, or superscript, +@code{^}, as here. + +@example +\begin@{displaymath@} + 1+1/2+\underbrace@{1/3+1/4@}_@{>1/2@}+ + \underbrace@{1/5+1/6+1/7+1/8@}_@{>1/2@}+\cdots +\end@{displaymath@} +@end example + +The superscript appears on top of the expression, and so can look +unconnected to the underbrace. + +@item \overbrace@{@var{math}@} +Put a brace over @var{math}, as with +@code{\overbrace@{x+x+\cdots+x@}^@{\mbox@{\(k\) times@}@}}. See also +@code{\underbrace}. + +@end ftable + +@PkgIndex{mathtools} +The package @file{mathtools} adds an over- and underbrace, as well as +some improvements on the braces. See the documentation on CTAN. + + +@node Spacing in math mode +@section Spacing in math mode + +@cindex spacing within math mode +@cindex math mode, spacing + +When typesetting mathematics, @LaTeX{} puts in spacing according to the +normal rules for mathematics texts. If you enter @code{y=m x} then +@LaTeX{} ignores the space and in the output the m is next to the x, +as @math{y=mx}. + +But @LaTeX{}'s rules sometimes need tweaking. For example, in an +integral the tradition is to put a small extra space between the +@code{f(x)} and the @code{dx}, here done with the @code{\,} command. + +@example +\int_0^1 f(x)\,dx +@end example + +@LaTeX{} provides the commands that follow for use in math mode. Many +of these spacing definitions are expressed in terms of the math unit +@dfn{mu}. It is defined as 1/18@dmn{em}, where the em is taken from the +current math symbols family (@pxref{Units of length}). Thus, a +@code{\thickspace} is something like 5/18 times the width of +a@tie{}@samp{M}. + +@table @code +@item \; +@findex \; +@findex \thickspace +@anchor{spacing in math mode thickspace} +Synonym: @code{\thickspace}. Normally @code{5.0mu plus 5.0mu}. Math +mode only. + +@item \: +@itemx \> +@findex \: +@findex \> +@findex \medspace +@anchor{spacing in math mode medspace} +Synonym: @code{\medspace}. Normally @code{4.0mu plus 2.0mu minus 4.0mu}. +Math mode only. + +@item \, +@findex \, +@findex \thinspace +@cindex thin space +@anchor{Spacing in math mode/\thinspace} +@anchor{spacing in math mode thinspace} +Synonym: @code{\thinspace}. Normally @code{3mu}, which is 1/6@dmn{em}. +Can be used in both math mode and text mode (@pxref{\thinspace & +\negthinspace}). + +This space is widely used, for instance between the function and the +infinitesimal in an integral @code{\int f(x)\,dx} and, if an author does +this, before punctuation in a displayed equation. + +@example +The antiderivative is +\begin@{equation@} + 3x^@{-1/2@}+3^@{1/2@}\,. +\end@{equation@} +@end example + +@item \! +@findex \! +@findex \negthinspace +@cindex thin space, negative +@anchor{spacing in math mode negthinspace} +A negative thin space. Normally @code{-3mu}. The @code{\!} command is +math mode only but the @code{\negthinspace} command is available for +text mode (@pxref{\thinspace & \negthinspace}). + +@item \quad +@cindex quad +@findex \quad +@anchor{spacing in math mode quad} +This is 18@dmn{mu}, that is, 1@dmn{em}. This is often used for space +surrounding equations or expressions, for instance for the space between +two equations inside a @code{displaymath} environment. It is available +in both text and math mode. + +@item \qquad +@findex \qquad +@anchor{spacing in math mode qquad} +A length of 2 quads, that is, 36@dmn{mu} = 2@dmn{em}. It is available in +both text and math mode. +@end table + +@menu +* \smash:: Eliminate height or depth of a subformula. +* \phantom & \vphantom & \hphantom:: Make empty box with the same size as the argument. +@end menu + + +@node \smash +@subsection @code{\smash} + +@cindex vertical spacing, math mode +@cindex math mode, vertical space + +Synopsis: + +@example +\smash@{@var{subformula}@} +@end example + +Typeset @var{subformula} as if its height and depth were zero. + +In this example the exponential is so tall that without the +@code{\smash} command @LaTeX{} would separate its line from the line +above it, and the uneven line spacing might be unsightly. + +@example +To compute the tetration $\smash@{2^@{2^@{2^2@}@}@}$, +evaluate from the top down, as $2^@{2^4@}=2^@{16@}=65536$. +@end example + +(Because of the @code{\smash} the printed expression could run into the +line above so you may want to wait until the final version of the +document to make such adjustments.) + +This pictures the effect of @code{\smash} by using @code{\fbox} to +surround the box that @LaTeX{} will put on the line. The +@code{\blackbar} command makes a bar extending from 10@tie{}points below +the baseline to 20@tie{}points above. + +@example +\newcommand@{\blackbar@}@{\rule[-10pt]@{5pt@}@{30pt@}@} +\fbox@{\blackbar@} +\fbox@{\smash@{\blackbar@}@} +@end example + +The first box that @LaTeX{} places is 20@tie{}points high and +10@tie{}points deep. But the second box is treated by @LaTeX{} as +having zero height and zero depth, despite that the ink printed on the +page still extends well above and below the line. + +The @code{\smash} command appears often in mathematics to adjust the +size of an element that surrounds a subformula. Here the first radical +extends below the baseline while the second lies just on the baseline. + +@example +\begin@{equation@} +\sqrt@{\sum_@{0\leq k< n@} f(k)@} +\sqrt@{\vphantom@{\sum@}\smash@{\sum_@{0\leq k< n@}@} f(k)@} +\end@{equation@} +@end example + +Note the use of @code{\vphantom} to give the @code{\sqrt} command an +argument with the height of the @code{\sum} (@pxref{\phantom & \vphantom +& \hphantom}). + +While most often used in mathematics, the @code{\smash} command can +appear in other contexts. However, it doesn't change into horizontal +mode. So if it starts a paragraph then you should first put a +@code{\leavevmode}, as in the bottom line below. + +@example +xxx xxx xxx + +\smash@{yyy@} % no paragraph indent + +\leavevmode\smash@{zzz@} % usual paragraph indent +@end example + +@PkgIndex{mathtools} +The package @code{mathtools} has operators that provide even finer +control over smashing a subformula box. + + +@node \phantom & \vphantom & \hphantom +@subsection @code{\phantom} & @code{\vphantom} & @code{\hphantom} + +@cindex spacing, math mode +@cindex horizontal spacing +@cindex vertical spacing +@cindex math mode, spacing +@cindex invisible character +@cindex character, invisible + +Synopsis: + +@example +\phantom@{@var{subformula}@} +@end example + +or + +@example +\vphantom@{@var{subformula}@} +@end example + +or + +@example +\hphantom@{@var{subformula}@} +@end example + +The @code{\phantom} command creates a box with the same height, depth, +and width as @var{subformula}, but empty. That is, this command causes +@LaTeX{} to typeset the box but not its ink. The @code{\vphantom} +variant also produces an invisible box with the same height and depth as +@var{subformula}, but it has width zero. And @code{\hphantom} makes a +box with the same width as @var{subformula} but with height and depth +zero. + +Without the @code{\vphantom} in this example, the top bars of the two +square roots would be at different heights. + +@example +\( \sqrt@{\vphantom@{a^3@}a@}\cdot\sqrt@{a^3@} \) +@end example + +The @code{\vphantom@{a^3@}} causes the first @code{\sqrt} to have inside +it a box of the same height as the second @code{\sqrt}, so @LaTeX{} +makes the bars align. + +These commands often are combined with @code{\smash}. @xref{\smash} +for another example of the use of @code{\vphantom}. + +@PkgIndex{mathtools} +The three phantom commands appear often but note that @LaTeX{} provides +a suite of other commands to work with box sizes that may be more +convenient, including @code{\makebox} (@pxref{\mbox & \makebox}) as well +as @code{\settodepth} (@pxref{\settodepth}), @code{\settoheight} +(@pxref{\settoheight}), and @code{\settowidth} (@pxref{\settowidth}). +In addition, the @file{mathtools} package has many commands that offer +fine-grained control over spacing. + +@PkgIndex{amsmath} +All three commands produce an ordinary box, without any special +mathematics status. So to do something like attaching a superscript you +should give it such a status, for example with the @code{\operatorname} +command from the package @file{amsmath}. + +While most often used in mathematics, these three can appear in other +contexts. However, they don't cause @LaTeX{} to change into horizontal +mode. So if one of these starts a paragraph then you should prefix it +with @code{\leavevmode}. + + +@node Math miscellany +@section Math miscellany + +@cindex math miscellany + +@LaTeX{} contains a wide variety of mathematics facilities. Here are +some that don't fit into other categories. + +@menu +* Colon character & \colon:: Colon. +* \*:: Discretionary multiplication. +* \frac:: Fraction. +* \left & \right:: Paired delimiters. +* \sqrt:: Radicals. +* \stackrel:: Text over a relation. +@end menu + + +@node Colon character & \colon +@subsection Colon character @code{:} & @code{\colon} + +@cindex : +@cindex colon character +@findex : +@findex \colon + +Synopsis, one of: + +@example +: +\colon +@end example + +In mathematics, the colon character, @code{:}, is a relation. + +@example +With side ratios \( 3:4 \) and \( 4:5 \), the triangle is right. +@end example + +@PkgIndex{amsmath} +@noindent +Ordinary @LaTeX{} defines @code{\colon} to produce the colon character +with the spacing appropriate for punctuation, as in set-builder notation +@code{\@{x\colon 0\leq x<1\@}}. + +@PkgIndex{amsmath} +But the widely-used @file{amsmath} package defines @code{\colon} for use +in the definition of functions @code{f\colon D\to C}. So if you want +the colon character as a punctuation then use @code{\mathpunct@{:@}}. + + +@node \* +@subsection @code{\*} + +@cindex multiplication, discretionary +@cindex breaks, multiplication discretionary +@cindex line breaks, multiplication discretionary +@cindex discretionary breaks, multiplication +@findex \* + +Synopsis: + +@example +\* +@end example + +A multiplication symbol that allows a line break. If there is a break +then @LaTeX{} puts a @code{\times} symbol, @BES{00D7,\times}, before +that break. + +In @code{\( A_1\* A_2\* A_3\* A_4 \)}, if there is no line break then +@LaTeX{} outputs it as though it were @code{\( A_1 A_2 A_3 A_4 \)}. If +a line break does happen, for example between the two middle ones, then +@LaTeX{} sets it like @code{\( A_1 A_2 \times \)}, followed by the +break, followed by @code{\( A_3 A_4 \)}. + + +@node \frac +@subsection @code{\frac} + +@cindex fraction +@findex \frac + +Synopsis: + +@example +\frac@{@var{numerator}@}@{@var{denominator}@} +@end example + +Produces the fraction. Used as: @code{\begin@{displaymath@} +\frac@{1@}@{\sqrt@{2\pi\sigma@}@} \end@{displaymath@}}. In inline math +mode it comes out small; see the discussion of @code{\displaystyle} +(@pxref{Math formulas}). + + +@node \left & \right +@subsection @code{\left} & @code{\right} + +@cindex delimiters, paired +@cindex paired delimiters +@cindex matching parentheses +@cindex matching brackets +@cindex null delimiter +@findex \left +@findex \right + +Synopsis: + +@example +\left @var{delimiter1} ... \right @var{delimiter2} +@end example + +Make matching parentheses, braces, or other delimiters. The delimiters +are sized according to the math they enclose. This makes a unit vector +surrounded by appropriate-height parentheses. + +@example +\begin@{equation@} + \left(\begin@{array@}@{c@} + 1 \\ + 0 \\ + \end@{array@}\right) +@end example + +Every @code{\left} must have a matching @code{\right}. Leaving out the +@code{\left(} in the above gets @samp{Extra \right}. Leaving off the +@code{\right)} gets @samp{You can't use `\eqno' in math mode}. + +However, the two delimiters @var{delimiter1} and @var{delimiter2} need +not match. A common case is that you want an unmatched brace, as +below. Use a period, @samp{.}, as a null delimiter. + +@example +\begin@{equation@} + f(n)=\left\@{\begin@{array@}@{ll@} + 1 &\mbox@{--if \(n=0\)@} \\ + f(n-1)+3n^2 &\mbox@{--else@} + \end@{array@}\right. +\end@{equation@} +@end example + +@noindent +Note that to get a curly brace as a delimiter you must prefix it with a +backslash, @code{\@{}. + + +@node \sqrt +@subsection @code{\sqrt} + +@cindex square root +@cindex roots +@cindex radical +@findex \sqrt + +Synopsis, one of: + +@example +\sqrt@{@var{arg}@} +\sqrt[@var{root-number}]@{@var{arg}@} +@end example + +The square root, or optionally other roots, of @var{arg}. The optional +argument @var{root-number} gives the root, i.e., enter the cube root of +@code{x+y} as @code{\sqrt[3]@{x+y@}}. +@ifset HAS-MATH +It comes out like this: @math{\root 3 \of {x+y}}. +@end ifset +The radical grows with the size of @var{arg} (as the height of the +radical grows, the angle on the leftmost part gets steeper, until for +a large enough @code{arg}, it is vertical). + +@LaTeX{} has a separate @code{\surd} character (@pxref{Math symbols}). + + +@node \stackrel +@subsection @code{\stackrel} + +@cindex stack math +@cindex relation, text above +@findex \stackrel + +Synopsis, one of: + +@example +\stackrel@{@var{text}@}@{@var{relation}@} +@end example + +Put @var{text} above @var{relation}. To put a function name above an +arrow enter @code{\stackrel@{f@}@{\longrightarrow@}}. +@ifset HAS-MATH + The result looks like this: @math{\buildrel f \over \longrightarrow}. +@end ifset + + +@node Modes +@chapter Modes + +@cindex modes + +As @LaTeX{} processes your document, at any point it is in one of six +modes. They fall into three categories of two each, the horizontal +modes, the math modes, and the vertical modes. Some commands only work +in one mode or another (in particular, many commands only work in one of +the math modes), and error messages will refer to these. + +@itemize +@item +@anchor{modes paragraph mode} +@cindex paragraph mode +@dfn{Paragraph mode} is what @LaTeX{} is in when processing ordinary +text. It breaks the input text into lines and breaks the lines into +pages. This is the mode @LaTeX{} is in most of the time. + +@cindex left-to-right mode +@cindex LR mode +@anchor{modes lr mode} +@dfn{LR mode} (for left-to-right mode; in plain @TeX{} this is called +@dfn{restricted horizontal mode}) is in effect when @LaTeX{} starts +making a box with an @code{\mbox} command. As in paragraph mode, +@LaTeX{}'s output is a string of words with spaces between them. Unlike +in paragraph mode, in LR mode @LaTeX{} never starts a new line, it just +keeps going from left to right. (Although @LaTeX{} will not complain +that the LR box is too long, when it is finished and next tries to put +that box into a line, it could very well complain that the finished LR +box won't fit there.) + +@item +@cindex math mode +@anchor{modes math mode} @dfn{Math mode} is when @LaTeX{} is generating +an inline mathematical formula. + +@cindex display math mode +@dfn{Display math mode} is when @LaTeX{} is generating a displayed +mathematical formula. (Displayed formulas differ somewhat from inline +ones. One example is that the placement of the subscript on @code{\int} +differs in the two situations.) + +@item +@cindex vertical mode +@anchor{modes vertical mode} +@dfn{Vertical mode} is when @LaTeX{} is building the list of lines and +other material making the output page. This is the mode @LaTeX{} is in +when it starts a document. + +@cindex internal vertical mode +@anchor{modes internal vertical mode} +@dfn{Internal vertical mode} is in effect when @LaTeX{} starts making a +@code{\vbox}. This is the vertical analogue of LR mode. + +@end itemize + +@noindent +For instance, if you begin a @LaTeX{} article with @samp{Let \( x \) be +...} then these are the modes: first @LaTeX{} starts every document in +vertical mode, then it reads the @samp{L} and switches to paragraph +mode, then the next switch happens at the @samp{\(} where @LaTeX{} +changes to math mode, and then when it leaves the formula it pops +back to paragraph mode. + +@cindex inner paragraph mode +@cindex outer paragraph mode +@anchor{modes inner paragraph mode} +@anchor{modes outer paragraph mode} +Paragraph mode has two subcases. If you use a @code{\parbox} command +or a @code{minipage} then @LaTeX{} is put into paragraph mode. But it +will not put a page break here. Inside one of these boxes, called a +@dfn{parbox}, @LaTeX{} is in @dfn{inner paragraph mode}. Its more usual +situation, where it can put page breaks, is @dfn{outer paragraph mode} +(@pxref{Page breaking}). + +@menu +* \ensuremath:: Ensure that math mode is active. +@end menu + +@node \ensuremath +@section @code{\ensuremath} + +Synopsis: + +@example +\ensuremath@{@var{formula}@} +@end example + +Ensure that @var{formula} is typeset in math mode. + +For instance, you can redefine commands that ordinarily can be used only +in math mode, so that they can be used both in math and in plain text. + +@example +\newcommand@{\dx@}@{\ensuremath@{dx@}@} +In $\int f(x)\, \dx$, the \dx@{@} is an infinitesimal. +@end example + +Caution: the @code{\ensuremath} command is useful but not a panacea. + +@example +\newcommand@{\alf@}@{\ensuremath@{\alpha@}@} +You get an alpha in text mode: \alf. +But compare the correct spacing in $\alf+\alf$ with that in \alf+\alf. +@end example + +@noindent +Best is to typeset math things in a math mode. + + +@node Page styles +@chapter Page styles + +@cindex styles, page +@cindex page styles + +The style of a page determines where @LaTeX{} places the components of +that page, such as headers and footers, and the text body. This +includes pages in the main part of the document but also includes +special pages such as the title page of a book, a page from an index, or +the first page of an article. + +@PkgIndex{fancyhdr} +The package @file{fancyhdr} is very helpful for constructing page +styles. See its documentation on CTAN. + +@menu +* \maketitle:: Generate a title page. +* \pagenumbering:: Set the style used for page numbers. +* \pagestyle:: Change the headings/footings style. +* \thispagestyle:: Change the headings/footings style for this page. +@end menu + + +@node \maketitle +@section @code{\maketitle} + +@cindex titles, making +@findex \maketitle + +Synopsis: + +@example +\maketitle +@end example + +Generate a title. In the standard classes the title appears on a +separate page, except in the @code{article} class where it is at the top +of the first page. (@xref{Document class options} for information about +the @code{titlepage} document class option.) + +This example shows @code{\maketitle} appearing in its usual place, +immediately after @code{\begin@{document@}}. + +@example +\documentclass@{article@} +\title@{Constructing a Nuclear Reactor Using Only Coconuts@} +\author@{Jonas Grumby\thanks@{% + With the support of a Ginger Grant from the Roy Hinkley Society.@} \\ + Skipper, \textit@{Minnow@} + \and + Willy Gilligan\thanks@{% + Thanks to the Mary Ann Summers foundation + and to Thurston and Lovey Howell.@} \\ + Mate, \textit@{Minnow@} + @} +\date@{1964-Sep-26@} +\begin@{document@} +\maketitle +Just sit right back and you'll hear a tale, a tale of a fateful trip. +That started from this tropic port, aboard this tiny ship. The mate was +a mighty sailin' man, the Skipper brave and sure. Five passengers set +sail that day for a three hour tour. A three hour tour. + ... +@end example + +You tell @LaTeX{} the information used to produce the title by making +the following declarations. These must come before the +@code{\maketitle}, either in the preamble or in the document body. + +@ftable @code +@item \author@{@var{name1} \and @var{name2} \and ...@} +@cindex author, for titlepage +@findex \\ @r{for @code{\author}} +@findex \and @r{for @code{\author}} +Required. Declare the document author or authors. The argument is a +list of authors separated by @code{\and} commands. To separate lines +within a single author's entry, for instance to give the author's +institution or address, use a double backslash, @code{\\}. If you omit +the @code{\author} declaration then you get @samp{LaTeX Warning: No +\author given}. + +@item \date@{@var{text}@} +@cindex date, for titlepage +Optional. Declare @var{text} to be the document's date. The @var{text} +doesn't need to be in a date format; it can be any text at all. If you +omit @code{\date} then @LaTeX{} uses the current date (@pxref{\today}). +To have no date, instead use @code{\date@{@}}. + +@item \thanks@{@var{text}@} +@cindex thanks, for titlepage +@cindex credit footnote +Optional. Produce a footnote. You can use it in the author information +for acknowledgements as illustrated above, but you can also use it in +the title, or any place a footnote makes sense. It can be any text at +all so you can use it for any purpose, such as to print an email +address. + +@item \title@{@var{text}@} +@cindex title, for titlepage +@findex \\ @r{for @code{\title}} +Required. Declare @var{text} to be the title of the document. Get line +breaks inside @var{text} with a double backslash, @code{\\}. If you +omit the @code{\title} declaration then you get @samp{LaTeX Error: No +\title given}. + +@end ftable + +To make your own title page, see@tie{}@ref{titlepage}. You can either +create this as a one-off or you can include it as part of a renewed +@code{\maketitle} command. (Many publishers will provide a class to use +in place of @code{article} that formats the title according to their +house requirements.) + + +@node \pagenumbering +@section @code{\pagenumbering} + +@findex \pagenumbering +@cindex page numbering style + +Synopsis: + +@example +\pagenumbering@{@var{number-style}@} +@end example + +Specifies the style of page numbers, and resets the page number. The +numbering style is reflected on the page, and also in the table of +contents and other page references. This declaration has global scope +so its effect is not delimited by braces or environments. + +In this example, before the Main section the pages are numbered +@samp{a}, etc. Starting on the page containing that section, the pages +are numbered @samp{1}, etc. + +@example +\begin@{document@}\pagenumbering@{alph@} + ... +\section@{Main@}\pagenumbering@{arabic@} + ... +@end example + +The argument @var{number-style} is one of the following (see +also@tie{}@ref{\alph \Alph \arabic \roman \Roman \fnsymbol}). + +@table @code +@item arabic +Arabic numerals: 1, 2, @dots{} + +@item roman +lowercase Roman numerals: i, ii, @dots{} + +@item Roman +uppercase Roman numerals: I, II, @dots{} + +@item alph +lowercase letters: a, b, @dots{} If you have more than 26 pages then you +get @samp{LaTeX Error: Counter too large}. + +@item Alph +uppercase letters: A, B, @dots{} If you have more than 26 pages then you +get @samp{LaTeX Error: Counter too large}. + +@item gobble +@PkgIndex{hyperref} @LaTeX{} does not output a page number, although it +does get reset. References to that page also are blank. (This does not +work with the popular package @file{hyperref} so to have the page number +not appear you may want to instead use @code{\pagestyle@{empty@}} or +@code{\thispagestyle@{empty@}}.) + +@end table + +Traditionally, if a document has front matter---preface, table of +contents, etc.---then it is numbered with lowercase Roman numerals. The +main matter of a document uses arabic. @xref{\frontmatter & \mainmatter +& \backmatter}. + +If you want to address where the page number appears on the page, +see@tie{}@ref{\pagestyle}. If you want to change the value of page +number then you will manipulate the @code{page} counter +(@pxref{Counters}). + + +@node \pagestyle +@section @code{\pagestyle} + +@findex \pagestyle +@cindex header style +@cindex footer style +@cindex running header and footer style + +Synopsis: + +@example +\pagestyle@{@var{style}@} +@end example + +Declaration that specifies how the page headers and footers are typeset, +from the current page onwards. + +@PkgIndex{fancyhdr} +A discussion with an example is below. Note first that the package +@file{fancyhdr} is now the standard way to manipulate headers and +footers. New documents that need to do anything other than one of the +standard options below should use this package. See its documentation +on CTAN. + +Values for @var{style}: + +@table @code +@item plain +The header is empty. The footer contains only a page number, centered. + +@item empty +The header and footer is empty. + +@item headings +Put running headers and footers on each page. The document style +specifies what goes in there; see the discussion below. + +@item myheadings +Custom headers, specified via the @code{\markboth} or the +@code{\markright} commands. + +@end table + +Some discussion of the motivation for @LaTeX{}'s mechanism will help you +work with the options @code{headings} or @code{myheadings}. The +document source below produces an article, two-sided, with the pagestyle +@code{headings}. On this document's left hand pages, @LaTeX{} wants (in +addition to the page number) the title of the current section. On its +right hand pages @LaTeX{} wants the title of the current subsection. +When it makes up a page, @LaTeX{} gets this information from the +commands @code{\leftmark} and @code{\rightmark}. So it is up to +@code{\section} and @code{\subsection} to store that information there. + +@example +\documentclass[twoside]@{article@} +\pagestyle@{headings@} +\begin@{document@} + ... \section@{Section 1@} ... \subsection@{Subsection 1.1@} ... +\section@{Section 2@} + ... +\subsection@{Subsection 2.1@} + ... +\subsection@{Subsection 2.2@} + ... +@end example + +@noindent +Suppose that the second section falls on a left page. Although when the +page starts it is in the first section, @LaTeX{} will put +@samp{Section@tie{}2} in the left page header. As to the right header, +if no subsection starts before the end of the right page then @LaTeX{} +blanks the right hand header. If a subsection does appear before the +right page finishes then there are two cases. If at least one +subsection starts on the right hand page then @LaTeX{} will put in the +right header the title of the first subsection starting on that right +page. If at least one of 2.1, 2.2, @dots{}, starts on the left page but +none starts on the right then @LaTeX{} puts in the right hand header the +title of the last subsection to start, that is, the one in effect during +the right hand page. + +To accomplish this, in a two-sided article, @LaTeX{} has @code{\section} +issue a command @code{\markboth}, setting @code{\leftmark} +to @samp{Section@tie{}2} and setting @code{\rightmark} to blank. +And, @LaTeX{} has @code{\subsection} issue a command @code{\markright}, +setting @code{\rightmark} to @samp{Subsection@tie{}2.1}, etc. + +Here are the descriptions of @code{\markboth} and @code{\markright}: + +@ftable @code +@item \markboth@{@var{left-head}@}@{@var{right-head}@} +Sets both the right hand and left hand heading information for either a +page style of @code{headings} or @code{myheadings}. A left hand page +heading @var{left-head} is generated by the last @code{\markboth} +command before the end of the page. A right hand page heading +@var{right-head} is generated by the first @code{\markboth} or +@code{\markright} that comes on the page if there is one, otherwise by +the last one that came before that page. + +@item \markright@{@var{right}@} +Sets the right hand page heading, leaving the left unchanged. + +@end ftable + + +@node \thispagestyle +@section @code{\thispagestyle} + +@findex \thispagestyle +@cindex page style, this page + +Synopsis: + +@example +\thispagestyle@{@var{style}@} +@end example + +Works in the same way as the @code{\pagestyle} (@pxref{\pagestyle}), +except that it changes to @var{style} for the current page only. This +declaration has global scope, so its effect is not delimited by braces +or environments. + +Often the first page of a chapter or section has a different style. For +example, this @LaTeX{} book document has the first page of the first +chapter in @code{plain} style, as is the default (@pxref{Page +styles}). + +@example +\documentclass@{book@} +\pagestyle@{headings@} +\begin@{document@} +\chapter@{First chapter@} + ... +\chapter@{Second chapter@}\thispagestyle@{empty@} + ... +@end example + +@noindent +The @code{plain} style has a page number on it, centered in the footer. +To make the page entirely empty, the command +@code{\thispagestyle@{empty@}} immediately follows the second +@code{\chapter}. + + +@node Spaces +@chapter Spaces + +@cindex spaces +@cindex white space + +@LaTeX{} has many ways to produce white (or filled) space. Some of +these are best suited to mathematical text; see@tie{}@ref{Spacing in +math mode}. Some spacing commands are suitable for both regular text +and mathematical text; versions of some of these commands are in this +chapter. + +@menu +Horizontal space +* \enspace & \quad & \qquad:: Traditional horizontal spaces. +* \hspace:: Any horizontal space. +* \hfill:: Stretchable horizontal space. +* \hss:: Infinitely stretchable/shrinkable horizontal space. +* \spacefactor:: Stretchability of following space +* \(SPACE):: Backslash-space; and explicit space. +* ~:: Tie, an unbreakable space. +* \thinspace & \negthinspace:: One-sixth of an em, and negative one-sixth. +* \/:: Italic correction. +* \hrulefill & \dotfill:: Stretchable horizontal rule or dots. + +Vertical space +* \bigskip & \medskip & \smallskip:: Inter-paragraph vertical spaces. +* \bigbreak & \medbreak & \smallbreak:: Inter-paragraph space and page breaks. +* \strut:: Ensure height of a line. +* \vspace:: Vertical space. +* \vfill:: Stretchable vertical space. +* \addvspace:: Add arbitrary vertical space if needed. +@end menu + + +@node \enspace & \quad & \qquad +@section @code{\enspace} & @code{\quad} & @code{\qquad} + +@findex \enspace +@findex \quad +@findex \qquad + +Synopsis, one of: + +@example +\enspace +\quad +\qquad +@end example + +Insert a horizontal space of 1/2@dmn{em}, 1@dmn{em}, or 2@dmn{em}. The +em is a length defined by a font designer, often thought of as being the +width of a capital@tie{}M. One advantage of describing space in ems is +that it can be more portable across documents than an absolute +measurement such as points (@pxref{Lengths/em}). + +This puts a suitable gap between two graphics. + +@example +\begin@{center@} + \includegraphics@{womensmile.png@}% + \qquad\includegraphics@{mensmile.png@} +\end@{center@} +@end example + +@noindent +@xref{Spacing in math mode} for @code{\quad} and @code{\qquad}. These +are lengths from centuries of typesetting and so may be a better choice +in many circumstances than arbitrary lengths, such as you get with +@code{\hspace}. + + +@node \hspace +@section @code{\hspace} + +@findex \hspace + +Synopsis, one of: + +@example +\hspace@{@var{length}@} +\hspace*@{@var{length}@} +@end example + +Insert the horizontal space @var{length}. The @var{length} can be +positive, negative, or zero; adding negative space is like backspacing. +It is a rubber length, that is, it may contain a @code{plus} or +@code{minus} component, or both (@pxref{Lengths}). Because the space is +stretchable and shrinkable, it is sometimes called @dfn{glue}. + +This makes a line with @samp{Name:} an inch from the right margin. + +@example +\noindent\makebox[\linewidth][r]@{Name:\hspace@{1in@}@} +@end example + +The @code{*}-version inserts horizontal space that non-discardable. +More precisely, when @TeX{} breaks a paragraph into lines any white +space---glues and kerns---that come at a line break are discarded. The +@code{*}-version avoids that (technically, it adds a non-discardable +invisible item in front of the space). + +In this example + +@example +\parbox@{0.8\linewidth@}@{% + Fill in each blank: Four \hspace*@{1in@} and seven years ago our + fathers brought forth on this continent, a new \hspace*@{1in@}, + conceived in \hspace*@{1in@}, and dedicated to the proposition + that all men are created \hspace*@{1in@}.@} +@end example + +@noindent +the 1@tie{}inch blank following @samp{conceived in} falls at the start +of a line. If you erase the @code{*} then @LaTeX{} discards the blank. + +Here, the @code{\hspace} separates the three graphics. + +@example +\begin@{center@} + \includegraphics@{lion.png@}% comment keeps out extra space + \hspace@{1cm minus 0.25cm@}\includegraphics@{tiger.png@}% + \hspace@{1cm minus 0.25cm@}\includegraphics@{bear.png@} +\end@{center@} +@end example + +@noindent +Because the argument to each @code{\hspace} has @code{minus 0.25cm}, +each can shrink a little if the three figures are too wide. But each +space won't shrink more than 0.25@dmn{cm} (@pxref{Lengths}). + + +@node \hfill +@section @code{\hfill} + +@findex \hfill + +@cindex stretch, infinite horizontal +@cindex infinite horizontal stretch + +Synopsis: + +@example +\hfill +@end example + +Produce a rubber length which has no natural space but that can stretch +horizontally as far as needed (@pxref{Lengths}). + +This creates a one-line paragraph with @samp{Name:} on the left side +of the page and @samp{Quiz One} on the right. + +@example +\noindent Name:\hfill Quiz One +@end example + +@findex \fill +The @code{\hfill} command is equivalent to @code{\hspace@{\fill@}} and +so the space can be discarded at line breaks. To avoid that instead use +@code{\hspace*@{\fill@}} (@pxref{\hspace}). + +Here the graphs are evenly spaced in the middle of the figure. + +@example +\newcommand*@{\vcenteredhbox@}[1]@{\begin@{tabular@}@{@@@{@}c@@@{@}@}#1\end@{tabular@}@} + ... +\begin@{figure@} + \hspace*@{\fill@}% + \vcenteredhbox@{\includegraphics@{graph0.png@}@}% + \hfill\vcenteredhbox@{\includegraphics@{graph1.png@}@}% + \hspace*@{\fill@}% + \caption@{Comparison of two graphs@} \label@{fig:twographs@} +\end@{figure@} +@end example + +@noindent +Note the @code{\hspace*}'s where the space could otherwise be dropped. + + +@node \hss +@section @code{\hss} + +@findex \hss +@cindex horizontal space +@cindex horizontal space, stretchable +@cindex space, inserting horizontal + +Synopsis: + +@example +\hss +@end example + +Produce a horizontal space that is infinitely shrinkable as well as +infinitely stretchable (this command is a @TeX{} primitive). @LaTeX{} +authors should reach first for the @code{\makebox} command to get the +effects of @code{\hss} (@pxref{\mbox & \makebox}). + +Here, the first line's @code{\hss} makes the Z stick out to the right, +overwriting the Y. In the second line the Z sticks out to the left, +overwriting the X. + +@example +X\hbox to 0pt@{Z\hss@}Y +X\hbox to 0pt@{\hss Z@}Y +@end example + +@noindent +Without the @code{\hss} you get something like @samp{Overfull \hbox +(6.11111pt too wide) detected at line 20}. + + +@node \spacefactor +@section @code{\spacefactor} + +Synopsis: + +@example +\spacefactor=@var{integer} +@end example + +@findex \spacefactor +Influence @LaTeX{}'s glue stretch and shrink behavior. Most user-level +documents do not use this command. + +While @LaTeX{} is laying out the material, it may stretch or shrink the +gaps between words. (This space is not a character; it is called the +@dfn{interword glue}; @pxref{\hspace}). The @code{\spacefactor} command +(from Plain@tie{}@TeX{}) allows you to, for instance, have the space +after a period stretch more than the space after a word-ending letter. + +After @LaTeX{} places each character, or rule or other box, it sets a +parameter called the @dfn{space factor}. If the next thing in the input +is a space then this parameter affects how much stretching or shrinking +can happen. A space factor that is larger than the normal value means +that the glue can stretch more and shrink less. Normally, the space +factor is 1000. This value is in effect following most characters, and +any non-character box or math formula. But it is 3000 after a period, +exclamation mark, or question mark, it is 2000 after a colon, 1500 after +a semicolon, 1250 after a comma, and 0 after a right parenthesis or +bracket, or closing double quote or single quote. Finally, it is 999 +after a capital letter. + +If the space factor@tie{}@var{f} is 1000 then the glue gap will be the +font's normal space value (for Computer Modern Roman 10 point this is +3.3333@tie{}points). Otherwise, if the space factor @var{f} is greater +than 2000 then @TeX{} adds the font's extra space value (for Computer +Modern Roman 10 point this is 1.11111@tie{}points), and then the font's +normal stretch value is multiplied by @math{f /1000} and the normal +shrink value is multiplied by @math{1000/f} (for Computer Modern Roman +10 point these are 1.66666 and 1.11111@tie{}points). + +For example, consider the period ending @code{A man's best friend is his +dog.} After it, @TeX{} puts in a fixed extra space, and also allows the +glue to stretch 3 times as much and shrink 1/3 as much, as the glue +after @code{friend}, which does not end in a period. + +The rules for space factors are even more complex because they play +additional roles. In practice, there are two consequences. First, if a +period or other punctuation is followed by a right parenthesis or +bracket, or right single or double quote then the spacing effect of that +period carries through those characters (that is, the following glue +will have increased stretch and shrink). Second, if +punctuation comes after a capital letter then its effect is not in place +so you get an ordinary space. This second case also affects abbreviations +that do not end in a capital letter (@pxref{\@@}). + +You can only use @code{\spacefactor} in paragraph mode or LR mode +(@pxref{Modes}). You can see the current value with +@code{\the\spacefactor} or @code{\showthe\spacefactor}. + +(Comment, not really related to @code{\spacefactor}: if you get errors +like @samp{You can't use `\spacefactor' in vertical mode}, or @samp{You +can't use `\spacefactor' in math mode.}, or @samp{Improper \spacefactor} +then you have probably tried to redefine an internal command. +@xref{\makeatletter & \makeatother}.) + + +@menu +* \@@:: Distinguish sentence-ending periods from abbreviations. +* \frenchspacing:: Equal interword and inter-sentence space. +* \normalsfcodes:: Restore space factor settings to the default. +@end menu + + +@node \@@ +@subsection @code{\@@} + +@findex \@@ +@findex at-sign +@cindex period, sentence-ending +@cindex period, abbreviation-ending +@cindex period, spacing after +@anchor{\AT}@c old name + +Synopsis: + +@example +@var{capital-letter}\@@. +@end example + +Treat a period as sentence-ending, where @LaTeX{} would otherwise think +it is part of an abbreviation. @LaTeX{} thinks that a period ends an +abbreviation if the period comes after a capital letter, and otherwise +thinks the period ends the sentence. By default, in justifying a line +@LaTeX{} adjusts the space after a sentence-ending period (or a question +mark, exclamation point, comma, or colon) more than it adjusts the space +between words (@pxref{\spacefactor}). + +This example shows the two cases to remember. + +@example +The songs \textit@{Red Guitar@}, etc.\ are by Loudon Wainwright~III\@@. +@end example + +@noindent +The second period ends the sentence, despite that it is preceded by a +capital. We tell @LaTeX{} that it ends the sentence by putting +@code{\@@} before it. The first period ends the abbreviation +@samp{etc.} but not the sentence. The backslash-space, @code{\ }, +produces a mid-sentence space. + +So: if you have a capital letter followed by a period that ends the +sentence, then put @code{\@@} before the period. This holds even if +there is an intervening right parenthesis or bracket, or right single or +double quote, because the spacing effect of that period carries through +those characters. For example, this + +@example +Use the \textit@{Instructional Practices Guide@}, +(a book by the MAA)\@@. +@end example + +@noindent +will have correct inter-sentence spacing after the period. + +The @code{\@@} command is only for a text mode. If you use it outside of +a text mode then you get @samp{You can't use `\spacefactor' in vertical +mode} (@pxref{Modes}). + +Comment: the converse case is a period ending an abbreviation whose last +letter is not a capital letter, and that abbreviation is not the last +word in the sentence. For that case follow the period with a +backslash-space, (@code{\ }), or a tie, (@code{~}), or @code{\@@}. +Examples are @code{Nat.\ Acad.\ Science}, and @code{Mr.~Bean}, and +@code{(manure, etc.\@@) for sale} (note in the last one that the +@code{\@@} comes before the closing parenthesis). + + +@node \frenchspacing +@subsection @code{\frenchspacing} + +@findex \frenchspacing +@findex \nonfrenchspacing +@cindex spacing, inter-sentence + +Synopsis, one of: + +@example +\frenchspacing +\nonfrenchspacing +@end example + +The first declaration causes @LaTeX{} to treat spacing between sentences +in the same way as spacing between words in the middle of a sentence. +The second causes spacing between sentences to stretch or shrink more +(@pxref{\spacefactor}); this is the default. + +Some typographic traditions, including English, prefer to adjust the +space between sentences (or spaces following a question mark, +exclamation point, comma, or colon) more than the space between words +that are in the middle of a sentence. Declaring @code{\frenchspacing} +(the command is from Plain @TeX{}) switches to the tradition that all +spaces are treated equally. + + +@node \normalsfcodes +@subsection @code{\normalsfcodes} + +@findex \normalsfcodes +@cindex spacing, inter-sentence + +Synopsis: + +@example +\normalsfcodes +@end example + +Reset the @LaTeX{} space factor values to the default +(@pxref{\spacefactor}). + + +@node \(SPACE) +@section Backslash-space, @code{\ } + +@cindex \NEWLINE +@cindex \SPACE +@cindex \TAB + +This section refers to the command consisting of two characters, a +backslash followed by a space. Synopsis: + +@example +\ +@end example + +Produce a space. By default it produces white space of length +3.33333@dmn{pt} plus 1.66666@dmn{pt} minus 1.11111@dmn{pt}. + +When you type one or more blanks between words, @LaTeX{} produces white +space. But that is different than an explicit space. This illustrates. + +@example +\begin@{tabular@}@{l@} +One blank: makes some space \\ +Three blanks: in a row \\ +Three spaces:\ \ \ in a row \\ +\end@{tabular@} +@end example + +@noindent +On the first line @LaTeX{} puts some space after the colon. On the +second line @LaTeX{} collapses the three blanks to output one +whitespace, so you end with the same space after the colon as in the +first line. @LaTeX{} would similarly collapse a blank followed by a +tab, or a blank and a newline and a blank. However, the bottom line +asks for three spaces so the white area is wider. That is, the +backslash-space command creates a fixed amount of horizontal space. +(Note that you can define a horizontal space of any width at all with +@code{\hspace}; see@tie{}@ref{\hspace}.) + +The backslash-space command has two main uses. It is often used after +control sequences to keep them from gobbling the space that follows, as +in @code{\TeX\ is nice}. (But using curly parentheses, as in +@code{\TeX@{@} is best}, has the advantage of still working if the next +character is a period.) The other common use is that it marks a period +as ending an abbreviation instead of ending a sentence, as in @code{So +says Prof.\ Smith} (@pxref{\@@}). + +Under normal circumstances, @code{\}@key{tab} and @code{\}@key{newline} +are equivalent to backslash-space, @code{\ }. + +@c @PkgIndex{xspace} +@c Some individual commands, notably those defined with the @code{xspace}, +@c package do not follow the standard behavior. + + +@node ~ +@section @code{~} + +@findex ~ +@cindex tie +@cindex space, hard +@cindex space, unbreakable +@cindex NBSP + +Synopsis: + +@example +@var{before}~@var{after} +@end example + +The tie character, @code{~}, produces a space between @var{before} and +@var{after} at which the line will not be broken. By default the white +space has length 3.33333@dmn{pt} plus 1.66666@dmn{pt} minus +1.11111@dmn{pt} (@pxref{Lengths}). + +Here @LaTeX{} will not break the line between the final two words. + +@example +Thanks to Prof.~Lerman. +@end example + +@noindent +In addition, despite the period, @LaTeX{} does not use the +end-of-sentence spacing (@pxref{\@@}). + +Ties prevent the end of line separation of things where that could cause +confusion. But they also reduce @LaTeX{}'s options when it breaks lines +into paragraphs, so you can use too many. They are also matters of +taste, sometimes alarmingly dogmatic taste, among readers. Nevertheless, +here are some usage models, many of them from the @TeX{}book. + +@itemize @bullet +@item +Between an enumerator and its item, such as in references: +@code{Chapter~12}, or @code{Theorem~\ref@{th:Wilsons@}}, or +@code{Figure~\ref@{fig:KGraph@}}. When cases are enumerated inline: +@code{(b)~Show that $f(x)$ is (1)~continuous, and (2)~bounded}. + +@PkgIndex{siunitx} +@item +Between a number and its unit: @code{$745.7.8$~watts} (the +@file{siunitx} package has a special facility for this) or +@code{144~eggs}. This includes between a month and a date: +@code{October~12} or @code{12~Oct}. In general, in any expressions where +numbers and abbreviations or symbols are separated by a space: +@code{AD~565}, or @code{2:50~pm}, or @code{Boeing~747}, or +@code{268~Plains Road}, or @code{\$$1.4$~billion}. + +@item +When mathematical phrases are rendered in words: @code{equals~$n$}, or +@code{less than~$\epsilon$}, or @code{given~$X$}, or @code{modulo~$p^e$ +for all large~$n$} (but compare @code{is~$15$} with @code{is $15$~times +the height}). Between mathematical symbols in apposition with nouns: +@code{dimension~$d$} or @code{function~$f(x)$} (but compare @code{with +length $l$~or more}). When a symbol is a tightly bound object of a +preposition: @code{of~$x$}, or @code{from $0$ to~$1$}, or @code{in +common with~$m$}. + +@item +Between symbols in series: @code{$1$,~$2$, or~$3$} or @code{$1$,~$2$, +\ldots,~$n$}. + +@item +Between a person's forenames and between multiple surnames: +@code{Donald~E. Knuth}, or @code{Luis~I. Trabb~Pardo}, or +@code{Charles~XII} (but you must give TeX places to break the line so +you may do @code{Charles Louis Xavier~Joseph de~la Vall\'ee~Poussin}). + +@item +Before a dash: @code{pages 12~--14} or @code{it is~--- it must be +said~--- plausible}. + +@end itemize + + +@node \thinspace & \negthinspace +@section @code{\thinspace} & @code{\negthinspace} + +@findex \thinspace +@findex \negthinspace +@cindex thin space +@cindex space, thin +@cindex thin space, negative +@cindex space, negative thin + +Synopsis, one of: + +@example +\thinspace +\negthinspace +@end example + +Produce an unbreakable and unstretchable space of 1/6@dmn{em} and +-1/6@dmn{em}. These are the text mode equivalents of @code{\,} and +@code{\!} (@pxref{Spacing in math mode/\thinspace}). You can use +@code{\,} as a synonym for @code{\thinspace} in text mode. + +The @code{\negthinspace} command is used in text mode mostly for +fiddling with spaces. One common use of @code{\thinspace} is as the +space between nested quotes. + +@example +Killick replied, ``I heard the Captain say, `Ahoy there.'\thinspace'' +@end example + +@noindent +Another use is that some style guides call for a @code{\thinspace} +between an ellipsis and a sentence ending period (other style guides, +though, think the three dots are quite enough already). Still another +use is between initials, as in @code{D.\thinspace E.\ Knuth}. + + +@node \/ +@section @code{\/} + +@findex \/ +@cindex italic correction + +Synopsis: + +@example +@var{before-character}\/@var{after-character} +@end example + +Insert an @dfn{italic correction}, a small space defined by the font +designer for each character, to avoid the character colliding with +whatever follows. When you use @code{\/}, @LaTeX{} takes the correction +from the font metric file, scales it by any scaling that has been +applied to the font, and then inserts that much horizontal space. + +Here, were it not for the @code{\/}, the @var{before-character} +italic@tie{}f would hit the @var{after-character} roman@tie{}H + +@example +\newcommand@{\companylogo@}@{@{\it f@}\/H@} +@end example + +@noindent +because the italic letter leans far to the right. + +If @var{after-character} is a period or comma then don't insert an +italic correction since those punctuation symbols have a very small +height. However, with semicolons or colons as well as with normal +letters, the italic correction can help. + +When you use commands such as @code{\textit} or @code{\itshape} to +change fonts, @LaTeX{} will automatically insert any needed italic +correction (@pxref{Font styles}). + +Roman characters can also have an italic correction. An example is in +the name @code{pdf\/\TeX}. + +There is no concept of italic correction in math mode; spacing is done +in a different way. + + +@node \hrulefill & \dotfill +@section @code{\hrulefill} & @code{\dotfill} + +@findex \hrulefill +@findex \dotfill + +Synopsis, one of: + +@example +\hrulefill +\dotfill +@end example + +Produce an infinite horizontal rubber length (@pxref{Lengths}) that +@LaTeX{} fills with a rule (that is, a line) or with dots, instead of +white space. + +This outputs a line 2 inches long. + +@example +Name:~\makebox[2in]@{\hrulefill@} +@end example + +@noindent +This example, when placed between blank lines, creates a paragraph that +is left and right justified and where the middle is filled with evenly +spaced dots. + +@example +\noindent John Aubrey, RN \dotfill@{@} Melbury Lodge +@end example + +To make the rule or dots go to the line's end use @code{\null} at the +start or end. + +To change the rule's thickness, copy the definition and adjust it, as +here + +@example +\renewcommand@{\hrulefill@}@{% + \leavevmode\leaders\hrule height 1pt\hfill\kern\z@@@} +@end example + +@noindent +which changes the default thickness of 0.4@dmn{pt} to 1@dmn{pt}. +Similarly, adjust the dot spacing as with + +@example +\renewcommand@{\dotfill@}@{% + \leavevmode\cleaders\hb@@xt@@1.00em@{\hss .\hss @}\hfill\kern\z@@@} +@end example + +@noindent +which changes the default length of 0.33@dmn{em} to 1.00@dmn{em}. + +This example produces a line for a signature. + +@example +\begin@{minipage@}@{4cm@} + \centering + \hrulefill\\ + Signed +\end@{minipage@} +@end example + +@noindent +The line is 4@dmn{cm} long. + + +@node \bigskip & \medskip & \smallskip +@section @code{\bigskip} & @code{\medskip} & @code{\smallskip} + +Synopsis, one of: + +@example +\bigskip +\medskip +\smallskip +@end example + +Produce an amount of vertical space, large or medium-sized or +small. These commands are fragile (@pxref{\protect}). + +Here the skip suggests the passage of time (from @i{The Golden Ocean} by +O'Brian). + +@example +Mr Saumarez would have something rude to say to him, no doubt: he +was at home again, and it was delightful. + +\bigskip +``A hundred and fifty-seven miles and one third, in twenty-four hours,'' +said Peter. +@end example + +Each command is associated with a length defined in the document class +file. + +@ftable @code +@anchor{bigskip} +@item \bigskip +@findex \bigskipamount +The same as @code{\vspace@{\bigskipamount@}}, ordinarily about one line +space, with stretch and shrink. The default for the @code{book} and +@code{article} classes is @code{12pt plus 4pt minus 4pt}. + +@anchor{medskip} +@item \medskip +@findex \medskipamount +The same as @code{\vspace@{\medskipamount@}}, ordinarily about half of a +line space, with stretch and shrink. The default for the @code{book} +and @code{article} classes is @code{6pt plus 2pt minus 2pt}. + +@anchor{smallskip} +@item \smallskip +@findex \smallskipamount +The same as @code{\vspace@{\smallskipamount@}}, ordinarily about a +quarter of a line space, with stretch and shrink. The default for the +@code{book} and @code{article} classes is @code{3pt plus 1pt minus 1pt}. + +@end ftable + +Because each command is a @code{\vspace}, if you use on in mid-paragraph +then it will insert its vertical space between the line in which you use +it and the next line, not necessarily at the place that you use it. So +these are best between paragraphs. + +The commands @code{\bigbreak}, @code{\medbreak}, and @code{\smallbreak} +are similar but also suggest to @LaTeX{} that this is a good place to +put a page break (@pxref{\bigbreak & \medbreak & \smallbreak}. + + +@node \bigbreak & \medbreak & \smallbreak +@section @code{\bigbreak} & @code{\medbreak} & @code{\smallbreak} + +Synopsis, one of: + +@example +\bigbreak +\medbreak +\smallbreak +@end example + +Produce a vertical space that is big or medium-sized or small, and +suggest to @LaTeX{} that this is a good place to break the page. (The +associated penalties are -200, -100, and -50.) + +@xref{\bigskip & \medskip & \smallskip}, for more. These commands +produce the same vertical space but differ in that they also remove a +preceding vertical space if it is less than what they would insert (as +with @code{\addvspace}). In addition, they terminate a paragraph where +they are used: this example + +@example +abc\bigbreak def ghi + +jkl mno pqr +@end example + +@noindent +will output three paragraphs, the first ending in @samp{abc} and the +second starting, after an extra vertical space and a paragraph indent, +with @samp{def}. + + +@node \strut +@section @code{\strut} + +@findex \strut +@cindex strut + +Synopsis: + +@example +\strut +@end example + +Ensure that the current line has height at least @code{0.7\baselineskip} +and depth at least @code{0.3\baselineskip}. Essentially, @LaTeX{} +inserts into the line a rectangle having zero width, +@code{\rule[-0.3\baselineskip]@{0pt@}@{\baselineskip@}} (@pxref{\rule}). +The @code{\baselineskip} changes with the current font and fontsize. + +In this example the @code{\strut} keeps the box inside the frame from +having zero height. + +@example +\setlength@{\fboxsep@}@{0pt@}\framebox[2in]@{\strut@} +@end example + +This example has four lists. In the first there is a much bigger gap +between items 2 and@tie{}3 than there is between items 1 and@tie{}2. +The second list fixes that with a @code{\strut} at the end of its first +item's second line. + +@example +\setlength@{\fboxsep@}@{0pt@} +\noindent\begin@{minipage@}[t]@{0.2\linewidth@} +\begin@{enumerate@} + \item \parbox[t]@{15pt@}@{test \\ test@} + \item test + \item test +\end@{enumerate@} +\end@{minipage@}% +\begin@{minipage@}[t]@{0.2\linewidth@} +\begin@{enumerate@} + \item \parbox[t]@{15pt@}@{test \\ test\strut@} + \item test + \item test +\end@{enumerate@} +\end@{minipage@}% +\begin@{minipage@}[t]@{0.2\linewidth@} +\begin@{enumerate@} + \item \fbox@{\parbox[t]@{15pt@}@{test \\ test@}@} + \item \fbox@{test@} + \item \fbox@{test@} +\end@{enumerate@} +\end@{minipage@}% +\begin@{minipage@}[t]@{0.2\linewidth@} +\begin@{enumerate@} + \item \fbox@{\parbox[t]@{15pt@}@{test \\ test\strut@}@} + \item \fbox@{test@} + \item \fbox@{test@} +\end@{enumerate@} +\end@{minipage@}% +@end example + +@noindent +The final two lists use @code{\fbox} to show what's happening. The +third list's @code{\parbox} goes only to the bottom of its second +@samp{test}, which happens not have any characters that descend below +the baseline. The fourth list adds the strut that gives the needed +extra below-baseline space. + +@PkgIndex{TikZ} @PkgIndex{Asymptote} +The @code{\strut} command is often useful in graphics, such as in +@file{TikZ} or @file{Asymptote}. For instance, you may have a command +such as @code{\graphnode@{@var{node-name}@}} that fits a circle around +@var{node-name}. However, unless you are careful the @var{node-name}'s +@samp{x} and @samp{y} will produce different-diameter circles because +the characters are different sizes. A careful @code{\graphnode} might +insert a @code{\strut}, then @var{node-name}, and then draw the circle. + +The general approach of using a zero width @code{\rule} is useful in +many circumstances. In this table, the zero-width rule keeps the top of +the first integral from hitting the @code{\hline}. Similarly, the +second rule keeps the second integral from hitting the first. + +@example +\begin@{tabular@}@{rl@} + \textsc@{Integral@} &\textsc@{Value@} \\ + \hline + $\int_0^x t\, dt$ &$x^2/2$ \rule@{0em@}@{2.5ex@} \\ + $\int_0^x t^2\, dt$ &$x^3/3$ \rule@{0em@}@{2.5ex@} +\end@{tabular@} +@end example + +@noindent +(Although the line-ending double backslash command has an available +optional argument to put in more vertical room, that won't work here. +Changing the first double backslash to something like @code{\\[2.5ex]} +will put the room between the header line and the @code{\hline}, and the +integral would still hit the line.) + + +@node \vspace +@section @code{\vspace} + +@findex \vspace +@cindex vertical space +@cindex space, vertical + +Synopsis, one of: + +@example +\vspace@{@var{length}@} +\vspace*@{@var{length}@} +@end example + +Add the vertical space @var{length}. The @var{length} can be positive, +negative, or zero. It is a rubber length---it may contain a @code{plus} +or @code{minus} component (@pxref{Lengths}). + +This puts space between the two paragraphs. + +@example +And I slept. + +\vspace@{1ex plus 0.5ex@} +The new day dawned cold. +@end example + +@noindent +(@xref{\bigskip & \medskip & \smallskip} for common inter-paragraph +spaces.) + +The @code{*}-version inserts vertical space that non-discardable. More +precisely, @LaTeX{} discards vertical space at a page break and the +@code{*}-version causes the space to stay. This example leaves space +between the two questions. + +@example +Question: Find the integral of \( 5x^4+5 \). + +\vspace*@{2cm plus 0.5cm@} +Question: Find the derivative of \( x^5+5x+9 \). +@end example + +@noindent +That space will be present even if the page break happens to fall +between the questions. + +If you use @code{\vspace} in the middle of a paragraph (i.e., in +horizontal mode) then the space is inserted after the line containing +the @code{\vspace} command; it does not start a new paragraph at the +@code{\vspace} command. + +In this example the two questions will be evenly spaced vertically on +the page, with at least one inch of space below each. + +@example +\begin@{document@} +1) Who put the bomp in the bomp bah bomp bah bomp? +\vspace@{1in plus 1fill@} + +2) Who put the ram in the rama lama ding dong? +\vspace@{1in plus 1fill@} +\end@{document@} +@end example + + +@node \vfill +@section @code{\vfill} + +@findex \vfill + +@cindex stretch, infinite vertical +@cindex infinite vertical stretch + +Synopsis: + +@example +\vfill +@end example + +End the current paragraph and insert a vertical rubber length that is +infinite, so it can stretch or shrink as far as needed +(@pxref{Lengths}). + +It is often used in the same way as @code{\vspace@{\fill@}}, except that +@code{\vfill} ends the current paragraph whereas @code{\vspace@{\fill@}} +adds the infinite vertical space below its line, irrespective of the +paragraph structure. In both cases that space will disappear at a page +boundary; to circumvent this see the starred option +in@tie{}@ref{\vspace}. + +In this example the page is filled, so the top and bottom lines contain +the text @samp{Lost Dog!} and the second @samp{Lost Dog!} is exactly +halfway between them. + +@example +\begin@{document@} +Lost Dog! +\vfill +Lost Dog! % perfectly in the middle +\vfill +Lost Dog! +\end@{document@} +@end example + + +@node \addvspace +@section @code{\addvspace} + +@findex \addvspace +@cindex vertical space +@cindex space, inserting vertical + +Synopsis: + +@example +\addvspace@{@var{vert-length}@} +@end example + +Add a vertical space of @var{vert-length}. However, if there are two or +more @code{\addvspace}'s in a sequence then together they only add the +space needed to make the natural length equal to the maximum of the +@var{vert-length}'s in that sequence. This command is fragile +(@pxref{\protect}). The @var{vert-length} is a rubber length +(@pxref{Lengths}). + +This example illustrates. The @code{picture} draws a scale. In a +standard @LaTeX{} article the length @code{\baselineskip} is 12@dmn{pt}. +The two rules here are 22@dmn{pt} apart: the sum of the +@code{\baselineskip} and the 10@dmn{pt} from the first @code{addvspace}. + +@example +\documentclass@{article@} +\usepackage@{color@} +\begin@{document@} +\setlength@{\unitlength@}@{2pt@}% +\noindent\begin@{picture@}(0,0)% + \multiput(0,0)(0,-1)@{25@}@{@{\color@{blue@}\line(1,0)@{1@}@}@} + \multiput(0,0)(0,-5)@{6@}@{@{\color@{red@}\line(1,0)@{2@}@}@} +\end@{picture@}% +\rule@{0.25\linewidth@}@{0.1pt@}% +\par\addvspace@{10pt@}% \addvspace@{20pt@}% +\par\noindent\rule@{0.25\linewidth@}@{0.1pt@}% +\end@{document@} +@end example + +@noindent +Now uncomment the second @code{\addvspace}. It does not make the gap +20@dmn{pt} longer; instead the gap is the sum of @code{\baselineskip} +and 20@dmn{pt}. So @code{\addvspace} in a sense does the opposite of +its name --- it makes sure that multiple vertical spaces do not +accumulate, but instead that only the largest one is used. + +@LaTeX{} uses this command to adjust the vertical space above or below +an environment that starts a new paragraph. For instance, a +@code{theorem} environment begins and ends with @code{\addvspace} so +that two consecutive @code{theorem}'s are separated by one vertical +space, not two. + +A error @samp{Something's wrong--perhaps a missing \item} pointing to an +@code{\addvspace} means that you were not in vertical mode when you hit +this command. One way to change that is to precede @code{\addvspace} +with a @code{\par} command (@pxref{\par}), as in the above example. + + +@node Boxes +@chapter Boxes + +@cindex boxes + +@c xx Expand on boxes and glue, for xref from elsewhere. +At its core, @LaTeX{} puts things in boxes and then puts the boxes on a +page. So these commands are central. + +There are many packages on CTAN that are useful for manipulating boxes. +One useful adjunct to the commands here is @file{adjustbox}. + +@menu +* \mbox & \makebox:: Horizontal boxes. +* \fbox & \framebox:: Put a frame around a box. +* \parbox:: Box with text in paragraph mode. +* \raisebox:: Raise or lower text. +* \sbox & \savebox:: Like @code{\makebox} but save the text for later. +* lrbox:: Environment version of @code{\sbox}. +* \usebox:: Print saved text. +@end menu + + +@node \mbox & \makebox +@section @code{\mbox} & @code{\makebox} + +@findex \mbox +@findex \makebox +@cindex box +@cindex make a box +@cindex hyphenation, preventing + +Synopsis, one of: + +@example +\mbox@{@var{text}@} +\makebox@{@var{text}@} +\makebox[@var{width}]@{@var{text}@} +\makebox[@var{width}][@var{position}]@{@var{text}@} +@end example + +Create a box, a container for material. The @var{text} is typeset in +LR mode (@pxref{Modes}) so it is not broken into lines. The +@code{\mbox} command is robust, while @code{\makebox} is fragile +(@pxref{\protect}). + +Because @code{text} is not broken into lines, you can use @code{\mbox} +to prevent hyphenation. In this example, @LaTeX{} will not hyphenate +the table name, @samp{T-4}. + +@example +See Table~\mbox@{T-4@} +@end example + +The first two command versions, @code{\mbox} and @code{\makebox}, are +roughly equivalent. They create a box just wide enough to contain the +@var{text}. (They are like plain @TeX{}'s @code{\hbox}.) + +In the third version the optional argument @var{width} specifies the +width of the box. Note that the space occupied by the text need not +equal the width of the box. For one thing, @var{text} can be too small; +this creates a full-line box + +@example +\makebox[\linewidth]@{Chapter Exam@} +@end example + +@noindent +with @samp{Chapter Exam} centered. But @var{text} can also be too wide +for @var{width}. See the example below of zero-width boxes. + +@anchor{mbox makebox depth} +@anchor{mbox makebox height} +@anchor{mbox makebox width} +@anchor{mbox makebox totalheight} +In the @var{width} argument you can use the following lengths that refer +to the dimension of the box that @LaTeX{} gets on typesetting +@var{text}: @code{\depth}, @code{\height}, @code{\width}, +@code{\totalheight} (this is the box's height plus its depth). For +example, to make a box with the text stretched to double the natural +size you can say this. + +@example +\makebox[2\width]@{Get a stretcher@} +@end example + +For the fourth command version the optional argument @var{position} +gives position of the text within the box. It may take the following +values: + +@table @code +@item c +The @var{text} is centered (default). + +@item l +The @var{text} is flush left. + +@item r +Flush right. + +@item s +Stretch the interword space in @var{text} across the entire @var{width}. +The @var{text} must contain stretchable space for this to work. For +instance, this could head a press release: +@code{\noindent\makebox[\textwidth][s]@{\large\hfil IMMEDIATE\hfil +RELEASE\hfil@}} +@end table + +A common use of @code{\makebox} is to make zero-width text boxes. This +puts the value of the quiz questions to the left of those questions. + +@example +\newcommand@{\pts@}[1]@{\makebox[0em][r]@{#1 points\hspace*@{1em@}@}@} +\pts@{10@}What is the air-speed velocity of an unladen swallow? + +\pts@{90@}An African or European swallow? +@end example + +@noindent +@PkgIndex{TikZ} +@PkgIndex{Asymptote} +The right edge of the output @samp{10 points } (note the ending space) +will be just before the @samp{What} (note the space after +@samp{points}). You can use @code{\makebox} similarly when making +graphics, such as in @file{TikZ} or @file{Asymptote}, where you put the +edge of the text at a known location, regardless of the length of that +text. + +For boxes with frames see@tie{}@ref{\fbox & \framebox}. For colors +see@tie{}@ref{Colored boxes}. + +There is a related version of @code{\makebox} that is used within the +@code{picture} environment, where the length is given in terms of +@code{\unitlength} (@pxref{\makebox (picture)}). + +If you put a double-backslash into @var{text} then @LaTeX{} will not +give you a new line; for instance @code{\makebox@{abc def \\ ghi@}} +outputs @samp{abc defghi} while @code{\makebox@{abc def \par ghi@}} +outputs @samp{abc def ghi}, but neither go to a second line. To get +multiple lines see@tie{}@ref{\parbox} and@tie{}@ref{minipage}. + + +@node \fbox & \framebox +@section @code{\fbox} & @code{\framebox} + +@findex \fbox +@findex \framebox + +Synopses, one of: + +@example +\fbox@{@var{text}@} +\framebox@{@var{text}@} +\framebox[@var{width}]@{@var{text}@} +\framebox[@var{width}][@var{position}]@{@var{text}@} +@end example + +Create a box with an enclosing frame, four lines surrounding the space. +These commands are the same as @code{\mbox} and @code{\makebox} except +for the frame (@pxref{\mbox & \makebox}). The @code{\fbox} command is +robust, the @code{\framebox} command is fragile (@pxref{\protect}). + +@example +\fbox@{Warning! No work shown, no credit given.@} +@end example + +@noindent +@LaTeX{} puts the text into a box that cannot be split or hyphenated. +Around that box, separated from it by a small gap, are four lines making +a frame. + +The first two command invocations, @code{\fbox@{...@}} and +@code{\framebox@{...@}}, are roughly the same. As to the third and +fourth invocations, the optional arguments allow you to specify the box +width as @var{width} and the position of the text inside that box as +@var{position}. @xref{\mbox & \makebox} for the full description but +here is an example creating an empty box that is 1/4@dmn{in} wide. + +@example +\setlength@{\fboxsep@}@{0pt@}\framebox[0.25in]@{\strut@}@} +@end example + +@noindent +The @code{\strut} inserts a vertical height of @code{\baselineskip} +(@pxref{\strut}). + +These parameters determine the frame layout. + +@ftable @code +@anchor{fbox framebox fboxrule} +@item \fboxrule +@findex frame, line width +@findex frame rule width +@cindex \fboxrule +The thickness of the lines around the enclosed box. The default is +0.2@dmn{pt}. Change it with a command such as +@code{\setlength@{\fboxrule@}@{0.8pt@}} (@pxref{\setlength}). + +@anchor{fbox framebox fboxsep} +@item \fboxsep +@findex frame, separation from contents +@cindex \fboxsep +The distance from the frame to the enclosed box. The default is 3@dmn{pt}. +Change it with a command such as @code{\setlength@{\fboxsep@}@{0pt@}} +(@pxref{\setlength}). Setting it to 0@dmn{pt} is useful sometimes: +this will put a frame around the picture with no white border. + +@example +@{\setlength@{\fboxsep@}@{0pt@} + \framebox@{% + \includegraphics[width=0.5\textwidth]@{prudence.jpg@}@}@} +@end example + +@noindent +The extra curly braces keep the effect of the @code{\setlength} local. + +@end ftable + +As with @code{\mbox} and @code{\makebox}, @LaTeX{} will not break lines +in @var{text}. But this example has @LaTeX{} break lines to make a +paragraph, and then frame the result. + +@example +\framebox@{% + \begin@{minipage@}@{0.6\linewidth@} + My dear, here we must run as fast as we can, just to stay in place. + And if you wish to go anywhere you must run twice as fast as that. + \end@{minipage@}@} +@end example + +@xref{Colored boxes} for colors other than black and white. + +The @code{picture} environment has a version of this command where the +units depend on @code{picture}'s @code{\unitlength} (@pxref{\framebox +(picture)}). + + +@node \parbox +@section @code{\parbox} + +@findex \parbox +@cindex paragraph mode +@cindex paragraph, in a box + +Synopses, one of: + +@example +\parbox@{@var{width}@}@{@var{contents}@} +\parbox[@var{position}]@{@var{width}@}@{@var{contents}@} +\parbox[@var{position}][@var{height}]@{@var{width}@}@{@var{contents}@} +\parbox[@var{position}][@var{height}][@var{inner-pos}]@{@var{width}@}@{@var{contents}@} +@end example + +Produce a box of text that is @var{width} wide. Use this command to make +a box of small pieces of text, of a single paragraph. This command is +fragile (@pxref{\protect}). + +@example +\begin@{picture@}(0,0) + ... + \put(1,2)@{\parbox@{1.75in@}@{\raggedright Because the graph is a line on + this semilog paper, the relationship is + exponential.@}@} +\end@{picture@} +@end example + +The @var{contents} are processed in a text mode (@pxref{Modes}) so +@LaTeX{} will break lines to make a paragraph. But it won't make +multiple paragraphs; for that, use a @code{minipage} environment +(@pxref{minipage}). + +The options for @code{\parbox} (except for @var{contents}) are the same +as those for @code{minipage}. For convenience a summary of the options +is here but see@tie{}@ref{minipage} for a complete description. + +There are two required arguments. The @var{width} is a rigid length +(@pxref{Lengths}). It sets the width of the box into which @LaTeX{} +typesets @var{contents}. The @var{contents} is the text that is placed +in that box. It should not have any paragraph-making components. + +There are three optional arguments, @var{position}, @var{height}, and +@var{inner-pos}. The @var{position} gives the vertical alignment of the +@code{parbox} with respect to the surrounding material. The possible +values are @code{c} or @code{m} to make the vertical center of the +@code{parbox} lines up with the center of the adjacent line (this is the +default), or @code{t} to match the top line of the @code{parbox} with +the baseline of the surrounding material, or @code{b} to match the +bottom line. + +The optional argument @var{height} overrides the natural height of the +box. + +The optional argument @var{inner-pos} controls the placement of +@var{content} inside the @code{parbox}. Its default is the value of +@var{position}. Its possible values are: @code{t} to put the +@var{content} at the top of the box, @code{c} to put it in the vertical +center, @code{b} to put it at the bottom of the box, and @code{s} to +stretch it out vertically (for this, the text must contain vertically +stretchable space). + +@node \raisebox +@section @code{\raisebox} + +@findex \raisebox + +Synopsis, one of: + +@example +\raisebox@{@var{distance}@}@{@var{text}@} +\raisebox@{@var{distance}@}[@var{height}]@{@var{text}@} +\raisebox@{@var{distance}@}[@var{height}][@var{depth}]@{@var{text}@} +@end example + +Raise or lower @var{text}. This command is fragile (@pxref{\protect}). + +This example makes a command for the restriction of a function by +lowering the vertical bar symbol. + +@c credit: egreg https://tex.stackexchange.com/a/278631/121234 +@example +\newcommand\restricted[1]@{\raisebox@{-.5ex@}@{$|$@}_@{#1@}@} +$f\restricted@{A@}$ +@end example + +The first mandatory argument @var{distance} specifies how far to raise +the second mandatory argument @var{text}. This is a rigid length +(@pxref{Lengths}). If it is negative then it lowers @var{text}. The +@var{text} is processed in LR mode so it cannot contain line breaks +(@pxref{Modes}). + +The optional arguments @var{height} and @var{depth} are dimensions. If +they are specified, they override the natural height and depth of the +box @LaTeX{} gets by typesetting @var{text}. + +@anchor{raisebox depth} +@anchor{raisebox height} +@anchor{raisebox width} +@anchor{raisebox totalheight} +In the arguments @var{distance}, @var{height}, and @var{depth} you can +use the following lengths that refer to the dimension of the box that +@LaTeX{} gets on typesetting @var{text}: @code{\depth}, @code{\height}, +@code{\width}, @code{\totalheight} (this is the box's height plus its +depth). + +This will align two graphics on their top (@pxref{Graphics}). + +@c credit: FAQ https://texfaq.org/FAQ-topgraph +@example +\usepackage@{graphicx@} \usepackage@{calc@} % in preamble + ... +\begin@{center@} + \raisebox@{1ex-\height@}@{% + \includegraphics[width=0.4\linewidth]@{lion.png@}@} + \qquad + \raisebox@{1ex-\height@}@{% + \includegraphics[width=0.4\linewidth]@{meta.png@}@} +\end@{center@} +@end example + +@noindent +The first @code{\height} is the height of @file{lion.png} while the +second is the height of @file{meta.png}. + + +@node \sbox & \savebox +@section @code{\sbox} & @code{\savebox} + +@findex \sbox +@findex \savebox +@cindex box, save + +Synopsis, one of: + +@example +\sbox@{@var{box-cmd}@}@{@var{text}@} +\savebox@{@var{box-cmd}@}@{@var{text}@} +\savebox@{@var{box-cmd}@}[@var{width}]@{@var{text}@} +\savebox@{@var{box-cmd}@}[@var{width}][@var{pos}]@{@var{text}@} +@end example + +Typeset @var{text} just as with @code{\makebox} (@pxref{\mbox & +\makebox}) except that @LaTeX{} does not output it but instead saves it +in a storage bin named @var{box-cmd}. The bin name @var{box-cmd} begins +with a backslash, @code{\}. You must have previously allocated the bin +@var{box-cmd} with @code{\newsavebox} (@pxref{\newsavebox}).The +@code{\sbox} command is robust while @code{\savebox} is fragile +(@pxref{\protect}). + +This creates and uses a bin. + +@example +\newsavebox@{\fullname@} +\sbox@{\fullname@}@{John Jacob Jingleheimer Schmidt@} + ... +\usebox@{\fullname@}! His name is my name, too! +Whenever we go out, the people always shout! +There goes \\usebox@{\fullname@}! Ya da da da da da da. +@end example + +@noindent +One advantage of using and reusing a bin over a @code{\newcommand} is +efficiency, that @LaTeX{} need not repeatedly retypeset the contents. +See the example below. + +The first two command invocations, +@code{\sbox@{@var{box-cmd}@}@{@var{text}@}} and +@code{\savebox@{@var{box-cmd}@}@{@var{text}@}}, are roughly equivalent. +As to the third and fourth, the optional arguments allow you to specify +the box width as @var{width}, and the position of the text inside that +box as @var{position}. @xref{\mbox & \makebox} for the full +description. + +In the @code{\sbox} and @code{\savebox} commands the @var{text} is +typeset in LR mode so it does not have line breaks (@pxref{Modes}). If +you use these then @LaTeX{} doesn't give you an error but it ignores +what you want: if you enter @code{\sbox@{\newbin@}@{test \\ test@}} and +@code{\usebox@{\newbin@}} then you get @samp{testtest}, while if you +enter @code{\sbox@{\newbin@}@{test \par test@}} and +@code{\usebox@{\newbin@}} then you get @samp{test test}, but no error or +warning. To fix this use a @code{\parbox} or @code{minipage} as here. + +@c credit: egreg https://tex.stackexchange.com/a/41668/121234 +@example +\savebox@{\abin@}@{% + \begin@{minipage@}@{\linewidth@} + \begin@{enumerate@} + \item First item + \item Second item + \end@{enumerate@} + \end@{minipage@}@} + ... +\usebox@{\abin@} +@end example + +As an example of the efficiency of reusing a bin's contents, this puts +the same picture on each page of the document by putting it in the +header. @LaTeX{} only typesets it once. + +@example +\usepackage@{graphicx@} % all this in the preamble +\newsavebox@{\sealbin@} +\savebox@{\sealbin@}@{% + \setlength@{\unitlength@}@{1in@}% + \begin@{picture@}(0,0)% + \put(1.5,-2.5)@{% + \begin@{tabular@}@{c@} + \includegraphics[height=2in]@{companylogo.png@} \\ + Office of the President + \end@{tabular@}@} + \end@{picture@}% +@} +\markright@{\usebox@{\sealbin@}@} +\pagestyle@{headings@} +@end example + +@noindent +The @code{picture} environment is good for fine-tuning the placement. + +If the bin has not already been defined then you get something like +@samp{Undefined control sequence. <argument> \nobin}. + + +@node lrbox +@section @code{lrbox} + +@findex lrbox + +Synopsis: + +@example +\begin@{lrbox@}@{@var{box-cmd}@} + @var{text} +\end@{lrbox@} +@end example + +The @var{text} inside the environment is saved in the bin +@code{@var{box-cmd}}. The @var{box-cmd} must begin with a +backslash. You must create this bin in advance with @code{\newsavebox} +(@pxref{\newsavebox}). This is the environment form of the @code{\sbox} +and @code{\savebox} commands, and is equivalent to them. @xref{\sbox & +\savebox} for the full information. + +In this example the environment is convenient for entering the +@code{tabular}. + +@example +\newsavebox@{\jhbin@} +\begin@{lrbox@}@{\jhbin@} + \begin@{tabular@}@{c@} + \includegraphics[height=1in]@{jh.png@} \\ + Jim Hef@{@}feron + \end@{tabular@} +\end@{lrbox@} + ... +\usebox@{\jhbin@} +@end example + + +@node \usebox +@section @code{\usebox} + +@findex \usebox +@cindex box, use saved box + +Synopsis: + +@example +\usebox@{@var{box-cmd}@} +@end example + +Produce the box most recently saved in the bin @var{box-cmd} by the +commands @code{\sbox} or @code{\savebox}, or the @code{lrbox} +environment. @xref{\sbox & \savebox} for more information and examples. +(Note that @var{box-cmd} starts with a backslash.) This command is +robust (@pxref{\protect}). + + +@node Color +@chapter Color + +@cindex color + +You can add color to text, rules, etc. You can also have color in a box +or on an entire page and write text on top of it. + +Color support comes as an additional package. So put +@code{\usepackage@{color@}} in your document preamble to use the +commands described here. + +Many other packages also supplement @LaTeX{}'s color abilities. +Particularly worth mentioning is @file{xcolor}, which is widely used and +significantly extends the capabilities described here, including adding +@samp{HTML} and @samp{Hsb} color models. + +@menu +* Color package options:: Options when you load the standard package. +* Color models:: How colors are represented. +* Commands for color:: The available commands. +@end menu + + +@node Color package options +@section @code{color} package options + +@cindex color package options +@cindex options, color package + +Synopsis (must be in the document preamble): + +@example +\usepackage[@var{comma-separated option list}]@{color@} +@end example + +When you load the @file{color} package there are two kinds of available +options. + +The first specifies the @dfn{printer driver}. @LaTeX{} doesn't contain +information about different output systems but instead depends on +information stored in a file. Normally you should not specify the +driver option in the document, and instead rely on your system's +default. One advantage of this is that it makes the document portable +across systems. For completeness we include a list of the drivers. The +currently relevant ones are: @file{dvipdfmx}, @file{dvips}, +@file{dvisvgm}, @file{luatex}, @file{pdftex}, @file{xetex}. The two +@file{xdvi} and @file{oztex} are essentially aliases for @file{dvips} +(and @file{xdvi} is monochrome). Ones that should not be used for new +systems are: @file{dvipdf}, @file{dvipdfm}, @file{dviwin}, +@file{dvipsone}, @file{emtex}, @file{pctexps}, @file{pctexwin}, +@file{pctexhp}, @file{pctex32}, @file{truetex}, @file{tcidvi}, +@file{vtex} (and @file{dviwindo} is an alias for @file{dvipsone}). + +The second kind of options, beyond the drivers, are below. + +@table @code + +@item monochrome +Disable the color commands, so that they do not generate errors but do +not generate color either. + +@item dvipsnames +Make available a list of 68 color names that are often used, +particularly in legacy documents. These color names were originally +provided by the @file{dvips} driver, giving the option name. + +@item nodvipsnames +Do not load that list of color names, saving @LaTeX{} a tiny amount of +memory space. + +@end table + + +@node Color models +@section Color models + +@cindex color models + +A @dfn{color model} is a way of representing colors. @LaTeX{}'s +capabilities depend on the printer driver. However, the @file{pdftex}, +@file{xetex}, and @file{luatex} printer drivers are today by far the +most commonly used. The models below work for those drivers. All but +one of these is also supported by essentially all other printer drivers +used today. + +Note that color combination can be additive or subtractive. Additive +mixes colors of light, so that for instance combining full intensities +of red, green, and blue produces white. Subtractive mixes pigments, +such as with inks, so that combining full intensity of cyan, magenta, +and yellow makes black. + +@table @code +@anchor{color models cmyk} +@item cmyk +A comma-separated list with four real numbers between 0 and 1, +inclusive. The first number is the intensity of cyan, the second is +magenta, and the others are yellow and black. A number value of 0 means +minimal intensity, while a 1 is for full intensity. This model is often +used in color printing. It is a subtractive model. + +@anchor{color models gray} +@item gray +A single real number between 0 and 1, inclusive. The colors are shades +of grey. The number 0 produces black while 1 gives white. + +@anchor{color models rgb} +@item rgb +A comma-separated list with three real numbers between 0 and 1, +inclusive. The first number is the intensity of the red component, the +second is green, and the third the blue. A number value of 0 means that +none of that component is added in, while a 1 means full intensity. +This is an additive model. + +@anchor{color models RGB} +@item RGB +(@file{pdftex}, @file{xetex}, @file{luatex} drivers) A comma-separated +list with three integers between 0 and 255, inclusive. This model is a +convenience for using @code{rgb} since outside of @LaTeX{} colors are +often described in a red-green-blue model using numbers in this range. +The values entered here are converted to the @code{rgb} model by +dividing by 255. + +@anchor{color models named} +@item named +Colors are accessed by name, such as @samp{PrussianBlue}. The list of +names depends on the driver, but all support the names @samp{black}, +@samp{blue}, @samp{cyan}, @samp{green}, @samp{magenta}, @samp{red}, +@samp{white}, and @samp{yellow} (See the @code{dvipsnames} option in +@ref{Color package options}). + +@end table + + +@node Commands for color +@section Commands for color + +@cindex color package commands + +These are the commands available with the @file{color} package. + +@menu +* Define colors:: Give a color a name. +* Colored text:: Text or rules in color. +* Colored boxes:: A box of color, to write over. +* Colored pages:: A whole page colored. +@end menu + + +@node Define colors +@subsection Define colors + +@cindex color +@cindex define color +@cindex color, define + +Synopsis: + +@example +\definecolor@{@var{name}@}@{@var{model}@}@{@var{specification}@} +@end example + +Give the name @var{name} to the color. For example, after this + +@example +\definecolor@{silver@}@{rgb@}@{0.75,0.75,0.74@} +@end example + +@noindent +you can use that color name with @code{Hi ho, +\textcolor@{silver@}@{Silver@}!}. + +This example gives the color a more abstract name, so it could change and +not be misleading. + +@example +\definecolor@{logocolor@}@{RGB@}@{145,92,131@} % RGB needs pdflatex +\newcommand@{\logo@}@{\textcolor@{logocolor@}@{Bob's Big Bagels@}@} +@end example + +Often a document's colors are defined in the preamble, or in the class +or style, rather than in the document body. + + +@node Colored text +@subsection Colored text + +@cindex color +@cindex colored text + +Synopses: + +@example +\textcolor@{@var{name}@}@{...@} +\textcolor[@var{color model}]@{@var{color specification}@}@{...@} +@end example + +@noindent +or + +@example +\color@{@var{name}@} +\color[@var{color model}]@{@var{specification}@} +@end example + +The affected text gets the color. This line + +@example +\textcolor@{magenta@}@{My name is Ozymandias, king of kings:@} +Look on my works, ye Mighty, and despair! +@end example + +@noindent +causes the first half to be in magenta while the rest is in black. You +can use a color declared with @code{\definecolor} in exactly the same +way that we just used the builtin color @samp{magenta}. + +@example +\definecolor@{MidlifeCrisisRed@}@{rgb@}@{1.0,0.11,0.0@} +I'm thinking about getting a \textcolor@{MidlifeCrisisRed@}@{sports car@}. +@end example + +The two @code{\textcolor} and @code{\color} differ in that the first is +a command form, enclosing the text to be colored as an argument. Often +this form is more convenient, or at least more explicit. The second +form is a declaration, as in @code{The moon is made of @{\color@{green@} +green@} cheese}, so it is in effect until the end of the current group +or environment. This is sometimes useful when writing macros or as +below where it colors everything inside the @code{center} environment, +including the vertical and horizontal lines. + +@example +\begin@{center@} \color@{blue@} + \begin@{tabular@}@{l|r@} + UL &UR \\ \hline + LL &LR + \end@{tabular@} +\end@{center@} +@end example + +You can use color in equations. A document might have this definition +in the preamble + +@example +\definecolor@{highlightcolor@}@{RGB@}@{225,15,0@} +@end example + +@noindent +and then contain this equation. + +@example +\begin@{equation@} + \int_a^b \textcolor@{highlightcolor@}@{f'(x)@}\,dx=f(b)-f(a) +\end@{equation@} +@end example + +Typically the colors used in a document are declared in a class or style +but sometimes you want a one-off. Those are the second forms in the +synopses. + +@example +Colors of \textcolor[rgb]@{0.33,0.14,0.47@}@{Purple@} and +@{\color[rgb]@{0.72,0.60,0.37@} Gold@} for the team. +@end example + +The format of @var{color specification } depends on the color model +(@pxref{Color models}). For instance, while @code{rgb} takes three +numbers, @code{gray} takes only one. + +@example +The selection was \textcolor[gray]@{0.5@}@{grayed out@}. +@end example + +Colors inside colors do not combine. Thus + +@example +\textcolor@{green@}@{kind of \textcolor@{blue@}@{blue@}@} +@end example + +@noindent +has a final word that is blue, not a combination of blue and green. + +@c xx address coloring a line of a table? + + +@node Colored boxes +@subsection Colored boxes + +@cindex color +@cindex colored boxes +@cindex box, colored + +Synopses: + +@example +\colorbox@{@var{name}@}@{...@} +\colorbox[@var{model name}]@{@var{box background color}@}@{...@} +@end example + +@noindent +or + +@example +\fcolorbox@{@var{frame color}@}@{@var{box background color}@}@{...@} +\fcolorbox[@var{model name}]@{@var{frame color}@}@{@var{box background color}@}@{...@} +@end example + +Make a box with the stated background color. The @code{\fcolorbox} +command puts a frame around the box. For instance this + +@example +Name:~\colorbox@{cyan@}@{\makebox[5cm][l]@{\strut@}@} +@end example + +@noindent +makes a cyan-colored box that is five centimeters long and gets its +depth and height from the @code{\strut} (so the depth is +@code{-.3\baselineskip} and the height is @code{\baselineskip}). This +puts white text on a blue background. + +@example +\colorbox@{blue@}@{\textcolor@{white@}@{Welcome to the machine.@}@} +@end example + +The @code{\fcolorbox} commands use the same parameters as @code{\fbox} +(@pxref{\fbox & \framebox}), @code{\fboxrule} and @code{\fboxsep}, to +set the thickness of the rule and the boundary between the box interior +and the surrounding rule. @LaTeX{}'s defaults are @code{0.4pt} and +@code{3pt}, respectively. + +This example changes the thickness of the border to 0.8 points. Note +that it is surrounded by curly braces so that the change ends at the end +of the second line. + +@example +@{\setlength@{\fboxrule@}@{0.8pt@} +\fcolorbox@{black@}@{red@}@{Under no circumstances turn this knob.@}@} +@end example + + +@node Colored pages +@subsection Colored pages + +@cindex color +@cindex colored page +@cindex page, colored +@cindex background, colored + +Synopses: + +@example +\pagecolor@{@var{name}@} +\pagecolor[@var{color model}]@{@var{color specification}@} +\nopagecolor +@end example + +The first two set the background of the page, and all subsequent pages, +to the color. For an explanation of the specification in the second +form @pxref{Colored text}. The third returns the background to normal, +which is a transparent background. (If that is not supported use +@code{\pagecolor@{white@}}, although that will make a white background +rather than the default transparent background.) + +@example + ... +\pagecolor@{cyan@} + ... +\nopagecolor +@end example + + +@node Graphics +@chapter Graphics + +@cindex graphics +@cindex graphics package + +You can use graphics such as PNG or PDF files in your @LaTeX{} document. +You need an additional package, which comes standard with @LaTeX{}. +This example is the short how-to. + +@example +\include@{graphicx@} % goes in the preamble + ... +\includegraphics[width=0.5\linewidth]@{plot.pdf@} +@end example + +To use the commands described here your document preamble must contain +either @code{\usepackage@{graphicx@}} or +@code{\usepackage@{graphics@}}. Most of the time, @file{graphicx} is the +better choice. + +Graphics come in two main types, raster and vector. @LaTeX{} can use +both. In raster graphics the file contains an entry for each location +in an array, describing what color it is. An example is a photograph, +in JPG format. In vector graphics, the file contains a list of +instructions such as @samp{draw a circle with this radius and that +center}. An example is a line drawing produced by the Asymptote +program, in PDF format. Generally vector graphics are more useful +because you can rescale their size without pixelation or other problems, +and because they often have a smaller size. + +There are systems particularly well-suited to make graphics for a +@LaTeX{} document. For example, these allow you to use the same fonts +as in your document. @LaTeX{} comes with a @code{picture} environment +(@pxref{picture}) that has simple capabilities. Besides that, there are +other ways to include the graphic-making commands in the document. Two +such systems are the PSTricks and TikZ packages. There are also systems +external to @LaTeX{}, that generate a graphic that you include using the +commands of this chapter. Two that use a programming language are +Asymptote and MetaPost. One that uses a graphical interface is Xfig. +Full description of these systems is outside the scope of this document; +see their documentation on CTAN. + +@menu +* Graphics package options:: Options when you load the package. +* Graphics package configuration:: Where to look for files, which file types. +* Commands for graphics:: The available commands. +@end menu + + +@node Graphics package options +@section @code{graphics} package options + +@cindex graphics package options +@cindex options, graphics package + +Synopsis (must be in the document preamble): + +@example +\usepackage[@var{comma-separated option list}]@{graphics@} +@end example + +@noindent +or + +@example +\usepackage[@var{comma-separated option list}]@{graphicx@} +@end example + +The @code{graphicx} package has a format for optional arguments to the +@code{\includegraphics} command that is convenient (it is the key-value +format), so it is the better choice for new documents. When you load +the @file{graphics} or @file{graphicx} package with @code{\usepackage} +there are two kinds of available options. + +The first is that @LaTeX{} does not contain information about different +output systems but instead depends on information stored in a +@dfn{printer driver} file. Normally you should not specify the driver +option in the document, and instead rely on your system's default. One +advantage of this is that it makes the document portable across systems. + +For completeness here is a list of the drivers. The currently relevant +ones are: @file{dvipdfmx}, @file{dvips}, @file{dvisvgm}, @file{luatex}, +@file{pdftex}, @file{xetex}. The two @file{xdvi} and @file{oztex} are +essentially aliases for @file{dvips} (and @file{xdvi} is monochrome). +Ones that should not be used for new systems are: @file{dvipdf}, +@file{dvipdfm}, @file{dviwin}, @file{dvipsone}, @file{emtex}, +@file{pctexps}, @file{pctexwin}, @file{pctexhp}, @file{pctex32}, +@file{truetex}, @file{tcidvi}, @file{vtex} (and @file{dviwindo} is an +alias for @file{dvipsone}). These are stored in files with a +@file{.def} extension, such as @file{pdftex.def}. + +The second kind of options are below. + +@table @code +@item demo +Instead of an image file, @LaTeX{} puts in a 150@tie{}pt by 100@tie{}pt +rectangle (unless another size is specified in the +@code{\includegraphics} command). + +@item draft +For each graphic file, it is not shown but instead the file name is +printed in a box of the correct size. In order to determine the size, +the file must be present. + +@item final +(Default) Override any previous @code{draft} option, so that the +document shows the contents of the graphic files. + +@item hiderotate +Do not show rotated text. (This allows for the possibility that a +previewer does not have the capability to rotate text.) +@c what does it show? + +@item hidescale +Do not show scaled text. (This allows for the possibility that a +previewer does not have the capability to scale.) +@c what does it show? + +@item hiresbb +In a PS or EPS file the graphic size may be specified in two ways. The +@code{%%BoundingBox} lines describe the graphic size using integer +multiples of a PostScript point, that is, integer multiples of 1/72 +inch. A later addition to the PostScript language allows decimal +multiples, such as 1.23, in @code{%%HiResBoundingBox} lines. This +option has @LaTeX{} to read the size from the latter. + +@end table + + +@node Graphics package configuration +@section @code{graphics} package configuration + +@cindex graphics +@cindex graphics package +@cindex configuration, graphics package +@cindex EPS files +@cindex JPEG files +@cindex JPG files +@cindex PDF graphic files +@cindex PNG files + +These commands configure the way @LaTeX{} searches the file system for +the graphic. + +The behavior of file system search code is necessarily platform +dependent. In this document we cover GNU/Linux, Macintosh, and Windows, as +those systems are typically configured. For other situations consult +the documentation in @file{grfguide.pdf}, or the @LaTeX{} source, or your +@TeX{} distribution's documentation. + +@menu +* \graphicspath:: Directories to search. +* \DeclareGraphicsExtensions:: File types, such as JPG or EPS. +* \DeclareGraphicsRule:: How to handle file types. +@end menu + + +@node \graphicspath +@subsection @code{\graphicspath} + +@findex \graphicspath + +Synopsis: + +@example +\graphicspath@{@var{list of dir names inside curly brackets}@} +@end example + +Declare a list of directories to search for graphics files. This allows +you to later say something like @code{\includegraphics@{lion.png@}} +instead of having to give its path. + +@LaTeX{} always looks for graphic files first in the current directory. +The declaration below tells the system to then look in the subdirectory +@file{pix}, and then @file{../pix}. + +@example +\usepackage@{graphicx@} % or graphics; put in preamble + ... +\graphicspath@{ @{pix/@} @{../pix/@} @} +@end example + +The @code{\graphicspath} declaration is optional. If you don't include +it then @LaTeX{}'s default is to search all of the places that it +usually looks for a file (it uses @LaTeX{}'s @code{\input@@path}). In +particular, in this case one of the places it looks is the current +directory. + +Enclose each directory name in curly braces; for example, above it says +@samp{@code{@{pix@}}}. Do this even if there is only one directory. +Each directory name must end in a forward slash, @file{/}. This is true +even on Windows, where good practice is to use forward slashes for all +the directory separators since it makes the document portable to other +platforms. If you have spaces in your directory name then use double +quotes, as with @code{@{"my docs/"@}}. Getting one of these rules wrong +will cause @LaTeX{} to report @code{Error: File `@var{filename}' not +found}. + +Basically, the algorithm is that with this example, after looking in the +current directory, + +@example +\graphicspath@{ @{pix/@} @{../pix/@} @} +... +\usepackage@{lion.png@} +@end example + +@noindent +for each of the listed directories, @LaTeX{} concatenates it with the +file name and searches for the result, checking for @file{pix/lion.png} +and then @file{../pix/lion.png}. This algorithm means that the +@code{\graphicspath} command does not recursively search subdirectories: +if you issue @code{\graphicspath@{@{a/@}@}} and the graphic is in +@file{a/b/lion.png} then @LaTeX{} will not find it. It also means that +you can use absolute paths such as +@code{\graphicspath@{@{/home/jim/logos/@}@}} or +@code{\graphicspath@{@{C:/Users/Albert/Pictures/@}@}}. However, using +these means that the document is not portable. (You could preserve +portability by adjusting your @TeX{} system settings configuration file +parameter @code{TEXINPUTS}; see the documentation of your system.) + +You can use @code{\graphicspath} anywhere in the document. You can use +it more than once. Show its value with +@code{\makeatletter\typeout@{\Ginput@@path@}\makeatother}. + +The directories are taken with respect to the base file. That is, +suppose that you are working on a document based on @file{book/book.tex} +and it contains @code{\include@{chapters/chap1@}}. If in +@file{chap1.tex} you put @code{\graphicspath@{@{plots/@}@}} then +@LaTeX{} will not search for graphics in @file{book/chapters/plots}, but +instead in @file{book/plots}. + + +@node \DeclareGraphicsExtensions +@subsection @code{\DeclareGraphicsExtensions} + +@findex \DeclareGraphicsExtensions + +Synopses: + +@example +\DeclareGraphicsExtensions@{@var{comma-separated list of file extensions}@} +@end example + +Declare the filename extensions to try. This allows you to specify the +order in which to choose graphic formats when you include graphic files +by giving the filename without the extension, as in +@code{\includegraphics@{functionplot@}}. + +In this example, @LaTeX{} will find files in the PNG format before PDF +files. + +@example +\DeclareGraphicsExtensions@{.png,PNG,.pdf,.PDF@} + ... +\includegraphics@{lion@} % will find @file{lion.png} before @file{lion.pdf} +@end example + +@noindent +Because the file name @file{lion} does not have a period, @LaTeX{} uses +the extension list. For each directory in the graphics path +(@pxref{\graphicspath}), @LaTeX{} will try the extensions in the order +given. If it does not find such a file after trying all the directories +and extensions then it reports @samp{! LaTeX Error: File `@file{lion}' +not found}. Note that you must include the periods at the start of the +extensions. + +Because GNU/Linux and Macintosh filenames are case sensitive, the list of +file extensions is case sensitive on those platforms. The Windows +platform is not case sensitive. + +You are not required to include @code{\DeclareGraphicsExtensions} in +your document; the printer driver has a sensible default. For example, +the most recent @file{pdftex.def} has this extension list. + +@example +.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2 +@end example + +You can use this command anywhere in the document. You can use it more +than once. Show its value with +@code{\makeatletter\typeout@{\Gin@@extensions@}\makeatother}. + + +@node \DeclareGraphicsRule +@subsection @code{\DeclareGraphicsRule} + +@findex \DeclareGraphicsRule + +Synopsis: + +@example +\DeclareGraphicsRule@{@var{extension}@}@{@var{type}@}@{@var{size-file extension}@}@{@var{command}@} +@end example + +Declare how to handle graphic files whose names end in @var{extension}. + +This example declares that all files with names have the form +@file{filename-without-dot.mps} will be treated as output from MetaPost, +meaning that the printer driver will use its MetaPost-handling code to +input the file. + +@example +\DeclareGraphicsRule@{.mps@}@{mps@}@{.mps@}@{@} +@end example + +This + +@example +\DeclareGraphicsRule@{*@}@{mps@}@{*@}@{@} +@end example + +@noindent +tells @LaTeX{} that it should handle as MetaPost output any file with an +extension not covered by another rule, so it covers @file{filename.1}, +@file{filename.2}, etc. + +This describes the four arguments. + +@table @var +@item extension +The file extension to which this rule applies. The extension is anything +after and including the first dot in the filename. Use the Kleene star, +@code{*}, to denote the default behaviour for all undeclared extensions. + +@item type +The type of file involved. This type is a string that must be defined +in the printer driver. For instance, files with extensions @file{.ps}, +@file{.eps}, or @file{.ps.gz} may all be classed as type @code{eps}. +All files of the same type will be input with the same internal command +by the printer driver. For example, the file types that @file{pdftex} +recognizes are: @code{jpg}, @code{jbig2}, @code{mps}, @code{pdf}, +@code{png}, @code{tif}. + +@item size-file extension +The extension of the file to be read to determine the size of the +graphic, if there is such a file. It may be the same as @var{extension} +but it may be different. + +As an example, consider a PostScript graphic. To make it smaller, it +might be compressed into a @file{.ps.gz} file. Compressed files are not +easily read by @LaTeX{} so you can put the bounding box information in a +separate file. If @var{size-file extension} is empty then you must +specify size information in the arguments of @code{\includegraphics}. + +If the driver file has a procedure for reading size files for +@code{type} then that will be used, otherwise it will use the procedure +for reading @file{.eps} files. (Thus you may specify the size of bitmap +files in a file with a PostScript style @code{%%BoundingBox} line if no +other format is available.) + +@item command +A command that will be applied to the +file. This is very often left blank. This command must start with a +single backward quote. Thus, +@code{\DeclareGraphicsRule@{.eps.gz@}@{eps@}@{.eps.bb@}@{`gunzip -c +#1@}} specifies that any file with the extension @file{.eps.gz} should +be treated as an @code{eps} file, with the BoundingBox information +stored in the file with extension @file{.eps.bb}, and that the command +@code{gunzip -c} will run on your platform to decompresses the file. + +Such a command is specific to your platform. In addition, your @TeX{} +system must allow you to run external commands; as a security measure +modern systems restrict running commands unless you explicitly allow it. +See the documentation for your @TeX{} distribution. + +@end table + +@node Commands for graphics +@section Commands for graphics + +@cindex graphics package commands +@cindex commands, graphics package + +These are the commands available with the @file{graphics} and +@file{graphicx} packages. + +@menu +* \includegraphics:: Using a graphic in your document. +* \rotatebox:: Rotating boxes, including graphics. +* \scalebox:: Scaling boxes, including graphics. +* \resizebox:: Scaling boxes, including graphics, to a set size. +@end menu + + +@node \includegraphics +@subsection @code{\includegraphics} + +@cindex graphics +@cindex graphics package +@cindex including graphics +@cindex importing graphics +@cindex EPS files +@cindex JPEG files +@cindex JPG files +@cindex PDF graphic files +@cindex PNG files +@findex \includegraphics + +Synopses for @file{graphics} package: + +@example +\includegraphics@{@var{filename}@} +\includegraphics[@var{urx},@var{ury}]@{@var{filename}@} +\includegraphics[@var{llx},@var{lly}][@var{urx},@var{ury}]@{@var{filename}@} +\includegraphics*@{@var{filename}@} +\includegraphics*[@var{urx},@var{ury}]@{@var{filename}@} +\includegraphics*[@var{llx},@var{lly}][@var{urx},@var{ury}]@{@var{filename}@} +@end example + +Synopses for @file{graphicx} package: + +@example +\includegraphics@{@var{filename}@} +\includegraphics[@var{key-value list}]@{@var{filename}@} +\includegraphics*@{@var{filename}@} +\includegraphics*[@var{key-value list}]@{@var{filename}@} +@end example + +Include a graphics file. The starred form @code{\includegraphics*} will +clip the graphic to the size specified, while for the unstarred form any +part of the graphic that is outside the box of the specified size will +over-print the surrounding area. + +This + +@example +\usepackage@{graphicx@} % in preamble + ... +\begin@{center@} + \includegraphics@{plot.pdf@} +\end@{center@} +@end example + +@noindent +will incorporate into the document the graphic in @file{plot.pdf}, +centered and at its nominal size. You can also give a path to the file, +as with @code{\includegraphics@{graphics/plot.pdf@}}. To specify a list +of locations to search for the file, @pxref{\graphicspath}. + +If your filename includes spaces then put it in double quotes. An example +is @code{\includegraphics@{"sister picture.jpg"@}}. + +The @code{\includegraphics@{@var{filename}@}} command decides on the +type of graphic by splitting @var{filename} on the first dot. You can +use @var{filename} with no dot, as in @code{\includegraphics@{turing@}} +and then @LaTeX{} tries a sequence of extensions such as @code{.png} and +@code{.pdf} until it finds a file with that extension +(@pxref{\DeclareGraphicsExtensions}). + +If your file name contains dots before the extension then you can hide +them with curly braces, as in +@code{\includegraphics@{@{plot.2018.03.12.a@}.pdf@}}. Or, if you use +the @file{graphicx} package then you can use the options @code{type} and +@code{ext}; see below. This and other filename issues are also handled +with the package @file{grffile}. + +This example puts a graphic in a figure environment so @LaTeX{} can +move it to the next page if fitting it on the current page is awkward +(@pxref{figure}). + +@example +\begin@{figure@} + \centering + \includegraphics[width=3cm]@{lungxray.jpg@} + \caption@{The evidence is overwhelming: don't smoke.@} \label@{fig:xray@} +\end@{figure@} +@end example + +This places a graphic that will not float, so it is sure to appear at +this point in the document even if makes @LaTeX{} stretch the text or +resort to blank areas on the page. It will be centered and will have a +caption. + +@example +\usepackage@{caption@} % in preamble + ... +\begin@{center@} + \includegraphics@{pix/nix.png@} + \captionof@{figure@}@{The spirit of the night@} \label@{pix:nix@} % optional +\end@{center@} +@end example + +This example puts a box with a graphic side by side with one having +text, with the two vertically centered. + +@example +\newcommand*@{\vcenteredhbox@}[1]@{\begin@{tabular@}@{@@@{@}c@@@{@}@}#1\end@{tabular@}@} + ... +\begin@{center@} + \vcenteredhbox@{\includegraphics[width=0.4\textwidth]@{plot@}@} + \hspace@{1em@} + \vcenteredhbox@{\begin@{minipage@}@{0.4\textwidth@} + \begin@{displaymath@} + f(x)=x\cdot \sin (1/x) + \end@{displaymath@} + \end@{minipage@}@} +\end@{center@} +@end example + +If you use the @file{graphics} package then the only options involve the +size of the graphic (but see @ref{\rotatebox} and @ref{\scalebox}). +When one optional argument is present then it is +@code{[@var{urx},@var{ury}]} and it gives the coordinates of the top +right corner of the image, as a pair of @TeX{} dimensions (@pxref{Units +of length}). If the units are omitted they default to @code{bp}. In +this case, the lower left corner of the image is assumed to be at (0,0). +If two optional arguments are present then the leading one is +@code{[@var{llx},@var{lly}]}, specifying the coordinates of the image's +lower left. Thus, @code{\includegraphics[1in,0.618in]@{...@}} calls for +the graphic to be placed so it is 1@tie{}inch wide and 0.618@tie{}inches +tall and so its origin is at (0,0). + +The @file{graphicx} package gives you many more options. Specify them +in a key-value form, as here. + +@example +\begin@{center@} + \includegraphics[width=1in,angle=90]@{lion@} + \hspace@{2em@} + \includegraphics[angle=90,width=1in]@{lion@} +\end@{center@} +@end example + +@noindent +The options are read left-to-right. So the first graphic above is made +one inch wide and then rotated, while the second is rotated and then +made one inch wide. Thus, unless the graphic is perfectly square, the +two will end with different widths and heights. + +There are many options. The primary ones are listed first. + +Note that a graphic is placed by @LaTeX{} into a box, which is +traditionally referred to as its bounding box (distinct from the +PostScript BoundingBox described below). The graphic's printed area may +go beyond this box, or sit inside this box, but when @LaTeX{} makes up a +page it puts together boxes and this is the box allocated for the +graphic. + +@table @code +@anchor{includegraphics width} +@item width +The graphic will be shown so its bounding box is this width. An example +is @code{\includegraphics[width=1in]@{plot@}}. You can use the standard +@TeX{} dimensions (@pxref{Units of length}) and also convenient is +@code{\linewidth}, or in a two-column document, @code{\columnwidth} +(@pxref{Page layout parameters}). An example is that by using the +@file{calc} package you can make the graphic be 1@tie{}cm narrow than +the width of the text with +@code{\includegraphics[width=\linewidth-1.0cm]@{hefferon.jpg@}}. + +@item height +@anchor{includegraphics height} +The graphic will be shown so its bounding box is this height. You can +use the standard @TeX{} dimensions (@pxref{Units of length}), and also +convenient are @code{\pageheight} and @code{\textheight} (@pxref{Page +layout parameters}). For instance, the command +@code{\includegraphics[height=0.25\textheight]@{godel@}} will make the +graphic a quarter of the height of the text area. + +@item totalheight +@anchor{includegraphics totalheght} +The graphic will be shown so its bounding box has this height plus +depth. This differs from the height if the graphic was rotated. For +instance, if it has been rotated by -90 then it will have zero height +but a large depth. + +@item keepaspectratio +@anchor{includegraphics keepaspectratio} +If set to @code{true}, or just specified as here + +@example +@code{\includegraphics[...,keepaspectratio,...]@{...@}} +@end example + +@noindent +and you give as options both @code{width} and @code{height} (or +@code{totalheight}), then @LaTeX{} will make the graphic is as large as +possible without distortion. That is, @LaTeX{} will ensure that neither +is the graphic wider than @code{width} nor taller than @code{height} (or +@code{totalheight}). + +@item scale +Factor by which to scale the graphic. To make a graphic twice its +nominal size, enter @code{\includegraphics[scale=2.0]@{...@}}. This +number may be any value; a number between 1 and@tie{}0 will shrink the +graphic and a negative number will reflect it. + +@item angle +Rotate the graphic. The angle is taken in degrees and counterclockwise. +The graphic is rotated about its @code{origin}; see that option. For a +complete description of how rotated material is typeset, +@pxref{\rotatebox}. + +@item origin +The point of the graphic about which the rotation happens. Possible +values are any string containing one or two of: @code{l} for left, +@code{r} for right, @code{b} for bottom, @code{c} for center, @code{t} +for top, and @code{B} for baseline. Thus, entering the command +@code{\includegraphics[angle=180,origin=c]@{moon@}} will turn the +picture upside down about that picture's center, while the command +@code{\includegraphics[angle=180,origin=lB]@{LeBateau@}} will turn its +picture upside down about its left baseline. (The character @code{c} +gives the horizontal center in @code{bc} or @code{tc}, but gives the +vertical center in @code{lc} or @code{rc}.) The default is @code{lB}. + +To rotate about an arbitrary point, @pxref{\rotatebox}. + +@end table + +These are lesser-used options. + +@table @code +@anchor{includegraphics viewport} +@item viewport +Pick out a subregion of the graphic to show. Takes four arguments, +separated by spaces and given in @TeX{} dimensions, as with +@code{\includegraphics[.., viewport=0in 0in 1in 0.618in]@{...@}}. The +dimensions default to big points,@tie{}@code{bp}. They are taken +relative to the origin specified by the bounding box. See also the +@code{trim} option. + +@anchor{includegraphics trim} +@item trim +Gives parts of the graphic to not show. Takes four arguments, separated +by spaces, that are given in @TeX{} dimensions, as with +@code{\includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]@{...@}}. +These give the amounts of the graphic not to show, that is, @LaTeX{} +will crop the picture by 0@tie{}inches on the left, 0.1@tie{}inches on +the bottom, 0.2@tie{}inches on the right, and 0.3@tie{}inches on the +top. See also the @code{viewport} option. + +@anchor{includegraphics clip} +@item clip +If set to @code{true}, or just specified as here + +@example +\includegraphics[...,clip,...]@{...@} +@end example + +@noindent +then the graphic is cropped to the bounding box. This is the same as +using the starred form of the command, +@code{\includegraphics*[...]@{...@}}. + +@anchor{includegraphics page} +@item page +Give the page number of a multi-page PDF file. The default is +@code{page=1}. + +@anchor{includegraphics pagebox} +@item pagebox +Specifies which bounding box to use for PDF files from among +@code{mediabox}, @code{cropbox}, @code{bleedbox}, @code{trimbox}, or +@code{artbox}. PDF files do not have the BoundingBox that PostScript +files have, but may specify up to four predefined rectangles. The +MediaBox gives the boundaries of the physical medium. The CropBox is the +region to which the contents of the page are to be clipped when +displayed. The BleedBox is the region to which the contents of the page +should be clipped in production. The TrimBox is the intended dimensions +of the finished page. The ArtBox is the extent of the page's meaningful +content. The driver will set the image size based on CropBox if +present, otherwise it will not use one of the others, with a +driver-defined order of preference. MediaBox is always present. + +@anchor{includegraphics interpolate} +@item interpolate +Enable or disable interpolation of raster images by the viewer. Can be +set with @code{interpolate=true} or just specified as here. + +@example +\includegraphics[...,interpolate,...]@{...@} +@end example + +@anchor{includegraphics quiet} +@item quiet +Do not write information to the log. You can set it with +@code{quiet=true} or just specified it with +@code{\includegraphics[...,quite,...]@{...@}}, + +@anchor{includegraphics draft} +@item draft +If you set it with @code{draft=true} or just specify it with + +@example +\includegraphics[...,draft,...]@{...@} +@end example + +@noindent +then the graphic will not appear in the document, possibly saving color +printer ink. Instead, @LaTeX{} will put an empty box of the correct +size with the filename printed in it. + +@end table + +These options address the bounding box for Encapsulated PostScript +graphic files, which have a size specified with a line +@code{%%BoundingBox} that appears in the file. It has four values, +giving the lower @math{x} coordinate, lower @math{y} coordinate, upper +@math{x} coordinate, and upper @math{y} coordinate. The units are +PostScript points, equivalent to @TeX{}'s big points, 1/72@tie{}inch. +For example, if an @file{.eps} file has the line @code{%%BoundingBox 10 +20 40 80} then its natural size is 30/72@tie{}inch wide by +60/72@tie{}inch tall. + +@table @code +@anchor{includegraphics bb} +@item bb +Specify the bounding box of the displayed region. The argument is four +dimensions separated by spaces, as with @code{\includegraphics[.., bb= +0in 0in 1in 0.618in]@{...@}}. Usually @code{\includegraphics} reads the +BoundingBox numbers from the EPS file automatically, so this option is +only useful if the bounding box is missing from that file or if you want +to change it. + +@anchor{includegraphics bbllx} +@anchor{includegraphics bblly} +@anchor{includegraphics bburx} +@anchor{includegraphics bbury} +@item bbllx, bblly, bburx, bbury +Set the bounding box. These four are obsolete, but are retained for +compatibility with old packages. + +@anchor{includegraphics natwidth} +@anchor{includegraphics natheight} +@item natwidth, natheight +An alternative for @code{bb}. Setting + +@example +\includegraphics[...,natwidth=1in,natheight=0.618in,...]@{...@} +@end example + +@noindent +is the same as setting @code{bb=0 0 1in 0.618in}. + +@anchor{includegraphics hiresbb} +@item hiresbb +If set to @code{true}, or just specified as with + +@example +\includegraphics[...,hiresbb,...]@{...@} +@end example + +@noindent +then @LaTeX{} will look for @code{%%HiResBoundingBox} lines instead of +@code{%%BoundingBox} lines. (The @code{BoundingBox} lines use only +natural numbers while the @code{HiResBoundingBox} lines use decimals; +both use units equivalent to @TeX{}'s big points, 1/72@tie{}inch.) To +override a prior setting of @code{true}, you can set it to @code{false}. + +@end table + +These following options allow a user to override @LaTeX{}'s method of +choosing the graphic type based on the filename extension. An example +is that @code{\includegraphics[type=png,ext=.xxx,read=.xxx]@{lion@}} +will read the file @file{lion.xxx} as though it were +@file{lion.png}. For more on these, @pxref{\DeclareGraphicsRule}. + +@table @code +@anchor{includegraphics type} +@item type +Specify the graphics type. + +@anchor{includegraphics ext} +@item ext +Specify the graphics extension. +Only use this in conjunction with the option @code{type}. + +@anchor{includegraphics read} +@item read +Specify the file extension of the read file. +Only use this in conjunction with the option @code{type}. + +@anchor{includegraphics command} +@item command +Specify a command to be applied to this file. Only use this in +conjunction with the option @code{type}. @xref{Command line options} +for a discussion of enabling the @code{\write18} functionality to run +external commands. + +@end table + + +@node \rotatebox +@subsection @code{\rotatebox} + +@cindex rotation +@cindex rotating graphics +@cindex rotating text +@findex \rotatebox + +Synopsis if you use the @file{graphics} package: + +@example +\rotatebox@{@var{angle}@}@{@var{material}@} +@end example + +Synopses if you use the @file{graphicx} package: + +@example +\rotatebox@{@var{angle}@}@{@var{material}@} +\rotatebox[@var{key-value list}]@{@var{angle}@}@{@var{material}@} +@end example + +Put @var{material} in a box and rotate it @var{angle} degrees +counterclockwise. + +This example rotates the table column heads forty five degrees. + +@example +\begin@{tabular@}@{ll@} + \rotatebox@{45@}@{Character@} &\rotatebox@{45@}@{NATO phonetic@} \\ + A &AL-FAH \\ + B &BRAH-VOH +\end@{tabular@} +@end example + +The @var{material} can be anything that goes in a box, including a graphic. + +@example + \rotatebox[origin=c]@{45@}@{\includegraphics[width=1in]@{lion@}@} +@end example + +To place the rotated material, the first step is that @LaTeX{} sets +@var{material} in a box, with a reference point on the left baseline. +The second step is the rotation, by default about the reference point. +The third step is that @LaTeX{} computes a box to bound the rotated +material. Fourth, @LaTeX{} moves this box horizontally so that the left +edge of this new bounding box coincides with the left edge of the box +from the first step (they need not coincide vertically). This new +bounding box, in its new position, is what @LaTeX{} uses as the box when +typesetting this material. + +If you use the @file{graphics} package then the rotation is about the +reference point of the box. If you use the @file{graphicx} package +then these are the options that can go in the @var{key-value list}, +but note that you can get the same effect without needing this +package, except for the @code{x} and @code{y} options +(@pxref{\includegraphics}). + +@table @code +@item origin +The point of the @var{material}'s box about which the rotation happens. +Possible value is any string containing one or two of: @code{l} for +left, @code{r} for right, @code{b} for bottom, @code{c} for center, +@code{t} for top, and @code{B} for baseline. Thus, the first line here + +@example +\rotatebox[origin=c]@{180@}@{moon@} +\rotatebox[origin=lB]@{180@}@{LeBateau@} +@end example + +@noindent +will turn the picture upside down from the center while the second will +turn its picture upside down about its left baseline. (The character +@code{c} gives the horizontal center in @code{bc} or @code{tc} but gives +the vertical center in @code{lc} or @code{rc}, and gives both in +@code{c}.) The default is @code{lB}. + +@item x, y +Specify an arbitrary point of rotation with +@code{\rotatebox[x=@var{@TeX{} dimension},y=@var{@TeX{} +dimension}]@{...@}} (@pxref{Units of length}). These give the offset +from the box's reference point. + +@item units +This key allows you to change the default of degrees counterclockwise. +Setting @code{units=-360} changes the direction to degrees clockwise and +setting @code{units=6.283185} changes to radians counterclockwise. + +@end table + + +@node \scalebox +@subsection @code{\scalebox} + +@cindex graphics, scaling +@cindex graphics, resizing +@cindex scaling +@cindex resizing +@cindex text, scaling +@cindex text, resizing +@findex \scalebox +@findex \reflectbox + +Synopses: + +@example +\scalebox@{@var{horizontal factor}@}@{@var{material}@} +\scalebox@{@var{horizontal factor}@}[@var{vertical factor}]@{@var{material}@} +\reflectbox@{@var{material}@} +@end example + +Scale the @var{material}. + +This example halves the size, both horizontally and vertically, of the +first text and doubles the size of the second. + +@example +\scalebox@{0.5@}@{DRINK ME@} and \scalebox@{2.0@}@{Eat Me@} +@end example + +If you do not specify the optional @var{vertical factor} then it +defaults to the same value as the @var{horizontal factor}. + +You can use this command to resize a graphic, as here. + +@example +\scalebox@{0.5@}@{\includegraphics@{lion@}@} +@end example + +@noindent +If you use the @file{graphicx} package then you can accomplish the same +thing with optional arguments to @code{\includegraphics} +(@pxref{\includegraphics}). + +The @code{\reflectbox} command abbreviates +@code{\scalebox@{-1@}[1]@{@var{material}@}}. Thus, @code{Able was +I\reflectbox@{Able was I@}} will show the phrase @samp{Able was I} +immediately followed by its mirror reflection. + + +@node \resizebox +@subsection @code{\resizebox} + +@cindex graphics, scaling +@cindex graphics, resizing +@cindex scaling +@cindex resizing +@cindex text, scaling +@cindex text, resizing +@findex \resizebox + +Synopses: + +@example +\resizebox@{@var{horizontal length}@}@{@var{vertical length}@}@{@var{material}@} +\resizebox*@{@var{horizontal length}@}@{@var{vertical length}@}@{@var{material}@} +@end example + +Given a size, such as @code{3cm}, transform @var{material} to make it +that size. If either @var{horizontal length} or @var{vertical length} +is an exclamation point@tie{}@code{!} then the other argument is used +to determine a scale factor for both directions. + +This example makes the graphic be a half inch wide and scales it +vertically by the same factor to keep it from being distorted. + +@example +\resizebox@{0.5in@}@{!@}@{\includegraphics@{lion@}@} +@end example + +The unstarred form @code{\resizebox} takes @var{vertical length} to be +the box's height while the starred form @code{\resizebox*} takes it to +be height+depth. For instance, make the text have a height+depth of a +quarter inch with @code{\resizebox*@{!@}@{0.25in@}@{\parbox@{1in@}@{This +box has both height and depth.@}@}}. + +You can use @code{\depth}, @code{\height}, @code{\totalheight}, and +@code{\width} to refer to the original size of the box. Thus, make the +text two inches wide but keep the original height with +@code{\resizebox@{2in@}@{\height@}@{Two inches@}}. + + +@node Special insertions +@chapter Special insertions + +@cindex special insertions +@cindex insertions of special characters + +@LaTeX{} provides commands for inserting characters that have a +special meaning do not correspond to simple characters you can type. + +@menu +* Reserved characters:: Inserting @samp{# $ % & @{ @} _ ~ ^ \} +* Upper and lower case:: Make text upper or lower case. +* Symbols by font position:: Inserting font symbols by number. +* Text symbols:: Inserting other non-letter symbols in text. +* Accents:: Inserting accents. +* Additional Latin letters:: Inserting other non-English characters. +* \rule:: Inserting lines and rectangles. +* \today:: Inserting today's date. +@end menu + + +@node Reserved characters +@section Reserved characters + +@cindex reserved characters +@cindex characters, reserved +@cindex special characters +@cindex characters, special +@LaTeX{} sets aside the following characters for special purposes. For +example, the percent sign@tie{}@code{%} is for comments. They are +called @dfn{reserved characters} or @dfn{special characters}. + +@example +# $ % & @{ @} _ ~ ^ \ +@end example + +@findex \# +@findex \$ +@findex \% +@findex \& +@findex \_ +@findex \@{ +@findex \@} +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@tie{}@code{\} in front of the character. Thus, +typing @code{\$1.23} will produce@tie{}@code{$1.23} in your output. + +@findex \~ +@findex \^ +@findex \textbackslash +As to the last three characters, to get a tilde in the text body font +use @code{\~@{@}} (omitting the curly braces would result in the next +character receiving a tilde accent). Similarly, to get a get a text +body font circumflex use @code{\^@{@}}. To get a backslash in the font +of the text body, enter @code{\textbackslash@{@}}. + +To produce the reserved characters in a typewriter font use +@code{\verb!!} as below (the double backslash@tie{}@code{\\} is only +there to split the lines). + +@example +\begin@{center@} + \# \$ \% \& \@{ \@} \_ \~@{@} \^@{@} \textbackslash \\ + \verb!# $ % & @{ @} _ ~ ^ \! +\end@{center@} +@end example + + +@node Upper and lower case +@section Upper and lower case + +@cindex uppercase +@cindex lowercase +@cindex characters, case of + +Synopsis: + +@example +\uppercase@{@var{text}@} +\lowercase@{@var{text}@} +\MakeUppercase@{@var{text}@} +\MakeLowercase@{@var{text}@} +@end example + +Change the case of characters. The @TeX{} primitives commands +@code{\uppercase} and @code{\lowercase} only work for American +characters. The @LaTeX{} commands @code{\MakeUppercase} and +@code{\MakeLowercase} commands also change characters accessed by +commands such as @code{\ae} or @code{\aa}. The commands +@code{\MakeUppercase} and @code{\MakeLowercase} are robust but they have +moving arguments (@pxref{\protect}). + +These commands do not change the case of letters used in the name of a +command within @var{text}. But they do change the case of every other +Latin letter inside the argument @var{text}. Thus, +@code{\MakeUppercase@{Let $y=f(x)$}@} produces @samp{LET Y=F(X)}. Another +example is that the name of an environment will be changed, so that +@code{\MakeUppercase@{\begin@{tabular@} ... \end@{tabular@}@}} will +produce an error because the first half is changed to +@code{\begin@{TABULAR@}}. + +@LaTeX{} uses the same fixed table for changing case throughout a +document, The table used is designed for the font encoding T1; this +works well with the standard @TeX{} fonts for all Latin alphabets but +will cause problems when using other alphabets. + +To change the case of text that results from a macro inside @var{text} +you need to do expansion. Here the @code{\Schoolname} produces +@samp{COLLEGE OF MATHEMATICS}. + +@example +\newcommand@{\schoolname@}@{College of Mathematics@} +\newcommand@{\Schoolname@}@{\expandafter\MakeUppercase +@w{ }\expandafter@{\schoolname@}@} +@end example + +@PkgIndex{textcase} +The @file{textcase} package brings some of the missing feature of the +standard @LaTeX{} commands @code{\MakeUppercase} and +@code{\MakeLowerCase}. + +@PkgIndex{mfirstuc} +To uppercase only the first letter of words, you can use the package +@file{mfirstuc}. + + +@node Symbols by font position +@section Symbols by font position + +@findex \symbol +@cindex accessing any character of a font +@cindex font symbols, by number + +You can access any character of the current font using its number with +the @code{\symbol} command. For example, the visible space character +used in the @code{\verb*} command has the code decimal 32, so it can be +typed as @code{\symbol@{32@}}. + +You can also specify numbers in octal (base 8) by using a @code{'} +prefix, or hexadecimal (base 16) with a @code{"} prefix, so the previous +example could also be written as @code{\symbol@{'40@}} or +@code{\symbol@{"20@}}. + + +@node Text symbols +@section Text symbols + +@cindex text symbols +@cindex symbols, text + +@findex textcomp @r{package} +@LaTeX{} provides commands to generate a number of non-letter symbols in +running text. Some of these, especially the more obscure ones, are not +available in OT1. Unless you are using Xe@LaTeX{} or Lua@LaTeX{} then +you may need to load the @code{textcomp} package. + +@ftable @code +@item \copyright +@itemx \textcopyright +@cindex copyright symbol +@copyright{} The copyright symbol. + +@item \dag +@cindex dagger, in text +@BES{2020,@math{\dag}} The dagger symbol (in text). + +@item \ddag +@cindex double dagger, in text +@BES{2021,@math{\ddag}} The double dagger symbol (in text). + +@item \LaTeX +@cindex @LaTeX{} logo +@cindex logo, @LaTeX{} +The @LaTeX{} logo. + +@item \LaTeXe +@cindex @LaTeX{}2e logo +@cindex logo, @LaTeX{}2e +The @LaTeX{}2e logo. + +@item \guillemotleft @r{(@guillemotleft{})} +@itemx \guillemotright @r{(@guillemotright{})} +@itemx \guilsinglleft @r{(@guilsinglleft{})} +@itemx \guilsinglright @r{(@guilsinglright{})} +@cindex double guillemets +@cindex single guillemets +@cindex left angle quotation marks +@cindex right angle quotation marks +@cindex double angle quotation marks +@cindex single angle quotation marks +@cindex French quotation marks +@cindex quotation marks, French +@guillemotleft{}, @guillemotright{}, @guilsinglleft{}, @guilsinglright{} +Double and single angle quotation marks, commonly used in French. + +@item \ldots +@itemx \dots +@itemx \textellipsis +@cindex ellipsis +@dots{} An ellipsis (three dots at the baseline): @code{\ldots} +and @code{\dots} also work in math mode. + +@item \lq +@cindex left quote +@cindex opening quote +` Left (opening) quote. + +@item \P +@itemx \textparagraph +@cindex paragraph symbol +@cindex pilcrow +@BES{00B6,\P} Paragraph sign (pilcrow). + +@item \pounds +@itemx \textsterling +@cindex pounds symbol +@cindex sterling symbol +@pounds{} English pounds sterling. + +@item \quotedblbase @r{(@quotedblbase{})} +@itemx \quotesinglbase @r{(@quotesinglbase{})} +@cindex double low-9 quotation mark +@cindex single low-9 quotation mark +@cindex low-9 quotation marks, single and double +@quotedblbase{} and @quotesinglbase{} +Double and single quotation marks on the baseline. + +@item \rq +@cindex right quote +@cindex closing quote +' Right (closing) quote. + +@item \S +@itemx \textsection +@cindex section symbol +@BES{00A7,\S} Section sign. + +@item \TeX +@cindex @TeX{} logo +@cindex logo, @TeX{} +The @TeX{} logo. + +@item \textasciicircum +@cindex circumflex, ASCII, in text +@cindex ASCII circumflex, in text +^ ASCII circumflex. + +@item \textasciitilde +@cindex tilde, ASCII, in text +@cindex ASCII tilde, in text +~ ASCII tilde. + +@item \textasteriskcentered +@cindex asterisk, centered, in text +@cindex centered asterisk, in text +* Centered asterisk. + +@item \textbackslash +@cindex backslash, in text +\ Backslash. + +@item \textbar +@cindex vertical bar, in text +@cindex bar, vertical, in text +| Vertical bar. + +@item \textbardbl +@cindex vertical bar, double, in text +@cindex bar, double vertical, in text +@cindex double vertical bar, in text +@BES{23F8,||} Double vertical bar. + +@item \textbigcircle +@cindex big circle symbols, in text +@cindex circle symbol, big, in text +@BES{25EF,} Big circle symbol. + +@item \textbraceleft +@cindex left brace, in text +@cindex brace, left, in text +@{ Left brace. + +@item \textbraceright +@cindex right brace, in text +@cindex brace, right, in text +@} Right brace. + +@item \textbullet +@cindex bullet, in text +@bullet{} Bullet. + +@item \textcircled@{@var{letter}@} +@cindex circled letter, in text +@BES{24B6,} Circle around @var{letter}. + +@item \textcompwordmark +@itemx \textcapitalcompwordmark +@itemx \textascendercompwordmark +@cindex composite word mark, in text +@cindex cap height +@cindex ascender height +Used to separate letters that would normally ligature. For example, +@code{f\textcompwordmark i} produces @samp{fi} without a ligature. This +is most useful in non-English languages. The +@code{\textcapitalcompwordmark} form has the cap height of the font +while the @code{\textascendercompwordmark} form has the ascender height. + +@item \textdagger +@cindex dagger, in text +@BES{2020,@math{\dag}} Dagger. + +@item \textdaggerdbl +@cindex dagger, double, in text +@cindex double dagger, in text +@BES{2021,@math{\ddag}} Double dagger. + +@item \textdollar @r{(or @code{\$})} +@cindex dollar sign +@cindex currency, dollar +$ Dollar sign. + +@item \textemdash @r{(or @code{---})} +@cindex em-dash +--- Em-dash (used for punctuation, as in +@code{The playoffs --- if you are fortunate enough to make the playoffs --- +is more like a sprint.}). + +@item \textendash @r{(or @code{--})} +@cindex e-dash +-- En-dash (used for ranges, as in @code{See pages 12--14}). + +@item \texteuro +@cindex euro symbol +@cindex currency, euro +@PkgIndex{eurosym} +The Euro symbol: @euro{}. For an alternative glyph design, try the +@file{eurosym} package; also, most fonts nowadays come with their own +Euro symbol (Unicode U+20AC). + +@item \textexclamdown @r{(or @code{!`})} +@cindex exclamation point, upside-down +@exclamdown{} Upside down exclamation point. + +@item \textgreater +@cindex greater than symbol, in text +> Greater than symbol. + +@item \textless +@cindex less than symbol, in text +< Less than symbol. + +@item \textleftarrow +@cindex arrow, left, in text +@cindex left arrow, in text +@BES{2190,} Left arrow. + +@item \textordfeminine +@itemx \textordmasculine +@cindex feminine ordinal symbol +@cindex masculine ordinal symbol +@cindex ordinals, feminine and masculine +@cindex Spanish ordinals, feminine and masculine +@ordf{}, @ordm{} Feminine and masculine ordinal symbols. + +@item \textperiodcentered +@cindex period, centered, in text +@cindex centered period, in text +@BES{00B7,\cdot} Centered period. + +@item \textquestiondown @r{(or @code{?`})} +@cindex question mark, upside-down +@questiondown{} Upside down question mark. + +@item \textquotedblleft @r{(or @code{``})} +@cindex left quote, double +@cindex double left quote +`` Double left quote. + +@item \textquotedblright @r{(or @code{''})} +@cindex right quote, double +@cindex double right quote +'' Double right quote. + +@item \textquoteleft @r{(or @code{`})} +@cindex left quote, single +@cindex single left quote +` Single left quote. + +@item \textquoteright @r{(or @code{'})} +@cindex right quote, single +@cindex single right quote +' Single right quote. + +@item \textquotesingle +@cindex quote, single straight +@cindex straight single quote +@cindex single quote, straight +@BES{0027,} Straight single quote. (From TS1 encoding.) + +@item \textquotestraightbase +@itemx \textquotestraightdblbase +@cindex quote, straight base +@cindex straight quote, base +@cindex double quote, straight base +@cindex straight double quote, base +@c Unicode doesn't have these https://en.wikipedia.org/wiki/Quotation_mark +Single and double straight quotes on the baseline. + +@item \textregistered +@cindex registered symbol +@registeredsymbol{} Registered symbol. + +@item \textrightarrow +@cindex arrow, right, in text +@cindex right arrow, in text +@BES{2192,} Right arrow. + +@item \textthreequartersemdash +@cindex three-quarters em-dash +@cindex em-dash, three-quarters +@BES{FE58,} ``Three-quarters'' em-dash, between en-dash and em-dash. + +@item \texttrademark +@cindex trademark symbol +@BES{2122,^{\hbox{TM}}} Trademark symbol. + +@c ?? Diff from \textthreequartersemdash? In Unicode? +@item \texttwelveudash +@cindex two-thirds em-dash +@cindex em-dash, two-thirds +@BES{FE58,} ``Two-thirds'' em-dash, between en-dash and em-dash. + +@item \textunderscore +@cindex underscore, in text +_ Underscore. + +@item \textvisiblespace +@cindex visible space symbol, in text +@BES{2423,} Visible space symbol. + +@end ftable + + +@node Accents +@section Accents + +@cindex accents +@cindex characters, accented +@cindex letters, accented + +@PkgIndex{babel} +@PkgIndex{polyglossia} +@cindex multilingual support +@LaTeX{} has wide support for many of the world's scripts and languages, +through the @code{babel} package and related support if you are using +pdf@LaTeX{}, or @file{polyglossia} if you are using Xe@LaTeX{} or +Lua@LaTeX{}. This section does not cover that support. It only lists +the core @LaTeX{} commands for creating accented characters. The +@code{\capital...} commands shown here produce alternative forms for use +with capital letters. These are not available with OT1. + +Below, to make them easier to find, the accents are all illustrated with +lowercase @samp{o}. + +@findex \i @r{(dotless i)} +@cindex dotless i +Note that @code{\i} produces a dotless i, +@c @dotless{i}, +@findex \j @r{(dotless j)} +@cindex dotless j +and @code{\j} produces a dotless j. +@c @dotless{j}. +These are often used in place of their dotted counterparts when they are +accented. + +@table @code +@item \" +@itemx \capitaldieresis +@findex \" @r{(umlaut accent)} +@findex \capitaldieresis +@cindex umlaut accent +@cindex dieresis accent +@"{o} Umlaut (dieresis). + +@item \' +@itemx \capitalacute +@findex \' @r{(acute accent)} +@findex \capitalacute +@cindex acute accent +@'{o} Acute accent. + +@item \. +@findex \. @r{(dot-over accent)} +@cindex dot accent +@cindex dot-over accent +@dotaccent{o} Dot accent. + +@item \= +@itemx \capitalmacron +@findex \= @r{(macron accent)} +@findex \capitalmacron +@cindex macron accent +@cindex overbar accent +@cindex bar-over accent +@={o} Macron (overbar) accent. + +@item \^ +@itemx \capitalcircumflex +@findex \^ @r{(circumflex accent)} +@findex \capitalcircumflex +@cindex circumflex accent +@cindex hat accent +@^{o} Circumflex (hat) accent. + +@item \` +@itemx \capitalgrave +@findex \` @r{(grave accent)} +@findex \capitalgrave +@cindex grave accent +@`{o} Grave accent. + +@item \~ +@itemx \capitaltilde +@findex \~ @r{(tilde accent)} +@findex \capitaltilde +@cindex tilde accent +@~{n} Tilde accent. + +@item \b +@findex \b @r{(bar-under accent)} +@cindex bar-under accent +@ubaraccent{o} Bar accent underneath. + +@findex \underbar +@cindex underbar +Related to this, @code{\underbar@{@var{text}@}} produces a bar under +@var{text}. The argument is always processed in LR mode +(@pxref{Modes}). The bar is always a fixed position under the baseline, +thus crossing through descenders. See also @code{\underline} in +@ref{Math miscellany}. + +@item \c +@itemx \capitalcedilla +@findex \c @r{(cedilla accent)} +@findex \capitalcedilla +@cindex cedilla accent +@,{c} Cedilla accent underneath. + +@item \d +@itemx \capitaldotaccent +@findex \d @r{(dot-under accent)} +@findex \capitaldotaccent +@cindex dot-under accent +@udotaccent{o} Dot accent underneath. + +@item \H +@itemx \capitalhungarumlaut +@findex \H @r{(Hungarian umlaut accent)} +@findex \capitalhungarumlaut +@cindex hungarian umlaut accent +@H{o} Long Hungarian umlaut accent. + +@item \k +@itemx \capitalogonek +@findex \k @r{(ogonek)} +@findex \capitalogonek +@cindex ogonek +@ogonek{o} Ogonek. Not available in the OT1 encoding. + +@item \r +@itemx \capitalring +@findex \r @r{(ring accent)} +@findex \capitalring +@cindex ring accent +@ringaccent{o} Ring accent. + +@item \t +@itemx \capitaltie +@itemx \newtie +@itemx \capitalnewtie +@findex \t @r{(tie-after accent)} +@findex \capitaltie +@findex \newtie +@findex \capitalnewtie +@cindex tie-after accent +@tieaccent{oo} Tie-after accent. The @code{\newtie} form is centered in +its box. + +@item \u +@itemx \capitalbreve +@findex \u @r{(breve accent)} +@findex \capitalbreve +@cindex breve accent +@u{o} Breve accent. + +@item \v +@itemx \capitalcaron +@findex \v @r{(breve accent)} +@findex \capitalcaron +@cindex hacek accent +@cindex check accent +@cindex caron accent +@v{o} H@'a@v{c}ek (check, caron) accent. + +@end table + + +@node Additional Latin letters +@section Additional Latin letters + +@anchor{Non-English characters} +@cindex Latin letters, additional +@cindex letters, additional Latin +@cindex extended Latin +@cindex special characters +@cindex non-English characters +@cindex characters, non-English + +Here are the basic @LaTeX{} commands for inserting letters beyond +A--Z that extend the Latin alphabet, used primarily in languages other +than English. + +@table @code +@item \aa +@itemx \AA +@findex \aa (@aa{}) +@findex \AA (@AA{}) +@cindex aring +@aa{} and @AA{}. + +@item \ae +@itemx \AE +@findex \ae (@ae{}) +@findex \AE (@AE{}) +@cindex ae ligature +@ae{} and @AE{}. + +@item \dh +@itemx \DH +@findex \dh (@dh{}) +@findex \DH (@DH{}) +@cindex Icelandic eth +@cindex eth, Icelandic letter +Icelandic letter eth: @dh{} and @DH{}. Not available with @sc{OT1} +encoding, you need the @file{fontenc} package to select an alternate +font encoding, such as @sc{T1}. + +@item \dj +@itemx \DJ +@findex \dj +@findex \DJ +Crossed d and D, a.k.a.@: capital and small letter d with stroke. Not +available with @sc{OT1} encoding, you need the @file{fontenc} package to +select an alternate font encoding, such as @sc{T1}. + +@item \ij +@itemx \IJ +@findex \ij (ij) +@findex \IJ (IJ) +@cindex ij letter, Dutch +ij and IJ (except somewhat closer together than appears here). + +@item \l +@itemx \L +@findex \l (@l{}) +@findex \L (@L{}) +@cindex polish l +@l{} and @L{}. + +@item \ng +@itemx \NG +@findex \ng +@findex \NG +Lappish letter eng, also used in phonetics. + +@item \o +@itemx \O +@findex \o (@o{}) +@findex \O (@O{}) +@cindex oslash +@o{} and @O{}. + +@item \oe +@itemx \OE +@findex \oe (@oe{}) +@findex \OE (@OE{}) +@cindex oe ligature +@oe{} and @OE{}. + +@item \ss +@itemx \SS +@findex \ss (@ss{}) +@findex \SS (SS) +@cindex es-zet German letter +@cindex sharp S letters +@ss{} and SS. + +@item \th +@itemx \TH +@findex \th (@th{}) +@findex \TH (@TH{}) +@cindex Icelandic thorn +@cindex thorn, Icelandic letter +Icelandic letter thorn: @th{} and @TH{}. Not available with @sc{OT1} +encoding, you need the @file{fontenc} package to select an alternate +font encoding, such as @sc{T1}. + +@end table + + +@node \rule +@section @code{\rule} + +@findex \rule + +Synopsis, one of: + +@example +\rule@{@var{width}@}@{@var{thickness}@} +\rule[@var{raise}]@{@var{width}@}@{@var{thickness}@} +@end example + +Produce a @dfn{rule}, a filled-in rectangle. + +@cindex Halmos symbol +@cindex tombstone +This produces a rectangular blob, sometimes called a Halmos symbol, +often used to mark the end of a proof. + +@example +\newcommand@{\qedsymbol@}@{\rule@{0.4em@}@{2ex@}@} +@end example + +@PkgIndex{amsthm} +@noindent +The @file{amsthm} package includes this command, with a somewhat +different-looking symbol. + +The mandatory arguments give the horizontal @var{width} and vertical +@var{thickness} of the rectangle. They are rigid lengths +(@pxref{Lengths}). The optional argument @var{raise} is also a rigid +length, and tells @LaTeX{} how much to raise the rule above the +baseline, or lower it if the length is negative. + +This produces a line, a rectangle that is wide but not tall. + +@example +\noindent\rule@{\textwidth@}@{0.4pt@} +@end example + +@noindent +The line is the width of the page and 0.4@tie{}points tall. This line +thickness is common in @LaTeX{}. + +A rule that has zero width, or zero thickness, will not show up in the +output, but can cause @LaTeX{} to change the output around it. +@xref{\strut} for examples. + + +@node \today +@section @code{\today} + +@findex \today +@cindex date, today's +@cindex today's date + +Synopsis: + +@example +\today +@end example + +Produce today's date in the format @samp{@var{month} @var{dd}, +@var{yyyy}}. An example of a date in that format is @samp{July 4, +1976}. + +@PkgIndex{babel} +@PkgIndex{polyglossia} +Multilingual packages such as @file{babel} or @file{polyglossia}, or +classes such as @file{lettre}, will localize @code{\today}. For example, +the following will output @samp{4 juillet 1976}: + +@example +\year=1976 \month=7 \day=4 +\documentclass@{minimal@} +\usepackage[french]@{babel@} +\begin@{document@} +\today +\end@{document@} +@end example + +@noindent +@code{\today} uses the counters @code{\day}, @code{\month}, and +@code{\year} (@pxref{\day & \month & \year}). + +@PkgIndex{datetime} +A number of package on CTAN work with dates. One is @file{datetime} package +which can produce a wide variety of date formats, including ISO standards. + +The date is not updated as the @LaTeX{} process runs, so in principle the +date could be incorrect by the time the program finishes. + + +@node Splitting the input +@chapter Splitting the input + +@cindex splitting the input file +@cindex input file + +@LaTeX{} lets you split a large document into several smaller ones. +This can simplify editing or allow multiple authors to work on the +document. It can also speed processing. + +Regardless of how many separate files you use, there is always one +@cindex root file +@cindex file, root +@dfn{root file}, on which @LaTeX{} compilation starts. This shows such +a file with five included files. + +@example +\documentclass@{book@} +\includeonly@{ % comment out lines below to omit compiling + pref, + chap1, + chap2, + append, + bib + @} +\begin@{document@} +\frontmatter +\include@{pref@} +\mainmatter +\include@{chap1@} +\include@{chap2@} +\appendix +\include@{append@} +\backmatter +\include@{bib@} +\end@{document@} +@end example + +@noindent +This will bring in material from @file{pref.tex}, @file{chap1.tex}, +@file{chap2.tex}, @file{append.tex}, and @file{bib.tex}. If you compile +this file, and then comment out all of the lines inside +@code{\includeonly@{...@}} except for @code{chap1,} and compile again, +then @LaTeX{} will only process the material in the first chapter. +Thus, your output will appear more quickly and be shorter to print. +However, the advantage of the @code{\includeonly} command is that +@LaTeX{} will retain the page numbers and all of the cross reference +information from the other parts of the document so these will appear in +your output correctly. + +@xref{Larger book template} for another example of @code{\includeonly}. + +@menu +* \endinput:: Stop including material from a file. +* \include & \includeonly:: Conditionally include files. +* \input:: Unconditionally include a file. +@end menu + + + +@node \endinput +@section @code{\endinput} + +@findex \endinput + +Synopsis: + +@example +\endinput +@end example + +When you @code{\include@{filename@}}, inside @file{filename.tex} the +material after @code{\endinput} will not be included. This command is +optional; if @file{filename.tex} has no @code{\endinput} then @LaTeX{} +will read all of the file. + +For example, suppose that a document's root file has +@code{\input@{chap1@}} and this is @file{chap1.tex}. + +@example +\chapter@{One@} +This material will appear in the document. +\endinput +This will not appear. +@end example + +This can be useful for putting documentation or comments at the end of a +file, or for avoiding junk characters that can be added during mailing. +It is also useful for debugging: one strategy to localize errors is to +put @code{\endinput} halfway through the included file and see if the +error disappears. Now, knowing which half contains the error, moving +@code{\endinput} to halfway through that area further narrows down the +location. This process rapidly finds the offending line. + +After reading @code{\endinput}, @LaTeX{} continues to read to the end of +the line, so something can follow this command and be read nonetheless. +This allows you, for instance, to close an @code{\if...} with a +@code{\fi}. + + +@node \include & \includeonly +@section @code{\include} & @code{\includeonly} + +@findex \include +@findex \includeonly + +Synopsis: + +@example +\includeonly@{ % in document preamble + ... + @var{filename}, + ... + @} + ... +\include@{@var{filename}@} % in document body +@end example + +Bring material from the external file @file{@var{filename}.tex} into a +@LaTeX{} document. + +The @code{\include} command does three things: it executes +@code{\clearpage} (@pxref{\clearpage & \cleardoublepage}), then it +inputs the material from @file{@var{filename}.tex} into the document, +and then it does another @code{\clearpage}. This command can only +appear in the document body. The @code{\includeonly} command controls +which files will be read by @LaTeX{} under subsequent @code{\include} +commands. Its list of filenames is comma-separated, and it can only +appear in the preamble. + +This example root document, @file{constitution.tex}, brings in +three files, @file{preamble.tex}, @file{articles.tex}, and +@file{amendments.tex}. + +@example +\documentclass@{book@} +\includeonly@{ + preamble, + articles, + amendments + @} +\begin@{document@} +\include@{preamble@} +\include@{articles@} +\include@{amendments@} +\end@{document@} +@end example + +@noindent +The file @file{preamble.tex} contains no special code; you have just +excerpted the chapter from @file{consitution.tex} and put it in a +separate file just for editing convenience. + +@example +\chapter@{Preamble@} +We the People of the United States, +in Order to form a more perfect Union, ... +@end example + +@noindent +Running @LaTeX{} on @file{constitution.tex} makes the material from the +three files appear in the document but also generates the auxiliary +files @file{preamble.aux}, @file{articles.aux}, and +@file{amendments.tex}. These contain information such as page numbers +and cross-references (@pxref{Cross references}). If you now comment out +@code{\includeonly}'s lines with @code{preamble} and @code{amendments} +and run @LaTeX{} again then the resulting document shows only the +material from @file{articles.tex}, not the material from +@file{preamble.tex} or @file{amendments.tex}. Nonetheless, all of the +auxiliary information from the omitted files is still there, including +the starting page number of the chapter. + +If the document preamble does not have @code{\includeonly} then +@LaTeX{} will include all the files you call for with @code{\include} +commands. + +The @code{\include} command makes a new page. To avoid that, see +@ref{\input} (which, however, does not retain the auxiliary +information). + +@xref{Larger book template} for another example using @code{\include} +and @code{\includeonly}. That example also uses @code{\input} for some +material that will not necessarily start on a new page. + +File names can involve paths. + +@example +\documentclass@{book@} +\includeonly@{ + chapters/chap1, + @} +\begin@{document@} +\include@{chapters/chap1@} +\end@{document@} +@end example + +To make your document portable across distributions and platforms you +should avoid spaces in the file names. The tradition is to instead use +dashes or underscores. Nevertheless, for the name @samp{amo amas amat}, +this works under @TeX{} Live on GNU/Linux: + +@example +\documentclass@{book@} +\includeonly@{ + "amo\space amas\space amat" + @} +\begin@{document@} +\include@{"amo\space amas\space amat"@} +\end@{document@} +@end example + +and this works under MiK@TeX{} on Windows: + +@example +\documentclass@{book@} +\includeonly@{ + @{"amo amas amat"@} + @} +\begin@{document@} +\include@{@{"amo amas amat"@}@} +\end@{document@} +@end example + +@cindex nested @code{\include}, not allowed +You cannot use @code{\include} inside a file that is being included or +you get @samp{LaTeX Error: \include cannot be nested.} The +@code{\include} command cannot appear in the document preamble; you will +get @samp{LaTeX Error: Missing \begin@{document@}}. + +If a file that you @code{\include} does not exist, for instance if you +@code{\include@{athiesm@}} but you meant @code{\include@{atheism@}}, +then @LaTeX{} does not give you an error but will warn you @samp{No file +athiesm.tex.} (It will also create @file{athiesm.aux}.) + +If you @code{\include} the root file in itself then you first get +@samp{LaTeX Error: Can be used only in preamble.} Later runs get +@samp{TeX capacity exceeded, sorry [text input levels=15]}. To fix +this, you must remove the inclusion @code{\include@{root@}} but also +delete the file @file{@var{root}.aux} and rerun @LaTeX{}. + + +@node \input +@section @code{\input} + +@findex \input + +Synopsis: + +@example +\input@{@var{filename}@} +@end example + +@LaTeX{} processes the file as if its contents were inserted in the +current file. For a more sophisticated inclusion mechanism see +@ref{\include & \includeonly}. + +If @var{filename} does not end in @samp{.tex} then @LaTeX{} first tries +the filename with that extension; this is the usual case. If +@var{filename} ends with @samp{.tex} then @LaTeX{} looks for the +filename as it is. + +For example, this + +@example +\input@{macros@} +@end example + +@noindent +will cause @LaTeX{} to first look for @file{macros.tex}. If it finds +that file then it processes its contents as thought they had been +copy-pasted in. If there is no file of the name @file{macros.tex} then +@LaTeX{} tries the name @file{macros}, without an extension. (This may +vary by distribution.) + +To make your document portable across distributions and platforms you +should avoid spaces in the file names. The tradition is to instead use +dashes or underscores. Nevertheless, for the name @samp{amo amas amat}, +this works under @TeX{} Live on GNU/Linux: + +@example +\input@{"amo\space amas\space amat"@} +@end example + +and this works under MiK@TeX{} on Windows: + +@example +\input@{@{"amo amas amat"@}@} +@end example + + +@node Front/back matter +@chapter Front/back matter + +@menu +* Table of contents etc.:: Table of contents, list of figures, list of tables. +* Indexes:: Generate an index. +* Glossaries:: Generate a glossary. +@end menu + + +@node Table of contents etc. +@section Table of contents etc. + +@cindex table of contents, creating + +@findex \tableofcontents +@findex .toc @r{file} +@findex \listoffigures +@findex \listoftables +@findex .lof @r{file} +@findex .lot @r{file} + +Synopsis, one of: + +@example +\tableofcontents +\listoffigures +\listoftables +@end example + +Produce a table of contents, or list of figures, or list of tables. Put +the command in the input file where you want the table or list to +go. You do not type the entries; for example, typically the table of +contents entries are automatically generated from the sectioning +commands @code{\chapter}, etc. + +This example illustrates the first command, @code{\tableofcontents}. +@LaTeX{} will produce a table of contents on the book's first page. + +@example +\documentclass@{book@} +% \setcounter@{tocdepth@}@{1@} +\begin@{document@} +\tableofcontents\newpage + ... +\chapter@{...@} + ... +\section@{...@} + ... +\subsection@{...@} + ... +\end@{document@} +@end example + +@noindent +Uncommenting the second line would cause that table to contain chapter +and section listings but not subsection listings, because the +@code{\section} command has level@tie{}1. @xref{Sectioning} for level +numbers of the sectioning units. For more on the @code{tocdepth} +@pxref{Sectioning/tocdepth}. + +Another example of the use of @code{\tableofcontents} is in @ref{Larger +book template}. + +If you want a page break after the table of contents, write a +@code{\newpage} command after the @code{\tableofcontents} command, as +above. + +To make the table of contents @LaTeX{} stores the information in an +auxiliary file named @file{@var{root-file}.toc} (@pxref{Splitting the +input}). For example, this @LaTeX{} file @file{test.tex} + +@example +\documentclass@{article@} +\begin@{document@} +\tableofcontents\newpage +\section@{First section@} +\subsection@{First subsection@} + ... +@end example + +@noindent +writes the following line to @file{test.toc}. + +@example +\contentsline @{section@}@{\numberline @{1@}First section@}@{2@} +\contentsline @{subsection@}@{\numberline @{1.1@}First subsection@}@{2@} +@end example + +@noindent +The @code{section} or @code{subsection} is the sectioning unit. The +hook @code{\numberline} lets you to change how the information appears +in the table of contents. Of its two arguments, @code{1} or @code{1.1} +is the sectioning unit number and @code{First section} or @code{First +subsection} is the title. Finally, @code{2} is the page number on which +the sectioning units start. + +One consequence of this auxiliary file storage strategy is that to get the +contents page correct you must run @LaTeX{} twice, once to store the +information and once to get it. In particular, the first time that you +run @LaTeX{} on a new document, the table of contents page will be empty +except for its @samp{Contents} header. Just run it again. + +The commands @code{\listoffigures} and @code{\listoftables} produce a +list of figures and a list of tables. They work the same way as the +contents commands; for instance, these work with information stored in +@file{.lof} and @file{.lot} files. + +@PkgIndex{babel} +@PkgIndex{polyglossia} +To change the header for the table of contents page do something like +the first line here. + +@example +\renewcommand@{\contentsname@}@{Table of contents@} +\renewcommand@{\listfigurename@}@{Plots@} +\renewcommand@{\listtablename@}@{Tables@} +@end example + +@noindent +Similarly, the other two lines will do the other two. +Internationalization packages such as @file{babel} or @file{polyglossia} +will change the headers depending on the chosen base language. + +@PkgIndex{tocloft} +@PkgIndex{tocbibbind} +CTAN has many packages for the table of contents and lists of figures +and tables. One convenient one for adjusting some aspects of the +default, such as spacing, is @file{tocloft}. And, @file{tocbibbind} +will automatically add the bibliography, index, etc. to the table of +contents. + +@menu +* \addcontentsline:: Add an entry to table of contents, etc. +* \addtocontents:: Add text directly to table of contents file, etc. +* \nofiles:: Prevent writing to auxiliary files. +@end menu + + +@node \addcontentsline +@subsection @code{\addcontentsline} + +@findex \addcontentsline +@cindex table of contents entry, manually adding + +Synopsis: + +@example +\addcontentsline@{@var{ext}@}@{@var{unit}@}@{@var{text}@} +@end example + +@findex \contentsline +Add an entry to the file specified by @var{ext}. Usually @var{ext} is +one of @code{toc} for the table of contents, @code{lof} for the list of +figures, or @code{lot} for the list of tables. + +The following will result in an @samp{Appendices} line in the table of +contents. + +@example +\addcontentsline@{toc@}@{section@}@{\protect\textbf@{Appendices@}@} +@end example + +@noindent +It will appear at the same indentation level as the sections, will be in +boldface, and will be assigned the page number associated with the point +where it appears in the input file. + +The @code{\addcontentsline} command writes information to the file +@file{@var{root-name}.@var{ext}}. It writes that information as the +text of the command +@code{\contentsline@{@var{unit}@}@{@var{text}@}@{@var{num}@}}, where +@code{@var{num}} is the current value of counter @code{@var{unit}}. The +most common case is the table of contents and there @var{num} is the +page number of the first page of @var{unit}. + +This command is invoked by the sectioning commands @code{\chapter}, +etc., and also by @code{\caption} inside a float environment. But it is +also used by authors. For example, in a book to have the preface +unnumbered, you may use the starred @code{\chapter*}. But that does not +put in table of contents information, so you can enter it manually, as +here. + +@example +\chapter*@{Preface@} +\addcontentsline@{toc@}@{chapter@}@{\protect\numberline@{@}Preface@} +@end example + +@noindent +In the @file{.toc} file @LaTeX{} will put the line @code{\contentsline +@{chapter@}@{\numberline @{@}Preface@}@{3@}}; note the page number +@samp{3}. + +@c xx how hardwired are these values? other unit names? + +All of the arguments for @code{\addcontentsline} are required. + +@table @var +@item ext +Typically one of the strings @code{toc} for the table of contents, +@code{lof} for the list of figures, or @code{lot} for the list of +tables. The filename extension of the information file. + +@item unit +A string that depends on the value of the @var{ext} argument: + +@table @code +@item toc +For the table of contents, this is the name of a sectional unit: +@code{part}, @code{chapter}, @code{section}, @code{subsection}, etc. + +@item lof +For the list of figures: @code{figure}. + +@item lot +For the list of tables: @code{table}. +@end table + +@item text +The text of the entry. You must @code{\protect} any commands that are +fragile (@pxref{\protect}). +@end table + +The @code{\addcontentsline} command has an interaction with +@code{\include} (@pxref{\include & \includeonly}). If you use them at +the same level, as with +@code{\addcontentsline@{...@}@{...@}@{...@}\include@{...@}} then lines +in the table of contents can come out in the wrong order. The solution +is to move @code{\addcontentsline} into the file being included. + +If you use a @var{unit} that @LaTeX{} does not recognize, as here + +@example +\addcontentsline@{toc@}@{setcion@}@{\protect\textbf@{Appendices@}@} +@end example + +@noindent +then you don't get an error but the formatting in the table of contents +will not make sense. + + +@node \addtocontents +@subsection @code{\addtocontents} + +@findex \addtocontents@{@var{ext}@}@{@var{text}@} + +Synopsis: + +@example +\addtocontents@{@var{ext}@}@{@var{text}@} +@end example + +Add @var{text}, which may be text or formatting commands, directly to +the auxiliary file with extension @var{ext}. This is most commonly used +for the table of contents so that is the discussion here, but this also +applies to the list of figures and list of tables. + +This will put some vertical space in the table of contents after the +@samp{Contents} header. + +@example +\tableofcontents\newpage +\addtocontents@{toc@}@{\protect\vspace*@{3ex@}@} +@end example + +The @code{\addtocontents} command has two arguments. Both are +required. + +@table @var +@item ext +Typically one of: @file{toc} for the table of contents, @file{lof} for +the list of figures, or @file{lot} for the list of tables. The +extension of the file holding the information. + +@item text +The text, and possibly commands, to be written. +@end table + +The sectioning commands such as @code{\chapter} use the +@code{\addcontentsline} command to store information. This command +creates lines in the @file{.toc} auxiliary file containing the +@code{\contentsline} command (@pxref{\addcontentsline}). In contrast, +the command @code{\addtocontents} puts material directly in that file. + +The @code{\addtocontents} command has an interaction with +@code{\include} (@pxref{\include & \includeonly}). If you use them at +the same level, as with +@code{\addtocontents@{...@}@{...@}\include@{...@}} then lines in the +table of contents can come out in the wrong order. The solution is to +move @code{\addtocontents} into the file being included. + + +@node \nofiles +@subsection @code{\nofiles} + +@findex \nofiles + +Synopsis: + +@example +\nofiles +@end example + +Prevent @LaTeX{} from writing any auxiliary files. The only output will +be the @file{.log} and @file{.pdf} (or @file{.dvi}) files. This command +must go in the preamble. + +Because of the @code{\nofiles} command this example will not produce a +@file{.toc} file. + +@example +\documentclass@{book@} +\nofiles +\begin@{document@} +\tableofcontents\newpage +\chapter@{...@} + ... +@end example + +@noindent +@LaTeX{} will not erase any existing auxiliary files, so if you insert +the @code{\nofiles} command after you have run the file and gotten +a @file{.toc} then the table of contents page will continue to show +the old information. + + +@node Indexes +@section Indexes + +@cindex indexes + +@findex \makeindex +@findex \index +@cindex @file{.idx} file + +This document has an index. + +@example +\documentclass@{article@} +\usepackage@{makeidx@} \makeindex + ... +\begin@{document@} + ... +Recall Wilson's Theorem: \index@{Wilson's Theorem@} +a number \( n>1 \) is prime if and only if the factorial of \( n-1 \) +is congruent to \( -1 \) modulo~\( n \). + ... +\printindex + ... +@end example + +@noindent +The @code{\usepackage@{makeidx@}} and @code{\makeindex} in the preamble +bring in the relevant commands. + +Producing an index is a three stage process. First, in the document +body you declare index entries with the @code{\index} command +(@pxref{\index}). When you run @LaTeX{}, the @code{\index} writes its +information to an auxiliary file @file{@var{root-name}.idx}. Next, to +alphabetize and to do other manipulations you run an external command, +typically @command{makeindex} or @command{xindy} (@pxref{makeindex}). +These output a file @file{@var{root-name}.ind}. Finally, you bring the +information back into your document and typeset it with the +@code{\printindex} command (@pxref{\printindex}). + +@PkgIndex{showidx} +@PkgIndex{multind} +There are many packages that apply to indexing commands. The +@code{showidx} package causes each index entries to be shown in the +margin on the page where the entry appears. This can help in preparing +the index. The @code{multind} package supports multiple indexes. See +also the @TeX{} FAQ entry on this topic, +@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind}. + +@menu +* \index:: Declare an index entry. +* makeindex:: Alphabetize index entries. +* \printindex:: Put the index here. +@end menu + + +@node \index +@subsection @code{\index} + +@cindex index entry +@findex \index + +Synopsis: + +@example +\index@{@var{index-entry-string}@} +@end example + +Declare an entry in the index. This command is fragile +(@pxref{\protect}). + +For example, as described in @ref{Indexes}, one way to get an index from +what's below is to compile the document with @code{pdflatex test}, then +process the index entries with @code{makeindex test}, and then compile +again with @code{pdflatex test}. + +@example +W~Ackermann (1896--1962).\index@{Ackermann@} + ... +Ackermann function\index@{Ackermann!function@} + ... +rate of growth\index@{Ackermann!function!growth rate@} +@end example + +@noindent +All three index entries will get a page number, such as @samp{Ackermann, +22}. @LaTeX{} will format the second as a subitem of the first, on the +line below it and indented, and the third as a subitem of the second. +Three levels deep is as far as you can nest subentries. (If you add +@code{\index@{Ackermann!function!growth rate!comparison@}} then +@command{makeindex} says @samp{Scanning input file test.idx....done (4 +entries accepted, 1 rejected)} and nothing appears in the index). + +If you enter a second @code{\index} with the same +@var{index-entry-string} then you will get a single index entry with two +page numbers (unless they happen to fall on the same page). Thus, +adding @code{as for Ackermann.\index@{Ackermann@}} later in the same +document as above will give an index entry like @samp{Ackermann, 22, +151}. Also, you can enter the index entries in any order, so for +instance @code{\index@{Ackermann!function@}} could come before +@code{\index@{Ackermann@}}. + +@cindex index, page range +Get a page range in the output, like @samp{Hilbert, 23--27}, as here. + +@example +W~Ackermann (1896--1962).\index@{Ackermann@} + ... +D~Hilbert (1862--1943)\index@{Ackermann!Hilbert\(@} + ... +disapproved of his marriage.\index@{Ackermann!Hilbert\)@} +@end example + +@noindent +If the beginning and ending of the page range are equal then the system +just gives a single page entry, not a range. + +If you index subentries but not a main entry, as with +@code{\index@{Jones!program@}} and @code{\index@{Jones!results@}}, then +the output is the item @samp{Jones} with no comma or page number, +followed by two subitems, like @samp{program, 50} and @samp{results, +51}. + +@cindex `see' and `see also' index entries +@cindex index entries, `see' and `see also' +@findex \seename +@findex \alsoname +@PkgIndex{babel} @PkgIndex{polyglossia} + +Generate a index entry that says @samp{See} by using a vertical bar +character: @code{\index@{Ackermann!function|see@{P\'eter's +function@}@}}. You can instead get @samp{See also} with @code{seealso}. +(The text @samp{See} is defined by @code{\seename}, and @samp{See also} +by @code{\alsoname}. You can redefine these either by using an +internationalization package such as @file{babel} or @file{polyglossia}, +or directly as with @code{\renewcommand@{\alsoname@}[1]@{Also see +#1@}}.) + +The @samp{See} feature is part of a more general functionality. After +the vertical bar you can put the name of a one-input command, as in +@code{\index@{group|textit@}} (note the missing backslash on the +@code{\textit} command) and the system will apply that command to the +page number, here giving something like @code{\textit@{7@}}. You can +define your own one-input commands, such as +@code{\newcommand@{\definedpage@}[1]@{@{\color@{blue@}#1@}@}} and then +@code{\index@{Ackermann!function|definedpage@}} will give a blue page +number (@pxref{Color}). Another, less practical, example is this, + +@c credit Ian Thompson https://tex.stackexchange.com/a/272572/121234 +@example +\newcommand\indexownpage[1]@{#1, \thepage@} + ... Epimenides.\index@{self-reference|indexownpage@} +@end example + +@noindent +which creates an entry citing the page number of its own index listing. + +The two functions just described combine, as here + +@example +\index@{Ackermann!function|(definedpage@} + ... +\index@{Ackermann!function|)@} +@end example + +@noindent +which outputs an index entry like @samp{function, 23--27} where the page +number range is in blue. + +Consider an index entry such as @samp{@BES{03B1,\alpha}-ring}. Entering +it as @code{$\alpha$-ring} will cause it to be alphabetized according to +the dollar sign. You can instead enter it using an at-sign, as +@code{\index@{alpha-ring@@$\alpha$-ring@}}. If you specify an entry +with an at-sign separating two strings, @code{@var{pos}@@@var{text}}, +then @var{pos} gives the alphabetical position of the entry while +@var{text} produces the text of the entry. Another example is that +@code{\index@{Saint Michael's College@@SMC@}} produces an index entry +@samp{SMC} alphabetized into a different location than its spelling +would naturally give it. + +To put a @code{!}, or @code{@@}, or @code{|} character in an index +entry, preceding it with a double quote, @code{"}. (The double quote +gets deleted before alphabetization.) + +@PkgIndex{index} +A number of packages on CTAN have additional functionality beyond that +provided by @file{makeidx}. One is @file{index}, which allows for +multiple indices and contains a command +@code{\index*@{@var{index-entry-string}@}} that prints the +@var{index-entry-string} as well as indexing it. + +@findex \indexentry +@cindex idx file +The @code{\index} command writes the indexing information to the file +@file{@var{root-name}.idx} file. Specifically, it writes text of the +command +@code{\indexentry@{@var{index-entry-string}@}@{@var{page-num}@}}, +where @var{page-num} is the value of the @code{\thepage} counter. On +occasion, when the @code{\printindex} command is confused, you have to +delete this file to start with a fresh slate. + +If you omit the closing brace of an @code{\index} command then you get a +message like this. + +@example +Runaway argument? @{Ackermann!function +! Paragraph ended before \@@wrindex was complete. +@end example + + +@node makeindex +@subsection @command{makeindex} + +@cindex index, processing +@findex makeindex +@cindex @command{makeindex} program +@cindex @file{.ind} file +@cindex @file{.idx} file + +Synopsis, one of: + +@example +makeindex @var{filename} +makeindex -s @var{style-file} @var{filename} +makeindex @var{options} @var{filename0} ... +@end example + +Sort, and otherwise process, the index information in the auxiliary file +@var{filename}. This is a command line program. It takes one or more +raw index files, @file{@var{filename}.idx} files, and produces the +actual index file, the @file{@var{filename}.ind} file that is input by +@code{\printindex} (@pxref{\printindex}). + +@cindex @file{.isty} file +@findex index, style file +@findex makeindex, style file +The first form of the command suffices for many uses. The second allows +you to format the index by using an @dfn{index style file}, a +@file{.isty} file. The third form is the most general; see the full +documentation on CTAN. + +This is a simple @file{.isty} file. + +@example +% book.isty +% $ makeindex -s book.isty -p odd book.idx +% creates the index as book.ind, starting on an odd page. +preamble +"\\pagestyle@{empty@} +\\small +\\begin@{theindex@} +\\thispagestyle@{empty@}" + +postamble +"\n +\\end@{theindex@}" +@end example + +The description here covers only some of the index formatting +possibilities in @var{style-file}. For a full list see the documentation +on CTAN. + +A style file consists of a list of pairs: @var{specifier} and +@var{attribute}. These can appear in the file in any order. All of the +@var{attributes} are strings, except where noted. Strings are +surrounded with double quotes, @code{"}, and the maximum length of a +string is 144 characters. The @code{\n} is for a newline and @code{\t} +is for a tab. Backslashes are escaped with another backslash, +@code{\\}. If a line begins with a percent sign, @code{%}, then it is a +comment. + +@ftable @code +@anchor{makeindex preamble} +@item preamble +Preamble of the output file. Defines the context in which the index is +formatted. Default: @code{"\\begin@{theindex@}\n"}. + +@anchor{makeindex postamble} +@item postamble +Postamble of the output file. Default: @code{"\n\n\\end@{theindex@}\n"}. + +@anchor{makeindex group skip} +@item group_skip +@findex \indexspace +Traditionally index items are broken into groups, typically a group for +entries starting with @samp{a}, etc. This specifier gives what is +inserted when a new group begins. Default: @code{"\n\n \\indexspace\n"} +(@code{\indexspace} is a rubber length with default value @code{10pt +plus5pt minus3pt}). + +@anchor{makeindex letheadflag} +@item lethead_flag +An integer. It governs what is inserted for a new group or letter. If +it is 0 (which is the default) then other than @code{group_skip} nothing +will be inserted before the group. If it is positive then at a new +letter the @code{lethead_prefix} and @code{lethead_suffix} will be +inserted, with that letter in uppercase between them. If it is negative +then what will be inserted is the letter in lowercase. The default +is@tie{}0. + +@anchor{makeindex lethead prefix} +@item lethead_prefix +If a new group begins with a different letter then this is the prefix +inserted before the new letter header. Default: @code{""} + +@anchor{makeindex lethead suffix} +@item lethead_suffix +If a group begins with a different letter then this is the suffix +inserted after the new letter header. Default: @code{""}. + +@anchor{makeindex item 0} +@item item_0 +What is put between two level@tie{}0 items. Default: @code{"\n \\item +"}. + +@anchor{makeindex item 1} +@item item_1 +Put between two level@tie{}1 items. Default: @code{"\n \\subitem "}. + +@anchor{makeindex item 2} +@item item_2 +put between two level@tie{}2 items. Default: @code{"\n \\subsubitem "}. + +@anchor{makeindex item 01} +@item item_01 +What is put between a level@tie{}0 item and a level@tie{}1 item. +Default: @code{"\n \\subitem "}. + +@anchor{makeindex item x1} +@item item_x1 +What is put between a level@tie{}0 item and a level@tie{}1 item in the +case that the level@tie{}0 item doesn't have any page numbers (as in +@code{\index@{aaa|see@{bbb@}@}}). Default: @code{"\n \\subitem "}. + +@anchor{makeindex item 12} +@item item_12 +What is put between a level@tie{}1 item and a level@tie{}2 item. +Default: @code{"\n \\subsubitem "}. + +@anchor{makeindex item x2} +@item item_x2 +What is put between a level@tie{}1 item and a level@tie{}2 item, if the +level@tie{}1 item doesn't have page numbers. Default: @code{"\n +\\subsubitem "}. + +@anchor{makeindex delim 0} +@item delim_0 +Delimiter put between a level@tie{}0 key and its first page +number. Default: a comma followed by a blank, @code{", "}. + +@anchor{makeindex delim 1} +@item delim_1 +Delimiter put between a level@tie{}1 key and its first page +number. Default: a comma followed by a blank, @code{", "}. + +@anchor{makeindex delim 2} +@item delim_2 +Delimiter between a level@tie{}2 key and its first page number. Default: +a comma followed by a blank, @code{", "}. + +@anchor{makeindex delim n} +@item delim_n +Delimiter between two page numbers for the same key (at any +level). Default: a comma followed by a blank, @code{", "}. + +@anchor{makeindex delim r} +@item delim_r +What is put between the starting and ending page numbers of a range. +Default: @code{"--"}. + +@anchor{makeindex line max} +@item line_max +An integer. Maximum length of an index entry's line in the output, +beyond which the line wraps. Default: @code{72}. + +@anchor{makeindex indent space} +@item indent_space +What is inserted at the start of a wrapped line. Default: +@code{"\t\t"}. + +@anchor{makeindex indent length} +@item indent_length +A number. The length of the wrapped line indentation. The default +@code{indent_space} is two tabs and each tab is eight spaces so the +default here is @code{16}. + +@anchor{makeindex page precedence} +@item page_precedence +A document may have pages numbered in different ways. For example, a +book may have front matter pages numbered in lowercase roman while main +matter pages are in arabic. This string specifies the order in which +they will appear in the index. The @command{makeindex} command supports +five different types of numerals: lowercase roman @code{r}, and numeric +or arabic @code{n}, and lowercase alphabetic @code{a}, and uppercase +roman @code{R}, and uppercase alphabetic @code{A}. Default: +@code{"rnaRA"}. + +@end ftable + +@findex xindy +@cindex @command{xindy} program +There are a number of other programs that do the job +@command{makeindex} does. One is @command{xindy}, which does +internationalization and can process indexes for documents marked up +using @LaTeX{} and a number of other languages. It is highly +configurable, both in markup terms and in terms of the collating order +of the text, as described in its documentation. + + +@node \printindex +@subsection @command{\printindex} + +@cindex index, printing +@findex \printindex + +Synopsis: + +@example +\printindex +@end example + +@findex \printindex +Place the index into the output. + +To get an index you must first include +@code{\usepackage@{makeidx@}\makeindex} in the document preamble and +compile the document, then run the system command @command{makeindex}, +and then compile the document again. @xref{Indexes} for further +discussion and an example of the use of @code{\printindex}. + + +@node Glossaries +@section Glossaries + +@cindex glossary +@cindex glossaries +@cindex acronyms, list of +@findex \makeglossary +@findex \printglossaries + +Synopsis: + +@example +\usepackage@{glossaries@} \makeglossaries + ... +\newglossaryentry@{@var{label}@}@{@var{settings}@} + ... +\gls@{@var{label}@}. + ... +\printglossaries +@end example + +The @file{glossaries} package allows you to make glossaries, including +multiple glossaries, as well as lists of acronyms. + +To get the output from this example, compile the document (for instance +with @code{pdflatex filename}), then run the command line command +@code{makeglossaries filename}, and then compile the document again. + +@example +\documentclass@{...@} +\usepackage@{glossaries@} \makeglossaries +\newglossaryentry@{tm@}@{% + name=@{Turing machine@}, + description=@{A model of a machine that computes. The model is simple + but can compute anything any existing device can compute. + It is the standard model used in Computer Science.@}, + @} +\begin@{document@} +Everything begins with the definition of a \gls@{tm@}. + ... +\printglossaries +\end@{document@} +@end example + +@noindent +That gives two things. In the main text it outputs @samp{... definition +of a Turing machine}. In addition, in a separate sectional unit headed +@samp{Glossary} there appears a description list. In boldface it says +@samp{Turing machine} and the rest of the item says in normal type +@samp{A model of a machine @dots{} Computer Science}. + +@findex \makeglossary +@findex \printglossaries +@cindex @file{.glo} file +The command @code{\makeglossary} opens the file that will contain the +entry information, @file{@var{root-file}.glo}. Put the +@code{\printglossaries} command where you want the glossaries to appear +in your document. + +The @file{glossaries} package is very powerful. For instance, besides +the commands @code{\newglossaryentry} and @code{\gls}, there are similar +commands for a list of acronyms. See the package documentations on +CTAN. + +@menu +* \newglossaryentry:: Declare the content of a glossary entry. +* \gls:: Give a page reference for a glossary entry. +@end menu + + +@node \newglossaryentry +@subsection @code{\newglossaryentry} + +@cindex glossary, entries +@findex \newglossaryentry + +Synopsis, one of: + +@example +\newglossaryentry@{@var{label}@} +@{ + name=@{@var{name}@}, + description=@{@var{description}@}, + @var{other options}, ... +@} +@end example + +or + +@example +\longnewglossaryentry@{@var{label}@} +@{ + name=@{@var{name}@}, + @var{other options} ..., +@} +@{@var{description}@} +@end example + +Declare a new entry for a glossary. The @var{label} must be unique for +the document. The settings associated with the label are pairs: +@code{@var{key}=@var{value}}. + +This puts the blackboard bold symbol for the real numbers @BES{211D,} in the +glossary. + +@example +\newglossaryentry@{R@} +@{ + name=@{\ensuremath@{\mathbb@{R@}@}@}, + description=@{the real numbers@}, +@} +@end example + +Use the second command form if the @var{description} spans more than one +paragraph. + +For a full list of @var{key}s see the package documentation on CTAN but +here are a few. + +@ftable @code +@item name +(Required.) The word, phrase, or symbol that you are defining. + +@item description +(Required.) The description that will appear in the glossary. +If this has more than one paragraph then you must use the second command +form given in the synopsis. + +@item plural +The plural form of @var{name}. Refer to the plural form using +@code{\glspl} or @code{\Glspl} (@pxref{\gls}). + +@item sort +How to place this entry in the list of entries that the glossary holds. + +@item symbol +A symbol, such as a mathematical symbol, besides the name. + +@end ftable + + +@node \gls +@subsection @code{\gls} + +@cindex glossary, entry reference +@findex \gls + +Synopsis, one of: + +@example +\gls@{@var{label}@} +\glspl@{@var{label}@} +\Gls@{@var{label}@} +\Glspl@{@var{label}@} +@end example + +Refer to a glossary entry. The entries are declared with +@code{\newglossaryentry} (@pxref{\newglossaryentry}). + +This + +@example +\newglossaryentry@{N@}@{% + name=@{the natural numbers@}, + description=@{The numbers $0$, $1$, $2$, $\ldots$\@@@}, + symbol=@{\ensuremath@{\mathbb@{N@}@}@}, + @} + ... +Consider \gls@{N@}. +@end example + +@noindent +gives the output @samp{Consider the natural numbers}. + +The second command form @code{\glspl@{@var{label}@}} produces the plural +of @var{name} (by default it tries adding an @samp{s}). The third form +capitalizes the first letter of @var{name}, as does the fourth form, +which also takes the plural. + + +@node Letters +@chapter Letters + +@cindex letters, writing +@cindex writing letters + +Synopsis: + +@example +\documentclass@{letter@} +\address@{@var{senders address}@} % return address +\signature@{@var{sender name}@} +\begin@{document@} +\begin@{letter@}@{@var{recipient address}@} +\opening@{@var{salutation}@} + @var{letter body} +\closing@{@var{closing text}@} +\end@{letter@} + ... +\end@{document@} +@end example + +Produce one or more letters. + +Each letter is in a separate @code{letter} environment, whose argument +@var{recipient address} often contains multiple lines separated with a +double backslash,@tie{}(@code{\\}). For example, you might have: + +@example + \begin@{letter@}@{Ninon de l'Enclos \\ + l'h\^otel Sagonne@} + ... + \end@{letter@} +@end example + +The start of the @code{letter} environment resets the page number to 1, +and the footnote number to 1 also. + +The @var{sender address} and @var{sender name} are common to all of the +letters, whether there is one or more, so these are best put in the +preamble. As with the recipient address, often @var{sender address} +contains multiple lines separated by a double +backslash@tie{}(@code{\\}). @LaTeX{} will put the @var{sender name} +under the closing, after a vertical space for the traditional +hand-written signature. + +Each @code{letter} environment body begins with a required +@code{\opening} command such as @code{\opening@{Dear Madam or Sir:@}}. +The @var{letter body} text is ordinary @LaTeX{} so it can contain +everything from enumerated lists to displayed math, except that commands +such as @code{\chapter} that make no sense in a letter are turned off. +Each @code{letter} environment body typically ends with a +@code{\closing} command such as @code{\closing@{Yours,@}}. + +@findex \\ @r{for letters} +Additional material may come after the @code{\closing}. You can say who +is receiving a copy of the letter with a command like @code{\cc@{the +Boss \\ the Boss's Boss@}}. There's a similar @code{\encl} command for +a list of enclosures. And, you can add a postscript with @code{\ps}. + +@LaTeX{}'s default is to indent the sender name and the closing above it +by a length of @code{\longindentation}. By default this is +@code{0.5\textwidth}. To make them flush left, put +@code{\setlength@{\longindentation@}@{0em@}} in your preamble. + +To set a fixed date use something like +@code{\renewcommand@{\today@}@{1958-Oct-12@}}. If put in your preamble +then it will apply to all the letters. + +This example shows only one @code{letter} environment. The three lines +marked as optional are typically omitted. + +@example +\documentclass@{letter@} +\address@{Sender's street \\ Sender's town@} +\signature@{Sender's name \\ Sender's title@} +% optional: \location@{Mailbox 13@} +% optional: \telephone@{(102) 555-0101@} +\begin@{document@} +\begin@{letter@}@{Recipient's name \\ Recipient's address@} +\opening@{Sir:@} +% optional: \thispagestyle@{firstpage@} +I am not interested in entering a business arrangement with you. +\closing@{Your most humble, etc.,@} +\end@{letter@} +\end@{document@} +@end example + +These commands are used with the @code{letter} class. + +@menu +* \address:: Sender's return address. +* \cc:: Carbon copy list. +* \closing:: Saying goodbye. +* \encl:: List of enclosed material. +* \location:: Sender's organizational location. +* \makelabels:: Make address labels. +* \name:: Sender's name, for the return address. +* \opening:: Saying hello. +* \ps:: Adding a postscript. +* \signature:: Sender's signature. +* \telephone:: Sender's phone number. +@end menu + + +@node \address +@section @code{\address} + +@findex \address + +Synopsis: + +@example +\address@{@var{senders address}@} +@end example + +Specify the return address, as it appears on the letter and on the +envelope. Separate multiple lines in @var{senders address} with a +double backslash,@tie{}@code{\\}. + +Because it can apply to multiple letters this declaration is often put +in the preamble. However, it can go anywhere, including inside an +individual @code{letter} environment. + +This command is optional: if you do not use it then the letter is +formatted with some blank space on top, for copying onto pre-printed +letterhead paper. If you do use the @code{\address} declaration then it +is formatted as a personal letter. + +Here is an example. + +@example +\address@{Stephen Maturin \\ + The Grapes of the Savoy@} +@end example + + +@node \cc +@section @code{\cc} + +@findex \cc +@cindex cc list, in letters + +Synopsis: + +@example +\cc@{@var{name0} \\ + ... @} +@end example + +Produce a list of names to which copies of the letter were sent. This +command is optional. If it appears then typically it comes after +@code{\closing}. Put the names on different lines by separating them +with a double backslash, @code{\\}, as in: + +@example +\cc@{President \\ + Vice President@} +@end example + + +@node \closing +@section @code{\closing} + +@findex \closing +@cindex letters, ending +@cindex closing letters + +Synopsis: + +@example +\closing@{@var{text}@} +@end example + +Produce the letter's closing. This is optional, but usual. It appears +at the end of a letter, above a handwritten signature. For example: + +@example +\closing@{Regards,@} +@end example + + +@node \encl +@section @code{\encl} + +@findex \encl +@cindex enclosure list + +Synopsis: + +@example +\encl@{@var{first enclosed object} \\ + ... @} +@end example + +Produce a list of things included with the letter. This command is +optional; when it is used, it typically is put after @code{\closing}. +Separate multiple lines with a double backslash, @code{\\}. + +@example +\encl@{License \\ + Passport@} +@end example + + +@node \location +@section @code{\location} + +@findex \location + +Synopsis: + +@example +\location@{@var{text}@} +@end example + +The @var{text} appears centered at the bottom of the page. It only +appears if the page style is @code{firstpage}. + + +@node \makelabels +@section @code{\makelabels} + +@findex \makelabels + +Synopsis: + +@example +\makelabels % in preamble +@end example + +Optional, for a document that contains @code{letter} environments. If +you just put @code{\makelabels} in the preamble then at the end of the +document you will get a sheet with labels for all the recipients, one +for each letter environment, that you can copy to a sheet of peel-off +address labels. + +Customize the labels by redefining the commands @code{\startlabels}, +@code{\mlabel}, and @code{\returnaddress} (and perhaps @code{\name}) in +the preamble. The command @code{\startlabels} sets the width, height, +number of columns, etc., of the page onto which the labels are printed. +The command @code{\mlabel@{@var{return address}@}@{@var{recipient +address}@}} produces the two labels (or one, if you choose to ignore the +@var{return address}) for each letter environment. The first argument, +@var{return address}, is the value returned by the macro +@code{\returnaddress}. The second argument, @var{recipient address}, is +the value passed in the argument to the @code{letter} environment. By +default @code{\mlabel} ignores the first argument, the @var{return +address}, causing the default behavior described in the prior paragraph. + +This illustrates customization. Its output includes a page with two +columns having two labels each. + +@example +\documentclass@{letter@} +\renewcommand*@{\returnaddress@}@{Fred McGuilicuddy \\ + Oshkosh, Mineola 12305@} +\newcommand*\originalMlabel@{@} +\let\originalMlabel\mlabel +\def\mlabel#1#2@{\originalMlabel@{@}@{#1@}\originalMlabel@{@}@{#2@}@} +\makelabels + ... +\begin@{document@} +\begin@{letter@}@{A Einstein \\ + 112 Mercer Street \\ + Princeton, New Jersey, USA 08540@} + ... +\end@{letter@} +\begin@{letter@}@{K G\"odel \\ + 145 Linden Lane \\ + Princeton, New Jersey, USA 08540@} + ... +\end@{letter@} +\end@{document@} +@end example + +@noindent +The first column contains the return address twice. The second column +contains the address for each recipient. + +@PkgIndex{envlab} +The package @code{envlab} makes formatting the labels easier, with +standard sizes already provided. The preamble lines +@code{\usepackage[personalenvelope]@{envlab@}} and @code{\makelabels} +are all that you need to print envelopes. + + +@node \name +@section @code{\name} + +@findex \name + +Synopsis: + +@example +\name@{@var{name}@} +@end example + +Optional. Sender's name, used for printing on the envelope together +with the return address. + + +@node \opening +@section @code{\opening} + +@findex \opening +@cindex letters, starting + +Synopsis: + +@example +\opening@{@var{salutation}@} +@end example + +Required. Follows the @code{\begin@{letter@}@{...@}}. The argument +@var{salutation} is mandatory. For instance: + +@example +\opening@{Dear John:@} +@end example + + +@node \ps +@section @code{\ps} +@findex \ps +@cindex postscript, in letters + +Synopsis: + +@example +\ps@{@var{text}@} +@end example + +Add a postscript. This command is optional and usually is used after +@code{\closing}. + +@example +\ps@{P.S. After you have read this letter, burn it. Or eat it.@} +@end example + + +@node \signature +@section @code{\signature} + +Synopsis: + +@example +\signature@{@var{first line} \\ + ... @} +@end example + +@findex \signature + +The sender's name. This command is optional, although its inclusion is +usual. + +The argument text appears at the end of the letter, after the closing. +@LaTeX{} leaves some vertical space for a handwritten +signature. Separate multiple lines with a double +backslash,@tie{}@code{\\}. For example: + +@example +\signature@{J Fred Muggs \\ + White House@} +@end example + +@LaTeX{}'s default for the vertical space from the @code{\closing} text +down to the @code{\signature} text is @code{6\medskipamount}, which is +six times @code{\medskipamount} (where @code{\medskipamount} is equal to +a @code{\parskip}, which in turn is defined by default here to +0.7@dmn{em}). + +This command is usually in the preamble, to apply to all the letters in +the document. To have it apply to one letter only, put it inside a +@code{letter} environment and before the @code{\closing}. + +You can include a graphic in the signature as here. + +@example +\signature@{\vspace@{-6\medskipamount@}\includegraphics@{sig.png@}\\ + My name@} +@end example + +@noindent +For this you must put @code{\usepackage@{graphicx@}} in the preamble +(@pxref{Graphics}). + + +@c I think this is not a user-level command; it is used to keep from breaking +@c the page between the closing and the signature +@c @node \stopbreaks and \startbreaks +@c @section @code{\stopbreaks} and @code{\startbreaks} + +@c @findex \startbreak +@c @findex \stopbreaks + +@c @example +@c @code{\stopbreaks} +@c text +@c @code{\startbreaks} +@c @end example + +@c The @code{\stopbreaks} inhibits page breaking. The @code{\startbreaks} resumes +@c normal page breaking. +@c +@c +@node \telephone +@section @code{\telephone} + +@findex \telephone + +Synopsis: + +@example +\telephone@{@var{number}@} +@end example + +The sender's telephone number. This is typically in the preamble, where +it applies to all letters. This only appears if the @code{firstpage} +pagestyle is selected. If so, it appears on the lower right of the +page. + + +@node Terminal input/output +@chapter Terminal input/output + +@cindex input/output, to terminal +@cindex terminal input/output + +@menu +* \typein:: Read text from the terminal. +* \typeout:: Write text to the terminal. +@end menu + + +@node \typein +@section @code{\typein} + +@findex \typein + +Synopsis, one of: + +@example +\typein@{@var{prompt-msg}@} +\typein[@var{cmd}]@{@var{prompt-msg}@} +@end example + +Print @var{prompt-msg} on the terminal and cause @LaTeX{} to stop and +wait for you to type a line of input. This line of input ends when you +hit the return key. + +For example, this + +@example +As long as I live I shall never forget \typein@{Enter student name:@} +@end example + +@noindent +coupled with this command line interaction + +@example +Enter student name: + +\@@typein=Aphra Behn +@end example + +@noindent +gives the output @samp{... never forget Aphra Behn}. + +The first command version, @code{\typein@{@var{prompt-msg}@}}, causes +the input you typed to be processed as if it had been included in the +input file in place of the @code{\typein} command. + +In the second command version the optional argument @code{@var{cmd}} +argument must be a command name --- it must begin with a backslash, \. +This command name is then defined or redefined to be the input that you +typed. For example, this + +@example +\typein[\student]@{Enter student name:@} +\typeout@{Recommendation for \student .@} +@end example + +@noindent +gives this output on the command line, + +@example +Enter student name: + +\student=John Dee +Recommendation for John Dee. +@end example + +@noindent +where the user has entered @samp{John Dee.} + + +@node \typeout +@section @code{\typeout} + +@findex \typeout + +Synopsis: + +@example +\typeout@{@var{msg}@} +@end example + +Print @code{msg} on the terminal and in the @code{log} file. + +This + +@example +\newcommand@{\student@}@{John Dee@} +\typeout@{Recommendation for \student .@} +@end example + +@noindent +outputs @samp{Recommendation for John Dee}. Like what happens here with +@code{\student}, commands that are defined with @code{\newcommand} or +@code{\renewcommand} (among others) are replaced by their definitions +before being printed. + +@LaTeX{}'s usual rules for treating multiple spaces as a single space +and ignoring spaces after a command name apply to @code{msg}. As above, +use the command @code{\space} to get a single space, independent of +surrounding spaces. Use @code{^^J} to get a newline. Get a percent +character with @code{\csname @@percentchar\endcsname}. + +This command can be useful for simple debugging, as here: + +@example +\newlength@{\jhlength@} +\setlength@{\jhlength@}@{5pt@} +\typeout@{The length is \the\jhlength.@} +@end example + +@noindent +produces on the command line @samp{The length is 5.0pt}. + + +@node Command line +@chapter Command line + +@cindex command line + +Synopsis (from a terminal command line): + +@example +pdflatex @var{options} @var{argument} +@end example + +Run @LaTeX{} on @var{argument}. In place of @command{pdflatex} you can +also use @command{xelatex}, or @code{lualatex}, or @code{dviluatex}, or +@code{latex}. + +For example, this will run @LaTeX{} on the file @file{thesis.tex}, +creating the output @file{thesis.pdf}. + +@example +pdflatex thesis +@end example + +@noindent +@findex .tex, @r{default extension} +Note that @file{.tex} is the default file extension. + +pdf@TeX{} is a development of the original @TeX{} program, as are +Xe@TeX{} and Lua@TeX{} (@pxref{@TeX{} engines}). They are completely +backward compatible. But the original program had a custom output +format, DVI, while the newer ones can output directly to PDF. This +allows them to take advantage of the extra features in PDF such as +hyperlinks, support for modern image formats such as JPG and PNG, and +ubiquitous viewing programs. In short, if you run @command{pdflatex} or +@command{xelatex} or @command{lualatex} then you will by default get PDF +and have access to all its modern features. If you run @command{latex}, +or @code{dvilualatex}, then you will get DVI. The description here +assumes pdf@LaTeX{}. + +@xref{Command line options}, for a selection of the most useful +command line options. As to @var{argument}, the usual case is that it +does not begin with a backslash, so the system takes it to be the name +of a file and it compiles that file. If @var{argument} begins with a +backslash then the system will interpret it as a line of @LaTeX{} +input, which can be used for special effects (@pxref{Command line +input}). + +If you gave no arguments or options then @command{pdflatex} prompts for +input from the terminal. You can escape from this by entering +@code{<control>-D}. + +If @LaTeX{} finds an error in your document then by default it stops and +asks you about it. @xref{Recovering from errors} for an outline of what +to do. + +@menu +* Command line options:: Read text from the terminal. +* Command line input:: Write text to the terminal. +* Recovering from errors:: When something goes wrong. +@end menu + + +@node Command line options +@section Command line options + +@cindex options, command line + +These are the command-line options relevant to ordinary document +authoring. For a full list, try running @samp{latex --help} from the +command line. + +With many implementations you can specify command line options by +prefixing them with @samp{-} or @samp{--}. This is the case for +both @TeX{} Live (and Mac@TeX{}) and MiK@TeX{}. We will use both +conventions interchangeably. + +@table @code +@findex --version @r{command-line option} +@item -version +Show the current version, like @samp{pdfTeX 3.14159265-2.6-1.40.16 (TeX +Live 2015/Debian)} along with a small amount of additional information, +and exit. + +@findex --help @r{command-line option} +@item -help +Give a brief usage message that is useful as a prompt and exit. + +@findex --interaction @r{command-line option} +@item -interaction=@var{mode} +@TeX{} compiles a document in one of four interaction modes: +@code{batchmode}, @code{nonstopmode}, @code{scrollmode}, +@code{errorstopmode}. In @dfn{errorstop mode} (the default), @TeX{} +stops at each error and asks for user intervention. In @dfn{batch +mode} it prints nothing on the terminal, errors are scrolled as if the +user hit @code{<return>} at every error, and missing files cause the +job to abort. In @dfn{nonstop mode}, diagnostic message appear on the +terminal but as in batch mode there is no user interaction. In +@dfn{scroll mode}, @TeX{} only stops for missing files or keyboard +input. + +For instance, starting @LaTeX{} with this command line + +@example +pdflatex -interaction=batchmode @var{filename} +@end example + +@noindent +eliminates most terminal output. + +@findex --jobname @r{command-line option} +@item -jobname=@var{string} +Set the value of @TeX{}'s @code{jobname} to the string. The log file +and output file will then be named @file{@var{string}.log} and +@file{@var{string}.pdf}. + +When you run @code{@command{pdflatex} @var{options} @var{argument}}, if +@var{argument} does not start with a backslash then @TeX{} considers it +the name of a file to input. Otherwise it waits for the first +@code{\input} instruction and the name of the input file will be the job +name. This is used to name the log file the output file. The +@code{jobname} option overrides that process and directly specifies the +name. @xref{Command line input} for an example of its use. + +@findex --output-directory @r{command-line option} +@item -output-directory=@var{directory} +Write files in the directory @var{directory}. It must already exist. + +@findex --shell-escape @r{command-line option} +@findex --no-shell-escape @r{command-line option} +@findex --enable-write18 @r{command-line option} +@findex --disable-write18 @r{command-line option} +@item --shell-escape +@itemx --no-shell-escape +@itemx --enable-write18 +@itemx --disable-write18 +Enable or disable @code{\write18@{@var{shell command}@}}. The first two +options are for with @TeX{} Live or Mac@TeX{} while the second two are +for MiK@TeX{}. + +@PkgIndex{sagetex} +Sometimes you want to run external system commands from inside a +@LaTeX{} file. For instance the package @file{sagetex} allows you to +have the mathematics software system @i{Sage} do calculations or draw +graphs and then incorporate that output in your document. For this +@TeX{} provides the @code{\write18} command. + +But with this functionality enabled, security issues could happen if you +compiled a @LaTeX{} file from the Internet. By default @code{\write18} +is disabled. (More precisely, by default @TeX{} Live, Mac@TeX{}, and +MiK@TeX{} only allow the execution of a limited number of @TeX{}-related +programs, which they distribute.) + +If you invoke @LaTeX{} with the option @code{no-shell-escape}, and in +your document you call @code{\write18@{ls -l@}}, then you do not get an +error but the log file says @samp{runsystem(ls -l)...disabled}. + +@findex --halt-on-error @r{command-line option} +@item -halt-on-error +Stop processing at the first error. + +@findex --file-line-error @r{command-line option} +@findex --no-file-line-error @r{command-line option} +@item -file-line-error +@item -no-file-line-error +Enable or disable @code{@var{filename}:@var{lineno}:@var{error}}-style +error messages. These are only available with @TeX{} Live or Mac@TeX{}. +@end table + + +@node Command line input +@section Command line input + +@cindex input, on command line + +As part of the command line invocation @code{pdflatex @var{options} +@var{argument}} you can specify arbitrary @LaTeX{} input by starting +@var{argument} with a backslash. This allows you to do some special +effects. + +@PkgIndex{hyperref} +For example, this file (which uses the @file{hyperref} package for +hyperlinks) can produce two kinds of output, one for paper and one for a +PDF. + +@example +\ifdefined\paperversion % in preamble +\newcommand@{\urlcolor@}@{black@} +\else +\newcommand@{\urlcolor@}@{blue@} +\fi +\usepackage[colorlinks=true,urlcolor=\urlcolor]@{hyperref@} + ... +\href@{https://www.ctan.org@}@{CTAN@} % in body + ... +@end example + +@noindent +Compiling this document @file{book.tex} with the command line +@code{pdflatex book} will give the @samp{CTAN} link in blue. But +compiling it with @code{pdflatex "\def\paperversion@{@}\input book.tex"} +has the link in black. (Note the use of double quotes to prevent +interpretation of the symbols by the command line shell; your system may +do this differently.) + +In a similar way, from the single file @file{main.tex} you can compile +two different versions. + +@c credit Paul Gaborit: https://tex.stackexchange.com/a/220101/121234 +@example +pdflatex -jobname=students "\def\student@{@}\input@{main@}" +pdflatex -jobname=teachers "\def\teachers@{@}\input@{main@}" +@end example + +@noindent +The @code{jobname} option is there because otherwise both files would be +called @file{main.pdf} and the second would overwrite the first. + +A final example. This loads the package @file{graphicx} with the option +@code{draft} + +@c credit Herbert Voss: https://tex.stackexchange.com/a/17236/121234 +@example +pdflatex -jobname=aa "\RequirePackage[draft]@{graphicx@}\input@{aa.tex@}" +@end example + +@noindent +so the graphic files are read for their size information but not +incorporated into the PDF. (The @code{jobname} option is there because +otherwise the output file would be @file{graphicx.pdf}, as +@code{\RequirePackage} does an @code{\input} of its own.) + + +@node Recovering from errors +@section Recovering from errors + +If @LaTeX{} finds an error in your document then it gives you an error +message and prompts you with a question mark, @code{?}. For instance, +running @LaTeX{} on this file + +@example +\newcommand@{\NP@}@{\ensuremath@{\textbf@{NP@}@}@} +The \PN@{@} problem is a million dollar one. +@end example + +@noindent +causes it show this, and wait for input. + +@example +! Undefined control sequence. +l.5 The \PN + @{@} problem is a million dollar one. +? +@end example + +@noindent +The simplest thing is to enter @samp{x} and @code{<return>} and fix the +typo. You could instead enter @samp{?} and @code{<return>} to see other +options. + +@cindex @samp{*} prompt +@cindex prompt, @samp{*} +@findex \stop +There are two other error scenarios. The first is that you forgot to +include the @code{\end@{document@}} or misspelled it. In this case +@LaTeX{} gives you a @samp{*} prompt. You can get back to the command +line by typing @code{\stop} and @code{<return>}. + +The last scenario is that you mistyped the file name. For instance, +instead of @code{pdflatex test} you might type @code{pdflatex tste}. + +@example +! I can't find file `tste'. +<*> tste + +(Press Enter to retry, or Control-D to exit) +Please type another input file name: +@end example + +@noindent +The simplest thing is to enter @code{<Control>} and @samp{d} (holding +them down at the same time), and then retype the correct command line. + + +@node Document templates +@appendix Document templates + +@cindex document templates +@cindex templates, document + +Although not reference material, perhaps these document templates will +be useful. Additional template resources are listed at +@url{http://tug.org/interest.html#latextemplates}. + +@menu +* beamer template:: +* article template:: +* book template:: +* Larger book template:: +* tugboat template:: +@end menu + + +@node beamer template +@section @code{beamer} template + +@cindex @code{beamer} template and class +@cindex template, @code{beamer} + +The @code{beamer} class creates presentation slides. It has a vast +array of features, but here is a basic template: + +@verbatim +\documentclass{beamer} + +\title{Beamer Class template} +\author{Alex Author} +\date{July 31, 2007} + +\begin{document} + +\maketitle + +% without [fragile], any {verbatim} code gets mysterious errors. +\begin{frame}[fragile] + \frametitle{First Slide} + +\begin{verbatim} + This is \verbatim! +\end{verbatim} + +\end{frame} + +\end{document} +@end verbatim + +One web resource for this: +@url{http://robjhyndman.com/hyndsight/beamer/}. + + +@node article template +@section @code{article} template + +@cindex template, @code{article} + +@verbatim +\documentclass{article} +\title{Article Class Template} +\author{Alex Author} + +\begin{document} +\maketitle + +\section{First section} +Some text. + +\subsection{First section, first subsection} +Additional text. + +\section{Second section} +Some more text. +\end{document} +@end verbatim + + +@node book template +@section @code{book} template + +@cindex template, @code{book} + +This is a straightforward template for a book. See @xref{Larger book +template} for a more elaborate one. + +@verbatim +\documentclass{book} +\title{Book Class Template} +\author{Alex Author} + +\begin{document} +\maketitle + +\chapter{First} +Some text. + +\chapter{Second} +Some other text. + +\section{A subtopic} +The end. +\end{document} +@end verbatim + + +@node Larger book template +@section Larger @code{book} template + +@cindex template, @code{book} + +This is a more elaborate template for a book. It has +@code{\frontmatter}, @code{\mainmatter}, and @code{\backmatter} to +control the typography of the three main areas of a book +(@pxref{\frontmatter & \mainmatter & \backmatter}). The book has a +bibliography and an index. + +Notable is that it uses @code{\include} and @code{\includeonly} +(@pxref{Splitting the input}). While you are working on a chapter you +can comment out all the other chapter entries from the argument to +@code{\includeonly}. That will speed up compilation without losing any +information such as cross-references. (Material that does not need to +come on a new page is brought in with @code{\input} instead of +@code{\include}. You don't get the cross-reference benefit this way.) + +@verbatim +\documentclass[titlepage]{book} +\usepackage{makeidx}\makeindex + +\title{Book Class Template} +\author{Alex Author} + +\includeonly{% + frontcover, + preface, + chap1, + ... + } +\begin{document} +\frontmatter +\include{frontcover} + % maybe comment out while drafting: +\maketitle \input{dedication} \input{copyright} +\tableofcontents +\include{preface} +\mainmatter +\include{chap1} +... +\appendix +\include{appena} +... +\backmatter +\bibliographystyle{apalike} +\addcontentsline{toc}{chapter}{Bibliography} +\bibliography +\addcontentsline{toc}{chapter}{Index} +\printindex +\include{backcover} +\end{document} +@end verbatim + + +@node tugboat template +@section @code{tugboat} template + +@cindex template, TUGboat +@cindex TUGboat template +@cindex @code{ltugboat} class + +@cite{TUGboat} is the journal of the @TeX{} Users Group, +@url{http://tug.org/TUGboat}. + +@verbatim +\documentclass{ltugboat} + +\usepackage{graphicx} +\usepackage{ifpdf} +\ifpdf +\usepackage[breaklinks,hidelinks]{hyperref} +\else +\usepackage{url} +\fi + +%%% Start of metadata %%% + +\title{Example \TUB\ article} + +% repeat info for each author. +\author{First Last} +\address{Street Address \\ Town, Postal \\ Country} +\netaddress{user (at) example dot org} +\personalURL{http://example.org/~user/} + +%%% End of metadata %%% + +\begin{document} + +\maketitle + +\begin{abstract} +This is an example article for \TUB{}. +Please write an abstract. +\end{abstract} + +\section{Introduction} + +This is an example article for \TUB, linked from +\url{http://tug.org/TUGboat/location.html}. + +We recommend the \texttt{graphicx} package for image inclusions, and the +\texttt{hyperref} package if active urls are desired (in the \acro{PDF} +output). Nowadays \TUB\ is produced using \acro{PDF} files exclusively. + +The \texttt{ltugboat} class provides these abbreviations (and many more): +% verbatim blocks are often better in \small +\begin{verbatim}[\small] +\AllTeX \AMS \AmS \AmSLaTeX \AmSTeX \aw \AW +\BibTeX \CTAN \DTD \HTML +\ISBN \ISSN \LaTeXe +\mf \MFB +\plain \POBox \PS +\SGML \TANGLE \TB \TP +\TUB \TUG \tug +\UNIX \XeT \WEB \WEAVE + +\, \bull \Dash \dash \hyph + +\acro{FRED} -> {\small[er] fred} % please use! +\cs{fred} -> \fred +\meta{fred} -> <fred> +\nth{n} -> 1st, 2nd, ... +\sfrac{3/4} -> 3/4 +\booktitle{Book of Fred} +\end{verbatim} + +For references to other \TUB\ issue, please use the format +\textsl{volno:issno}, e.g., ``\TUB\ 32:1'' for our \nth{100} issue. + +This file is just a template. The \TUB\ style documentation is the +\texttt{ltubguid} document at \url{http://ctan.org/pkg/tugboat}. (For +\CTAN\ references, where sensible we recommend that form of url, using +\texttt{/pkg/}; or, if you need to refer to a specific file location, +\texttt{http://mirror.ctan.org/\textsl{path}}.) + +Email \verb|tugboat@tug.org| if problems or questions. + +\bibliographystyle{plain} % we recommend the plain bibliography style +\nocite{book-minimal} % just making the bibliography non-empty +\bibliography{xampl} % xampl.bib comes with BibTeX + +\makesignature +\end{document} +@end verbatim + + +@node Index +@unnumbered Index + +@c Keep `Command Index' working for ltx-help.el. +@anchor{Command Index} + +@printindex cp + +@bye + +\def\DeclareTextCommand{\foo}{T1} +% then |\foo| is defined to be |\T1-cmd \foo \T1\foo|, +% % where |\T1\foo| is \emph{one} control sequence, not two! +\newcommand + +\def\ProvideTextCommand -- same with \providecommand +\@onlypreamble\DeclareTextCommand +\@onlypreamble\DeclareTextSymbol +\gdef\TextSymbolUnavailable#1{% +\@onlypreamble\def\DeclareTextCommandDefault#1{% +\def\ProvideTextCommandDefault#1{% +\def\DeclareTextAccent#1#2#3{% +\def\DeclareTextCompositeCommand#1#2#3#4{% +\@onlypreamble\def\DeclareTextComposite#1#2#3#4{% +\def\UseTextAccent#1#2#3{% +\def\UseTextSymbol#1#2{% +\@onlypreamble\DeclareTextSymbolDefault@item +\@onlypreamble\DeclareTextAccentDefault@item +\def\UndeclareTextCommand#1#2{% + +@c Local Variables: +@c ispell-dictionary: "english" +@c coding: latin-1-unix +@c End: |