path: root/Master/texmf-dist/doc/info/latex2e.info

This is latex2e.info, produced by makeinfo version 7.1 from
latex2e.texi.

This document is an unofficial reference manual for LaTeX, a document
preparation system, version of May 2024.

   This manual was originally translated from ‘LATEX.HLP’ v1.0a in the
VMS Help Library.  The pre-translation version was written by George D.
Greenwade of Sam Houston State University.  The LaTeX 2.09 version was
written by Stephen Gilmore.  The LaTeX2e version was adapted from this
by Torsten Martinsen.  Karl Berry made further updates and additions,
and gratefully acknowledges using ‘Hypertext Help with LaTeX’, by
Sheldon Green, and ‘LaTeX Command Summary’ (for LaTeX 2.09) by L. Botway
and C. Biemesderfer (published by the TeX Users Group as ‘TeXniques’
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, 2019, 2020, 2021, 2022 Karl Berry.
Copyright 1988, 1994, 2007 Stephen Gilmore.
Copyright 1994, 1995, 1996 Torsten Martinsen.

   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.

   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.
INFO-DIR-SECTION TeX
START-INFO-DIR-ENTRY
* LaTeX2e: (latex2e).              Unofficial LaTeX reference manual.
END-INFO-DIR-ENTRY


File: latex2e.info,  Node: Top,  Next: About this document,  Up: (dir)

LaTeX2e: An unofficial reference manual
***************************************

This document is an unofficial reference manual (version of May 2024)
for LaTeX2e, 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.
* Graphics::                    Importing graphics from outside LaTeX.
* Color::                       Defining and using colors.
* 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 ‘letter’ class.
* Input/output::        	User interaction.
* Command line interface::      Common command-line options.
* Document templates::          Starter templates for various document classes.
* Index::		        General index.


File: latex2e.info,  Node: About this document,  Next: Overview,  Prev: Top,  Up: Top

1 About this document
*********************

This is an unofficial reference manual for the LaTeX2e document
preparation system, which is a macro package for the TeX typesetting
program (*note Overview::).

   This document's home page is <https://latexref.xyz>; it has separate
web pages for each topic.  Alternatively.
<https://latexref.xyz/dev/latex2e.html> has the entire document on a
single page.  For other output formats, the sources, and plenty more
information, see <https://latexref.xyz/dev/>.

   In this document, we will mostly just use 'LaTeX' rather than
'LaTeX2e', since the previous version of LaTeX (2.09) was frozen decades
ago.

   LaTeX is maintained by a group of volunteers
(<https://latex-project.org>).  The official documentation written by
the LaTeX project is available from their web site.  The present
document is completely unofficial and has not been written or reviewed
by the LaTeX maintainers.  Do not send bug reports or anything else
about this document to them.  Instead, please send all comments to
<latexrefman@tug.org>.  This is a public list; you can (un)subscribe,
view the archives, etc., at <https://lists.tug.org/latexrefman>.

   This document is a reference, not a tutorial.  There is a vast array
of other information available about LaTeX, at all levels.  Here are a
few introductions.

<https://ctan.org/pkg/latex-doc-ptr>
     Two pages of recommended references to LaTeX documentation.

<https://ctan.org/pkg/first-latex-doc>
     Writing your first document, with a bit of both text and math.

<https://ctan.org/pkg/lshort>
     A longer introduction to LaTeX, translated to many languages.

<https://tug.org/begin.html>
     Overview of getting started with TeX and LaTeX.


File: latex2e.info,  Node: Overview,  Next: Document classes,  Prev: About this document,  Up: Top

2 Overview of LaTeX
*******************

LaTeX is a system for typesetting documents.  It was originally created
by Leslie Lamport in 1984, but has been maintained by a group of
volunteers for many years now (<https://latex-project.org>).  It is
widely used, particularly but not exclusively for mathematical and
technical documents.

   A LaTeX user writes an input file containing text to be typeset along
with interspersed commands.  The default encoding for the text is UTF-8
(as of 2018).  The commands specify, for example, how the text should be
formatted.

   LaTeX is implemented as a set of so-called "macros" (a TeX “format”)
which use Donald E. Knuth's TeX typesetting program or one of its
derivatives, collectively known as "engines".  Thus, the user produces
output, typically PDF, by giving the input file to a TeX engine.  The
following sections describe all this in more detail.

   The term LaTeX is also sometimes used to mean the language in which
the input document is marked up, that is, to mean the set of commands
available to a LaTeX user.

   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 ‘\LaTeX’.  Where use of the logo is not sensible, such as in
plain text, write it as ‘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.
* Input text::              Input encodings and special characters.
* LaTeX command syntax:: General syntax of LaTeX commands.
* Environment syntax::      \begin{envname} ... \end{envname}.
* \DocumentMetadata::       Towards accessible PDF output.
* CTAN::                    The TeX world's general repository.


File: latex2e.info,  Node: Starting and ending,  Next: Output files,  Up: Overview

2.1 Starting and ending
=======================

LaTeX files have a simple global structure, with a standard beginning
and ending.  Here is a small example:

     \documentclass{article}
     \begin{document}
     Hello, \LaTeX\ world.
     \end{document}

Every LaTeX document has a ‘\begin{document}’ line and an
‘\end{document}’ line.

Here, the ‘article’ is the “document class”.  It is implemented in a
file ‘article.cls’.  You can use any document class available on your
system.  A few document classes are defined by LaTeX itself, and a vast
array of others are available.  *Note Document classes::.

   You can include other LaTeX commands between the ‘\documentclass’ and
the ‘\begin{document}’ commands.  This area is called the “preamble”.

   The ‘\begin{document}’ ... ‘\end{document}’ pair defines an
“environment”; the ‘document’ environment (and no others) is required in
all LaTeX documents (*note document::).  LaTeX provides many
environments that are documented here (*note Environments::).  Many more
are available to you from external packages, most importantly those
available at CTAN (*note CTAN::).

   The following sections discuss how to produce PDF or other output
from a LaTeX input file.


File: latex2e.info,  Node: Output files,  Next: TeX engines,  Prev: Starting and ending,  Up: Overview

2.2 Output files
================

LaTeX produces a main output file and at least two auxiliary files.  The
main output file's name ends in either ‘.dvi’ or ‘.pdf’.

‘.dvi’
     If LaTeX is invoked with the system command ‘latex’ then it
     produces a DeVice Independent file, with extension ‘.dvi’.  You can
     view this file with a command such as ‘xdvi’, or convert it to a
     PostScript ‘.ps’ file with ‘dvips’ or to a Portable Document Format
     ‘.pdf’ file with ‘dvipdfmx’.  The contents of the file can be
     dumped in human-readable form with ‘dvitype’.  A vast array of
     other DVI utility programs are available
     (<https://mirror.ctan.org/dviware>).

‘.pdf’
     If LaTeX is invoked via the system command ‘pdflatex’, among other
     commands (*note 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.

   LaTeX always produces at least two additional 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.

‘.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 ‘??’.  When the referred-to spot does eventually appear in the
     source then LaTeX writes its location information to this ‘.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.

   LaTeX may produce yet more files, characterized by the filename
ending.  These include a ‘.lof’ file that is used to make a list of
figures, a ‘.lot’ file used to make a list of tables, and a ‘.toc’ file
used to make a table of contents (*note Table of contents etc.::).  A
particular class may create others; the list is open-ended.


File: latex2e.info,  Node: TeX engines,  Next: Input text,  Prev: Output files,  Up: Overview

2.3 TeX engines
===============

LaTeX is a large set of commands (macros) that is executed by a TeX
program (*note Overview::).  Such a set of commands is called a
“format”, and is embodied in a binary ‘.fmt’ file, which can be read
much more quickly than the corresponding TeX source.

   This section gives a terse overview of the TeX programs that are
commonly available (see also *note Command line interface::).

‘latex’
‘pdflatex’
     In TeX Live (<https://tug.org/texlive>), if LaTeX is invoked via
     either the system command ‘latex’ or ‘pdflatex’, then the pdfTeX
     engine is run (<https://ctan.org/pkg/pdftex>).  When invoked as
     ‘latex’, the main output is a ‘.dvi’ file; as ‘pdflatex’, the main
     output is a ‘.pdf’ file.

     pdfTeX incorporates the e-TeX extensions to Knuth's original
     program (<https://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 ‘etex’, but this is plain TeX (and produces ‘.dvi’).

     In other TeX distributions, ‘latex’ may invoke e-TeX rather than
     pdfTeX.  In any case, the e-TeX extensions can be assumed to be
     available in LaTeX, and a few extensions beyond e-TeX, particularly
     for file manipulation.

‘lualatex’
     If LaTeX is invoked via the system command ‘lualatex’, the LuaTeX
     engine is run (<https://ctan.org/pkg/luatex>).  This program allows
     code written in the scripting language Lua (<http://luatex.org>) to
     interact with TeX's typesetting.  LuaTeX handles UTF-8 Unicode
     input natively, can handle OpenType and TrueType fonts, and
     produces a ‘.pdf’ file by default.  There is also ‘dvilualatex’ to
     produce a ‘.dvi’ file.

‘xelatex’
     If LaTeX is invoked with the system command ‘xelatex’, the XeTeX
     engine is run (<https://tug.org/xetex>).  Like LuaTeX, XeTeX
     natively supports UTF-8 Unicode and TrueType and OpenType fonts,
     though the implementation is completely different, mainly using
     external libraries instead of internal code.  XeTeX produces a
     ‘.pdf’ file as output; it does not support DVI output.

     Internally, XeTeX creates an ‘.xdv’ file, a variant of DVI, and
     translates that to PDF using the (‘x’)‘dvipdfmx’ program, but this
     process is automatic.  The ‘.xdv’ file is only useful for
     debugging.

‘hilatex’
     If LaTeX is invoked via the system command ‘hilatex’, the HiTeX
     engine is run (<https://ctan.org/pkg/hitex>).  This program
     produces its own format, named HINT, designed especially for
     high-quality typesetting on mobile devices.

‘platex’
‘uplatex’
     These commands provide significant additional support for Japanese
     and other languages; the ‘u’ variant supports Unicode.  See
     <https://ctan.org/pkg/ptex> and <https://ctan.org/pkg/uptex>.

   As of 2019, there is a companion ‘-dev’ command and format for all of
the above, except ‘hitex’:

‘dvilualatex-dev’
‘latex-dev’
‘lualatex-dev’
‘pdflatex-dev’
‘platex-dev’
‘uplatex-dev’
‘xelatex-dev’
     These are candidates for an upcoming LaTeX release.  The main
     purpose is to find and address compatibility problems before an
     official release.

     These ‘-dev’ formats make it easy for anyone to help test documents
     and code: you can run, say, ‘pdflatex-dev’ instead of ‘pdflatex’,
     without changing anything else in your environment.  Indeed, it is
     easiest and most helpful to always run the ‘-dev’ versions instead
     of bothering to switch back and forth.  During quiet times after a
     release, the commands will be equivalent.

     These are not daily snapshots or untested development code.  They
     undergo the same extensive regression testing by the LaTeX team
     before being released.

     For more information, see "The LaTeX release workflow and the LaTeX
     ‘dev’ formats" by Frank Mittelbach, ‘TUGboat’ 40:2,
     <https://tug.org/TUGboat/tb40-2/tb125mitt-dev.pdf>.


File: latex2e.info,  Node: Input text,  Next: LaTeX command syntax,  Prev: TeX engines,  Up: Overview

2.4 Input text
==============

To a first approximation, most input characters in LaTeX print as
themselves.  But there are exceptions, as discussed in the following
sections.

* Menu:

* Input encodings::
* Ligatures::            Combined characters: ff fi fl ffi ffl " " - -- '! '?
* Special characters::   With special meaning: ‘\ { } % $ & _ ^ # ~’


File: latex2e.info,  Node: Input encodings,  Next: Ligatures,  Up: Input text

2.4.1 Input encodings
---------------------

The input to TeX (or any computer program) ultimately consists of a
sequence of bytes.  (Nowadays, a byte is almost universally an eight-bit
number, i.e., an integer between 0 and 255, inclusive.)  The input
encoding defines how to interpret that sequence of bytes, and thus how
LaTeX behaves.

   Today, by far the most common way to encode text is with “UTF-8”, a
so-called "Unicode Transformation Format" which specifies how to
transform a sequence of 8-bit bytes to Unicode code points, which are
defined independent of any particular representation.  The Unicode
encoding defines code points for virtually all characters used today in
written text.

   When TeX was created, Unicode and UTF-8 did not exist and the 7-bit
ASCII encoding was by far the most widely used.  So TeX does not require
Unicode for text input.  UTF-8 is a superset of ASCII, so a pure 7-bit
ASCII document is also UTF-8.

   Since 2018, the default input encoding for LaTeX is UTF-8.  Some
methods for handling documents written in some other encoding, such as
ISO-8859-1 (Latin 1), are explained in *note inputenc package::.

   You can easily find more about all these topics in any introductory
computer text or online.  For example, you might start at:
<https://en.wikipedia.org/wiki/Unicode>.


File: latex2e.info,  Node: Ligatures,  Next: Special characters,  Prev: Input encodings,  Up: Input text

2.4.2 Ligatures
---------------

A “ligature” combines two or more letters (more generally, characters)
into a single glyph.  For example, in Latin-based typography, the two
letters ‘f’ and ‘i’ are often combined into the glyph 'fi'.

   TeX supports ligatures automatically.  To continue the example, if
the input has the word ‘fine’, written as four separate ASCII
characters, TeX will output the word 'fine' (with the default fonts),
with three typeset glyphs.

   In traditional TeX, the available ligatures, if any, are defined by
the current font.  TeX also uses the ligature mechanism to produce a few
typographical characters which were not available in any computer
encoding when TeX was invented.  In all, in the original Computer Modern
fonts, the following input character sequences are defined to lead to
ligatures:

‘ff’
     ff (ff ligature, U+FB00)
‘fi’
     fi (fi ligature, U+FB01)
‘fl’
     fl (fl ligature, U+FB02)
‘ffi’
     ffi (ffi ligature, U+FB03)
‘ffl’
     ffl (ffl ligature, U+FB04)
‘``’
     " (left double quotation mark, U+201C)
‘''’
     " (right double quotation mark, U+201D)
‘--’
     - (en-dash, U+2013)
‘---’
     -- (em-dash, U+2014)
‘!`’
     !'  (inverted exclamation mark, U+00A1)
‘?`’
     ?'  (inverted question mark, U+00BF)

(For the f-ligatures above, the text in parentheses shows the individual
characters, so in the typeset output you can easily see the difference
between the ligature and the original character sequence.)

   Nowadays it's usually possible to directly input the punctuation
characters as Unicode characters, and LaTeX supports that (see previous
section).  But even today, it can still often be useful to use the ASCII
ligature input form; for example, the difference between an en-dash and
em-dash, as a single glyph, can be all but impossible to discern, but
the difference between two and three ASCII hyphen characters is clear.
Similarly with quotation marks, in some fonts.

   Thus, even the engines with native support for UTF-8, namely LuaTeX
and XeTeX, also support the ASCII ligature input sequences by default,
independent of the font used.  They also need to do so for
compatibility.

   By the way, the f-ligatures are also available in Unicode (the
"Alphabetic Presentation Forms" block starting at U+FB00), but it's
almost never desirable to use them as input characters, since in
principle it should be up to the typesetter and the current font whether
to use ligatures.  Also, in practice, using them will typically cause
searches to fail, that is, a search for the two characters ‘fi’ will not
be matched by the ligature 'fi' at U+FB01.


File: latex2e.info,  Node: Special characters,  Prev: Ligatures,  Up: Input text

2.4.3 Special characters: ‘\ { } % $ & _ ^ # ~’
-----------------------------------------------

Besides ligatures (see previous section), a few individual characters
have special meaning to LaTeX.  They are called “reserved characters” or
“special characters”.  Here they are:

‘\’
     Introduces a command name, as seen throughout this manual.

‘{’
‘}’
     Delimits a required argument to a command or a level of grouping,
     as seen throughout this manual.

‘%’
     Starts a comment: the ‘%’ and all remaining characters on the
     current line are ignored.

‘$’
     Starts and ends math mode (*note Math formulas::).

‘&’
     Separates cells in a table (*note tabular::).

‘_’
‘^’
     Introduce a subscript or superscript, respectively, in math (*note
     Subscripts & superscripts::); they produce an error outside math
     mode.  As a little-used special feature, two superscript characters
     in a row can introduce special notation for an arbitrary character.

‘#’
     Stands for arguments in a macro definition (*note \newcommand &
     \renewcommand::).

‘~’
     Produces a nonbreakable interword space (*note ~::).

   *Note Printing special characters::, for how to typeset these
characters when you need them literally.


File: latex2e.info,  Node: LaTeX command syntax,  Next: Environment syntax,  Prev: Input text,  Up: Overview

2.5 LaTeX command syntax
========================

In the LaTeX input file, a command name starts with a backslash
character, ‘\’.  The name itself then consists of either (a) a string of
letters or (b) a single non-letter.

   LaTeX commands names are case sensitive; for example, ‘\pagebreak’
differs from ‘\Pagebreak’ (the latter is not a standard command).  Most
command names 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, ‘{...}’.  Optional arguments are contained in
square brackets, ‘[...]’.  Generally, but not universally, if the
command accepts an optional argument, it comes first, before any
required arguments; optional arguments could come after required
arguments, or both before and after.

   Inside of an optional argument, to use the character close square
bracket (‘]’) hide it inside curly braces, as in ‘\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.

   LaTeX has the convention that some commands have a ‘*’ form that is
closely related to the form without a ‘*’, such as ‘\chapter’ and
‘\chapter*’.  The difference in behavior varies from command to command.

   This manual describes all accepted options and ‘*’-forms for the
commands it covers (barring unintentional omissions, a.k.a. bugs).

   As of the 2020-10-01 release of LaTeX, the ‘expl3’ and ‘xparse’
packages are part of the LaTeX2e format.  They provide a completely
different underlying programming language syntax.  We won't try to cover
that in this document; see the related package documentation and other
LaTeX manuals.


File: latex2e.info,  Node: Environment syntax,  Next: \DocumentMetadata,  Prev: LaTeX command syntax,  Up: Overview

2.6 Environment syntax
======================

Synopsis:

     \begin{ENVIRONMENT-NAME}
       ...
     \end{ENVIRONMENT-NAME}

   An “environment” is an area of LaTeX source, inside of which there is
a distinct behavior.  For instance, for poetry in LaTeX put the lines
between ‘\begin{verse}’ and ‘\end{verse}’.

     \begin{verse}
       There once was a man from Nantucket \\
       ...
     \end{verse}

   *Note Environments::, for a list of environments.  Particularly
notable is that every LaTeX document must have a ‘document’ environment,
a ‘\begin{document} ... \end{document}’ pair.

   The ENVIRONMENT-NAME at the beginning must exactly match that at the
end.  This includes the case where ENVIRONMENT-NAME ends in a
star (‘*’); both the ‘\begin’ and ‘\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).

     \begin{tabular}[t]{r|l}
       ... ROWS-OF-TABLE ...
     \end{tabular}


File: latex2e.info,  Node: \DocumentMetadata,  Next: CTAN,  Prev: Environment syntax,  Up: Overview

2.7 ‘\DocumentMetadata’: Producing tagged PDF output
====================================================

The ‘\DocumentMetadata’ command was added to LaTeX in 2022.  It enables
so-called "tagging" of the PDF output, aiding accessibility of the PDF.
It is supported best with LuaLaTeX; pdfLaTeX and XeLaTeX are supported
as well as possible (*note TeX engines::).

   It is unlike nearly any other command in LaTeX in that it must occur
before the ‘\documentclass’ command that starts a LaTeX document proper
(*note \documentclass::).  Therefore it must be called with
‘\RequirePackage’ rather than ‘\usepackage’ (*note \RequirePackage::).

   This support is still in development, so we will not try to list all
the possible settings.  Please see the ‘documentmetadata-support-doc’
document, part of the ‘latex-lab’ package
(<https://ctan.org/pkg/latex-lab>).  Here is a simple example which
enables most tagging currently implemented:

     \DocumentMetadata{testphase={phase-III,firstaid}}
     \documentclass{article}
     ...

   As you can see from the key name ‘testphase’, this is all still in an
experimental phase.  The LaTeX developers strongly encourage users to
give it a try and report problems, so it can be improved.


File: latex2e.info,  Node: CTAN,  Prev: \DocumentMetadata,  Up: Overview

2.8 CTAN: The Comprehensive TeX Archive Network
===============================================

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 <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 its massive holdings, the ‘ctan.org’ web site offers
features such as search by name or by functionality.

   CTAN is not a single host, but instead is a set of hosts, one of
which is the so-called "master".  The master host actively manages the
material, for instance, by accepting uploads of new or updated packages.
For many years, it has been 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 master 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 master site.
The list of mirrors is at <https://ctan.org/mirrors>.


File: latex2e.info,  Node: Document classes,  Next: Fonts,  Prev: Overview,  Up: Top

3 Document classes
******************

The document's overall class is defined with the ‘\documentclass’
command, which is normally the first command in a LaTeX source file.

     \documentclass[OPTIONS]{CLASS}

   The following document CLASS names are built into LaTeX.  Many other
document classes are available as separate packages (*note Overview::).

‘article’
     For a journal article, a presentation, and miscellaneous general
     use.

‘book’
     Full-length books, including chapters and possibly including front
     matter, such as a preface, and back matter, such as an appendix
     (*note Front/back matter::).

‘letter’
     Mail, optionally including mailing labels (*note Letters::).

‘report’
     For documents of length between an ‘article’ and a ‘book’, such as
     technical reports or theses, which may contain several chapters.

‘slides’
     For slide presentations--rarely used nowadays.  The ‘beamer’
     package is perhaps the most prevalent replacement
     (<https://ctan.org/pkg/beamer>).  *Note beamer template::, for a
     small template for a beamer document.

   Standard OPTIONS are described in the next section.

* Menu:

* Document class options::           Global options.
* \usepackage::                      Bring in additional packages.
* Class and package creation::       Writing new classes and packages.


File: latex2e.info,  Node: Document class options,  Next: \usepackage,  Up: Document classes

3.1 Document class options
==========================

You can specify “global options” or “class options” to the
‘\documentclass’ command by enclosing them in square brackets.  To
specify more than one OPTION, separate them with a comma.

     \documentclass[OPTION1,OPTION2,...]{CLASS}

   LaTeX automatically passes options specified for ‘\documentclass’ on
to any other loaded classes that can handle them.

   Here is the list of the standard class options.

   All of the standard classes except ‘slides’ accept the following
options for selecting the typeface size; the default is ‘10pt’:

     10pt  11pt  12pt

   All of the standard classes accept these options for selecting the
paper size (dimensions are listed height by width):

‘a4paper’
     210 by 297mm (about 8.25 by 11.75 inches)

‘a5paper’
     148 by 210mm (about 5.8 by 8.3 inches)

‘b5paper’
     176 by 250mm (about 6.9 by 9.8 inches)

‘executivepaper’
     7.25 by 10.5 inches

‘legalpaper’
     8.5 by 14 inches

‘letterpaper’
     8.5 by 11 inches (the default)

   When using one of the engines pdfLaTeX, LuaLaTeX, or XeLaTeX (*note
TeX engines::), options other than ‘letterpaper’ set the print area but
you must also set the physical paper size.  Usually, the ‘geometry’
package is the best way to do that; it provides flexible ways of setting
the print area and physical page size.  Otherwise, setting the paper
size is engine-dependent.  For example, with pdfLaTeX, you could include
‘\pdfpagewidth=\paperwidth’ and ‘\pdfpageheight=\paperheight’ in the
preamble.

   Miscellaneous other options:

‘draft’
‘final’
     Mark (‘draft’) or do not mark (‘final’) overfull boxes with a black
     box in the margin; default is ‘final’.

‘fleqn’
     Put displayed formulas flush left; default is centered.

‘landscape’
     Selects landscape format; default is portrait.

‘leqno’
     Put equation numbers on the left side of equations; default is the
     right side.

‘openbib’
     Use "open" bibliography format.

‘titlepage’
‘notitlepage’
     Specifies whether there is a separate page for the title
     information and for the abstract also, if there is one.  The
     default for the ‘report’ class is ‘titlepage’, for the other
     classes it is ‘notitlepage’.

   The following options are not available with the ‘slides’ class.

‘onecolumn’
‘twocolumn’
     Typeset in one or two columns; default is ‘onecolumn’.

‘oneside’
‘twoside’
     Selects one- or two-sided layout; default is ‘oneside’, except that
     in the ‘book’ class the default is ‘twoside’.

     For one-sided printing, the text is centered on the page.  For
     two-sided printing, the ‘\evensidemargin’ (‘\oddsidemargin’)
     parameter determines the distance on even (odd) numbered pages
     between the left side of the page and the text's left margin, with
     ‘\oddsidemargin’ being 40% of the difference between ‘\paperwidth’
     and ‘\textwidth’, and ‘\evensidemargin’ is the remainder.

‘openright’
‘openany’
     Determines if a chapter should start on a right-hand page; default
     is ‘openright’ for ‘book’, and ‘openany’ for ‘report’.

   The ‘slides’ class offers the option ‘clock’ for printing the time at
the bottom of each note.


File: latex2e.info,  Node: \usepackage,  Next: Class and package creation,  Prev: Document class options,  Up: Document classes

3.2 ‘\usepackage’: Additional packages
======================================

To load a package PKG, with the package options given in the
comma-separated list OPTIONS:

     \usepackage[OPTIONS]{PKG}[MINDATE]

   To specify more than one package you can separate them with a comma,
as in ‘\usepackage{PKG1,PKG2,...}’, or use multiple ‘\usepackage’
commands.

   If the MINDATE optional argument is given, LaTeX gives a warning if
the loaded package has an earlier date, i.e., is too old.  The MINDATE
argument must be in the form ‘YYYY/MM/DD’.  More info on this:
<https://tex.stackexchange.com/questions/47743>.

   ‘\usepackage’ must be used in the document preamble, between the
‘\documentclass’ declaration and the ‘\begin{document}’.  Occasionally
it is necessary to load packages before the ‘\documentclass’; see
‘\RequirePackage’ for that (*note \RequirePackage::).

   Any options given in the global ‘\documentclass’ command that are
unknown to the selected document class are passed on to the packages
loaded with ‘\usepackage’.


File: latex2e.info,  Node: Class and package creation,  Prev: \usepackage,  Up: Document classes

3.3 Class and package creation
==============================

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 ‘smcmemo.cls’
and begin your documents with ‘\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 be ‘Memo from the SMC
Math Department’ is for a class.

   Inside of a class or package definition you can use the at-sign ‘@’
as a character in command names without having to surround the code
containing that command with ‘\makeatletter’ and ‘\makeatother’ (*note
\makeatletter & \makeatother::).  This allows you to create commands
that users will not accidentally redefine.

   It is also highly desirable to prefix class- or package-specific
commands with your package name or similar string, to prevent your
definitions from clashing with those from other packages.  For instance,
the class ‘smcmemo’ might have commands ‘\smc@tolist’, ‘\smc@fromlist’,
etc.

* Menu:

* Class and package structure::     Layout of the file.


File: latex2e.info,  Node: Class and package structure,  Up: Class and package creation

3.3.1 Class and package structure
---------------------------------

A class file or package file typically has four parts.

  1. In the “identification part”, the file says that it is a LaTeX
     package or class and describes itself, using the ‘\NeedsTeXFormat’
     and ‘\ProvidesClass’ or ‘\ProvidesPackage’ commands.

  2. The “preliminary declarations part” declares some commands and can
     also load other files.  Usually these commands will be those needed
     for the code used in the next part.  For example, an ‘smcmemo’
     class might be called with an option to read in a file with a list
     of people for the to-head, as ‘\documentclass[mathto]{smcmemo}’,
     and therefore needs to define a command
     ‘\newcommand{\setto}[1]{\def\@tolist{#1}}’ used in that file.

  3. In the “handle options part” the class or package declares and
     processes its options.  Class options allow a user to start their
     document as ‘\documentclass[OPTION LIST]{CLASS NAME}’, to modify
     the behavior of the class.  An example is when you declare
     ‘\documentclass[11pt]{article}’ to set the default document font
     size.

  4. Finally, in the “more declarations part” the class or package
     usually does most of its work: declaring new variables, commands
     and fonts, and loading other files.

   Here is a starting class file, which should be saved as ‘stub.cls’
where LaTeX can find it, for example in the same directory as the ‘.tex’
file.

     \NeedsTeXFormat{LaTeX2e}
     \ProvidesClass{stub}[2017/07/06 stub to start building classes from]
     \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
     \ProcessOptions\relax
     \LoadClass{article}

It identifies itself, handles the class options via the default of
passing them all to the ‘article’ class, and then loads the ‘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 <https://ctan.org/pkg/clsguide> (much of the description
here derives from this document), or the tutorial at
<https://tug.org/TUGboat/tb26-3/tb84heff.pdf>.

   *Note Class and package commands::, for some of the commands
specifically intended for class and package writers.


File: latex2e.info,  Node: Fonts,  Next: Layout,  Prev: Document classes,  Up: Top

4 Fonts
*******

LaTeX comes with powerful font capacities.  For one thing, its New Font
Selection Scheme allows you to work easily with the font families in
your document (for instance, see *note Font styles::).  And, LaTeX
documents can use most fonts that are available today, including
versions of Times Roman, Helvetica, Courier, etc.  (Note, though, that
many fonts do not have support for mathematics.)

   The first typeface in the TeX world was the Computer Modern family,
developed by Donald Knuth.  It is the default for LaTeX documents and is
still the most widely used.  But changing to another font often only
involves a few commands.  For instance, putting the following in your
preamble gives you a Palatino-like font, which is handsome and more
readable online than many other fonts, while still allowing you to
typeset mathematics.  (This example is from Michael Sharpe,
<https://math.ucsd.edu/~msharpe/RcntFnts.pdf>.)

     \usepackage[osf]{newpxtext} % osf for text, not math
     \usepackage{cabin} % sans serif
     \usepackage[varqu,varl]{inconsolata} % sans serif typewriter
     \usepackage[bigdelims,vvarbb]{newpxmath} % bb from STIX
     \usepackage[cal=boondoxo]{mathalfa} % mathcal

In addition, the ‘xelatex’ or ‘lualatex’ engines allow you to use any
fonts on your system that are in OpenType or TrueType format (*note TeX
engines::).

   The LaTeX Font Catalogue (<https://tug.org/FontCatalogue>) shows font
sample graphics and copy-and-pasteable source to use many fonts,
including many with support for mathematics.  It aims to cover all Latin
alphabet free fonts available for easy use with LaTeX.

   More information is also available from the TeX Users Group, at
<https://www.tug.org/fonts/>.

* Menu:

* fontenc package::             Encoding of the font.
* Font styles::                 Select roman, italics, etc.
* Font sizes::                  Select point size.
* Low-level font commands::     Select encoding, family, series, shape.


File: latex2e.info,  Node: fontenc package,  Next: Font styles,  Up: Fonts

4.1 ‘fontenc’ package
=====================

Synopsis:

     \usepackage[FONT_ENCODING]{fontenc}

   or

     \usepackage[FONT_ENCODING1, FONT_ENCODING2, ...]{fontenc}

   Specify the font encodings.  A font encoding is a mapping of the
character codes to the font glyphs that are used to typeset your output.

   This package only applies if you use the ‘pdflatex’ engine (*note TeX
engines::).  If you use the ‘xelatex’ or ‘lualatex’ engine then instead
use the ‘fontspec’ package.

   TeX's original font family, Computer Modern, has a limited character
set.  For instance, to make common accented characters you must use
‘\accent’ (*note \accent::) but this disables hyphenation.  TeX users
have agreed on a number of standards to access the larger sets of
characters provided by modern fonts.  If you are using ‘pdflatex’ then
put this in the preamble

     \usepackage[T1]{fontenc}

gives you support for the most widespread European languages, including
French, German, Italian, Polish, and others.  In particular, if you have
words with accented letters then LaTeX will hyphenate them and your
output can be copied and pasted.  (The optional second line allows you
to directly enter accented characters into your source file.)

   If you are using an encoding such as ‘T1’ and the characters appear
blurry or do not magnify well then your fonts may be bitmapped,
sometimes called raster or Type 3.  You want vector fonts.  Use a
package such as ‘lmodern’ or ‘cm-super’ to get a font that extends
LaTeX's default using vector fonts.

   For each FONT_ENCODING given as an option but not already declared,
this package loads the encoding definition files, named
‘FONT_ENCODINGenc.def’.  It also sets ‘\encodingdefault’ to be the last
encoding in the option list.

   These are the common values for FONT_ENCODING:

‘OT1’
     The original 7-bit encoding for TeX.  Limited to mostly English
     characters.

‘OMS, OML’
     Math symbols and math letters encoding.

‘T1’
     TeX text extended.  Sometimes called the Cork encoding for the
     users group meeting where it was developed (1990).  Gives access to
     most European accented characters.  The most common option for this
     package.

‘TS1’
     Text Companion encoding.

LaTeX's default is to load ‘OML’, ‘T1’, ‘OT1’, and then ‘OMS’, and set
the default to ‘OT1’.

   Even if you do not use accented letters, you may need to specify a
font encoding if your font requires it.

   If you use ‘T1’ encoded fonts other than the default Computer Modern
family then you may need to load the package that selects your fonts
before loading ‘fontenc’, to prevent the system from loading any
‘T1’ encoded fonts from the default.

   The LaTeX team reserves encoding names starting with: ‘T’ for the
standard text encodings with 256 characters, ‘TS’ for symbols that
extend the corresponding T encodings, ‘X’ for test encodings, ‘M’ for
standard math encodings with 256 characters, ‘A’ for special
applications, ‘OT’ for standard text encodings with 128 characters, and
‘OM’ for standard math encodings with 128 characters (‘O’ stands for
‘obsolete’).

   This package provides a number of commands, detailed below.  Many of
them are encoding-specific, so if you have defined a command that works
for one encoding but the current encoding is different then the command
is not in effect.

* Menu:

* \DeclareFontEncoding::          Define an encoding.
* \DeclareTextAccent::            Define an accent in the encoding.
* \DeclareTextAccentDefault::     Fallback for using an accent in the encoding.
* \DeclareTextCommand & \ProvideTextCommand::  New encoding-specific command.
* \DeclareTextCommandDefault & \ProvideTextCommandDefault::  Fallback for encoding-specific commands.
* \DeclareTextComposite::   Directly access an accented glyph, in the encoding.
* \DeclareTextCompositeCommand::    Run code in slot, in the encoding.
* \DeclareTextSymbol::              Define a symbol in the encoding.
* \DeclareTextSymbolDefault::       Fallback for a symbol in the encoding.
* \LastDeclaredEncoding::           Save most recently declared encoding.
* \UseTextSymbol & \UseTextAccent:: Temporarily switch to another encoding.


File: latex2e.info,  Node: \DeclareFontEncoding,  Next: \DeclareTextAccent,  Up: fontenc package

4.1.1 ‘\DeclareFontEncoding’
----------------------------

Synopsis:

     \DeclareFontEncoding{ENCODING}{TEXT-SETTINGS}{MATH-SETTINGS}

   Declare the font encoding ENCODING.  It also saves the value of
ENCODING in ‘\LastDeclaredEncoding’ (*note \LastDeclaredEncoding::).

   The file ‘t1enc.def’ contains this line (followed by many others).

     \DeclareFontEncoding{T1}{}{}

   The TEXT-SETTINGS are the commands that LaTeX will run every time it
switches from one encoding to another with the ‘\selectfont’ and
‘\fontencoding’ commands.  The MATH-SETTINGS are the commands that LaTeX
will use whenever the font is accessed as a math alphabet.

   LaTeX ignores any space characters inside TEXT-SETTINGS and
MATH-SETTINGS, to prevent unintended spaces in the output.

   If you invent an encoding you should pick a two or three letter name
starting with ‘L’ for ‘local’, or ‘E’ for ‘experimental’.

   Note that output encoding files may be read several times by LaTeX so
using, e.g., ‘\newcommand’ may cause an error.  In addition, such files
should contain ‘\ProvidesFile’ line (*note Class and package
commands::).

   Note also that you should use the ‘\...Default’ commands only in a
package, not in the encoding definition files, since those files should
only contain declarations specific to that encoding.


File: latex2e.info,  Node: \DeclareTextAccent,  Next: \DeclareTextAccentDefault,  Prev: \DeclareFontEncoding,  Up: fontenc package

4.1.2 ‘\DeclareTextAccent’
--------------------------

Synopsis:

     \DeclareTextAccent{CMD}{ENCODING}{SLOT}

   Define an accent, to be put on top of other glyphs, in the encoding
ENCODING at the location SLOT.

   A “slot” is the number identifying a glyph within a font.

   This line from ‘t1enc.def’ declares that to make a circumflex accent
as in ‘\^A’, the system will put the accent in slot 2 over the ‘A’
character, which is represented in ASCII as 65.  (This holds unless
there is a relevant ‘DeclareTextComposite’ or
‘\DeclareTextCompositeCommand’ declaration; *note
\DeclareTextComposite::.)

     \DeclareTextAccent{\^}{T1}{2}

   If CMD has already been defined then ‘\DeclareTextAccent’ does not
give an error but it does log the redefinition in the transcript file.


File: latex2e.info,  Node: \DeclareTextAccentDefault,  Next: \DeclareTextCommand & \ProvideTextCommand,  Prev: \DeclareTextAccent,  Up: fontenc package

4.1.3 ‘\DeclareTextAccentDefault’
---------------------------------

Synopsis:

     \DeclareTextAccentDefault{\CMD}{ENCODING}

   If there is an encoding-specific accent command \CMD but there is no
associated ‘\DeclareTextAccent’ for that encoding then this command will
pick up the slack, by saying to use it as described for ENCODING.

   For example, to make the encoding ‘OT1’ be the default encoding for
the accent ‘\"’, declare this.

     \DeclareTextAccentDefault{\"}{OT1}

If you issue a ‘\"’ when the current encoding does not have a definition
for that accent then LaTeX will use the definition from ‘OT1’

   That is, this command is equivalent to this call (*note
\UseTextSymbol & \UseTextAccent::).

     \DeclareTextCommandDefault[1]{\CMD}
        {\UseTextAccent{ENCODING}{\CMD}{#1}}

   Note that ‘\DeclareTextAccentDefault’ works for any one-argument
‘fontenc’ command, not just the accent command.


File: latex2e.info,  Node: \DeclareTextCommand & \ProvideTextCommand,  Next: \DeclareTextCommandDefault & \ProvideTextCommandDefault,  Prev: \DeclareTextAccentDefault,  Up: fontenc package

4.1.4 ‘\DeclareTextCommand’ & ‘\ProvideTextCommand’
---------------------------------------------------

Synopsis, one of:

     \DeclareTextCommand{\CMD}{ENCODING}{DEFN}
     \DeclareTextCommand{\CMD}{ENCODING}[NARGS]{DEFN}
     \DeclareTextCommand{\CMD}{ENCODING}[NARGS][OPTARGDEFAULT]{DEFN}

   or one of:

     \ProvideTextCommand{\CMD}{ENCODING}{DEFN}
     \ProvideTextCommand{\CMD}{ENCODING}[NARGS]{DEFN}
     \ProvideTextCommand{\CMD}{ENCODING}[NARGS][OPTARGDEFAULT]{DEFN}

   Define the command ‘\CMD’, which will be specific to one encoding.
The command name CMD must be preceded by a backslash, ‘\’.  These
commands can only appear in the preamble.  Redefining \CMD does not
cause an error.  The defined command will be robust even if the code in
DEFN is fragile (*note \protect::).

   For example, the file ‘t1enc.def’ contains this line.

     \DeclareTextCommand{\textperthousand}{T1}{\%\char 24 }

   With that, you can express parts per thousand.

     \usepackage[T1]{fontenc}  % in preamble
       ...
     Legal limit is \( 0.8 \)\textperthousand.

If you change the font encoding to ‘OT1’ then you get an error like
‘LaTeX Error: Command \textperthousand unavailable in encoding OT1’.

   The ‘\ProvideTextCommand’ variant does the same, except that it does
nothing if ‘\CMD’ is already defined.  The ‘\DeclareTextSymbol’ command
is faster than this one for simple slot-to-glyph association (*note
\DeclareTextSymbol::)

   The optional NARGS and OPTARGDEFAULT arguments play the same role
here as in ‘\newcommand’ (*note \newcommand & \renewcommand::).
Briefly, NARGS is an integer from 0 to 9 specifying the number of
arguments that the defined command ‘\CMD’ takes.  This number includes
any optional argument.  Omitting this argument is the same as specifying
0, meaning that ‘\CMD’ will have no arguments.  And, if OPTARGDEFAULT is
present then the first argument of ‘\CMD’ is optional, with default
value OPTARGDEFAULT (which may be the empty string).  If OPTARGDEFAULT
is not present then ‘\CMD’ does not take an optional argument.


File: latex2e.info,  Node: \DeclareTextCommandDefault & \ProvideTextCommandDefault,  Next: \DeclareTextComposite,  Prev: \DeclareTextCommand & \ProvideTextCommand,  Up: fontenc package

4.1.5 ‘\DeclareTextCommandDefault’ & ‘\ProvideTextCommandDefault ’
------------------------------------------------------------------

Synopsis:

     \DeclareTextCommandDefault{\CMD}{DEFN}

   or:

     \ProvideTextCommandDefault{\CMD}{DEFN}

   Give a default definition for ‘\CMD’, for when that command is not
defined in the encoding currently in force.  This default should only
use encodings known to be available.

   This makes ‘\copyright’ available.

     \DeclareTextCommandDefault{\copyright}{\textcircled{c}}

It uses only an encoding (OMS) that is always available.

   The ‘\DeclareTextCommandDefault’ should not occur in the encoding
definition files since those files should declare only commands for use
when you select that encoding.  It should instead be in a package.

   As with the related non-default commands, the
‘\ProvideTextCommandDefault’ has exactly the same behavior as
‘\DeclareTextCommandDefault’ except that it does nothing if ‘\CMD’ is
already defined (*note \DeclareTextCommand & \ProvideTextCommand::).
So, packages can use it to provide fallbacks that other packages can
improve upon.


File: latex2e.info,  Node: \DeclareTextComposite,  Next: \DeclareTextCompositeCommand,  Prev: \DeclareTextCommandDefault & \ProvideTextCommandDefault,  Up: fontenc package

4.1.6 ‘\DeclareTextComposite’
-----------------------------

Synopsis:

     \DeclareTextComposite{\CMD}{ENCODING}{SIMPLE_OBJECT}{SLOT}

   Access an accented glyph directly, that is, without having to put an
accent over a separate character.

   This line from ‘t1enc.def’ means that ‘\^o’ will cause LaTeX to
typeset lowercase ‘o’ by taking the character directly from slot 224 in
the font.

     \DeclareTextComposite{\^}{T1}{o}{244}

   *Note fontenc package::, for a list of common encodings.  The
SIMPLE_OBJECT should be a single character or a single command.  The
SLOT argument is usually a positive integer represented in decimal
(although octal or hexadecimal are possible).  Normally \CMD has already
been declared for this encoding, either with ‘\DeclareTextAccent’ or
with a one-argument ‘\DeclareTextCommand’.  In ‘t1enc.def’, the above
line follows the ‘\DeclareTextAccent{\^}{T1}{2}’ command.


File: latex2e.info,  Node: \DeclareTextCompositeCommand,  Next: \DeclareTextSymbol,  Prev: \DeclareTextComposite,  Up: fontenc package

4.1.7 ‘\DeclareTextCompositeCommand’
------------------------------------

Synopsis:

     \DeclareTextCompositeCommand{\CMD}{ENCODING}{ARG}{CODE}

   A more general version of ‘\DeclareTextComposite’ that runs arbitrary
code with ‘\CMD’.

   This allows accents on ‘i’ to act like accents on dotless i, ‘\i’.

     \DeclareTextCompositeCommand{\'}{OT1}{i}{\'\i}

   *Note fontenc package::, for a list of common encodings.  Normally
‘\CMD’ will have already been declared with ‘\DeclareTextAccent’ or as a
one argument ‘\DeclareTextCommand’.


File: latex2e.info,  Node: \DeclareTextSymbol,  Next: \DeclareTextSymbolDefault,  Prev: \DeclareTextCompositeCommand,  Up: fontenc package

4.1.8 ‘\DeclareTextSymbol’
--------------------------

Synopsis:

     \DeclareTextSymbol{\CMD}{ENCODING}{SLOT}

   Define a symbol in the encoding ENCODING at the location SLOT.
Symbols defined in this way are for use in text, not mathematics.

   For example, this line from ‘t1enc.def’ declares the number of the
glyph to use for «, the left guillemet.

     \DeclareTextSymbol{\guillemetleft}{T1}{19}

The command ‘\DeclareTextCommand{\guillemetleft}{T1}{\char 19}’ has the
same effect but is slower (*note \DeclareTextCommand &
\ProvideTextCommand::).

   *Note fontenc package::, for a list of common encodings.  The SLOT
can be specified in decimal, or octal (as in ‘'023’), or hexadecimal (as
in ‘"13’), although decimal has the advantage that single quote or
double quote could be redefined by another package.

   If ‘\CMD’ has already been defined then ‘\DeclareTextSymbol’ does not
give an error but it does log the redefinition in the transcript file.


File: latex2e.info,  Node: \DeclareTextSymbolDefault,  Next: \LastDeclaredEncoding,  Prev: \DeclareTextSymbol,  Up: fontenc package

4.1.9 ‘\DeclareTextSymbolDefault’
---------------------------------

Synopsis:

     \DeclareTextSymbolDefault{\CMD}{ENCODING}

   If there is an encoding-specific symbol command ‘\CMD’ but there is
no associated ‘\DeclareTextSymbol’ for that encoding, then this command
will pick up the slack, by saying to get the symbol as described for
ENCODING.

   For example, to declare that if the current encoding has no meaning
for ‘\textdollar’ then use the one from ‘OT1’, declare this.

     \DeclareTextSymbolDefault{\textdollar}{OT1}

   That is, this command is equivalent to this call (*note
\UseTextSymbol & \UseTextAccent::).

     \DeclareTextCommandDefault{\CMD}
        {\UseTextSymbol{ENCODING}{\CMD}}

   Note that ‘\DeclareTextSymbolDefault’ can be used to define a default
for any zero-argument ‘fontenc’ command.


File: latex2e.info,  Node: \LastDeclaredEncoding,  Next: \UseTextSymbol & \UseTextAccent,  Prev: \DeclareTextSymbolDefault,  Up: fontenc package

4.1.10 ‘\LastDeclaredEncoding’
------------------------------

Synopsis:

     \LastDeclaredEncoding

   Get the name of the most recently declared encoding.  The
‘\DeclareFontEncoding’ command stores the name so that it can be
retrieved with this command (*note \DeclareFontEncoding::).

   This relies on ‘\LastDeclaredEncoding’ rather than give the name of
the encoding explicitly.

     \DeclareFontEncoding{JH1}{}{}
     \DeclareTextAccent{\'}{\LastDeclaredEncoding}{0}


File: latex2e.info,  Node: \UseTextSymbol & \UseTextAccent,  Prev: \LastDeclaredEncoding,  Up: fontenc package

4.1.11 ‘\UseTextSymbol’ & ‘\UseTextAccent’
------------------------------------------

Synopsis:

     \UseTextSymbol{ENCODING}{\CMD}

   or:

     \UseTextAccent{ENCODING}{\CMD}{TEXT}

   Use a symbol or accent not from the current encoding.

   In general, to use a ‘fontenc’ command in an encoding where it is not
defined, and if the command has no arguments, then you can use it like
this:

     \UseTextSymbol{OT1}{\ss}

which is equivalent to this (note the outer braces form a group, so
LaTeX reverts back to the prior encoding after the ‘\ss’):

     {\fontencoding{OT1}\selectfont\ss}

   Similarly, to use a ‘fontenc’ command in an encoding where it is not
defined, and if the command has one argument, you can use it like this:

     \UseTextAccent{OT1}{\'}{a}

which is equivalent to this (again note the outer braces forming a
group):

     {fontencoding{OT1}\selectfont\'{\fontencoding{ENC_IN_USE}\selectfont a}}

Here, ENC_IN_USE is the encoding in force before this sequence of
commands, so that ‘a’ is typeset using the current encoding and only the
accent is taken from ‘OT1’.


File: latex2e.info,  Node: Font styles,  Next: Font sizes,  Prev: fontenc package,  Up: Fonts

4.2 Font styles
===============

The following type style commands are supported by LaTeX.

   In the table below the listed commands, the ‘\text...’ commands, are
used with an argument as in ‘\textit{TEXT}’.  This is the preferred
form.  But shown after it in parenthesis is the corresponding
“declaration form”, which is often useful.  This form takes no
arguments, as in ‘{\itshape 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
‘\begin{itshape}...\end{itshape}’, which we'll describe further at the
end of the section.

   These commands, in any of the three forms, are cumulative; for
instance you can get bold sans serif by saying either of
‘\sffamily\bfseries’ or ‘\bfseries\sffamily’.

   One advantage of these commands is that they automatically insert
italic corrections if needed (*note \/::).  Specifically, they insert
the italic correction unless the following character is in the list
‘\nocorrlist’, which by default consists of period and comma.  To
suppress the automatic insertion of italic correction, use ‘\nocorr’ at
the start or end of the command argument, such as ‘\textit{\nocorr
text}’ or ‘\textsc{text \nocorr}’.

‘\textrm (\rmfamily)’
     Roman.

‘\textit (\itshape)’
     Italics.

‘\textmd (\mdseries)’
     Medium weight (default).

‘\textbf (\bfseries)’
     Boldface.

‘\textup (\upshape)’
     Upright (default).

‘\textsl (\slshape)’
     Slanted.

‘\textsf (\sffamily)’
     Sans serif.

‘\textsc (\scshape)’
     Small caps.

‘\texttt (\ttfamily)’
     Typewriter.

‘\textnormal (\normalfont)’
     Main document font.

   Although it also changes fonts, the ‘\emph{TEXT}’ command is
semantic, for TEXT to be emphasized, and should not be used as a
substitute for ‘\textit’.  For example, ‘\emph{START TEXT \emph{MIDDLE
TEXT} END TEXT}’ will result in the START TEXT and END TEXT in italics,
but MIDDLE TEXT will be in roman.

   LaTeX also provides the following commands, which unconditionally
switch to the given style, that is, are _not_ cumulative.  They are used
as declarations: ‘{\CMD...}’ instead of ‘\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 what is
needed.)

‘\bf’
     Switch to bold face.

‘\cal’
     Switch to calligraphic letters for math.

‘\it’
     Italics.

‘\rm’
     Roman.

‘\sc’
     Small caps.

‘\sf’
     Sans serif.

‘\sl’
     Slanted (oblique).

‘\tt’
     Typewriter (monospace, fixed-width).

   The ‘\em’ command is the unconditional version of ‘\emph’.

   The following commands are for use in math mode.  They are not
cumulative, so ‘\mathbf{\mathit{SYMBOL}}’ does not create a boldface and
italic SYMBOL; instead, it will just be in italics.  This is because
typically math symbols need consistent typographic treatment, regardless
of the surrounding environment.

‘\mathrm’
     Roman, for use in math mode.

‘\mathbf’
     Boldface, for use in math mode.

‘\mathsf’
     Sans serif, for use in math mode.

‘\mathtt’
     Typewriter, for use in math mode.

‘\mathit’
‘(\mit)’
     Italics, for use in math mode.

‘\mathnormal’
     For use in math mode, e.g., inside another type style declaration.

‘\mathcal’
     Calligraphic letters, for use in math mode.

   In addition, the command ‘\mathversion{bold}’ can be used for
switching to bold letters and symbols in formulas.
‘\mathversion{normal}’ restores the default.

   Finally, the command ‘\oldstylenums{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 ‘\textbf’ (but not other styles; there are no
italic old-style numerals in Computer Modern).  Many other fonts have
old-style numerals also; sometimes package options are provided to make
them the default.  FAQ entry: <https://www.texfaq.org/FAQ-osf>.


File: latex2e.info,  Node: Font sizes,  Next: Low-level font commands,  Prev: Font styles,  Up: Fonts

4.3 Font sizes
==============

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 ‘10pt’, ‘11pt’, and ‘12pt’ document size options,
respectively (*note Document class options::).

Command                     ‘10pt’    ‘11pt’    ‘12pt’
--------------------------------------------------------
‘\tiny’                     5         6         6
‘\scriptsize’               7         8         8
‘\footnotesize’             8         9         10
‘\small’                    9         10        10.95
‘\normalsize’ (default)     10        10.95     12
‘\large’                    12        12        14.4
‘\Large’                    14.4      14.4      17.28
‘\LARGE’                    17.28     17.28     20.74
‘\huge’                     20.74     20.74     24.88
‘\Huge’                     24.88     24.88     24.88

   The commands are listed here in declaration (not environment) form,
since that is how they are typically used.  For example.

     \begin{quotation} \small
       The Tao that can be named is not the eternal Tao.
     \end{quotation}

Here, the scope of the ‘\small’ lasts until the end of the ‘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 curly braces
‘{\small This text is typeset in the small font.}’.

   Trying to use these commands in math, as with ‘$\small mv^2/2$’,
results in ‘LaTeX Font Warning: Command \small invalid in math mode’,
and the font size doesn't change.  To work with a too-large formula,
often the best option is to use the ‘displaymath’ environment (*note
Math formulas::), or one of the environments from the ‘amsmath’ package.
For inline mathematics, such as in a table of formulas, an alternative
is something like ‘{\small $mv^2/2$}’.  (Sometimes ‘\scriptsize’ and
‘\scriptstyle’ are confused.  Both change the font size, but the latter
also changes a number of other aspects of how mathematics is typeset.
*Note Math styles::.)

   An “environment form” of each of these commands is also defined; for
instance, ‘\begin{tiny}...\end{tiny}’.  However, in practice this form
can easily lead to unwanted spaces at the beginning and/or end of the
environment without careful consideration, so it's generally less
error-prone to stick to the declaration form.

   (Aside: Technically, due to the way LaTeX defines ‘\begin’ and
‘\end’, nearly every command that does not take an argument technically
has an environment form.  But in almost all cases, it would only cause
confusion to use it.  The reason for mentioning the environment form of
the font size declarations specifically is that this particular use is
not rare.)


File: latex2e.info,  Node: Low-level font commands,  Prev: Font sizes,  Up: Fonts

4.4 Low-level font commands
===========================

These commands are primarily intended for writers of macros and
packages.  The commands listed here are only a subset of the available
ones.

‘\fontencoding{ENCODING}’
     Select the font encoding, the encoding of the output font.  There
     are a large number of valid encodings.  The most common are ‘OT1’,
     Knuth's original encoding for Computer Modern (the default), and
     ‘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
     <https://ctan.org/pkg/encguide>.

‘\fontfamily{FAMILY}’
     Select the font family.  The web page
     <https://tug.org/FontCatalogue/> provides one way to browse through
     many of the fonts easily used with LaTeX.  Here are examples of
     some common families.

     ‘pag’  Avant Garde
     ‘fvs’  Bitstream Vera Sans
     ‘pbk’  Bookman
     ‘bch’  Charter
     ‘ccr’  Computer Concrete
     ‘cmr’  Computer Modern
     ‘cmss’ Computer Modern Sans Serif
     ‘cmtt’ Computer Modern Typewriter
     ‘pcr’  Courier
     ‘phv’  Helvetica
     ‘fi4’  Inconsolata
     ‘lmr’  Latin Modern
     ‘lmss’ Latin Modern Sans
     ‘lmtt’ Latin Modern Typewriter
     ‘pnc’  New Century Schoolbook
     ‘ppl’  Palatino
     ‘ptm’  Times
     ‘uncl’ Uncial
     ‘put’  Utopia
     ‘pzc’  Zapf Chancery

‘\fontseries{SERIES}’
     Select the font series.  A “series” combines a “weight” and a
     “width”.  Typically, a font supports only a few of the possible
     combinations.  Some common combined series values include:

     ‘m’  Medium (normal)
     ‘b’  Bold
     ‘c’  Condensed
     ‘bc’ Bold condensed
     ‘bx’ Bold extended

     The possible values for weight, individually, are:

     ‘ul’ Ultra light
     ‘el’ Extra light
     ‘l’  Light
     ‘sl’ Semi light
     ‘m’  Medium (normal)
     ‘sb’ Semi bold
     ‘b’  Bold
     ‘eb’ Extra bold
     ‘ub’ Ultra bold

     The possible values for width, individually, are (the meaning and
     relationship of these terms varies with individual typefaces):

     ‘uc’ Ultra condensed
     ‘ec’ Extra condensed
     ‘c’  Condensed
     ‘sc’ Semi condensed
     ‘m’  Medium
     ‘sx’ Semi expanded
     ‘x’  Expanded
     ‘ex’ Extra expanded
     ‘ux’ Ultra expanded

     When forming the SERIES string from the weight and width, drop the
     ‘m’ that stands for medium weight or medium width, unless both
     weight and width are ‘m’, in which case use just one (‘‘m’’).

‘\fontshape{SHAPE}’
     Select font shape.  Valid shapes are:

     ‘n’  Upright (normal)
     ‘it’ Italic
     ‘sl’ Slanted (oblique)
     ‘sc’ Small caps
     ‘ui’ Upright italics
     ‘ol’ Outline

     The two last shapes are not available for most font families, and
     small caps are often missing as well.

‘\fontsize{SIZE}{SKIP}’
     Set the font size and the line spacing.  The unit of both
     parameters defaults to points (‘pt’).  The line spacing is the
     nominal vertical space between lines, baseline to baseline.  It is
     stored in the parameter ‘\baselineskip’.  The default
     ‘\baselineskip’ for the Computer Modern typeface is 1.2 times the
     ‘\fontsize’.  Changing ‘\baselineskip’ directly is inadvisable
     since its value is reset every time a size change happens; instead
     use ‘\baselinestretch’.  (*note \baselineskip &
     \baselinestretch::).

‘\linespread{FACTOR}’
     Equivalent to ‘\renewcommand{\baselinestretch}{FACTOR}’, and
     therefore must be followed by ‘\selectfont’ to have any effect.
     Best specified in the preamble.  *Note \baselineskip &
     \baselinestretch::, for using ‘setspace’ package instead.

‘\selectfont’
     The effects of the font commands described above do not happen
     until ‘\selectfont’ is called, as in
     ‘\fontfamily{FAMILYNAME}\selectfont’.  It is often useful to put
     this in a macro:
     ‘\newcommand*{\myfont}{\fontfamily{FAMILYNAME}\selectfont}’
     (*note \newcommand & \renewcommand::).

‘\usefont{ENC}{FAMILY}{SERIES}{SHAPE}’
     The same as invoking ‘\fontencoding’, ‘\fontfamily’, ‘\fontseries’
     and ‘\fontshape’ with the given parameters, followed by
     ‘\selectfont’.  For example:

          \usefont{ot1}{cmr}{m}{n}


File: latex2e.info,  Node: Layout,  Next: Sectioning,  Prev: Fonts,  Up: Top

5 Layout
********

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::  ‘\headheight’ ‘\footskip’.
* \baselineskip & \baselinestretch::           Space between lines.
* Floats::                  Figures, tables, etc.


File: latex2e.info,  Node: \onecolumn,  Next: \twocolumn,  Up: Layout

5.1 ‘\onecolumn’
================

Synopsis:

     \onecolumn

   Start a new page and produce single-column output.  If the document
is given the class option ‘onecolumn’ then this is the default behavior
(*note Document class options::).  This command is fragile (*note
\protect::).


File: latex2e.info,  Node: \twocolumn,  Next: \flushbottom,  Prev: \onecolumn,  Up: Layout

5.2 ‘\twocolumn’
================

Synopses:

     \twocolumn
     \twocolumn[PRELIM ONE COLUMN TEXT]

   Start a new page and produce two-column output.  If the document is
given the class option ‘twocolumn’ then this is the default (*note
Document class options::).  This command is fragile (*note \protect::).

   If the optional 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:

‘\columnsep’
     The distance between columns.  The default is 35pt.  Change it with
     a command such as ‘\setlength{\columnsep}{40pt}’.  You must change
     it before the two column mode starts; in the preamble is a good
     place.

‘\columnseprule’
     The width of the rule between columns.  The default is 0pt, meaning
     that there is no rule.  Otherwise, the rule appears halfway between
     the two columns.  Change it with a command such as
     ‘\setlength{\columnseprule}{0.4pt}’, before the two-column mode
     starts.

‘\columnwidth’
     The width of a single column.  In one-column mode this is equal to
     ‘\textwidth’.  In two-column mode by default LaTeX sets the width
     of each of the two columns, ‘\columnwidth’, to be half of
     ‘\textwidth’ minus ‘\columnsep’.

   In a two-column document, the starred environments ‘table*’ and
‘figure*’ are two columns wide, whereas the unstarred environments
‘table’ and ‘figure’ take up only one column (*note figure:: and *note
table::).  LaTeX places starred floats at the top of a page.  The
following parameters control float behavior of two-column output.

‘\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 ‘table*’ or ‘figure*’ environment must not
     exceed ‘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:

        • Use the ‘[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.

        • Use the ‘[t!]’ location specifier to override the effect of
          ‘\dbltopfraction’ for this particular float.

        • Increase the value of ‘\dbltopfraction’ to a suitably large
          number, to avoid going to float pages so soon.

     You can redefine it, as with ‘\renewcommand{\dbltopfraction}{0.9}’.

‘\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 ‘0.5’.  Change it with
     ‘\renewcommand’.

‘\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 ‘12pt plus2pt minus2pt’ for a document set at ‘10pt’
     or ‘11pt’, and ‘14pt plus2pt minus4pt’ for a document set at
     ‘12pt’.

‘\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 ‘20pt
     plus2pt minus4pt’.

‘\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 ‘2’.

   This example uses ‘\twocolumn’'s optional argument of to create a
title that spans the two-column article:

     \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.


File: latex2e.info,  Node: \flushbottom,  Next: \raggedbottom,  Prev: \twocolumn,  Up: Layout

5.3 ‘\flushbottom’
==================

Make all pages in the document 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 ‘Underfull \vbox (badness 10000) has
occurred while \output is active’.  If you get that, one option is to
change to ‘\raggedbottom’ (*note \raggedbottom::).  Alternatively, you
can adjust the ‘textheight’ to make compatible pages, or you can add
some vertical stretch glue between lines or between paragraphs, as in
‘\setlength{\parskip}{0ex plus0.1ex}’.  Your last option is to, in a
final editing stage, adjust the height of individual pages (*note
\enlargethispage::).

   The ‘\flushbottom’ state is the default only if you select the
‘twocolumn’ document class option (*note Document class options::), and
for indexes made using ‘makeidx’.


File: latex2e.info,  Node: \raggedbottom,  Next: Page layout parameters,  Prev: \flushbottom,  Up: Layout

5.4 ‘\raggedbottom’
===================

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.  *Note \flushbottom::.

   This is the default unless you select the ‘twocolumn’ document class
option (*note Document class options::).


File: latex2e.info,  Node: Page layout parameters,  Next: \baselineskip & \baselinestretch,  Prev: \raggedbottom,  Up: Layout

5.5 Page layout parameters
==========================

‘\columnsep’
‘\columnseprule’
‘\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 ‘twocolumn’ is in effect (*note Document class options::).
     *Note \twocolumn::.

‘\headheight’
     Height of the box that contains the running head.  The default in
     the ‘article’, ‘report’, and ‘book’ classes is ‘12pt’, at all type
     sizes.

‘\headsep’
     Vertical distance between the bottom of the header line and the top
     of the main text.  The default in the ‘article’ and ‘report’
     classes is ‘25pt’.  In the ‘book’ class the default is: if the
     document is set at 10pt then it is ‘0.25in’, and at 11pt or 12pt it
     is ‘0.275in’.

‘\footskip’
     Distance from the baseline of the last line of text to the baseline
     of the page footer.  The default in the ‘article’ and ‘report’
     classes is ‘30pt’.  In the ‘book’ class the default is: when the
     type size is 10pt the default is ‘0.35in’, while at 11pt it is
     ‘0.38in’, and at 12pt it is ‘30pt’.

‘\linewidth’
     Width of the current line, decreased for each nested ‘list’ (*note
     list::).  That is, the nominal value for ‘\linewidth’ is to equal
     ‘\textwidth’ but for each nested list the ‘\linewidth’ is decreased
     by the sum of that list's ‘\leftmargin’ and ‘\rightmargin’ (*note
     itemize::).

‘\marginparpush’
‘\marginsep’
‘\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 ‘\reversemarginpar’ changes that (and
     ‘\normalmarginpar’ changes it back).

     The defaults for ‘\marginparpush’ in both ‘book’ and ‘article’
     classes are: ‘7pt’ if the document is set at 12pt, and ‘5pt’ if the
     document is set at 11pt or 10pt.

     For ‘\marginsep’, in ‘article’ class the default is ‘10pt’ except
     if the document is set at 10pt and in two-column mode where the
     default is ‘11pt’.

     For ‘\marginsep’ in ‘book’ class the default is ‘10pt’ in
     two-column mode and ‘7pt’ in one-column mode.

     For ‘\marginparwidth’ in both ‘book’ and ‘article’ classes, in
     two-column mode the default is 60% of ‘\paperwidth − \textwidth’,
     while in one-column mode it is 50% of that distance.

‘\oddsidemargin’
‘\evensidemargin’
     The ‘\oddsidemargin’ length 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 ‘twoside’ is chosen and on all pages
     when ‘oneside’ is in effect.  When ‘twoside’ is in effect, on
     even-numbered pages the extra distance on the left is
     ‘\evensidemargin’.

     LaTeX's default is that ‘\oddsidemargin’ is 40% of the difference
     between ‘\paperwidth’ and ‘\textwidth’, and ‘\evensidemargin’ is
     the remainder.

‘\paperheight’
     The height of the paper, as distinct from the height of the print
     area.  Normally set with a document class option, as in
     ‘\documentclass[a4paper]{article}’ (*note Document class
     options::).

‘\paperwidth’
     The width of the paper, as distinct from the width of the print
     area.  Normally set with a document class option, as in
     ‘\documentclass[a4paper]{article}’ (*note Document class
     options::).

‘\textheight’
     The normal vertical height of the page body.  If the document is
     set at a nominal type size of 10pt then for an ‘article’ or
     ‘report’ the default is ‘43\baselineskip’, while for a ‘book’ it is
     ‘41\baselineskip’.  At a type size of 11pt the default is
     ‘38\baselineskip’ for all document classes.  At 12pt it is
     ‘36\baselineskip’ for all classes.

‘\textwidth’
     The full horizontal width of the entire page body.  For an
     ‘article’ or ‘report’ document, the default is ‘345pt’ when the
     chosen type size is 10pt, the default is ‘360pt’ at 11pt, and it is
     ‘390pt’ at 12pt.  For a ‘book’ document, the default is ‘4.5in’ at
     a type size of 10pt, and ‘5in’ at 11pt or 12pt.

     In multi-column output, ‘\textwidth’ remains the width of the
     entire page body, while ‘\columnwidth’ is the width of one column
     (*note \twocolumn::).

     In lists (*note list::), ‘\textwidth’ remains the width of the
     entire page body (and ‘\columnwidth’ the width of the entire
     column), while ‘\linewidth’ may decrease for nested lists.

     Inside a minipage (*note minipage::) or ‘\parbox’ (*note
     \parbox::), all the width-related parameters are set to the
     specified width, and revert to their normal values at the end of
     the ‘minipage’ or ‘\parbox’.

‘\hsize’
     This entry is included for completeness: ‘\hsize’ is the TeX
     primitive parameter used when text is broken into lines.  It should
     not be used in normal LaTeX documents.

‘\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: ‘\paperheight − 2in −
     \headheight − \headsep − \textheight − \footskip’, and then divided
     by two.

‘\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., ‘10pt’ at a type size of 10pt.


File: latex2e.info,  Node: \baselineskip & \baselinestretch,  Next: Floats,  Prev: Page layout parameters,  Up: Layout

5.6 ‘\baselineskip’ & ‘\baselinestretch’
========================================

The ‘\baselineskip’ is a rubber length (*note Lengths::).  It gives the
“leading”, the normal distance between lines in a paragraph, from
baseline to baseline.

   Ordinarily document authors do not directly change ‘\baselineskip’
while writing.  Instead, it is set by the low level font selection
command ‘\fontsize’ (*note low level font commands fontsize::).  The
‘\baselineskip’'s value is reset every time a font change happens and so
any direct change to ‘\baselineskip’ would vanish the next time there
was a font switch.  For how to influence line spacing, see the
discussion of ‘\baselinestretch’ below.

   Usually, a font's size and baseline skip is assigned by the font
designer.  These numbers are nominal in the sense that if, for instance,
a font's style file has the command ‘\fontsize{10pt}{12pt}’ then that
does not mean that the characters in the font are 10pt tall; for
instance, parentheses and accented capitals may be taller.  Nor does it
mean that if the lines are spaced less than 12pt apart then they risk
touching.  Rather these numbers are typographic judgements.  (Often, the
‘\baselineskip’ is about twenty percent larger than the font size.)

   The ‘\baselineskip’ is not a property of each line but of the entire
paragraph.  As a result, large text in the middle of a paragraph, such
as a single ‘{\Huge Q}’, will be squashed into its line.  TeX will make
sure it doesn't scrape up against the line above but won't change the
‘\baselineskip’ for that one line to make extra room above.  For the
fix, use a ‘\strut’ (*note \strut::).

   The value of ‘\baselineskip’ that TeX uses for the paragraph is the
value in effect at the blank line or command that ends the paragraph
unit.  So if a document contains this paragraph then its lines will be
scrunched together, compared to lines in surrounding paragraphs.

     Many people see a page break between text and a displayed equation as
     bad style, so in effect the display is part of the paragraph.
     Because this display is in footnotesize, the entire paragraph has the
     baseline spacing matching that size.
     {\footnotesize $$a+b = c$$}

   The process for making paragraphs is that when a new line is added,
if the depth of the previous line plus the height of the new line is
less than ‘\baselineskip’ then TeX inserts vertical glue to make up the
difference.  There are two fine points.  The first is that if the lines
would be too close together, closer than ‘\lineskiplimit’, then TeX
instead uses ‘\lineskip’ as the interline glue.  The second is that TeX
doesn't actually use the depth of the previous line.  Instead it uses
‘\prevdepth’, which usually contains that depth.  But at the beginning
of the paragraph (or any vertical list) or just after a rule,
‘\prevdepth’ has the value -1000pt and this special value tells TeX not
to insert any interline glue at the paragraph start.

   In the standard classes ‘\lineskiplimit’ is 0pt and ‘\lineskip’ is
1pt.  By the prior paragraph then, the distance between lines can
approach zero but if it becomes zero (or less than zero) then the lines
jump to 1pt apart.

   Sometimes authors must, for editing purposes, put the document in
double space or one-and-a-half space.  The right way to influence the
interline distance is via ‘\baselinestretch’.  It scales
‘\baselineskip’, and has a default value of 1.0.  It is a command, not a
length, and does not take effect until a font change happens, so set the
scale factor like this:
‘\renewcommand{\baselinestretch}{1.5}\selectfont’.

   The most straightforward way to change the line spacing for an entire
document is to put ‘\linespread{FACTOR}’ in the preamble.  For double
spacing, take FACTOR to be 1.6 and for one-and-a-half spacing use 1.3.
These numbers are rough: for instance, since the ‘\baselineskip’ is
about 1.2 times the font size, multiplying by 1.6 gives a baseline skip
to font size ratio of about 2.  (The ‘\linespread’ command is defined as
‘\renewcommand{\baselinestretch}{FACTOR}’ so it also won't take effect
until a font setting happens.  But that always takes place at the start
of a document, so there you don't need to follow it with ‘\selectfont’.)

   A simpler approach is the ‘setspace’ package.  The basic example:

     \usepackage{setspace}
     \doublespacing  % or \onehalfspacing for 1.5

In the preamble these will start the document off with that sizing.  But
you can also use these declarations in the document body to change the
spacing from that point forward, and consequently there is
‘\singlespacing’ to return the spacing to normal.  In the document body,
a better practice than using the declarations is to use environments,
such as ‘\begin{doublespace} ... \end{doublespace}’.  The package also
has commands to do arbitrary spacing: ‘\setstretch{FACTOR}’ and
‘\begin{spacing}{FACTOR} ... \end{spacing}’.  This package also keeps
the line spacing single-spaced in places where that is typically
desirable, such as footnotes and figure captions.  See the package
documentation.


File: latex2e.info,  Node: Floats,  Prev: \baselineskip & \baselinestretch,  Up: Layout

5.7 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, ‘figure’ (*note figure::) and ‘table’
(*note table::), but you can create a new class with the package
‘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.

   In addition to changing the parameters, for each float you can tweak
where the float placement algorithm tries to place it by using its
PLACEMENT argument.  The possible values are a sequence of the letters
below.  The default for both ‘figure’ and ‘table’, in both ‘article’ and
‘book’ classes, is ‘tbp’.

‘t’
     (Top)--at the top of a text page.

‘b’
     (Bottom)--at the bottom of a text page.  (However, ‘b’ is not
     allowed for full-width floats (‘figure*’) with double-column
     output.  To ameliorate this, use the ‘stfloats’ or ‘dblfloatfix’
     package, but see the discussion at caveats in the FAQ:
     <https://www.texfaq.org/FAQ-2colfloat>.

‘h’
     (Here)--at the position in the text where the ‘figure’ environment
     appears.  However, ‘h’ is not allowed by itself; ‘t’ is
     automatically added.

     To absolutely force a float to appear "here", you can
     ‘\usepackage{float}’ and use the ‘H’ specifier which it defines.
     For further discussion, see the FAQ entry at
     <https://www.texfaq.org/FAQ-figurehere>.

‘p’
     (Page of floats)--on a separate “float page”, which is a page
     containing no text, only floats.

‘!’
     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 ‘!’ specifier does _not_ mean "put the float here"; see
     above.

   Note: the order in which letters appear in the PLACEMENT argument
does not change the order in which LaTeX tries to place the float; for
instance, ‘btp’ has the same effect as ‘tbp’.  All that PLACEMENT does
is that if a letter is not present then the algorithm does not try that
location.  Thus, LaTeX's default of ‘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 ‘\clearpage’ command to start a new page and
insert all pending floats.  If a pagebreak is undesirable then you can
use the ‘afterpage’ package and issue ‘\afterpage{\clearpage}’.  This
will wait until the current page is finished and then flush all
outstanding floats.

   LaTeX can typeset a float before where it appears in the source
(although on the same output page) if there is a ‘t’ specifier in the
PLACEMENT parameter.  If this is not desired, and deleting the ‘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 ‘flafter’ package
or using the command ‘\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 ‘\renewcommand{PARAMETER}{DECIMAL
BETWEEN 0 AND 1}’):

‘\bottomfraction’
     The maximum fraction of the page allowed to be occupied by floats
     at the bottom; default ‘.3’.

‘\floatpagefraction’
     The minimum fraction of a float page that must be occupied by
     floats; default ‘.5’.

‘\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 ‘.2’.

‘\topfraction’
     Maximum fraction at the top of a page that may be occupied before
     floats; default ‘.7’.

   Parameters relating to vertical space around floats (change them with
a command of the form ‘\setlength{PARAMETER}{LENGTH EXPRESSION}’):

‘\floatsep’
     Space between floats at the top or bottom of a page; default ‘12pt
     plus2pt minus2pt’.

‘\intextsep’
     Space above and below a float in the middle of the main text;
     default ‘12pt plus2pt minus2pt’ for 10 point and 11 point
     documents, and ‘14pt plus4pt minus4pt’ for 12 point documents.

‘\textfloatsep’
     Space between the last (first) float at the top (bottom) of a page;
     default ‘20pt plus2pt minus4pt’.

   Counters relating to the number of floats on a page (change them with
a command of the form ‘\setcounter{CTRNAME}{NATURAL NUMBER}’):

‘bottomnumber’
     Maximum number of floats that can appear at the bottom of a text
     page; default 1.

‘dbltopnumber’
     Maximum number of full-sized floats that can appear at the top of a
     two-column page; default 2.

‘topnumber’
     Maximum number of floats that can appear at the top of a text page;
     default 2.

‘totalnumber’
     Maximum number of floats that can appear on a text page; default 3.

   The principal TeX FAQ entry relating to floats
<https://www.texfaq.org/FAQ-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?"
(<https://www.latex-project.org/publications/2014-FMi-TUB-tb111mitt-float-placement.pdf>).

* Menu:

* \caption::          Make a caption for a floating environment.


File: latex2e.info,  Node: \caption,  Up: Floats

5.7.1 ‘\caption’
----------------

Synopsis:

     \caption{CAPTION-TEXT}

or

     \caption[SHORT-CAPTION-TEXT]{CAPTION-TEXT}

   Make a caption for a floating environment, such as a ‘figure’ or
‘table’ environment (*note figure:: or *note table::).

   In this example, LaTeX places a caption below the vertical blank
space that is left by the author for the later inclusion of a picture.

     \begin{figure}
       \vspace*{1cm}
       \caption{Alonzo Cushing, Battery A, 4th US Artillery.}
       \label{fig:CushingPic}
     \end{figure}

The ‘\caption’ command will label the CAPTION-TEXT with something like
‘Figure 1:’ for an article or ‘Figure 1.1:’ for a book.  The text is
centered if it is shorter than the text width, or set as an unindented
paragraph if it takes more than one line.

   In addition to placing the CAPTION-TEXT in the output, the ‘\caption’
command also saves that information for use in a list of figures or list
of tables (*note Table of contents etc.::).

   Here the ‘\caption’ command uses the optional SHORT-CAPTION-TEXT, so
that the shorter text appears in the list of tables, rather than the
longer CAPTION-TEXT.

     \begin{table}
       \centering
       \begin{tabular}{|*{3}{c}|}
         \hline
         4  &9  &2 \\
         3  &5  &7 \\
         8  &1  &6 \\
         \hline
       \end{tabular}
       \caption[\textit{Lo Shu} magic square]{%
         The \textit{Lo Shu} magic square, which is unique among
         squares of order three up to rotation and reflection.}
       \label{tab:LoShu}
     \end{table}

LaTeX will label the CAPTION-TEXT with something like ‘Table 1:’ for an
article or ‘Table 1.1:’ for a book.

   The caption can appear at the top of the ‘figure’ or ‘table’.  For
instance, that would happen in the prior example by putting the
‘\caption’ between the ‘\centering’ and the ‘\begin{tabular}’.

   Different floating environments are numbered separately, by default.
It is ‘\caption’ that updates the counter, and so any ‘\label’ must come
after the ‘\caption’.  The counter for the ‘figure’ environment is named
‘figure’, and similarly the counter for the ‘table’ environment is
‘table’.

   The text that will be put in the list of figures or list of tables is
moving argument.  If you get the LaTeX error ‘! Argument of \@caption
has an extra }’ then you must put ‘\protect’ in front of any fragile
commands.  *Note \protect::.

   The ‘caption’ package has many options to adjust how the caption
appears, for example changing the font size, making the caption be
hanging text rather than set as a paragraph, or making the caption
always set as a paragraph rather than centered when it is short.


File: latex2e.info,  Node: Sectioning,  Next: Cross references,  Prev: Layout,  Up: Top

6 Sectioning
************

Structure your text into divisions: parts, chapters, sections, etc.  All
sectioning commands have the same form, one of:

     SECTIONING-COMMAND{TITLE}
     SECTIONING-COMMAND*{TITLE}
     SECTIONING-COMMAND[TOC-TITLE]{TITLE}

For instance, declare the start of a subsection as with
‘\subsection{Motivation}’.

   The table has each SECTIONING-COMMAND in LaTeX.  All are available in
all of LaTeX's standard document classes ‘book’, ‘report’,
and ‘article’, except that ‘\chapter’ is not available in ‘article’.

Sectioning unit    Command            Level
--------------------------------------------------------------------
Part               ‘\part’            -1 (‘book’, ‘report’), 0
                                      (‘article’)
Chapter            ‘\chapter’         0
Section            ‘\section’         1
Subsection         ‘\subsection’      2
Subsubsection      ‘\subsubsection’   3
Paragraph          ‘\paragraph’       4
Subparagraph       ‘\subparagraph’    5

   All these commands have a ‘*’-form that prints TITLE as usual but
does not number it and does not make an entry in the table of contents.
An example of using this is for an appendix in an ‘article’.  The input
‘\appendix\section{Appendix}’ gives the output ‘A Appendix’ (*note
\appendix::).  You can lose the numbering ‘A’ by instead entering
‘\section*{Appendix}’ (articles often omit a table of contents and have
simple page headers so the other differences from the ‘\section’ command
may not matter).

   The section title 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
(*note 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
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 LEVEL is less than or equal to the value of the
counter ‘secnumdepth’ then the titles for this sectioning command will
be numbered (*note Sectioning/secnumdepth::).  And, if LEVEL is less
than or equal to the value of the counter ‘tocdepth’ then the table of
contents will have an entry for this sectioning unit (*note
Sectioning/tocdepth::).

   LaTeX expects that before you have a ‘\subsection’ you will have a
‘\section’ and, in a ‘book’ class document, that before a ‘\section’ you
will have a ‘\chapter’.  Otherwise you can get something like a
subsection numbered ‘3.0.1’.

   LaTeX lets you change the appearance of the sectional units.  As a
simple example, you can change the section numbering to uppercase
letters with this (in the preamble):
‘\renewcommand\thesection{\Alph{section}}’ .  (*Note \alph \Alph \arabic
\roman \Roman \fnsymbol::.)  CTAN has many packages that make this
adjustment easier, notably ‘titlesec’.

   Two counters relate to the appearance of headings made by sectioning
commands.

‘secnumdepth’
     Controls which sectioning unit are numbered.  Setting the counter
     with ‘\setcounter{secnumdepth}{LEVEL}’ will suppress numbering of
     sectioning at any depth greater than LEVEL (*note \setcounter::).
     See the above table for the level numbers.  For instance, if the
     ‘secnumdepth’ is 1 in an ‘article’ then a ‘\section{Introduction}’
     command will produce output like ‘1 Introduction’ while
     ‘\subsection{Discussion}’ will produce output like ‘Discussion’,
     without the number.  LaTeX's default ‘secnumdepth’ is 3 in
     ‘article’ class and  2 in the ‘book’ and ‘report’ classes.

‘tocdepth’
     Controls which sectioning units are listed in the table of
     contents.  The setting ‘\setcounter{tocdepth}{LEVEL}’ makes the
     sectioning units at LEVEL be the smallest ones listed (*note
     \setcounter::).  See the above table for the level numbers.  For
     instance, if ‘tocdepth’ is 1 then the table of contents will list
     sections but not subsections.  LaTeX's default ‘tocdepth’ is 3 in
     ‘article’ class and  2 in the ‘book’ and ‘report’ classes.

* 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::                               Sectional unit headings.


File: latex2e.info,  Node: \part,  Next: \chapter,  Up: Sectioning

6.1 ‘\part’
===========

Synopsis, one of:

     \part{TITLE}
     \part*{TITLE}
     \part[TOC-TITLE]{TITLE}

   Start a document part.  The standard LaTeX classes ‘book’, ‘report’,
and ‘article’, all have this command.

   This produces a document part, in a book.

     \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.

   In each standard class the ‘\part’ command outputs a part number such
as ‘Part I’, alone on its line, in boldface, and in large type.  Then
LaTeX outputs TITLE, also alone on its line, in bold and in even larger
type.  In class ‘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 ‘report’ it is
again alone on a page, but LaTeX won't force it onto an odd-numbered
page.  In an ‘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 ‘*’ form shows TITLE but it does not show the part number, does
not increment the ‘part’ counter, and produces no table of contents
entry.

   The optional argument TOC-TITLE will appear as the part title in the
table of contents (*note Table of contents etc.::) and in running
headers (*note Page styles::).  If it is not present then TITLE will be
there.  This example puts a line break in TITLE but omits the break in
the table of contents.

     \part[Up from the bottom; my life]{Up from the bottom\\ my life}

   For determining which sectional units are numbered and which appear
in the table of contents, the level number of a part is -1 (*note
Sectioning/secnumdepth::, and *note Sectioning/tocdepth::).

   In the class ‘article’, if a paragraph immediately follows the part
title then it is not indented.  To get an indent you can use the package
‘indentfirst’.

   One package to change the behavior of ‘\part’ is ‘titlesec’.  See its
documentation on CTAN.


File: latex2e.info,  Node: \chapter,  Next: \section,  Prev: \part,  Up: Sectioning

6.2 ‘\chapter’
==============

Synopsis, one of:

     \chapter{TITLE}
     \chapter*{TITLE}
     \chapter[TOC-TITLE]{TITLE}

   Start a chapter.  The standard LaTeX classes ‘book’ and ‘report’ have
this command but ‘article’ does not.

   This produces a chapter.

     \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.

   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 ‘Chapter 1’ in large boldface type (the size is ‘\huge’).
It then puts TITLE on a fresh line, in boldface type that is still
larger (size ‘\Huge’).  It also increments the ‘chapter’ counter, adds
an entry to the table of contents (*note Table of contents etc.::), and
sets the running header information (*note Page styles::).

   The ‘*’ form shows TITLE on a fresh line, in boldface.  But it does
not show the chapter number, does not increment the ‘chapter’ counter,
produces no table of contents entry, and does not affect the running
header.  (If you use the page style ‘headings’ in a two-sided document
then the header will be from the prior chapter.)  This example
illustrates.

     \chapter*{Preamble}

   The optional argument TOC-TITLE will appear as the chapter title in
the table of contents (*note Table of contents etc.::) and in running
headers (*note Page styles::).  If it is not present then TITLE will be
there.  This shows the full name in the chapter title,

     \chapter[Weyl]{Hermann Klaus Hugo (Peter) Weyl (1885--1955)}

but only ‘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

     \chapter[Given it all; my story]{Given it all\\ my story}

   For determining which sectional units are numbered and which appear
in the table of contents, the level number of a chapter is 0 (*note
Sectioning/secnumdepth:: and *note Sectioning/tocdepth::).

   The paragraph that follows the chapter title is not indented, as is a
standard typographical practice.  To get an indent use the package
‘indentfirst’.

   You can change what is shown for the chapter number.  To change it to
something like ‘Lecture 1’, put in the preamble either
‘\renewcommand{\chaptername}{Lecture}’ or this (*note \makeatletter &
\makeatother::).

     \makeatletter
     \renewcommand{\@chapapp}{Lecture}
     \makeatother

To make this change because of the primary language for the document,
see the package ‘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 *note
\clearpage & \cleardoublepage::.

   To change the behavior of the ‘\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 ‘titlesec’.
See its documentation, but the example below gives a sense of what it
can do.

     \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

This omits the chapter number ‘Chapter 1’ from the page but unlike
‘\chapter*’ it keeps the chapter in the table of contents and the
running headers.


File: latex2e.info,  Node: \section,  Next: \subsection,  Prev: \chapter,  Up: Sectioning

6.3 ‘\section’
==============

Synopsis, one of:

     \section{TITLE}
     \section*{TITLE}
     \section[TOC-TITLE]{TITLE}

   Start a section.  The standard LaTeX classes ‘article’, ‘book’, and
‘report’ all have this command.

   This produces a section.

     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.

   For the standard LaTeX classes ‘book’ and ‘report’ the default output
is like ‘1.2 TITLE’ (for chapter 1, section 2), alone on its line and
flush left, in boldface and a larger type (the type size is ‘\Large’).
The same holds in ‘article’ except that there are no chapters in that
class so it looks like ‘2 TITLE’.

   The ‘*’ form shows TITLE.  But it does not show the section number,
does not increment the ‘section’ counter, produces no table of contents
entry, and does not affect the running header.  (If you use the page
style ‘headings’ in a two-sided document then the header will be from
the prior section.)

   The optional argument TOC-TITLE will appear as the section title in
the table of contents (*note Table of contents etc.::) and in running
headers (*note Page styles::).  If it is not present then TITLE will be
there.  This shows the full name in the title of the section:

     \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.}

but only ‘Elizabeth II’ on the contents page and in the headers.  This
has a line break in TITLE but that does not work with headers so it is
omitted from the contents and headers.

     \section[Truth is, I cheated; my life story]{Truth is,
       I cheated\\my life story}

   For determining which sectional units are numbered and which appear
in the table of contents, the level number of a section is 1 (*note
Sectioning/secnumdepth:: and *note Sectioning/tocdepth::).

   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 ‘indentfirst’.

   In general, to change the behavior of the ‘\section’ command, there
are a number of options.  One is the ‘\@startsection’ command (*note
\@startsection::).  There are also many packages on CTAN that address
this, including ‘titlesec’.  See the documentation but the example below
gives a sense of what they can do.

     \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]

That puts the section number in the margin.


File: latex2e.info,  Node: \subsection,  Next: \subsubsection & \paragraph & \subparagraph,  Prev: \section,  Up: Sectioning

6.4 ‘\subsection’
=================

Synopsis, one of:

     \subsection{TITLE}
     \subsection*{TITLE}
     \subsection[TOC-TITLE]{TITLE}

   Start a subsection.  The standard LaTeX classes ‘article’, ‘book’,
and ‘report’ all have this command.

   This produces a subsection.

     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.

   For the standard LaTeX classes ‘book’ and ‘report’ the default output
is like ‘1.2.3 TITLE’ (for chapter 1, section 2, subsection 3), alone on
its line and flush left, in boldface and a larger type (the type size is
‘\large’).  The same holds in ‘article’ except that there are no
chapters in that class so it looks like ‘2.3 TITLE’.

   The ‘*’ form shows TITLE.  But it does not show the subsection
number, does not increment the ‘subsection’ counter, and produces no
table of contents entry.

   The optional argument TOC-TITLE will appear as the subsection title
in the table of contents (*note Table of contents etc.::).  If it is not
present then TITLE will be there.  This shows the full text in the title
of the subsection:

     \subsection[$\alpha,\beta,\gamma$ paper]{\textit{The Origin of
       Chemical Elements} by R.A.~Alpher, H.~Bethe, and G.~Gamow}

but only ‘α,β,γ 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 2 (*note
Sectioning/secnumdepth:: and *note Sectioning/tocdepth::).

   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 ‘indentfirst’.

   There are a number of ways to change the behavior of the
‘\subsection’ command.  One is the ‘\@startsection’ command (*note
\@startsection::).  There are also many packages on CTAN that address
this, including ‘titlesec’.  See the documentation but the example below
gives a sense of what they can do.

     \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

That puts the subsection number and TITLE in the first line of text.


File: latex2e.info,  Node: \subsubsection & \paragraph & \subparagraph,  Next: \appendix,  Prev: \subsection,  Up: Sectioning

6.5 ‘\subsubsection’, ‘\paragraph’, ‘\subparagraph’
===================================================

Synopsis, one of:

     \subsubsection{TITLE}
     \subsubsection*{TITLE}
     \subsubsection[TOC-TITLE]{TITLE}

or one of:

     \paragraph{TITLE}
     \paragraph*{TITLE}
     \paragraph[TOC-TITLE]{TITLE}

or one of:

     \subparagraph{TITLE}
     \subparagraph*{TITLE}
     \subparagraph[TOC-TITLE]{TITLE}

   Start a subsubsection, paragraph, or subparagraph.  The standard
LaTeX classes ‘article’, ‘book’, and ‘report’ all have these commands,
although they are not commonly used.

   This produces a subsubsection.

     \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.

   The default output of each of the three does not change over the
standard LaTeX classes ‘article’, ‘book’, and ‘report’.  For
‘\subsubsection’ the TITLE is alone on its line, in boldface and normal
size type.  For ‘\paragraph’ the TITLE is inline with the text, not
indented, in boldface and normal size type.  For ‘\subparagraph’ the
TITLE is inline with the text, with a paragraph indent, in boldface and
normal size type (Because an ‘article’ has no chapters its
subsubsections are numbered and so it looks like ‘1.2.3 TITLE’, for
section 1, subsection 2, and subsubsection 3.  The other two divisions
are not numbered.)

   The ‘*’ form shows TITLE.  But it does not increment the associated
counter and produces no table of contents entry (and does not show the
number for ‘\subsubsection’).

   The optional argument TOC-TITLE will appear as the division title in
the table of contents (*note Table of contents etc.::).  If it is not
present then 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 3, of a
paragraph is 4, and of a subparagraph is 5 (*note
Sectioning/secnumdepth:: and *note Sectioning/tocdepth::).

   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 ‘indentfirst’.

   There are a number of ways to change the behavior of the these
commands.  One is the ‘\@startsection’ command (*note \@startsection::).
There are also many packages on CTAN that address this, including
‘titlesec’.  See the documentation on CTAN.


File: latex2e.info,  Node: \appendix,  Next: \frontmatter & \mainmatter & \backmatter,  Prev: \subsubsection & \paragraph & \subparagraph,  Up: Sectioning

6.6 ‘\appendix’
===============

Synopsis:

     \appendix

   This does not directly produce any output.  But in a ‘book’ or
‘report’ document it declares that subsequent ‘\chapter’ commands start
an appendix.  In an article it does the same, for ‘\section’ commands.
It also resets the ‘chapter’ and ‘section’ counters to 0 in a book or
report, and in an article resets the ‘section’ and ‘subsection’
counters.

   In this book

     \chapter{One}  ...
     \chapter{Two}  ...
      ...
     \appendix
     \chapter{Three}  ...
     \chapter{Four}  ...

the first two will generate output numbered ‘Chapter 1’ and ‘Chapter 2’.
After the ‘\appendix’ the numbering will be ‘Appendix A’ and ‘Appendix
B’.  *Note Larger book template::, for another example.

   The ‘appendix’ package adds the command ‘\appendixpage’ to put a
separate ‘Appendices’ in the document body before the first appendix,
and the command ‘\addappheadtotoc’ to do the same in the table of
contents.  You can reset the name ‘Appendices’ with a command like
‘\renewcommand{\appendixname}{Specification}’, as well as a number of
other features.  See the documentation on CTAN.


File: latex2e.info,  Node: \frontmatter & \mainmatter & \backmatter,  Next: \@startsection,  Prev: \appendix,  Up: Sectioning

6.7 ‘\frontmatter’, ‘\mainmatter’, ‘\backmatter’
================================================

Synopsis, one or more of:

     \frontmatter
     ...
     \mainmatter
     ...
     \backmatter
     ...

   Format a ‘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 ‘\frontmatter’ command 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 ‘*’-version (*note Sectioning::).

   The ‘\mainmatter’ command changes the behavior back to the expected
version, and resets the page number.

   The ‘\backmatter’ command leaves the page numbering alone but
switches the chapters back to being not numbered.

   *Note Larger book template::, for an example using these three
commands.


File: latex2e.info,  Node: \@startsection,  Prev: \frontmatter & \mainmatter & \backmatter,  Up: Sectioning

6.8 ‘\@startsection’: Typesetting sectional unit headings
=========================================================

Synopsis:

     \@startsection{NAME}{LEVEL}{INDENT}{BEFORESKIP}{AFTERSKIP}{STYLE}

   Used to help redefine the behavior of commands that start sectioning
divisions such as ‘\section’ or ‘\subsection’.

   The ‘titlesec’ package makes manipulation of sectioning easier.
Further, while most requirements for sectioning commands can be
satisfied with ‘\@startsection’, some cannot.  For instance, in the
standard LaTeX ‘book’ and ‘report’ classes the commands ‘\chapter’ and
‘\report’ are not constructed using this.  To make such a command you
may want to use the ‘\secdef’ command.

   The ‘\@startsection’ macro is used like this:

     \@startsection{NAME}
       {LEVEL}
       {INDENT}
       {BEFORESKIP}
       {AFTERSKIP}
       {STYLE}*[TOCTITLE]{TITLE}

so that issuing

     \renewcommand{\section}{\@startsection{NAME}
       {LEVEL}
       {INDENT}
       {BEFORESKIP}
       {AFTERSKIP}
       {STYLE}}

redefines ‘\section’ while keeping its standard calling form
‘\section*[TOCTITLE]{TITLE}’ (in which, as a reminder, the star ‘*’ is
optional).  *Note Sectioning::.  This implies that when you write a
command like ‘\renewcommand{\section}{...}’, the ‘\@startsection{...}’
must come last in the definition.  See the examples below.

NAME
     Name of the counter used to number the sectioning header.  This
     counter must be defined separately.  Most commonly this is either
     ‘section’, ‘subsection’, or ‘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 ‘\the’NAME displays the title number and ‘\’NAME‘mark’ is for
     the page headers.  See the third example below.

LEVEL
     An integer giving the depth of the sectioning command.  *Note
     Sectioning::, for the list of standard level numbers.

     If LEVEL is less than or equal to the value of the counter
     ‘secnumdepth’ then titles for this sectioning command will be
     numbered (*note Sectioning/secnumdepth::).  For instance, if
     ‘secnumdepth’ is 1 in an ‘article’ then the command
     ‘\section{Introduction}’ will produce output like "1 Introduction"
     while ‘\subsection{Discussion}’ will produce output like
     "Discussion", without the number prefix.

     If LEVEL is less than or equal to the value of the counter TOCDEPTH
     then the table of contents will have an entry for this sectioning
     unit (*note Sectioning/tocdepth::).  For instance, in an ‘article’,
     if TOCDEPTH is 1 then the table of contents will list sections but
     not subsections.

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 ‘0pt’.  A negative indentation such as ‘-\parindent’
     will move the title into the left margin.

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
     beginning of a 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.  (Example: the
     negative of ‘1pt plus 2pt minus 3pt’ is ‘-1pt plus -2pt minus
     -3pt’.)

     For example, if BEFORESKIP is ‘-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
     ‘plus’ and ‘minus’, is good practice here since it gives LaTeX more
     flexibility in making up the page (*note 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 ‘\parskip’ of the text
     font, the ‘\baselineskip’ of the title font, and the absolute value
     of the 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.)

AFTERSKIP
     This is a length.  If 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 ‘1pt plus 2pt minus 3pt’ is ‘-1pt plus
     -2pt minus -3pt’.)

     As with BEFORESKIP, using a rubber length, with ‘plus’ and ‘minus’
     components, is good practice here since it gives LaTeX more
     flexibility in putting together the page.

     If ‘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 ‘\parskip’ of the title font, the
     ‘\baselineskip’ of the text font, and the value of AFTER.  That
     space is typically rubber so it may stretch or shrink.  (Note that
     because the sign of ‘afterskip’ changes the sectioning unit
     header's from standalone to run-in, you cannot use a negative
     ‘afterskip’ to cancel part of the ‘\parskip’.)

STYLE
     Controls the styling of the title.  See the examples below.
     Typical commands to use here are ‘\centering’, ‘\raggedright’,
     ‘\normalfont’, ‘\hrule’, or ‘\newpage’.  The last command in STYLE
     may be one that takes one argument, such as ‘\MakeUppercase’ or
     ‘\fbox’ that takes one argument.  The section title will be
     supplied as the argument to this command.  For instance, setting
     STYLE to ‘\bfseries\MakeUppercase’ would produce titles that are
     bold and uppercase.

   These are LaTeX's defaults for the first three sectioning units that
are defined with ‘\@startsection’, for the ‘article’, ‘book’, and
‘report’ classes.

   • For ‘section’: LEVEL is 1, INDENT is 0pt, BEFORESKIP is ‘-3.5ex
     plus -1ex minus -0.2ex’, AFTERSKIP is ‘2.3ex plus 0.2ex’, and STYLE
     is ‘\normalfont\Large\bfseries’.

   • For ‘subsection’: LEVEL is 2, INDENT is 0pt, BEFORESKIP is ‘-3.25ex
     plus -1ex minus -0.2ex’, AFTERSKIP is ‘1.5ex plus 0.2ex’, and STYLE
     is ‘\normalfont\large\bfseries’.

   • For ‘subsubsection’: LEVEL is 3, INDENT is 0pt, BEFORESKIP is
     ‘-3.25ex plus -1ex minus -0.2ex’, AFTERSKIP is ‘1.5ex plus 0.2ex’,
     and STYLE is ‘\normalfont\normalsize\bfseries’.

   Some examples follow.  These 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 ‘\makeatletter’ command and a ‘\makeatother’.
(Probably the error message ‘You can't use `\spacefactor' in vertical
mode.’ means that you forgot this.)  *Note \makeatletter &
\makeatother::.

   This will put section titles in large boldface type, centered.  It
says ‘\renewcommand’ because LaTeX's standard classes have already
defined a ‘\section’.  For the same reason it does not define a
‘section’ counter, or the commands ‘\thesection’ and ‘\l@section’.

     \renewcommand\section{%
       \@startsection{section}% *note NAME: \@startsection/name.
         {1}% *note LEVEL: \@startsection/level.
         {0pt}% *note INDENT: \@startsection/indent.
         {-3.5ex plus -1ex minus -.2ex}% *note BEFORESKIP: \@startsection/beforeskip.
         {2.3ex plus.2ex}% *note AFTERSKIP: \@startsection/afterskip.
         {\centering\normalfont\Large\bfseries}% *note STYLE: \@startsection/style.
       }

   This will put ‘subsection’ titles in small caps type, inline with the
paragraph.

     \renewcommand\subsection{%
       \@startsection{subsection}%  *note NAME: \@startsection/name.
         {2}% *note LEVEL: \@startsection/level.
         {0em}% *note INDENT: \@startsection/indent.
         {-1ex plus 0.1ex minus -0.05ex}% *note BEFORESKIP: \@startsection/beforeskip.
         {-1em plus 0.2em}% *note AFTERSKIP: \@startsection/afterskip.
         {\scshape}% *note STYLE: \@startsection/style.
       }

   The prior examples redefined existing sectional unit title commands.
This defines a new one, illustrating the needed counter and macros to
display that counter.

     \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


File: latex2e.info,  Node: Cross references,  Next: Environments,  Prev: Sectioning,  Up: Top

7 Cross references
******************

We often want something like ‘See Theorem~31’.  But by-hand typing the
31 is poor practice.  Instead you should write a “label” such as
‘\label{eq:GreensThm}’ and then “reference” it, as with ‘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.

     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}.

   LaTeX tracks cross reference information in a file having the
extension ‘.aux’ and with the same base name as the file containing the
‘\label’.  So if ‘\label’ is in ‘calculus.tex’ then the information is
in ‘calculus.aux’.  LaTeX puts the information in that file every time
it runs across a ‘\label’.

   The behavior described in the prior paragraph results in a quirk that
happens when your document has a “forward reference”, a ‘\ref’ that
appears before the associated ‘\label’.  If this is the first time that
you are compiling the document then you will get ‘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 ‘??’,
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.

   The ‘cleveref’ package enhances LaTeX's cross referencing features.
You can arrange that if you enter
‘\begin{thm}\label{th:Nerode}...\end{thm}’ then ‘\cref{th:Nerode}’ will
output ‘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.
* xr package::        References from another document.


File: latex2e.info,  Node: \label,  Next: \pageref,  Up: Cross references

7.1 ‘\label’
============

Synopsis:

     \label{KEY}

   Assign a reference number to KEY.  In ordinary text ‘\label{KEY}’
assigns to KEY the number of the current sectional unit.  Inside an
environment with numbering, such as a ‘table’ or ‘theorem’ environment,
‘\label{KEY}’ assigns to KEY the number of that environment.  Retrieve
the assigned number with the ‘\ref{KEY}’ command (*note \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, ‘\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:

‘ch’
     for chapters

‘sec’
‘subsec’
     for lower-level sectioning commands

‘fig’
     for figures

‘tab’
     for tables

‘eq’
     for equations

   In the auxiliary file the reference information is kept as the text
of a command of the form ‘\newlabel{LABEL}{{CURRENTLABEL}{PAGENUMBER}}’.
Here CURRENTLABEL is the current value of the macro ‘\@currentlabel’
that is usually updated whenever you call ‘\refstepcounter{COUNTER}’.

   Below, the key ‘sec:test’ will get the number of the current section
and the key ‘fig:test’ will get the number of the figure.
(Incidentally, put labels after captions in figures and tables.)

     \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}.


File: latex2e.info,  Node: \pageref,  Next: \ref,  Prev: \label,  Up: Cross references

7.2 ‘\pageref’
==============

Synopsis:

     \pageref{KEY}

   Produce the page number of the place in the text where the
corresponding ‘\label’{KEY} command appears.

   If there is no ‘\label{KEY}’ then you get something like ‘LaTeX
Warning: Reference `th:GrensThm' on page 1 undefined on input line 11.’

   Below, the ‘\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.)

     The main result is formula~\ref{eq:main} on page~\pageref{eq:main}.
       ...
     \begin{equation} \label{eq:main}
        \mathbf{P}=\mathbf{NP}
     \end{equation}


File: latex2e.info,  Node: \ref,  Next: xr package,  Prev: \pageref,  Up: Cross references

7.3 ‘\ref’
==========

Synopsis:

     \ref{KEY}

   Produces the number of the sectional unit, equation, footnote,
figure, ..., of the corresponding ‘\label’ command (*note \label::).  It
does not produce any text, such as the word 'Section' or 'Figure', just
the bare number itself.

   If there is no ‘\label{KEY}’ then you get something like ‘LaTeX
Warning: Reference `th:GrensThm' on page 1 undefined on input line 11.’

   In this example the ‘\ref{popular}’ produces ‘2’.  Note that it is a
forward reference since it comes before ‘\label{popular}’ so this
document would have to be compiled twice.

     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}

   The ‘cleveref’ package includes text such as ‘Theorem’ in the
reference.  See the documentation on CTAN.


File: latex2e.info,  Node: xr package,  Prev: \ref,  Up: Cross references

7.4 ‘xr’ package
================

Synopsis:

     \usepackage{xr}
       \externaldocument{DOCUMENT-BASENAME}

or

     \usepackage{xr}
       \externaldocument[REFERENCE-PREFIX]{DOCUMENT-BASENAME}

   Make cross references to the external document
‘DOCUMENT-BASENAME.tex’.

   Here is an example.  If ‘lectures.tex’ has this in the preamble

     \usepackage{xr}
       \externaldocument{exercises}
       \externaldocument[H-]{hints}
       \externaldocument{answers}

then it can use cross reference labels from the other three documents.
Suppose that ‘exercises.tex’ has an enumerated list containing this,

     \item \label{exer:EulersThm} What if every vertex has odd degree?

and ‘hints.tex’ has an enumerated list with this,

     \item \label{exer:EulersThm} Distinguish the case of two vertices.

and ‘answers.tex’ has an enumerated list with this,

     \item \label{ans:EulersThm} There is no Euler path, except if there
       are exactly two vertices.

   After compiling the exercises, hints, and answers documents, entering
this in the body of ‘lectures.tex’ will result in the lectures getting
the reference numbers used in the other documents.

     See Exercise~\ref{exer:EulersThm}, with Hint~\ref{H-exer:EulersThm}.
     The solution is Answer~\ref{ans:EulersThm}.

   The prefix ‘H-’ for the reference from the hints file is needed
because the label in the hints file is the same as the label in the
exercises file.  Without that prefix, both references would get the
number from the later file.

   Note: if the document uses the ‘hyperref’ package then in place of
‘xr’, put ‘\usepackage{xr-hyper}’ before the ‘\usepackage{hyperref}’.
Also, if any of the multiple documents uses ‘hyperref’ then they all
must use it.


File: latex2e.info,  Node: Environments,  Next: Line breaking,  Prev: Cross references,  Up: Top

8 Environments
**************

LaTeX provides many environments for delimiting certain behavior.  An
environment begins with ‘\begin’ and ends with ‘\end’, like this:

     \begin{ENVIRONMENT-NAME}
       ...
     \end{ENVIRONMENT-NAME}

   The ENVIRONMENT-NAME at the beginning must exactly match that at the
end.  For instance, the input ‘\begin{table*}...\end{table}’ will cause
an error like: ‘! LaTeX Error: \begin{table*} on input line 5 ended by
\end{table}.’

   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.


File: latex2e.info,  Node: abstract,  Next: array,  Up: Environments

8.1 ‘abstract’
==============

Synopsis:

     \begin{abstract}
     ...
     \end{abstract}

   Produce an abstract, possibly of multiple paragraphs.  This
environment is only defined in the ‘article’ and ‘report’ document
classes (*note Document classes::).

   Using the example below in the ‘article’ class produces a displayed
paragraph.  Document class option ‘titlepage’ causes the abstract to be
on a separate page (*note Document class options::); this is the default
only in the ‘report’ class.

     \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}

   The next example produces a one column abstract in a two column
document (for a more flexible solution, use the package ‘abstract’).

     \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.}
     }


File: latex2e.info,  Node: array,  Next: center,  Prev: abstract,  Up: Environments

8.2 ‘array’
===========

Synopsis:

     \begin{array}{COLS}
       COLUMN 1 ENTRY &COLUMN 2 ENTRY ... &COLUMN N ENTRY \\
       ...
     \end{array}

or:

     \begin{array}[POS]{COLS}
       COLUMN 1 ENTRY &COLUMN 2 ENTRY ... &COLUMN N ENTRY \\
       ...
     \end{array}

   Produce a mathematical array.  This environment can only be used in
math mode (*note Modes::), and normally appears within a displayed
mathematics environment such as ‘equation’ (*note equation::).  Inside
of each row the column entries are separated by an ampersand, (‘&’).
Rows are terminated with double-backslashes (*note \\::).

   This example shows a three by three array.

     \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*}

   The required argument COLS describes the number of columns, their
alignment, and the formatting of the intercolumn regions.  For instance,
‘\begin{array}{rcl}...\end{array}’ gives three columns: the first flush
right, the second centered, and the third flush left.  See *note
tabular:: for the complete description of COLS and of the other common
features of the two environments, including the optional POS argument.

   There are two ways that ‘array’ diverges from ‘tabular’.  The first
is that ‘array’ entries are typeset in math mode, in textstyle (*note
Math styles::) except if the COLS definition specifies the column with
‘p{...}’, which causes the entry to be typeset in text mode.  The second
is that, instead of ‘tabular’'s parameter ‘\tabcolsep’, LaTeX's
intercolumn space in an ‘array’ is governed by ‘\arraycolsep’, which
gives half the width between columns.  The default for this is ‘5pt’ so
that between two columns comes 10pt of space.

   To obtain arrays with braces the standard is to use the ‘amsmath’
package.  It comes with environments ‘pmatrix’ for an array surrounded
by parentheses ‘(...)’, ‘bmatrix’ for an array surrounded by square
brackets ‘[...]’, ‘Bmatrix’ for an array surrounded by curly
braces ‘{...}’, ‘vmatrix’ for an array surrounded by vertical
bars ‘|...|’, and ‘Vmatrix’ for an array surrounded by double vertical
bars ‘||...||’, along with a number of other array constructs.

   The next example uses the ‘amsmath’ package.

     \usepackage{amsmath}  % in preamble

     \begin{equation}
       \begin{vmatrix}{cc}  % array with vert lines
         a  &b \\
         c  &d
       \end{vmatrix}=ad-bc
     \end{equation}

   There are many packages concerning arrays.  The ‘array’ package has
many useful extensions, including more column types.  The ‘dcolumn’
package adds a column type to center on a decimal point.  For both see
the documentation on CTAN.


File: latex2e.info,  Node: center,  Next: description,  Prev: array,  Up: Environments

8.3 ‘center’
============

Synopsis:

     \begin{center}
       LINE1 \\
       LINE2 \\
       ...
     \end{center}

   Create a new paragraph consisting of a sequence of lines that are
centered within the left and right margins.  Use double-backslash, ‘\\’,
to get a line break (*note \\::).  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
*note \centering:: to avoid such space, for example inside a ‘figure’
environment.

   This example produces three centered lines.  There is extra vertical
space between the last two lines.

     \begin{center}
       A Thesis Submitted in Partial Fufillment \\
       of the Requirements of \\[0.5ex]
       the School of Environmental Engineering
     \end{center}

   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.

     \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}

   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 ‘center’ environment.


File: latex2e.info,  Node: \centering,  Up: center

8.3.1 ‘\centering’
------------------

Synopsis:

     {\centering ... }

or

     \begin{group}
       \centering ...
     \end{group}

   Center the material in its scope.  It is most often used inside an
environment such as ‘figure’, or in a ‘parbox’.

   This example's ‘\centering’ declaration causes the graphic to be
horizontally centered.

     \begin{figure}
       \centering
       \includegraphics[width=0.6\textwidth]{ctan_lion.png}
       \caption{CTAN Lion}  \label{fig:CTANLion}
     \end{figure}

The scope of this ‘\centering’ ends with the ‘\end{figure}’.

   Unlike the ‘center’ environment, the ‘\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 ‘ww {\centering xx \\ yy} zz’ is surrounded
by blank lines then LaTeX will create a paragraph whose first line ‘ww
xx’ is centered and whose second line, not centered, contains ‘yy zz’.
Usually what is desired is for the scope of the declaration to contain a
blank line or the ‘\end’ command of an environment such as ‘figure’ or
‘table’ that ends the paragraph unit.  Thus, if ‘{\centering xx \\
yy\par} zz’ is surrounded by blank lines then it makes a new paragraph
with two centered lines ‘xx’ and ‘yy’, followed by a new paragraph with
‘zz’ that is formatted as usual.


File: latex2e.info,  Node: description,  Next: displaymath,  Prev: center,  Up: Environments

8.4 ‘description’
=================

Synopsis:

     \begin{description}
       \item[LABEL OF FIRST ITEM] TEXT OF FIRST ITEM
       \item[LABEL OF SECOND ITEM] TEXT OF SECOND ITEM
        ...
     \end{description}

   Environment to make a list of labeled items.  Each item's 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 ‘Something's wrong--perhaps a missing
\item’.

   This example shows the environment used for a sequence of
definitions.

     \begin{description}
       \item[lama] A priest.
       \item[llama] A beast.
     \end{description}

The labels ‘lama’ and ‘llama’ are output in boldface, with the left edge
on the left margin.

   Start list items with the ‘\item’ command (*note \item::).  Use the
optional labels, as in ‘\item[Main point]’, because there is no sensible
default.  Following the ‘\item’ is optional text, which may contain
multiple paragraphs.

   Since the labels are in bold style, if the label text calls for a
font change given in argument style (see *note Font styles::) then it
will come out bold.  For instance, if the label text calls for
typewriter with ‘\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:
‘\item[{\tt label text}]’.  Similarly, get the standard roman font with
‘\item[{\rm label text}]’.

   For other major LaTeX labelled list environments, see *note itemize::
and *note enumerate::.  Unlike those environments, nesting ‘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 *note
list::.  The package ‘enumitem’ is useful for customizing lists.

   This example changes the description labels to small caps.

     \renewcommand{\descriptionlabel}[1]{%
       {\hspace{\labelsep}\textsc{#1}}}


File: latex2e.info,  Node: displaymath,  Next: document,  Prev: description,  Up: Environments

8.5 ‘displaymath’
=================

Synopsis:

     \begin{displaymath}
       MATHEMATICAL TEXT
     \end{displaymath}

   Environment to typeset the MATHEMATICAL TEXT on its own line, in
display style and centered.  To make the text be flush-left use the
global option ‘fleqn’; see *note Document class options::.

   In the ‘displaymath’ environment no equation number is added to the
math text.  One way to get an equation number is to use the ‘equation’
environment (*note equation::).

   LaTeX will not break the MATH TEXT across lines.

   Note that the ‘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 ‘\[ MATH \]’ is a synonym for the environment
‘\begin{displaymath} MATH \end{displaymath}’ but the latter is easier to
work with in the source; for instance, searching for a square bracket
may get false positives but the word ‘displaymath’ will likely be
unique.

   The construct ‘$$MATH$$’ from Plain TeX is sometimes used as a
synonym for LaTeX's ‘displaymath’.  It is not a synonym, and is not
officially supported in LaTeX at all; ‘$$’ doesn't support the ‘fleqn’
option (*note Document class options::), has different vertical spacing,
and doesn't perform consistency checks.

   The output from this example is centered and alone on its line.

     \begin{displaymath}
       \int_1^2 x^2\,dx=7/3
     \end{displaymath}

Also, the integral sign is larger than the inline version ‘\( \int_1^2
x^2\,dx=7/3 \)’ produces.


File: latex2e.info,  Node: document,  Next: enumerate,  Prev: displaymath,  Up: Environments

8.6 ‘document’
==============

The ‘document’ environment encloses the entire body of a document.  It
is required in every LaTeX document.  *Note Starting and ending::.

* Menu:

* \AtBeginDocument::          Hook for commands at the start of the document.
* \AtEndDocument::            Hook for commands at the end of the document.


File: latex2e.info,  Node: \AtBeginDocument,  Next: \AtEndDocument,  Up: document

8.6.1 ‘\AtBeginDocument’
------------------------

Synopsis:

     \AtBeginDocument{CODE}

   Save CODE and execute it when ‘\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.


File: latex2e.info,  Node: \AtEndDocument,  Prev: \AtBeginDocument,  Up: document

8.6.2 ‘\AtEndDocument’
----------------------

Synopsis:

     \AtEndDocument{CODE}

   Save CODE and execute it near the end of the document.  Specifically,
it is executed when ‘\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 ‘\clearpage’ at the appropriate point in CODE.

   You can issue this command more than once; the successive code lines
will be executed in the order that you gave them.


File: latex2e.info,  Node: enumerate,  Next: eqnarray,  Prev: document,  Up: Environments

8.7 ‘enumerate’
===============

Synopsis:

     \begin{enumerate}
       \item[OPTIONAL LABEL OF FIRST ITEM] TEXT OF FIRST ITEM
       \item[OPTIONAL LABEL OF SECOND ITEM] TEXT OF SECOND ITEM
       ...
     \end{enumerate}

   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 ‘1.’, ‘2.’, etc.  Each
‘enumerate’ list environment must have at least one item; having none
causes the LaTeX error ‘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 ‘1.’ and
‘2.’.

     \begin{enumerate}
      \item Johnny Hayes (USA)
      \item Charles Hefferon (RSA)
     \end{enumerate}

   Start list items with the ‘\item’ command (*note \item::).  If you
give ‘\item’ an optional argument by following it with square brackets,
as in ‘\item[Interstitial label]’, then the next item will continue the
interrupted sequence (*note \item::).  That is, you will get labels like
‘1.’, then ‘Interstitial label’, then ‘2.’.  Following the ‘\item’ is
optional text, which may contain multiple paragraphs.

   Enumerations may be nested within other ‘enumerate’ environments, or
within any paragraph-making environment such as ‘itemize’ (*note
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.

  1. arabic number followed by a period: ‘1.’, ‘2.’, ...
  2. lowercase letter inside parentheses: ‘(a)’, ‘(b)’ ...
  3. lowercase roman numeral followed by a period: ‘i.’, ‘ii.’, ...
  4. uppercase letter followed by a period: ‘A.’, ‘B.’, ...

   The ‘enumerate’ environment uses the counters ‘\enumi’ through
‘\enumiv’ (*note Counters::).

   For other major LaTeX labeled list environments, see *note
description:: and *note itemize::.  For information about list layout
parameters, including the default values, and for information about
customizing list layout, see *note list::.  The package ‘enumitem’ is
useful for customizing lists.

   To change the format of the label use ‘\renewcommand’ (*note
\newcommand & \renewcommand::) on the commands ‘\labelenumi’ through
‘\labelenumiv’.  For instance, this first level list will be labelled
with uppercase letters, in boldface, and without a trailing period.

     \renewcommand{\labelenumi}{\textbf{\Alph{enumi}}}
     \begin{enumerate}
       \item Shows as boldface A
       \item Shows as boldface B
     \end{enumerate}

   For a list of counter-labeling commands see *note \alph \Alph \arabic
\roman \Roman \fnsymbol::.


File: latex2e.info,  Node: eqnarray,  Next: equation,  Prev: enumerate,  Up: Environments

8.8 ‘eqnarray’
==============

The ‘eqnarray’ environment is obsolete.  It has infelicities, including
spacing that is inconsistent with other mathematics elements.  (See
"Avoid eqnarray!" by Lars Madsen
<https://tug.org/TUGboat/tb33-1/tb103madsen.pdf>).  New documents should
include the ‘amsmath’ package and use the displayed mathematics
environments provided there, such as the ‘align’ environment.  We
include a description only for completeness and for working with old
documents.

   Synopsis:

     \begin{eqnarray}
       FIRST FORMULA LEFT  &FIRST FORMULA MIDDLE  &FIRST FORMULA RIGHT \\
       ...
     \end{eqnarray}

or

     \begin{eqnarray*}
       FIRST FORMULA LEFT  &FIRST FORMULA MIDDLE  &FIRST FORMULA RIGHT \\
       ...
     \end{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 ‘array’ environment, with items
within a row separated by an ampersand (‘&’), and with rows separated by
double backslash  ‘\\’).  The starred form of line break (‘\\*’) can
also be used to separate equations, and will disallow a page break there
(*note \\::).

   The unstarred form ‘eqnarray’ places an equation number on every line
(using the ‘equation’ counter), unless that line contains a ‘\nonumber’
command.  The starred form ‘eqnarray*’ omits equation numbering, while
otherwise being the same.

   The command ‘\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.

     \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*}


File: latex2e.info,  Node: equation,  Next: figure,  Prev: eqnarray,  Up: Environments

8.9 ‘equation’
==============

Synopsis:

     \begin{equation}
       MATHEMATICAL TEXT
     \end{equation}

   The same as a ‘displaymath’ environment (*note displaymath::) except
that LaTeX puts an equation number flush to the right margin.  The
equation number is generated using the ‘equation’ counter.

   You should have no blank lines between ‘\begin{equation}’ and
‘\end{equation}’, or LaTeX will tell you that there is a missing dollar
sign.

   The package ‘amsmath’ package has extensive displayed equation
facilities.  New documents should include this package.


File: latex2e.info,  Node: figure,  Next: filecontents,  Prev: equation,  Up: Environments

8.10 ‘figure’
=============

Synopsis:

     \begin{figure}[PLACEMENT]
       FIGURE BODY
       \caption[LOFTITLE]{TITLE}  % optional
       \label{LABEL}              % optional
     \end{figure}

or:

     \begin{figure*}[PLACEMENT]
       FIGURE BODY
       \caption[LOFTITLE]{TITLE}  % optional
       \label{LABEL}              % optional
     \end{figure*}

   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 (*note Floats::).

   The FIGURE BODY can consist of imported graphics (*note Graphics::),
or text, LaTeX commands, etc.  It is typeset in a ‘parbox’ of width
‘\textwidth’.

   The possible values of PLACEMENT are ‘h’ for ‘here’, ‘t’ for ‘top’,
‘b’ for ‘bottom’, and ‘p’ for ‘on a separate page of floats’.  For the
effect of these options on the float placement algorithm, see *note
Floats::.

   The starred form ‘figure*’ is used when a document is in
double-column mode (*note \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 PLACEMENT ‘b’ in *note
Floats::.

   The label is optional; it is used for cross references (*note Cross
references::).  The optional ‘\caption’ command specifies caption text
for the figure (*note \caption::).  By default it is numbered.  If
LOFTITLE is present, it is used in the list of figures instead of TITLE
(*note 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.

     \usepackage{graphicx}  % in preamble
       ...
     \begin{figure}[t]
       \centering
       \includegraphics[width=0.5\textwidth]{CTANlion.png}
       \caption{The CTAN lion, by Duane Bibby}
     \end{figure}


File: latex2e.info,  Node: filecontents,  Next: flushleft,  Prev: figure,  Up: Environments

8.11 ‘filecontents’
===================

Synopsis:

     \begin{filecontents}[OPTION]{FILENAME}
       TEXT
     \end{filecontents}

or

     \begin{filecontents*}[OPTION]{FILENAME}
       TEXT
     \end{filecontents*}

   Create a file named FILENAME in the current directory (or the output
directory, if specified; *note output directory::) and write TEXT to it.
By default, an existing file is not overwritten.

   The unstarred version of the environment ‘filecontents’ prefixes the
content of the created file with a header of TeX comments; see the
example below.  The starred version ‘filecontents*’ does not include the
header.

   The possible options are:

‘force’
‘overwrite’
     Overwrite an existing file.

‘noheader’
     Omit the header.  Equivalent to using ‘filecontents*’.

‘nosearch’
     Only check the current directory (and the output directory, if
     specified) for an existing file, not the entire search path.

   These options were added in a 2019 release of LaTeX.

   This environment can be used anywhere in the preamble, although it
often appears before the ‘\documentclass’ command.  It is commonly used
to create a ‘.bib’ or other such data file from the main document
source, to make the source file self-contained.  Similarly, it can be
used to create a custom style or class file, again making the source
self-contained.

   For example, this document:

     \documentclass{article}
     \begin{filecontents}{JH.sty}
     \newcommand{\myname}{Jim Hef{}feron}
     \end{filecontents}
     \usepackage{JH}
     \begin{document}
     Article by \myname.
     \end{document}

produces this file ‘JH.sty’:

     %% LaTeX2e file `JH.sty'
     %% generated by the `filecontents' environment
     %% from source `test' on 2015/10/12.
     %%
     \newcommand{\myname}{Jim Hef{}feron}


File: latex2e.info,  Node: flushleft,  Next: flushright,  Prev: filecontents,  Up: Environments

8.12 ‘flushleft’
================

Synopsis:

     \begin{flushleft}
       LINE1 \\
       LINE2 \\
       ...
     \end{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 interword spaces.  To force a new line use a
double backslash, ‘\\’.  For the declaration form see *note
\raggedright::.

   This creates a box of text that is at most 3 inches wide, with the
text flush left and ragged right.

     \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}

* Menu:

* \raggedright::        Declaration form of the ‘flushleft’ environment.


File: latex2e.info,  Node: \raggedright,  Up: flushleft

8.12.1 ‘\raggedright’
---------------------

Synopses:

     {\raggedright  ... }

or

     \begin{ENVIRONMENT} \raggedright
       ...
     \end{ENVIRONMENT}

   A declaration which causes lines to be flush to the left margin and
ragged right.  It can be used inside an ENVIRONMENT such as ‘quote’ or
in a ‘parbox’.  For the environment form see *note flushleft::.

   Unlike the ‘flushleft’ environment, the ‘\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 ‘\end’ command that ends the
paragraph unit.

   Here ‘\raggedright’ in each second column keeps LaTeX from doing
awkward typesetting to fit the text into the narrow column.  Note that
‘\raggedright’ is inside the curly braces ‘{...}’ to delimit its effect.

     \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}


File: latex2e.info,  Node: flushright,  Next: itemize,  Prev: flushleft,  Up: Environments

8.13 ‘flushright’
=================

     \begin{flushright}
       LINE1 \\
       LINE2 \\
       ...
     \end{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 inter-word spaces.  To force a
new line use a double backslash, ‘\\’.  For the declaration form
see *note \raggedleft::.

   For an example related to this environment, see *note flushleft::,
where one just have mutatis mutandis to replace ‘flushleft’ by
‘flushright’.

* Menu:

* \raggedleft::   Declaration form of the ‘flushright’ environment.


File: latex2e.info,  Node: \raggedleft,  Up: flushright

8.13.1 ‘\raggedleft’
--------------------

Synopses:

     {\raggedleft  ... }

or

     \begin{ENVIRONMENT} \raggedleft
       ...
     \end{ENVIRONMENT}

   A declaration which causes lines to be flush to the right margin and
ragged left.  It can be used inside an ENVIRONMENT such as ‘quote’ or in
a ‘parbox’.  For the environment form see *note flushright::.

   Unlike the ‘flushright’ environment, the ‘\raggedleft’ command does
not start a new paragraph; it only changes how LaTeX formats paragraph
units.  To affect a paragraph unit's formatting, the scope of the
declaration must contain the blank line or ‘\end’ command that ends the
paragraph unit.

   *Note \raggedright::, for an example related to this environment;
just replace ‘\raggedright’ there by ‘\raggedleft’.


File: latex2e.info,  Node: itemize,  Next: letter,  Prev: flushright,  Up: Environments

8.14 ‘itemize’
==============

Synopsis:

     \begin{itemize}
       \item[OPTIONAL LABEL OF FIRST ITEM] TEXT OF FIRST ITEM
       \item[OPTIONAL LABEL OF SECOND ITEM] TEXT OF SECOND ITEM
       ...
     \end{itemize}

   Produce an “unordered list”, sometimes called a bullet list.  There
must be at least one ‘\item’ within the environment; having none causes
the LaTeX error ‘Something's wrong--perhaps a missing \item’.

   This gives a two-item list.

     \begin{itemize}
      \item Pencil and watercolor sketch by Cassandra
      \item Rice portrait
     \end{itemize}

With the default locale--without loading e.g. ‘babel’ package with
another language than USenglish--as a top-level list each label would
come out as a bullet, •.  The format of the labeling depends on the
nesting level; see below.

   Start list items with the ‘\item’ command (*note \item::).  If you
give ‘\item’ an optional argument by following it with square brackets,
as in ‘\item[OPTIONAL LABEL]’, then by default OPTIONAL LABEL will
appear in bold and be flush right, so it could extend into the left
margin.  For labels that are flush left see the *note description::
environment.  Following the ‘\item’ is the text of the item, which may
be empty or contain multiple paragraphs.

   Unordered lists can be nested within one another, up to four levels
deep.  They can also be nested within other paragraph-making
environments, such as ‘enumerate’ (*note enumerate::).

   The ‘itemize’ environment uses the commands ‘\labelitemi’ through
‘\labelitemiv’ to produce the default label (note 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.

  1. • (bullet, from ‘\textbullet’)
  2. -- (bold en-dash, from ‘\normalfont\bfseries\textendash’)
  3. * (asterisk, from ‘\textasteriskcentered’)
  4. .  (vertically centered dot, rendered here as a period, from
     ‘\textperiodcentered’)

   Change the labels with ‘\renewcommand’.  For instance, this makes the
first level use diamonds.

     \renewcommand{\labelitemi}{$\diamond$}

   The distance between the left margin of the enclosing environment and
the left margin of the ‘itemize’ list is determined by the parameters
‘\leftmargini’ through ‘\leftmarginvi’.  (This also uses the convention
of using lowercase roman numerals a the end of the command name to
denote the nesting level.)  The defaults are: ‘2.5em’ in level 1 (‘2em’
in two-column mode), ‘2.2em’ in level 2, ‘1.87em’ in level 3, and
‘1.7em’ in level 4, with smaller values for more deeply nested levels.

   For other major LaTeX labeled list environments, see *note
description:: and *note enumerate::.  The ‘itemize’, ‘enumerate’ and
‘description’ environment use the same list layout parameters.  For a
description, including the default values, and for information about
customizing list layout, see *note list::.  The package ‘enumitem’ is
useful for customizing lists.

   This example greatly reduces the margin space for outermost itemized
lists.

     \setlength{\leftmargini}{1.25em} % default 2.5em

   Especially for lists with short items, it may be desirable to elide
space between items.  Here is an example defining an ‘itemize*’
environment with no extra spacing between items, or between paragraphs
within a single item (‘\parskip’ is not list-specific, *note \parindent
& \parskip::):

     \newenvironment{itemize*}%
       {\begin{itemize}%
         \setlength{\itemsep}{0pt}%
         \setlength{\parsep}{0pt}%
         \setlength{\parskip}{0pt}%
       }%
       {\end{itemize}}


File: latex2e.info,  Node: letter,  Next: list,  Prev: itemize,  Up: Environments

8.15 ‘letter’ environment: writing letters
==========================================

This environment is used for creating letters.  *Note Letters::.


File: latex2e.info,  Node: list,  Next: math,  Prev: letter,  Up: Environments

8.16 ‘list’
===========

Synopsis:

     \begin{list}{LABELING}{SPACING}
       \item[OPTIONAL LABEL OF FIRST ITEM] TEXT OF FIRST ITEM
       \item[OPTIONAL LABEL OF SECOND ITEM] TEXT OF SECOND ITEM
       ...
     \end{list}

   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 ‘description’, ‘enumerate’, and ‘itemize’ environments
(*note description::, *note enumerate::, and *note itemize::).

   Instead, the ‘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 ‘list’, including ‘quotation’,
‘quote’, and ‘center’ (*note quotation & quote::, *note center::).

   This uses the ‘list’ environment to define a new custom environment.

     \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}

   The mandatory first argument LABELING specifies the default labeling
of list items.  It can contain text and LaTeX commands, as above where
it contains both ‘Item’ and ‘\Roman{...}’.  LaTeX forms the label by
putting the LABELING argument in a box of width ‘\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 ‘\item’ an optional argument by including square
braces and the text, as in the above ‘\item[Special label.]’; *note
\item::.

   The mandatory second argument SPACING has a list of commands.  This
list can be empty.  A command that can go in here is
‘\usecounter{COUNTERNAME}’ (*note \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 ‘\item’ that does not
have an optional argument.

   Another command that can go in SPACING is ‘\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 (*note
Modes::).  One example of changing its definition is that to the above
‘named’ example, before the definition of the environment add
‘\newcommand{\namedmakelabel}[1]{\textsc{#1}}’, and between the
‘\setlength’ command and the parenthesis that closes the SPACING
argument also add ‘\let\makelabel\namedmakelabel’.  Then the labels will
be typeset in small caps.  Similarly, changing the second code line to
‘\let\makelabel\fbox’ puts the labels inside a framed box.  Another
example of the ‘\makelabel’ command is below, in the definition of the
‘redlabel’ environment.

   Also often in 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 ‘itemize’ can be
different than the values shown here.)  See also the figure that follows
the list.  Each is a length (*note Lengths::).  The vertical spaces are
normally rubber lengths, with ‘plus’ and ‘minus’ components, to give TeX
flexibility in setting the page.  Change each with a command such as
‘\setlength{\itemsep}{2pt plus1pt minus1pt}’.  For some effects these
lengths should be zero or negative.

‘\itemindent’
     Extra horizontal space indentation, beyond ‘leftmargin’, of the
     first line each item.  Its default value is ‘0pt’.

‘\itemsep’
     Vertical space between items, beyond the ‘\parsep’.  The defaults
     for the first three levels in LaTeX's ‘article’, ‘book’, and
     ‘report’ classes at 10 point size are: ‘4pt plus2pt minus1pt’,
     ‘\parsep’ (that is, ‘2pt plus1pt minus1pt’), and ‘\topsep’ (that
     is, ‘2pt plus1pt minus1pt’).  The defaults at 11 point are: ‘4.5pt
     plus2pt minus1pt’, ‘\parsep’ (that is, ‘2pt plus1pt minus1pt’), and
     ‘\topsep’ (that is, ‘2pt plus1pt minus1pt’).  The defaults at 12
     point are: ‘5pt plus2.5pt minus1pt’, ‘\parsep’ (that is, ‘2.5pt
     plus1pt minus1pt’), and ‘\topsep’ (that is, ‘2.5pt plus1pt
     minus1pt’).

‘\labelsep’
     Horizontal space between the label and text of an item.  The
     default for LaTeX's ‘article’, ‘book’, and ‘report’ classes is
     ‘0.5em’.

‘\labelwidth’
     Horizontal width.  The box containing the label is nominally this
     wide.  If ‘\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 ‘\makelabel’ returns text of width less than or
     equal to ‘\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
     ‘\leftmargin’+‘\itemindent’-‘\labelsep’-‘\labelwidth’ from the left
     margin of the enclosing environment.

     The default for LaTeX's ‘article’, ‘book’, and ‘report’ classes at
     the top level is ‘\leftmargini’-‘\labelsep’, (which is ‘2em’ in one
     column mode and ‘1.5em’ in two column mode).  At the second level
     it is ‘\leftmarginii’-‘\labelsep’, and at the third level it is
     ‘\leftmarginiii’-‘\labelsep’.  These definitions make the label's
     left edge coincide with the left margin of the enclosing
     environment.

‘\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 ‘\leftmargini’, while a list that is nested
     inside a top-level list has this margin set to ‘\leftmarginii’.
     More deeply nested lists get the values of ‘\leftmarginiii’ through
     ‘\leftmarginvi’.  (Nesting greater than level five generates the
     error message ‘Too deeply nested’.)

     The defaults for the first three levels in LaTeX's ‘article’,
     ‘book’, and ‘report’ classes are: ‘\leftmargini’ is ‘2.5em’ (in two
     column mode, ‘2em’), ‘\leftmarginii’ is ‘2.2em’, and
     ‘\leftmarginiii’ is ‘1.87em’.

‘\listparindent’
     Horizontal space of additional line indentation, beyond
     ‘\leftmargin’, for second and subsequent paragraphs within a list
     item.  A negative value makes this an "outdent".  Its default value
     is ‘0pt’.

‘\parsep’
     Vertical space between paragraphs within an item.  The defaults for
     the first three levels in LaTeX's ‘article’, ‘book’, and ‘report’
     classes at 10 point size are: ‘4pt plus2pt minus1pt’, ‘2pt plus1pt
     minus1pt’, and ‘0pt’.  The defaults at 11 point size are: ‘4.5pt
     plus2pt minus1pt’, ‘2pt plus1pt minus1pt’, and ‘0pt’.  The defaults
     at 12 point size are: ‘5pt plus2.5pt minus1pt’, ‘2.5pt plus1pt
     minus1pt’, and ‘0pt’.

‘\partopsep’
     Vertical space added, beyond ‘\topsep’+‘\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 ‘article’,
     ‘book’, and ‘report’ classes at 10 point size are: ‘2pt plus1
     minus1pt’, ‘2pt plus1pt minus1pt’, and ‘1pt plus0pt minus1pt’.  The
     defaults at 11 point are: ‘3pt plus1pt minus1pt’, ‘3pt plus1pt
     minus1pt’, and ‘1pt plus0pt minus1pt’).  The defaults at 12 point
     are: ‘3pt plus2pt minus3pt’, ‘3pt plus2pt minus2pt’, and ‘1pt
     plus0pt minus1pt’.

‘\rightmargin’
     Horizontal space between the right margin of the list and the right
     margin of the enclosing environment.  Its default value is ‘0pt’.
     It must be non-negative.

‘\topsep’
     Vertical space added to both the top and bottom of the list, in
     addition to ‘\parskip’ (*note \parindent & \parskip::).  The
     defaults for the first three levels in LaTeX's ‘article’, ‘book’,
     and ‘report’ classes at 10 point size are: ‘8pt plus2pt minus4pt’,
     ‘4pt plus2pt minus1pt’, and ‘2pt plus1pt minus1pt’.  The defaults
     at 11 point are: ‘9pt plus3pt minus5pt’, ‘4.5pt plus2pt minus1pt’,
     and ‘2pt plus1pt minus1pt’.  The defaults at 12 point are: ‘10pt
     plus4pt minus6pt’, ‘5pt plus2.5pt minus1pt’, and ‘2.5pt plus1pt
     minus1pt’.

   This shows the horizontal and vertical distances.