diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.texi')
-rw-r--r-- | Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.texi | 2666 |
1 files changed, 2277 insertions, 389 deletions
diff --git a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.texi b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.texi index e1c96ee6755..7cba667c8ed 100644 --- a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.texi +++ b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.texi @@ -1,8 +1,8 @@ \input texinfo -@c $Id: latex2e.texi 578 2017-08-06 00:04:43Z jimhefferon $ +@c $Id: latex2e.texi 613 2018-03-21 18:48:08Z jimhefferon $ @comment %**start of header (This is for running Texinfo on a region.) @setfilename latex2e.info -@set UPDATED August 2017 +@set UPDATED March 2018 @include common.texi @settitle @LaTeX{}2e unofficial reference manual (@value{UPDATED}) @comment %**end of header (This is for running Texinfo on a region.) @@ -11,9 +11,6 @@ @c xx but latex2e stuff is missing. @c xx random list of a few of the missing items is at the end of this file @c -@c xx misc commands from clsguide.pdf: \ignorespacesafterend, -@c \normalsfcodes -@c xx color (include info from clsguide.pdf) @c xx ending a run with errors @c xx ctan, distributions, components of TeX @c xx classes and packages -- required, additional, useful; oberdiek; fonts @@ -24,6 +21,7 @@ @c xx merge latex-manual from savannah @c xx merge display style math @c xx vertical mode, horizontal mode +@c xx JH Discuss restricted execution @c @c xx The typeset source2e has an index with all kernel @c xx commands, though some are internal and shouldn't be included. @@ -47,7 +45,7 @@ Group as @cite{@TeX{}niques} number 10), as reference material (no text was directly copied). Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, -2014, 2015, 2016, 2017 Karl Berry.@* +2014, 2015, 2016, 2017, 2018 Karl Berry.@* Copyright 1988, 1994, 2007 Stephen Gilmore.@* Copyright 1994, 1995, 1996 Torsten Martinsen. @@ -102,9 +100,6 @@ into another language, under the above conditions for modified versions. @macro BESU {utf8,math} @code{@backslashchar{}\math\} @end macro -@macro iftexthenelse {then,else} -\then\@c -@end macro @end iftex @ifnottex @macro BES {utf8,math} @@ -113,28 +108,22 @@ into another language, under the above conditions for modified versions. @macro BESU {utf8,math} @U{\utf8\} @end macro -@macro iftexthenelse {then,else} -\else\@c -@end macro @end ifnottex @macro EnvIndex {env} @findex @r{environment}, @code{\env\} @findex @code{\env\} @r{environment} + @end macro @macro PkgIndex {pkg} @cindex @r{package}, @code{\pkg\} @cindex @code{\pkg\} @r{package} + @end macro @set NotInPlainTeX Not available in plain @TeX{}. @set NeedsAMSSymb @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{amssymb} package. @set NeedsSTIX @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{stix} package. -@clear HAS-MATH -@iftex -@set HAS-MATH -@end iftex - @node Top @top @LaTeX{}2e: An unofficial reference manual @@ -162,6 +151,8 @@ This document is an unofficial reference manual (version of * Page styles:: Various styles of page layout. * Spaces:: Horizontal and vertical space. * Boxes:: Making boxes. +* Color:: Defining and using colors. +* Graphics:: Importing graphics from outside @LaTeX{}. * Special insertions:: Inserting reserved and special characters. * Splitting the input:: Dealing with big files by splitting. * Front/back matter:: Tables of contents, glossaries, indexes. @@ -815,8 +806,9 @@ When using one of the engines pdf@LaTeX{}, Lua@LaTeX{}, or Xe@LaTeX{} (@pxref{@TeX{} engines}), options other than @code{letterpaper} set the print area but you must also set the physical paper size. One way to do that is to put @code{\pdfpagewidth=\paperwidth} and -@code{\pdfpageheight=\paperheight} in your document's preamble. The -@code{geometry} package provides flexible ways of setting the print +@code{\pdfpageheight=\paperheight} in your document's preamble. +@PkgIndex{geometry} +The @code{geometry} package provides flexible ways of setting the print area and physical page size. @findex draft @r{option} @@ -1654,7 +1646,7 @@ formulas. @code{\mathversion@{normal@}} restores the default. Finally, the command @code{\oldstylenums@{@var{numerals}@}} will typeset so-called ``old-style'' numerals, which have differing heights and depths (and sometimes widths) from the standard ``lining'' numerals, -which all have the same height as upper-case letters. @LaTeX{}'s +which all have the same height as uppercase letters. @LaTeX{}'s default fonts support this, and will respect @code{\textbf} (but not other styles; there are no italic old-style numerals in Computer Modern). Many other fonts have old-style numerals also; sometimes the @@ -1738,7 +1730,8 @@ Knuth's original encoding for Computer Modern (the default), and @code{T1}, also known as the Cork encoding, which has support for the accented characters used by the most widespread European languages (German, French, Italian, Polish and others), which allows @TeX{} to -hyphenate words containing accented letters. +hyphenate words containing accented letters. For more, see +@url{https://ctan.org/pkg/encguide}. @item \fontfamily@{@var{family}@} @findex \fontfamily @@ -1749,30 +1742,49 @@ Select the font family. The web page through many of the fonts easily used with @LaTeX{}. Here are examples of some common families: -@c Sorry about the ugly @t{@ }. The idea is to make the lists line up -@c in Info. Since the items are so short, it seems nice to have them -@c on the same line instead of using @table. - -@itemize @w{} -@item @code{pag}@t{@ } Avant Garde -@item @code{fvs}@t{@ } Bitstream Vera Sans -@item @code{pbk}@t{@ } Bookman -@item @code{bch}@t{@ } Charter -@item @code{ccr}@t{@ } Computer Concrete -@item @code{cmr}@t{@ } Computer Modern -@item @code{pcr}@t{@ } Courier -@item @code{phv}@t{@ } Helvetica -@item @code{fi4}@t{@ } Inconsolata -@item @code{lmr}@t{@ } Latin Modern -@item @code{lmss} Latin Modern Sans -@item @code{lmtt} Latin Modern Typewriter -@item @code{pnc}@t{@ } New Century Schoolbook -@item @code{ppl}@t{@ } Palatino -@item @code{ptm}@t{@ } Times -@item @code{uncl} Uncial -@item @code{put}@t{@ } Utopia -@item @code{pzc}@t{@ } Zapf Chancery -@end itemize +@multitable {font} {Computer Modern Typewriter XXXX} +@item @code{pag} +@tab Avant Garde +@item @code{fvs} +@tab Bitstream Vera Sans +@item @code{pbk} +@tab Bookman +@item @code{bch} +@tab Charter +@item @code{ccr} +@tab Computer Concrete +@item @code{cmr} +@tab Computer Modern +@item @code{cmss} +@tab Computer Modern Sans Serif +@item @code{cmtt} +@tab Computer Modern Typewriter +@item @code{pcr} +@tab Courier +@item @code{phv} +@tab Helvetica +@item @code{fi4} +@tab Inconsolata +@item @code{lmr} +@tab Latin Modern +@item @code{lmss} +@tab Latin Modern Sans +@item @code{lmtt} +@tab Latin Modern Typewriter +@item @code{pnc} +@tab New Century Schoolbook +@item @code{ppl} +@tab Palatino +@item @code{ptm} +@tab Times +@item @code{uncl} +@tab Uncial +@item @code{put} +@tab Utopia +@item @code{pzc} +@tab Zapf Chancery +@end multitable + @item \fontseries@{@var{series}@} @findex \fontseries @@ -1781,44 +1793,69 @@ Select the font series. A @dfn{series} combines a @dfn{weight} and a @dfn{width}. Typically, a font supports only a few of the possible combinations. Some common combined series values include: -@itemize @w{} -@item @code{m}@t{@ } Medium (normal) -@item @code{b}@t{@ } Bold -@item @code{c}@t{@ } Condensed -@item @code{bc} Bold condensed -@item @code{bx} Bold extended -@end itemize +@multitable {xx} {Medium (normal)xx} +@item @code{m} +@tab Medium (normal) +@item @code{b} +@tab Bold +@item @code{c} +@tab Condensed +@item @code{bc} +@tab Bold condensed +@item @code{bx} +@tab Bold extended +@end multitable @cindex weights, of fonts The possible values for weight, individually, are: -@itemize @w{} -@item @code{ul} Ultra light -@item @code{el} Extra light -@item @code{l}@t{@ } Light -@item @code{sl} Semi light -@item @code{m}@t{@ } Medium (normal) -@item @code{sb} Semi bold -@item @code{b}@t{@ } Bold -@item @code{eb} Extra bold -@item @code{ub} Ultra bold -@end itemize +@multitable {xx} {Medium (normal) xx} +@item @code{ul} +@tab Ultra light +@item @code{el} +@tab Extra light +@item @code{l} +@tab Light +@item @code{sl} +@tab Semi light +@item @code{m} +@tab Medium (normal) +@item @code{sb} +@tab Semi bold +@item @code{b} +@tab Bold +@item @code{eb} +@tab Extra bold +@item @code{ub} +@tab Ultra bold +@end multitable @cindex widths, of fonts -The possible values for width, individually, are (the percentages -are just guides and are not followed precisely by all fonts): - -@itemize @w{} -@item @code{uc} Ultra condensed, 50% -@item @code{ec} Extra condensed, 62.5% -@item @code{c}@t{@ } Condensed, 75% -@item @code{sc} Semi condensed, 87.5% -@item @code{m}@t{@ } Medium, 100% -@item @code{sx} Semi expanded, 112.5% -@item @code{x}@t{@ } Expanded, 125% -@item @code{ex} Extra expanded, 150% -@item @code{ux} Ultra expanded, 200% -@end itemize +The possible values for width, individually, are (the meaning and +relationship of these terms varies with individual typefaces): + + +@multitable {xx} {Ultra condensed} +@item @code{uc} +@tab Ultra condensed +@item @code{ec} +@tab Extra condensed +@item @code{c} +@tab Condensed +@item @code{sc} +@tab Semi condensed +@item @code{m} +@tab Medium +@item @code{sx} +@tab Semi expanded +@item @code{x} +@tab Expanded +@item @code{ex} +@tab Extra expanded +@item @code{ux} +@tab Ultra expanded +@end multitable + When forming the @var{series} string from the weight and width, drop the @code{m} that stands for medium weight or medium width, unless both @@ -1830,14 +1867,21 @@ weight and width are @code{m}, in which case use just one @cindex shapes, of fonts Select font shape. Valid shapes are: -@itemize @w{} -@item @code{n}@t{@ } Upright (normal) -@item @code{it} Italic -@item @code{sl} Slanted (oblique) -@item @code{sc} Small caps -@item @code{ui} Upright italics -@item @code{ol} Outline -@end itemize +@multitable {xx} {Slanted (oblique)xx} +@item @code{n} +@tab Upright (normal) +@item @code{it} +@tab Italic +@item @code{sl} +@tab Slanted (oblique) +@item @code{sc} +@tab Small caps +@item @code{ui} +@tab Upright italics +@item @code{ol} +@tab Outline +@end multitable + The two last shapes are not available for most font families, and small caps are often missing as well. @@ -1859,8 +1903,9 @@ reset every time a size change happens; see @code{\baselinestretch}, next. @LaTeX{} multiplies the line spacing by the value of the @code{\baselinestretch} parameter; the default factor is 1. A change takes effect when @code{\selectfont} (see below) is called. You can -make line skip changes happen for the entire document by doing -@code{\renewcommand@{\baselinestretch@}@{2.0@}} in the preamble. +make a line skip change happen for the entire document, for instance +doubling it, by doing @code{\renewcommand@{\baselinestretch@}@{2.0@}} in +the preamble. @PkgIndex{setspace} @cindex double spacing @@ -2520,7 +2565,9 @@ The setting @noindent suppresses heading numbers at any depth @math{> @var{level}}, where -@code{chapter} is level zero. (@xref{\setcounter}.) +@code{chapter} is level zero. The default @code{secnumdepth} is 3 in +@LaTeX{}'s @file{article} class and 2 in the @file{book} and +@file{report} classes. (@xref{\setcounter}.) @menu * \@@startsection:: Redefine layout of start of sections, subsections, etc. @@ -2539,8 +2586,8 @@ Synopsis: \@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}@{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@} @end example -Redefine the behavior of commands that start sectioning divisions such -as @code{\section} or @code{\subsection}. +Used to help redefine the behavior of commands that start sectioning +divisions such as @code{\section} or @code{\subsection}. Note that the @file{titlesec} package makes manipulation of sectioning easier. Further, while most requirements for sectioning commands can be @@ -2550,31 +2597,34 @@ the standard @LaTeX{} @code{book} and @code{report} classes the commands make such a command you may want to use the @code{\secdef} command. @c xx define, and make a cross reference to, secdef. -Technically, this command has the form: +Technically, @code{\@@startsection} has the form @example -\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}@{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@} - *[@var{toctitle}]@{@var{title}@} +\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}@{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@}*[@var{toctitle}]@{@var{title}@} @end example -@noindent so that issuing: +@noindent (the star@tie{}@code{*} is optional), so that issuing @example -\renewcommand@{\section@}@{\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}% - @{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@}@} +\renewcommand@{\section@}@{\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}@{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@}@} @end example -@noindent redefine @code{\section} while keeping its standard calling form -@code{\section*[@var{toctitle}]@{@var{title}@}}. @xref{Sectioning} and +@noindent redefines @code{\section} to have the form +@code{\section*[@var{toctitle}]@{@var{title}@}} (here too, the +star@tie{}@code{*} is optional). @xref{Sectioning}. This implies that +when you write a command like @code{\renewcommand@{section@}@{...@}}, +the @code{\@@startsection@{...@}} must come last in the definition. See the examples below. @table @var @item name -@anchor{\@@startsection/name} Name of the counter (which must be defined -separately) used to number for the sectioning header. Most commonly -either @code{section}, @code{subsection}, or @code{paragraph}. Although -in those three cases the name of the counter is also the name of the -sectioning command itself, using the same name is not required. +@anchor{\@@startsection/name} Name of the counter used to number the +sectioning header. This counter must be defined separately. Most +commonly this is either @code{section}, @code{subsection}, or +@code{paragraph}. Although in those three cases the counter name is the +same as the sectioning command itself, using the same name is not +required. Then @code{\the}@var{name} displays the title number and -@code{\}@var{name}@code{mark} is for the page headers. +@code{\}@var{name}@code{mark} is for the page headers. See the third +example below. @item level @anchor{\@@startsection/level} An integer giving the depth of the @@ -2588,22 +2638,22 @@ classes @code{part} has level -1, while in the @code{article} class If @var{level} is less than or equal to the value of @code{secnumdepth} then the titles for this sectioning command will be numbered. For instance, in an @code{article}, if @code{secnumdepth} is 1 then a -@code{\section@{Introduction@}} command will produce output like @code{1 -Introduction} while @code{\subsection@{History@}} will produce output -like @code{History}, without the number -prefix. @xref{Sectioning/secnumdepth}. +@code{\section@{Introduction@}} command will produce output like ``1 +Introduction'' while @code{\subsection@{Discussion@}} will produce +output like ``Discussion'', without the number prefix. +@xref{Sectioning/secnumdepth}. If @var{level} is less than or equal to the value of @var{tocdepth} then -the table of contents will have an entrie for this sectioning unit. +the table of contents will have an entry for this sectioning unit. For instance, in an @code{article}, if @var{tocdepth} is 1 then the table of contents will list sections but not subsections. @c xx add, and cross reference to, tocdepth @item indent @anchor{\@@startsection/indent} A length giving the indentation of all -of the title lines with respect to the left margin. To have the -title flush with the margin use @code{0pt}. A negative indentation -such as @code{-1em} will move the title into the left margin. +of the title lines with respect to the left margin. To have the title +flush with the margin use @code{0pt}. A negative indentation such as +@code{-\parindent} will move the title into the left margin. @item beforeskip @anchor{\@@startsection/beforeskip} The absolute value of this length is @@ -2620,7 +2670,7 @@ then to start the new sectioning unit, @LaTeX{} will add about 3.5 times the height of a letter x in vertical space, and the first paragraph in the section will not be indented. Using a rubber length, with @code{plus} and @code{minus}, is good practice here since it gives -@LaTeX{} more flexibility in making up the page. +@LaTeX{} more flexibility in making up the page (@pxref{Lengths}). The full accounting of the vertical space between the baseline of the line prior to this sectioning unit's header and the baseline of the @@ -2642,9 +2692,9 @@ between the end of the title and the beginning of the following paragraph. (Note that the negative of @code{1pt plus 2pt minus 3pt} is @code{-1pt plus -2pt minus -3pt}.) -As with @var{beforeskip}, using a rubber length with @code{plus} and -@code{minus} components is good practice here since it gives @LaTeX{} -more flexibility in putting the page together. +As with @var{beforeskip}, using a rubber length, with @code{plus} and +@code{minus} components, is good practice here since it gives @LaTeX{} +more flexibility in putting together the page. If @code{afterskip} is non-negative then the full accounting of the vertical space between the baseline of the sectioning unit's header and @@ -2667,22 +2717,53 @@ instance, setting @var{style} to @code{\bfseries\MakeUppercase} would produce titles that are bold and upper case. @end table -Here are examples. To use them, either put them in a package or class -file, or put them in the preamble of a @LaTeX{} document between a -@code{\makeatletter} command and a @code{\makeatother}. (Probably the -error message @code{You can't use `\spacefactor' in vertical mode.} -means that you forgot this.) @xref{\makeatletter and \makeatother}. +These are @LaTeX{}'s defaults for the first three sectioning units that +are defined with @code{\@@startsection}, for the @file{article}, +@file{book}, and @file{report} classes. + +@multitable @columnfractions .10 .30 .30 .30 +@headitem @tab @code{section} @tab @code{subsection} @tab @code{subsubsection} +@item @ref{\@@startsection/name,@var{name},@var{name}} +@tab section @tab subsection @tab subsubsection +@item @ref{\@@startsection/level,@var{level},@var{level}} +@tab 1 @tab 2 @tab 3 +@item @ref{\@@startsection/indent,@var{indent},@var{indent}} +@tab @code{0pt} @tab @code{0pt} @tab @code{0pt} +@item @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}} +@tab @code{-3.5ex plus -1ex minus -0.2ex} +@tab @code{-3.25ex plus -1ex minus -0.2ex} +@tab @code{-3.25ex plus -1ex minus -0.2ex} +@item @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}} +@tab @code{2.3ex plus 0.2ex} +@tab @code{1.5ex plus 0.2ex} +@tab @code{1.5ex plus 0.2ex} +@item @ref{\@@startsection/style,@var{style},@var{style}} +@tab @code{\normalfont\Large\bfseries} +@tab @code{\normalfont\large\bfseries} +@tab @code{\normalfont\normalsize\bfseries} +@end multitable + +Here are examples. They go either in a package or class file or in the +preamble of a @LaTeX{} document. If you put them in the preamble they +must go between a @code{\makeatletter} command and a +@code{\makeatother}. (Probably the error message @code{You can't use +`\spacefactor' in vertical mode.} means that you forgot this.) +@xref{\makeatletter and \makeatother}. -This will put section titles in large boldface type, centered. +This will put section titles in large boldface type, centered. It says +@code{\renewcommand} because @LaTeX{}'s standard classes have already +defined a @code{\section}. For the same reason it does not define a +@code{section} counter, or the commands @code{\thesection} and +@code{\l@@section}. @example \renewcommand\section@{% - \@@startsection@{section@}% @ref{\@@startsection/name,@var{name},@var{name}}. - @{1@}% @ref{\@@startsection/level,@var{level},@var{level}}. - @{0pt@}% @ref{\@@startsection/indent,@var{indent},@var{indent}}. - @{-3.5ex plus -1ex minus -.2ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}}. - @{2.3ex plus.2ex@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}}. - @{\centering\normalfont\Large\bfseries@}% @ref{\@@startsection/style,@var{style},@var{style}}. + \@@startsection@{section@}% @ref{\@@startsection/name,@var{name},@var{name}} + @{1@}% @ref{\@@startsection/level,@var{level},@var{level}} + @{0pt@}% @ref{\@@startsection/indent,@var{indent},@var{indent}} + @{-3.5ex plus -1ex minus -.2ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}} + @{2.3ex plus.2ex@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}} + @{\centering\normalfont\Large\bfseries@}% @ref{\@@startsection/style,@var{style},@var{style}} @} @end example @@ -2690,12 +2771,12 @@ This will put @code{subsection} titles in small caps type, inline with the parag @example \renewcommand\subsection@{% - \@@startsection@{subsection@}% @ref{\@@startsection/name,@var{name},@var{name}}. - @{2@}% @ref{\@@startsection/level,@var{level},@var{level}}. - @{0em@}% @ref{\@@startsection/indent,@var{indent},@var{indent}}. - @{-1ex plus 0.1ex minus -0.05ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}}. - @{-1em plus 0.2em@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}}. - @{\scshape@}% @ref{\@@startsection/style,@var{style},@var{style}}. + \@@startsection@{subsection@}% @ref{\@@startsection/name,@var{name},@var{name}} + @{2@}% @ref{\@@startsection/level,@var{level},@var{level}} + @{0em@}% @ref{\@@startsection/indent,@var{indent},@var{indent}} + @{-1ex plus 0.1ex minus -0.05ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}} + @{-1em plus 0.2em@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}} + @{\scshape@}% @ref{\@@startsection/style,@var{style},@var{style}} @} @end example @@ -3195,45 +3276,62 @@ Synopsis: @example \begin@{description@} -\item [@var{first label}] text of first item -\item [@var{second label}] text of second item +\item[@var{label of first item}] text of first item +\item[@var{label of second item}] text of second item ... \end@{description@} @end example -Environment to make a labelled list of items. Each item's @var{label} -is typeset in bold, flush-left. Each item's text may contain multiple -paragraphs. Although the labels on the items are optional there is no -sensible default, so all items should have labels. +Environment to make a labeled list of items. Each item's @var{label} is +typeset in bold, and is flush left so that long labels continue into the +first line of the item text. There must be at least one item; having +none causes the @LaTeX{} error @samp{Something's wrong--perhaps a +missing \item}. + +This example shows the environment used for a sequence of definitions. +The labels @samp{lama} and @samp{llama} come out in boldface with their +left edges aligned on the left margin. + +@example +\begin@{definition@} + \item[lama] A priest. + \item[llama] A beast. +\end@{definition@} +@end example @findex \item -The list consists of at least one item, created with the @code{\item} -command (@pxref{\item}). Having no items causes the @LaTeX{} error -@samp{Something's wrong--perhaps a missing \item}). +Start list items with the @code{\item} command (@pxref{\item}). Use the +optional labels, as in @code{\item[Main point]}, because there is +no sensible default. Following the @code{\item} is optional text, which +may contain multiple paragraphs. @cindex bold typewriter, avoiding @cindex typewriter labels in lists Since the labels are in bold style, if the label text calls for a font -change given in argument style (see @ref{Font styles}) then it will -come out bold. For instance, if the label text calls for typewriter -with @code{\item[\texttt@{label text@}]} then it will appear in bold +change given in argument style (see @ref{Font styles}) then it will come +out bold. For instance, if the label text calls for typewriter with +@code{\item[\texttt@{label text@}]} then it will appear in bold typewriter, if that is available. The simplest way to get non-bold typewriter is to use declarative style: @code{\item[@{\tt label -text@}]}. Similarly, to get the standard roman font, use -@code{\item[@{\rm label text@}]}. +text@}]}. Similarly, get the standard roman font with @code{\item[@{\rm +label text@}]}. For other major @LaTeX{} labelled list environments, see @ref{itemize} -and @ref{enumerate}. For information about customizing list layout, see -@ref{list}; also, the package @file{enumitem} is useful for this. +and @ref{enumerate}. Unlike those environments, nesting +@code{description} environments does not change the default label; it is +boldface and flush left at all levels. -This example shows the environment used for a sequence of definitions. +For information about list layout parameters, including the default +values, and for information about customizing list layout, see +@ref{list}. The package @file{enumitem} is useful for customizing +lists. + +This example changes the description labels to small caps. @example -\begin@{definition@} - \item[lama] A priest. - \item[llama] A beast. -\end@{definition@} -@end example +\renewcommand@{\descriptionlabel@}[1]@{% + @{\hspace@{\labelsep@}\textsc@{#1@}@}@} +@end example @node displaymath @@ -3303,6 +3401,7 @@ It is required in every @LaTeX{} document. @xref{Starting and ending}. @node \AtBeginDocument +@subsection @code{\AtBeginDocument} @findex \AtBeginDocument @cindex beginning of document hook @@ -3324,6 +3423,7 @@ will be executed in the order that you gave them. @node \AtEndDocument +@subsection @code{\AtEndDocument} @findex \AtEndDocument @cindex end of document hook @@ -3355,22 +3455,22 @@ Synopsis: @example \begin@{enumerate@} -\item [@var{first label}] text of first item -\item [@var{second label}] text of second item +\item[@var{optional label of first item}] text of first item +\item[@var{optional label of second item}] text of second item ... \end@{enumerate@} @end example Environment to produce a numbered list of items. The format of the -label numbering depends on whether this environment is nested within -another; see below. +label numbering depends on the nesting level of this environment; see +below. The default top-level numbering is @samp{1.}, @samp{2.}, +etc. Each @code{enumerate} list environment must have at least one item; +having none causes the @LaTeX{} error @samp{Something's wrong--perhaps a +missing \item}. -@findex \item -The list consists of at least one item. Having no items causes the -@LaTeX{} error @samp{Something's wrong--perhaps a missing \item}. Each -item is produced with an @code{\item} command. - -This example lists the top two finishers in the 1908 Olympic marathon. +This example gives the first two finishers in the 1908 Olympic marathon. +As a top-level list the labels would come out as @samp{1.} and +@samp{2.}. @example \begin@{enumerate@} @@ -3379,12 +3479,20 @@ This example lists the top two finishers in the 1908 Olympic marathon. \end@{enumerate@} @end example -Enumerations may be nested within a paragraph-making environment, -including @code{itemize} (@pxref{itemize}), @code{description} -(@pxref{description}) and @code{enumeration}, up to four levels deep. -The format of the label produced depends on the place in the nesting. -This gives @LaTeX{}'s default for the format at each nesting level -(where 1 is the outermost level): +@findex \item +Start list items with the @code{\item} command (@pxref{\item}). If you +give @code{\item} an optional argument by following it with square +brackets, as in @code{\item[Interstitial label]}, then the next item +will continue the interrupted sequence (@pxref{\item}). That is, you +will get labels like @samp{1.}, then @samp{Interstitial label}, then +@samp{2.}. Following the @code{\item} is optional text, which may +contain multiple paragraphs. + +Enumerations may be nested within other @code{enumerate} environments, +or within any paragraph-making environment such as @code{itemize} +(@pxref{itemize}), up to four levels deep. This gives @LaTeX{}'s +default for the format at each nesting level, where 1 is the top level, +the outermost level. @enumerate @item arabic number followed by a period: @samp{1.}, @samp{2.},@tie{}@dots{} @@ -3398,9 +3506,13 @@ This gives @LaTeX{}'s default for the format at each nesting level @findex \enumiii @findex \enumiv The @code{enumerate} environment uses the counters @code{\enumi} through -@code{\enumiv} counters (@pxref{Counters}). If you use the optional -argument to @code{\item} then the counter is not incremented for that -item (@pxref{\item}). +@code{\enumiv} (@pxref{Counters}). + +For other major @LaTeX{} labeled list environments, see +@ref{description} and @ref{itemize}. For information about list layout +parameters, including the default values, and for information about +customizing list layout, see @ref{list}. The package @file{enumitem} is +useful for customizing lists. @findex \labelenumi @findex \labelenumii @@ -3410,24 +3522,19 @@ To change the format of the label use @code{\renewcommand} (@pxref{\newcommand & \renewcommand}) on the commands @code{\labelenumi} through @code{\labelenumiv}. For instance, this first level list will be labelled with uppercase letters, in boldface, and without a trailing -period: +period. @findex \Alph @r{example} @example \renewcommand@{\labelenumi@}@{\textbf@{\Alph@{enumi@}@}@} \begin@{enumerate@} - \item eI - \item bi: - \item si: + \item Shows as boldface A + \item Shows as boldface B \end@{enumerate@} @end example -For a list of counter-labelling commands like @code{\Alph} see -@ref{\alph \Alph \arabic \roman \Roman \fnsymbol}. - -For more on customizing the layout see @ref{list}. Also, the package -@file{enumitem} is useful for this. - +For a list of counter-labeling commands see @ref{\alph \Alph \arabic +\roman \Roman \fnsymbol}. @node eqnarray @@ -3524,6 +3631,10 @@ equation number in the right margin. The equation number is generated using the @code{equation} counter. +You should have no blank lines between @code{\begin@{equation@}} and +@code{\begin@{equation@}}, or @LaTeX{} will tell you that there is a +missing dollar sign,@tie{}$@code{$}. + Note that the @file{amsmath} package has extensive displayed equation facilities. Those facilities are the best approach for such output in new documents. @@ -3761,42 +3872,63 @@ Synopsis: @example \begin@{itemize@} -\item @var{item1} -\item @var{item2} +\item[@var{optional label of first item}] text of first item +\item[@var{optional label of second item}] text of second item ... \end@{itemize@} @end example The @code{itemize} environment produces an ``unordered'', ``bulleted'' -list. Itemized lists can be nested within one another, up to four -levels deep. They can also be nested within other paragraph-making -environments, such as @code{enumerate} (@pxref{enumerate}). +list. The format of the label numbering depends on the nesting level of +this environment; see below. Each @code{itemize} list environment must +have at least one item; having none causes the @LaTeX{} error +@samp{Something's wrong--perhaps a missing \item}. -Each item of an @code{itemize} list begins with an @code{\item} command. -There must be at least one @code{\item} command within the environment. +This example gives a two-item list. As a top-level list each label +would come out as a bullet, @bullet{}. -By default, the marks at each level look like this: +@example +\begin@{itemize@} + \item Pencil and watercolor sketch by Cassandra + \item Rice portrait +\end@{itemize@} +@end example + +@findex \item +Start list items with the @code{\item} command (@pxref{\item}). If you +give @code{\item} an optional argument by following it with square +brackets, as in @code{\item[Optional label]}, then by default it will +appear in bold and be flush right, so it could extend into the left +margin. For labels that are flush left see the @ref{description} +environment. Following the @code{\item} is optional text, which may +contain multiple paragraphs. + +@findex \labelitemi +@findex \labelitemii +@findex \labelitemiii +@findex \labelitemiv +Itemized lists can be nested within one another, up to four levels deep. +They can also be nested within other paragraph-making environments, such +as @code{enumerate} (@pxref{enumerate}). The @code{itemize} environment +uses the commands @code{\labelitemi} through @code{\labelitemiv} to +produce the default label (this also uses the convention of lower case +roman numerals at the end of the command names that signify the nesting +level). These are the default marks at each level. @enumerate -@item @bullet{} (bullet) -@item @b{-@w{-}} (bold en-dash) -@item * (asterisk) +@item @bullet{} (bullet, from @code{\textbullet}) +@item @b{-@w{-}} (bold en-dash, from @code{\normalfont\bfseries\textendash}) +@item * (asterisk, from @code{\textasteriskcentered}) @iftex -@item @math{\cdot} (centered dot) +@item @math{\cdot} (centered dot, from @code{\textperiodcentered}) @end iftex @ifnottex -@item . (centered dot, rendered here as a period) +@item . (centered dot, rendered here as a period, from @code{\textperiodcentered}) @end ifnottex @end enumerate -@findex \labelitemi -@findex \labelitemii -@findex \labelitemiii -@findex \labelitemiv -The @code{itemize} environment uses the commands @code{\labelitemi} -through @code{\labelitemiv} to produce the default label. So, you can -use @code{\renewcommand} to change the labels. For instance, to have -the first level use diamonds: +Change the labels with @code{\renewcommand}. For instance, this makes +the first level use diamonds. @example \renewcommand@{\labelitemi@}@{$\diamond$@} @@ -3809,73 +3941,28 @@ the first level use diamonds: @findex \leftmarginiv @findex \leftmarginv @findex \leftmarginvi -The @code{\leftmargini} through @code{\leftmarginvi} parameters define -the distance between the left margin of the enclosing environment and -the left margin of the list. By convention, @code{\leftmargin} is set -to the appropriate @code{\leftmargin@var{N}} when a new level of -nesting is entered. +The distance between the left margin of the enclosing environment and +the left margin of the @code{itemize} list is determined by the +parameters @code{\leftmargini} through @code{\leftmarginvi}. (Note the +convention of using lower case roman numerals a the end of the command +name to denote the nesting level.) The defaults are: @code{2.5em} in +level 1 (@code{2em} in two-column mode), @code{2.2em} in level 2, +@code{1.87em} in level 3, and @code{1.7em} in level 4, with smaller +values for more deeply nested levels. + +For other major @LaTeX{} labeled list environments, see +@ref{description} and @ref{enumerate}. For information about list +layout parameters, including the default values, and for information +about customizing list layout, see @ref{list}. The package +@file{enumitem} is useful for customizing lists. -The defaults vary from @samp{.5em} (highest levels of nesting) to -@samp{2.5em} (first level), and are a bit reduced in two-column mode. -This example greatly reduces the margin space for outermost lists: +This example greatly reduces the margin space for outermost itemized +lists. @example \setlength@{\leftmargini@}@{1.25em@} % default 2.5em @end example -@c xx should be in its own generic section -Some parameters that affect list formatting: - -@ftable @code -@item \itemindent -Extra indentation before each item in a list; default zero. - -@item \labelsep -Space between the label and text of an item; default @samp{.5em}. - -@item \labelwidth -Width of the label; default @samp{2em}, or @samp{1.5em} in two-column mode. - -@item \listparindent -Extra indentation added to second and subsequent paragraphs within a -list item; default @samp{0pt}. - -@item \rightmargin -Horizontal distance between the right margin of the list and the -enclosing environment; default @samp{0pt}, except in the @code{quote}, -@code{quotation}, and @code{verse} environments, where it is set equal -to @code{\leftmargin}. - -@end ftable - -Parameters affecting vertical spacing between list items (rather -loose, by default). - -@ftable @code -@item \itemsep -Vertical space between items. The default is @code{2pt plus1pt -minus1pt} for @code{10pt} documents, @code{3pt plus2pt minus1pt} for -@code{11pt}, and @code{4.5pt plus2pt minus1pt} for @code{12pt}. - -@item \parsep -Extra vertical space between paragraphs within a list item. Defaults -are the same as @code{\itemsep}. - -@item \topsep -Vertical space between the first item and the preceding paragraph. -For top-level lists, the default is @code{8pt plus2pt minus4pt} for -@code{10pt} documents, @code{9pt plus3pt minus5pt} for @code{11pt}, -and @code{10pt plus4pt minus6pt} for @code{12pt}. These are reduced -for nested lists. - -@item \partopsep -Extra space added to @code{\topsep} when the list environment starts a -paragraph. The default is @code{2pt plus1pt minus1pt} for @code{10pt} -documents, @code{3pt plus1pt minus1pt} for @code{11pt}, and @code{3pt -plus2pt minus2pt} for @code{12pt}. - -@end ftable - @findex \parskip @r{example} Especially for lists with short items, it may be desirable to elide space between items. Here is an example defining an @code{itemize*} @@ -3907,37 +3994,301 @@ This environment is used for creating letters. @xref{Letters}. @EnvIndex{list} @cindex lists of items, generic -The @code{list} environment is a generic environment which is used for -defining many of the more specific environments. It is seldom used in -documents, but often in macros. +Synopsis: @example \begin@{list@}@{@var{labeling}@}@{@var{spacing}@} -\item @var{item1} -\item @var{item2} +\item[@var{optional label of first item}] text of first item +\item[@var{optional label of second item}] text of second item ... \end@{list@} @end example -The mandatory @var{labeling} argument specifies how items should be -labelled (unless the optional argument is supplied to @code{\item}). -This argument is a piece of text that is inserted in a box to form the -label. It can and usually does contain other @LaTeX{} commands. +The @code{list} environment is a generic environment for constructing +more specialized lists. It is most often used to create lists via the +@code{description}, @code{enumerate}, and @code{itemize} environments +(@pxref{description}, @ref{enumerate}, and @ref{itemize}). + +Also, many standard @LaTeX{} environments that are not visually lists +are constructed using @code{list}, including @code{quotation}, +@code{quote}, @code{center}, @code{verbatim}, and plenty more +(@pxref{quotation and quote}, @pxref{center}, @pxref{flushright}). + +@PkgIndex{enumitem} +The third-party package @code{enumitem} is useful for customizing lists. +Here, we describe the @code{list} environment by defining a new custom +environment. + +@example +\newcounter@{namedlistcounter@} % number the items +\newenvironment@{named@} + @{\begin@{list@} + @{Item~\Roman@{namedlistcounter@}.@} % labeling argument + @{\usecounter@{namedlistcounter@} % spacing argument + \setlength@{\leftmargin@}@{3.5em@}@} % still spacing arg + @} + @{\end@{list@}@} + +\begin@{named@} + \item Shows as ``Item~I.'' + \item[Special label.] Shows as ``Special label.'' + \item Shows as ``Item~II.'' +\end@{named@} +@end example + +The @code{list} environment's mandatory first argument, +@var{labeling}, specifies the default labeling of list items. It can +contain text and @LaTeX{} commands, as above where it contains both +@samp{Item} and @samp{\Roman@{...@}}. @LaTeX{} forms the label by +putting the @var{labeling} argument in a box of width +@code{\labelwidth}. If the label is wider than that, the additional +material extends to the right. When making an instance of a list you +can override the default labeling by giving @code{\item} an optional +argument by including square braces and the text, as in the above +@code{\item[Special label.]}; @pxref{\item}. + +@findex \makelabel +The label box is constructed by the command @code{\makelabel}. By +default it positions the contents flush right. It takes one argument, +the label. It typesets the contents in LR mode. An example of changing +its definition is that to the above example before the definition of the +@code{named} environment add +@code{\newcommand@{\namedmakelabel@}[1]@{\textsc@{#1@}@}}, and between +the @code{\setlength} command and the parenthesis that closes the +@var{spacing} argument also add @code{\let\makelabel\namedmakelabel}. +Then the items will be typeset in small caps. Similarly, changing the +second code line to @code{\let\makelabel\fbox} puts the labels inside a +framed box. Another example is at the bottom of this entry. + +The mandatory second argument @var{spacing} can have a list of +commands to redefine the spacing parameters for the list, such as +@code{\setlength@{\labelwidth@}@{2em@}}. If this argument is empty, +i.e., @code{@{@}}, then the list will have the default spacing given +below. To number the items using a counter, put +@code{\usecounter@{@var{countername}@}} in this argument +(@pxref{\usecounter}). + +Below are the spacing parameters for list formatting. See also the +figure below. Each is a length (@pxref{Lengths}). The vertical +spaces are normally rubber lengths, with @code{plus} and @code{minus} +components, to give @TeX{} flexibility in setting the page. Change +each with a command such as @code{\setlength@{itemsep@}@{2pt plus1pt +minus1pt@}}. For some effects these lengths should be zero or +negative. Default values for derived environments such as +@code{itemize} can be changed from the values shown here for the basic +@code{list}. + +@ftable @code +@item \itemindent +Extra horizontal space indentation, beyond @code{leftmargin}, of the +first line each item. Its default value is @code{0pt}. + +@item \itemsep +Vertical space between items, beyond the @code{\parsep}. The defaults +for the first three levels in @LaTeX{}'s @samp{article}, @samp{book}, +and @samp{report} classes at 10 point size are: @code{4pt plus2pt +minus1pt}, @code{\parsep} (that is, @code{2pt plus1pt minus1pt}), and +@code{\topsep} (that is, @code{2pt plus1pt minus1pt}). The defaults at +11 point are: @code{4.5pt plus2pt minus1pt}, @code{\parsep} (that is, +@code{2pt plus1pt minus1pt}), and @code{topsep} (that is, @code{2pt +plus1pt minus1pt}). The defaults at 12 point are: @code{5pt plus2.5pt +minus1pt}, @code{\parsep} (that is, @code{2.5pt plus1pt minus1pt}), and +@code{\topsep} (that is, @code{2.5pt plus1pt minus1pt}). + +@item \labelsep +Horizontal space between the label and text of an item. +The default for @LaTeX{}'s @samp{article}, @samp{book}, +and @samp{report} classes is @code{0.5em}. + +@item \labelwidth +Horizontal width. The box containing the label is nominally this wide. +If @code{\makelabel} returns text that is wider than this then the first +line of the item will be indented to make room for this extra material. +If @code{\makelabel} returns text of width less than or equal to +@code{\labelwidth} then @LaTeX{}'s default is that the label is typeset +flush right in a box of this width. + +The left edge of the label box is +@code{\leftmargin}+@code{\itemindent}-@code{\labelsep}-@code{\labelwidth} +from the left margin of the enclosing environment. + +The default for @LaTeX{}'s @samp{article}, @samp{book}, and +@samp{report} classes at the top level is +@code{\leftmargini}-@code{\labelsep}, (which is @code{2em} in one column +mode and @code{1.5em} in two column mode). At the second level it is +@code{\leftmarginii}-@code{\labelsep}, and at the third level it is +@code{\leftmarginiii}-@code{\labelsep}. These definitions make the +label's left edge coincide with the left margin of the enclosing +environment. + +@item \leftmargin +Horizontal space between the left margin of the enclosing environment +(or the left margin of the page if this is a top-level list), and the +left margin of this list. It must be non-negative. + +In the standard @LaTeX{} document classes, a top-level list has this set +to the value of @code{\leftmargini}, while a list that is nested inside +a top-level list has this margin set to @code{\leftmarginii}. More +deeply nested lists get the values of @code{\leftmarginiii} through +@code{\leftmarginvi}. (Nesting greater than level five generates the +error message @samp{Too deeply nested}.) + +The defaults for the first three levels in @LaTeX{}'s @samp{article}, +@samp{book}, and @samp{report} classes are: @code{\leftmargini} is +@code{2.5em} (in two column mode, @code{2em}), @code{\leftmarginii} is +@code{2.2em}, and @code{\leftmarginiii} is @code{1.87em}. -The mandatory @var{spacing} argument contains commands to change the -spacing parameters for the list. This argument will most often be -empty, i.e., @code{@{@}}, which leaves the default spacing. +@item \listparindent +Horizontal space of additional line indentation, beyond +@code{\leftmargin}, for second and subsequent paragraphs within a list +item. A negative value makes this an ``outdent''. Its default value +is @code{0pt}. + +@item \parsep +Vertical space between paragraphs within an item. In the @samp{book} +and @samp{article} classes The defaults for the first three levels in +@LaTeX{}'s @samp{article}, @samp{book}, and @samp{report} classes at 10 +point size are: @code{4pt plus2pt minus1pt}, @code{2pt plus1pt +minus1pt}, and @code{0pt}. The defaults at 11 point size are: +@code{4.5pt plus2pt minus1pt}, @code{2pt plus1pt minus1pt}, and +@code{0pt}. The defaults at 12 point size are: @code{5pt plus2.5pt +minus1pt}, @code{2.5pt plus1pt minus1pt}, and @code{0pt}. + +@item \partopsep +Vertical space added, beyond @code{\topsep}+@code{\parskip}, to the top +and bottom of the entire environment if the list instance is preceded by +a blank line. (A blank line in the @LaTeX{} source before the list +changes spacing at both the top and bottom of the list; whether the line +following the list is blank does not matter.) + +The defaults for the first three levels in @LaTeX{}'s @samp{article}, +@samp{book}, and @samp{report} classes at 10 point size are: @code{2pt +plus1 minus1pt}, @code{2pt plus1pt minus1pt}, and @code{1pt plus0pt +minus1pt}. The defaults at 11 point are: @code{3pt plus1pt minus1pt}, +@code{3pt plus1pt minus1pt}, and @code{1pt plus0pt minus1pt}). The +defaults at 12 point are: @code{3pt plus2pt minus3pt}, @code{3pt plus2pt +minus2pt}, and @code{1pt plus0pt minus1pt}. -The width used for typesetting the list items is specified by -@code{\linewidth} (@pxref{Page layout parameters}). +@item \rightmargin +Horizontal space between the right margin of the list and the right +margin of the enclosing environment. Its default value is @code{0pt}. +It must be non-negative. + +@item \topsep +Vertical space added to both the top and bottom of the list, in addition +to @code{\parskip} (@pxref{\parskip}). The defaults for the first three +levels in @LaTeX{}'s @samp{article}, @samp{book}, and @samp{report} +classes at 10 point size are: @code{8pt plus2pt minus4pt}, @code{4pt +plus2pt minus1pt}, and @code{2pt plus1pt minus1pt}. The defaults at 11 +point are: @code{9pt plus3pt minus5pt}, @code{4.5pt plus2pt minus1pt}, +and @code{2pt plus1pt minus1pt}. The defaults at 12 point are: +@code{10pt plus4pt minus6pt}, @code{5pt plus2.5pt minus1pt}, and +@code{2.5pt plus1pt minus1pt}. + +@end ftable + +This shows the horizontal and vertical distances. + +@float +@image{latex2e-figures/list,3.21in,,,.png} +@end float + +The lengths shown are listed below. The key relationship is that the +right edge of the bracket for @var{h1} equals the right edge of the +bracket for @var{h4}, so that the left edge of the label box is at +@var{h3}+@var{h4}-(@var{h0}+@var{h1}). + +@table @var +@item v0 +@math{@code{@\topsep} + @code{@\parskip}} if +the list environment does not start a new paragraph, and +@code{\topsep}+@code{\parskip}+@code{\partopsep} if it does + +@item v1 +@code{\parsep} + +@item v2 +@code{\itemsep}+@code{\parsep} + +@item v3 +Same as @var{v0}. (This space is affected by whether a blank line +appears in the source above the environment; whether a blank line +appears in the source below the environment does not matter.) + +@item h1 +@code{\labelsep} + +@item h2 +@code{\listparindent} + +@item h3 +@code{\leftmargin} + +@item h4 +@code{\itemindent} + +@item h5 +@code{\rightmargin} + +@end table + +The list's left and right margins, shown above as @var{h3} and @var{h5}, +are with respect to the ones provided by the surrounding environment, or +with respect to the page margins for a top-level list. The line width +used for typesetting the list items is @code{\linewidth} (@pxref{Page +layout parameters}). For instance, set the list's left margin to be one +quarter of the distance between the left and right margins of the +enclosing environment with +@code{\setlength@{\leftmargin@}@{0.25\linewidth@}}. + +Page breaking in a list structure is controlled by the three +parameters below. For each, the @LaTeX{} default is +@code{-\@@lowpenalty}, that is, @code{-51}. Because it is negative, +it somewhat encourages a page break at each spot. Change it with, +e.g., @code{\@@beginparpenalty=9999}; a value of 10000 prohibits a +page break. + +@ftable @code +@item \@@beginparpenalty +The page breaking penalty for breaking before the list (default @code{-51}). + +@item \@@itempenalty +The page breaking penalty for breaking before a list item (default @code{-51}). + +@item \@@endparpenalty +The page breaking penalty for breaking after a list (default @code{-51}). + +@end ftable + +This example has the labels in red. They are numbered, and the left +edge of the label lines up with the left edge of the item text. + +@example +\usepackage@{color@} +\newcounter@{cnt@} +\newcommand@{\makeredlabel@}[1]@{\textcolor@{red@}@{#1.@}@} +\newenvironment@{redlabel@} + @{\begin@{list@} + @{\arabic@{cnt@}@} + @{\usecounter@{cnt@} + \setlength@{\labelwidth@}@{0em@} + \setlength@{\labelsep@}@{0.5em@} + \setlength@{\leftmargin@}@{1.5em@} + \setlength@{\itemindent@}@{0.5em@} % equals \labelwidth+\labelsep + \let\makelabel=\makeredlabel + @} + @} +@{\end@{list@} @} +@end example @menu * \item:: An entry in a list. +* trivlist:: A restricted form of @code{list}. @end menu @node \item -@subsection @code{\item}: An entry in a list. +@subsection @code{\item}: An entry in a list Synopsis: @@ -3947,21 +4298,25 @@ Synopsis: or @example -\item[@var{optional label}] text of item +\item[@var{optional-label}] text of item @end example An entry in a list. The entries are prefixed by a label, whose default -depends on the list type. +depends on the list type. + +Because the optional label is surrounded by square brackets +@samp{[...]}, if you have an item whose text starts with @samp{[}, you +have to to hide the bracket inside curly braces, as in: @code{\item +@{[@} is an open square bracket}; otherwise, @LaTeX{} will think it +marks the start of an optional label. -Because the optional argument @var{optional label} is surrounded by -square brackets@tie{}(@code{[} and @code{]}), to use square brackets -inside the optional argument you must hide them inside curly braces, as -in @code{\item[Close square bracket, @{]@}]}. Similarly, to use an open -square bracket as first character in the text of the item, also hide it -inside curly braces. @xref{@LaTeX{} command syntax}. +Similarly, if the item does have the optional label and you need a +close square bracket inside that label, you must hide it in the same +way: @code{\item[Close square bracket, @{]@}]}. @xref{@LaTeX{} +command syntax}. -In this example the @code{enumerate} list has two items that use the -default label and one that uses the optional label. +In this example the enumerate list has two items that use the default +label and one that uses the optional label. @example \begin@{enumerate@} @@ -3972,11 +4327,57 @@ default label and one that uses the optional label. @end example The first item is labelled @samp{1.}, the second item is labelled -@samp{sometimes}, and the third item is labelled @samp{2.} (note that, -because of the optional label in the second item, the third item does -not get a @samp{3.}). +@samp{sometimes}, and the third item is labelled @samp{2.}. Because +of the optional label in the second item, the third item is not +labelled@tie{}@samp{3.}. +@node trivlist +@subsection @code{trivlist}: A restricted form of @code{list} + +Synopsis: + +@example +\begin@{trivlist@} + ... +\end@{trivlist@} +@end example + +A restricted version of the list environment, in which margins are not +indented and an @code{\item} without an optional argument produces no +text. It is most often used in macros, to define an environment where +the @code{\item} command as part of the environment's definition. For +instance, the @code{center} environment is defined essentially like +this: + +@example +\newenvironment@{center@} + @{\begin@{trivlist@}\centering\item\relax@} + @{\end@{trivlist@}@} +@end example + +Using @code{trivlist} in this way allows the macro to inherit some +common code: combining vertical space of two adjacent environments; +detecting whether the text following the environment should be +considered a new paragraph or a continuation of the previous one; +adjusting the left and right margins for possible nested list +environments. + +Specifically, @code{trivlist} uses the current values of the list +parameters (@pxref{list}), except that @code{\parsep} is set to the +value of @code{\parskip}, and @code{\leftmargin}, @code{\labelwidth}, +and @code{\itemindent} are set to zero. + +This example outputs the items as two paragraphs, except that (by +default) they have no paragraph indent and are vertically separated. + +@example +\begin@{trivlist@} +\item The \textit@{Surprise@} is not old; no one would call her old. +\item She has a bluff bow, lovely lines. +\end@{trivlist@} +@end example + @node math @section @code{math} @@ -3992,8 +4393,8 @@ Synopsis: \end@{math@} @end example -The @code{math} environment inserts the given @var{math} within the -running text. @code{\(...\)} and @code{$...$} are synonyms. +The @code{math} environment inserts given @var{math} material within +the running text. @code{\(...\)} and @code{$...$} are synonyms. @xref{Math formulas}. @@ -4490,25 +4891,73 @@ Synopsis: @example \begin@{tabbing@} -@var{row1col1} \= @var{row1col2} \= @var{row1col3} \= @var{row1col4} \\ -@var{row2col1} \> \> @var{row2col3} \\ +@var{row1col1} \= @var{row1col2} ... \\ +@var{row2col1} \> @var{row2col2} ... \\ ... \end@{tabbing@} @end example -The @code{tabbing} environment provides a way to align text in -columns. It works by setting tab stops and tabbing to them much as -was done on an ordinary typewriter. It is best suited for cases where -the width of each column is constant and known in advance. +The @code{tabbing} environment aligns text in columns. It works by +setting tab stops and tabbing to them much as was done on a typewriter. +It is best suited for cases where the width of each column is constant +and known in advance. -This environment can be broken across pages, unlike the @code{tabular} -environment. +This example has a first line where the tab stops are set to explicit +widths, ended by a @code{\kill} command (which is described below): + +@example +\begin@{tabbing@} +\hspace@{0.75in@} \= \hspace@{0.40in@} \= \hspace@{0.40in@} \kill +Ship \> Guns \> Year \\ +\textit@{Sophie@} \> 14 \> 1800 \\ +\textit@{Polychrest@} \> 24 \> 1803 \\ +\textit@{Lively@} \> 38 \> 1804 \\ +\textit@{Surprise@} \> 28 \> 1805 \\ +\end@{tabbing@} +@end example -The following commands can be used inside a @code{tabbing} environment: +Both the @code{tabbing} environment and the more widely-used +@code{tabular} environment put text in columns. The most important +distinction is that in @code{tabular} the width of columns is +determined automatically by @LaTeX{}, while in @code{tabbing} the user +sets the tab stops. Another distinction is that @code{tabular} +generates a box, but @code{tabbing} can be broken across pages. +Finally, while @code{tabular} can be used in any mode, @code{tabbing} +can be used only in paragraph mode and it starts a new paragraph. + +A @code{tabbing} environment always starts a new paragraph, without +indentation. Moreover, as shown in the example above, there is no need +to use the starred form of the @code{\hspace} command at the beginning +of a tabbed row. The right margin of the @code{tabbing} environment is +the end of line, so that the width of the environment is +@code{\linewidth}. + +@cindex row, @r{tabbing} +The @code{tabbing} environment contains a sequence of @dfn{tabbed +rows}. The first tabbed row begins immediately after +@code{\begin@{tabbing@}} and each row ends with @code{\\} or +@code{\kill}. The last row may omit the @code{\\} and end with just +@code{\end@{tabbing@}}. + +At any point the @code{tabbing} environment has a current tab stop +pattern, a sequence of @math{@var{n} > 0} tab stops, numbered 0, 1, +etc. These create @var{n} corresponding columns. Tab stop@tie{}0 is +always the left margin, defined by the enclosing environment. Tab +stop number@tie{}@var{i} is set if it is assigned a horizontal +position on the page. Tab stop number@tie{}@var{i} can only be set if +all the stops 0, @dots{}, @math{i-1} have already been set; normally +later stops are to the right of earlier ones. + +By default any text typeset in a @code{tabbing} environment is typeset +ragged right and left-aligned on the current tab stop. Typesetting is +done in LR mode (@pxref{Modes}). + +The following commands can be used inside a @code{tabbing} environment. +They are all fragile (@pxref{\protect}). @ftable @code @item \\ @r{(tabbing)} -End a line. +End a tabbed line and typeset it. @item \= @r{(tabbing)} Sets a tab stop at the current position. @@ -4532,19 +4981,20 @@ following commands one tab stop to the left, beginning tabbed line if necessary. @item \' @r{(tabbing)} -Moves everything that you have typed so far in the -current column, i.e., everything from the most recent @code{\>}, -@code{\<}, @code{\'}, @code{\\}, or @code{\kill} command, to the right -of the previous column, flush against the current column's tab stop. +Moves everything that you have typed so far in the current column, i.e., +everything from the most recent @code{\>}, @code{\<}, @code{\'}, +@code{\\}, or @code{\kill} command, to the previous column and aligned +to the right, flush against the current column's tab stop. @item \` @r{(tabbing)} Allows you to put text flush right against any tab stop, including tab -stop@tie{}0. However, it can't move text to the right of the last column -because there's no tab stop there. The @code{\`} command moves all the -text that follows it, up to the @code{\\} or @code{\end@{tabbing@}} -command that ends the line, to the right margin of the tabbing -environment. There must be no @code{\>} or @code{\'} command between -the @code{\`} and the command that ends the line. +stop@tie{}0. However, it can't move text to the right of the last +column because there's no tab stop there. The @code{\`} command moves +all the text that follows it, up to the @code{\\} or +@code{\end@{tabbing@}} command that ends the line, to the right margin +of the @code{tabbing} environment. There must be no @code{\>} or +@code{\'} command between the @code{\`} and the @code{\\} or +@code{\end@{tabbing@}} command that ends the line. @item \a @r{(tabbing)} @findex \a' @r{(acute accent in tabbing)} @@ -4552,13 +5002,13 @@ the @code{\`} and the command that ends the line. @findex \a= @r{(macron accent in tabbing)} In a @code{tabbing} environment, the commands @code{\=}, @code{\'} and @code{\`} do not produce accents as usual (@pxref{Accents}). Instead, -the commands @code{\a=}, @code{\a'} and @code{\a`} are used. +use the commands @code{\a=}, @code{\a'} and @code{\a`}. @item \kill -Sets tab stops without producing text. Works just like @code{\\} -except that it throws away the current line instead of producing -output for it. The effect of any @code{\=}, @code{\+} or @code{\-} -commands in that line remain in effect. +Sets tab stops without producing text. Works just like @code{\\} except +that it throws away the current line instead of producing output for it. +Any @code{\=}, @code{\+} or @code{\-} commands in that line remain in +effect. @item \poptabs @findex \poptabs @@ -4569,17 +5019,17 @@ Saves all current tab stop positions. Useful for temporarily changing tab stop positions in the middle of a @code{tabbing} environment. @item \tabbingsep -Distance to left of tab stop moved by @code{\'}. +Distance of the text moved by @code{\'} to left of current tab stop. @end ftable -This example typesets a Pascal function in a traditional format: +This example typesets a Pascal function: @example \begin@{tabbing@} function \= fact(n : integer) : integer;\\ \> begin \= \+ \\ - \> if \= n $>$ 1 then \+ \\ + \> if \= n > 1 then \+ \\ fact := n * fact(n-1) \- \\ else \+ \\ fact := 1; \-\- \\ @@ -4587,7 +5037,28 @@ function \= fact(n : integer) : integer;\\ \end@{tabbing@} @end example +The output looks like this: +@example +function fact(n : integer) : integer; + begin + if n > 1 then + fact := n * fact(n-1); + else + fact := 1; + end; +@end example + +@PkgIndex{algorithm2e} @PkgIndex{listings} @PkgIndex{minted} +@PkgIndex{fancyvrb} +(The above example is just for illustration of the environment. To +actually typeset computer code in typewriter like this, a verbatim +environment (@pxref{verbatim}) would normally suffice. For +pretty-printed code, there are quite a few packages, including +@code{algorithm2e}, @code{fancyvrb}, @code{listings}, and +@code{minted}.) + + @node table @section @code{table} @@ -5051,14 +5522,30 @@ The @code{thebibliography} environment produces a bibliography or reference list. In the @code{article} class, this reference list is labelled -``References''; in the @code{report} class, it is labelled -``Bibliography''. You can change the label (in the standard classes) -by redefining the command @code{\refname}. For instance, this -eliminates it entirely: +@samp{References} and the label is stored in macro @code{\refname}; in +the @code{report} class, it is labelled @samp{Bibliography} and the +label is stored in macro @code{\bibname}. -@example -\renewcommand@{\refname@}@{@} -@end example +You can change the label by redefining the command @code{\refname} or +@code{\bibname}, whichever is applicable depending on the class: + +@itemize +@item +@findex \bibname +For standard classes whose top level sectioning is @code{\chapter} +(such as @file{book} and @file{report}), the label is in the macro +@code{\bibname}; + +@item +@findex \refname +For standard classes whose the top level sectioning is @code{\section} +(such as @file{article}), the label is in macro @code{\refname}. +@end itemize + +@PkgIndex{babel} +Typically it is neither necessary nor desirable to directly redefine +@code{\refname} or @code{\bibname}; language support packages like +@file{babel} do this. The mandatory @var{widest-label} argument is text that, when typeset, is as wide as the widest item label produced by the @code{\bibitem} @@ -5277,7 +5764,8 @@ which @LaTeX{} produces exactly what you type in; for instance the into a typewriter with carriage returns and blanks having the same effect that they would on a typewriter. -The @code{verbatim} uses a monospaced typewriter-like font (@code{\tt}). +The @code{verbatim} environment uses a monospaced typewriter-like font +(@code{\tt}). @menu * \verb:: The macro form of the @code{verbatim} environment. @@ -5973,6 +6461,7 @@ footnotes. This is @samp{6.65pt} for @samp{10pt}, @samp{7.7pt} for * \newtheorem:: Define a new theorem-like environment. * \newfont:: Define a new font name. * \protect:: Using tricky commands. +* \ignorespaces & \ignorespacesafterend:: Discard extra spaces. @end menu @@ -6571,6 +7060,96 @@ to @code{\protect\(..\protect\)}. @end example +@node \ignorespaces & \ignorespacesafterend +@section @code{\ignorespaces & \ignorespacesafterend} + +@findex \ignorespaces +@findex \ignorespacesafterend +@cindex spaces, ignore around commands +@cindex commands, ignore spaces + +Synopsis: + +@example +\ignorespaces +@end example + +or + +@example +\ignorespacesafterend +@end example + +Both commands cause @LaTeX{} to ignore spaces after the end of the +command up until the first non-space character. The first is a command +from Plain @TeX{}, and the second is @LaTeX{}-specific. + +The @code{ignorespaces} is often used when defining commands via +@code{\newcommand}, or @code{\newenvironment}, or @code{\def}. The +example below illustrates. It allows a user to show the points values +for quiz questions in the margin but it is inconvenient because, as +shown in the @code{enumerate} list, users must not put any space between +the command and the question text. + +@example +\newcommand@{\points@}[1]@{\makebox[0pt]@{\makebox[10em][l]@{#1~pts@}@} +\begin@{enumerate@} + \item\points@{10@}no extra space output here + \item\points@{15@} extra space output between the number and the word `extra' +\end@{enumerate@} +@end example + +The solution is to change to +@code{\newcommand@{\points@}[1]@{\makebox[0pt]@{\makebox[10em][l]@{#1~pts@}@}\ignorespaces@}}. + +A second example shows spaces being removed from the front of text. The +commands below allow a user to uniformly attach a title to names. But, +as given, if a title accidentally starts with a space then +@code{\fullname} will reproduce that. + +@example +\makeatletter +\newcommand@{\honorific@}[1]@{\def\@@honorific@{#1@}@} % remember title +\newcommand@{\fullname@}[1]@{\@@honorific~#1@} % recall title; put before name +\makeatother +\begin@{tabular@}@{|l|@} +\honorific@{Mr/Ms@} \fullname@{Jones@} \\ % no extra space here +\honorific@{ Mr/Ms@} \fullname@{Jones@} % extra space before title +\end@{tabular@} +@end example + +To fix this, change to +@code{\newcommand@{\fullname@}[1]@{\ignorespaces\@@honorific~#1@}}. + +The @code{\ignorespaces} is also often used in a @code{\newenvironment} +at the end of the @var{begin} clause, that is, as part of the second +argument, as in @code{\begin@{newenvironment@}@{@var{env +name}@}@{... \ignorespaces@}@{...@}}. + +To strip spaces off the end of an environment use +@code{\ignorespacesafterend}. An example is that this will show a much +larger vertical space between the first and second environments than +between the second and third. + +@example +\newenvironment@{eq@}@{\begin@{equation@}@}@{\end@{equation@}@} +\begin@{eq@} +e=mc^2 +\end@{eq@} +\begin@{equation@} +F=ma +\end@{equation@} +\begin@{equation@} +E=IR +\end@{equation@} +@end example + +Putting a comment character@tie{}@code{%} immediately after the +@code{\end@{eq@}} will make the vertical space disappear, but that is +inconvenient. The solution is to change to +@code{\newenvironment@{eq@}@{\begin@{equation@}@}@{\end@{equation@}\ignorespacesafterend@}}. + + @node Counters @chapter Counters @@ -7527,7 +8106,7 @@ arrow@tie{}@code{\Downarrow}. arrow@tie{}@code{\downarrow}. @item \ell -@BES{2113,\ell} Lower-case cursive letter l (ordinary). +@BES{2113,\ell} Lowercase cursive letter l (ordinary). @item \emptyset @BES{2205,\emptyset} Empty set symbol (ordinary). The variant form is @@ -8878,9 +9457,8 @@ changes to @var{style} for the current page only. Horizontal space * \hspace:: Fixed horizontal space. * \hfill:: Stretchable horizontal space. -* \(SPACE) and \@@:: Space after a period. +* \spacefactor:: Stretchability of following space * \(SPACE) after control sequence:: Space (gobbling) after a control sequence. -* \frenchspacing:: Equal interword and inter-sentence space. * \thinspace:: One-sixth of an em. * \/:: Insert italic correction. * \hrulefill \dotfill:: Stretchable horizontal rule or dots. @@ -8944,8 +9522,67 @@ space that does not disappear at line breaks use @code{\hspace*@{\fill@}} instead (@pxref{\hspace}). -@node \(SPACE) and \@@ -@section @code{\(SPACE)} and \@@ +@node \spacefactor +@section @code{\spacefactor} + +Synopsis: + +@example +\spacefactor=@var{integer} +@end example + +@findex \spacefactor +While @LaTeX{} is making the page, to give the lines the best appearance +it may stretch or shrink the gaps between words. The +@code{\spacefactor} command (from Plain@tie{}@TeX{}) allows you to +change the @LaTeX{}'s default behavior. + +After @LaTeX{} places each character, or rule or other box, it sets a +parameter called the @dfn{space factor}. If the next thing in the input +is a space then this parameter affects how much of a horizontal gap +@LaTeX{} will have it span. (This gap is not a character; it is called +@dfn{interword glue}.) A larger space factor means that the glue gap +can stretch more and shrink less. + +Normally, the space factor is 1000; this value is in effect following +most characters, and any non-character box or math formula. But it is +3000 after a period, exclamation mark, or question mark, it is 2000 +after a colon, 1500 after a semicolon, 1250 after a comma, and 0 after a +right parenthesis or bracket, or closing double quote or single quote. +Finally, it is 999 after a capital letter. + +If the space factor@tie{}@var{f} is 1000 then the glue gap will be the +font's normal space value (for Computer Modern Roman 10 point this is +3.3333@tie{}points). Otherwise, if the space factor @var{f} is greater +than 2000 then @TeX{} adds the font's extra space value (for Computer +Modern Roman 10 point this is 1.11111@tie{}points), and then the font's +normal stretch value is multiplied by @math{f /1000} and the normal +shrink value is multiplied by @math{1000/f} (for Computer Modern Roman +10 point these are 1.66666 and 1.11111@tie{}points). In short, compared +to a normal space, such as the space following a word ending in a +lowercase letter, inter-sentence spacing has a fixed extra space added +and then the space can stretch 3 times as much and shrink 1/3 as much. + +The rules for how @TeX{} uses space factors are even more complex +because they play two more roles. In practice, there are two +consequences. First, if a period or other punctuation is followed by a +close parenthesis or close double quote then its effect is still in +place, that is, the following glue will have increased stretch and +shrink. Second, conversely, if punctuation comes after a capital letter +then its effect is not in place so you get an ordinary space. For how +to adjust to this second case, for instance if an abbreviation does not +end in a capital letter, @pxref{\(SPACE) and \@@}. + + +@menu +* \(SPACE) and \@@:: Space after a period. +* \frenchspacing:: Equal interword and inter-sentence space. +* \normalsfcodes:: Restore space factor settings to the default. +@end menu + + +@node \(SPACE) and \@@ +@subsection @code{\(SPACE)} and @code{\@@} @findex \(SPACE) @findex \TAB @@ -8953,37 +9590,60 @@ space that does not disappear at line breaks use @findex \@@ @anchor{\AT}@c old name -Mark a punctuation character, typically a period, as either ending a -sentence or as ending an abbreviation. +Here, @code{\(SPACE)} means a backslash followed by a space. These +commands mark a punctuation character, typically a period, as either +ending a sentence or as ending an abbreviation. By default, in justifying a line @LaTeX{} adjusts the space after a sentence-ending period (or a question mark, exclamation point, comma, or -colon) more than the space between words -(@pxref{\frenchspacing}). @LaTeX{} assumes that the period ends a -sentence unless it is preceded by a capital letter, in which case it -takes that period for part of an abbreviation. Note that if a -sentence-ending period is immediately followed by a right parenthesis or -bracket, or right single or double quote, then the inter-sentence space -follows that parenthesis or quote. - -If you have a period ending an abbreviation whose last letter is not a -capital letter, and that abbreviation is not the last word in the +colon) more than the space between words. @xref{\spacefactor}. As +described there, @LaTeX{} assumes that the period ends a sentence unless +it is preceded by a capital letter, in which case it takes that period +for part of an abbreviation. Note that if a sentence-ending period is +immediately followed by a right parenthesis or bracket, or right single +or double quote, then the space effect of that period follows through +that parenthesis or quote. + +So: if you have a period ending an abbreviation whose last letter is not +a capital letter, and that abbreviation is not the last word in the sentence, then follow that period with a backslash-space (@code{\ }) or -a tie (@code{~}). Examples are @code{Nat.\ Acad.\ Science}, and -@code{Mr.~Bean}, and @code{(manure, etc.)\ for sale}. - -For another use of @code{\ }, @pxref{\(SPACE) after control sequence}. +a tie (@code{~}) or a @code{\@@}. Examples are @code{Nat.\ Acad.\ +Science}, and @code{Mr.~Bean}, and @code{(manure, etc.\@@) for sale} +(note that in the last the @code{\@@} comes before the closing parenthesis). In the opposite situation, if you have a capital letter followed by a -period that ends the sentence, then put @code{\@@} before that period. -For example, @code{book by the MAA\@@.} will have inter-sentence -spacing after the period. +period that does end the sentence, then put @code{\@@} before the +period. For example, @code{book by the MAA\@@.} will have correct +inter-sentence spacing after the period. + +For another use of @code{\(SPACE)}, @pxref{\(SPACE) after control sequence}. + -In contrast, putting @code{\@@} after a period tells @TeX{} that the -period does not end the sentence. In the example @code{reserved words -(if, then, etc.\@@) are different}, @TeX{} will put interword space -after the closing parenthesis (note that @code{\@@} is before the -parenthesis). +@node \frenchspacing +@subsection @code{\frenchspacing} + +@findex \frenchspacing +@findex \nonfrenchspacing +@cindex spacing, inter-sentence + +This declaration (from Plain @TeX{}) causes @LaTeX{} to treat +inter-sentence spacing in the same way as interword spacing. + +In justifying the text in a line, some typographic traditions, including +English, prefer to adjust the space between sentences (or after other +punctuation marks) more than the space between words. Following this +declaration, all spaces are instead treated equally. + +Revert to the default behavior by declaring @code{\nonfrenchspacing}. + + +@node \normalsfcodes +@subsection @code{\normalsfcodes} + +@findex \normalsfcodes +@cindex spacing, inter-sentence + +Reset the @LaTeX{} space factor values to the default. @node \(SPACE) after control sequence @@ -9010,24 +9670,6 @@ Some individual commands, notably those defined with the @code{xspace}, package do not follow the standard behavior. -@node \frenchspacing -@section @code{\frenchspacing} - -@findex \frenchspacing -@findex \nonfrenchspacing -@cindex spacing, inter-sentence - -This declaration (from Plain @TeX{}) causes @LaTeX{} to treat -inter-sentence spacing in the same way as interword spacing. - -In justifying the text in a line, some typographic traditions, including -English, prefer to adjust the space between sentences (or after other -punctuation marks) more than the space between words. Following this -declaration, all spaces are instead treated equally. - -Revert to the default behavior by declaring @code{\nonfrenchspacing}. - - @node \thinspace @section @code{\thinspace}: Insert 1/6@dmn{em} @@ -9295,8 +9937,8 @@ argument. @c xxref @findex \fboxrule @findex \fboxsep Both commands produce a rule of thickness @code{\fboxrule} (default -@samp{.4pt}), and leave a space of @code{\fboxsep} (default -@samp{3pt}) between the rule and the contents of the box. +@code{0.4pt}), and leave a space of @code{\fboxsep} (default @code{3pt}) +between the rule and the contents of the box. @xref{\framebox (picture)}, for the @code{\framebox} command in the @code{picture} environment. @@ -9481,6 +10123,1245 @@ Synopsis: @var{\boxcmd} by a @code{\savebox} command (@pxref{\savebox}). +@node Color +@chapter Color + +@cindex color + +You can add color to text, rules, etc. You can also have color in a box +or on an entire page and write text on top of it. + +Color support comes as an additional package. So all the commands below +will only work if your document preamble contains +@code{\usepackage@{color@}}, that brings in the standard package. + +Many other packages also supplement @LaTeX{}'s color abilities. +Particularly worth mentioning is @file{xcolor}, which is widely used and +significantly extends the capabilities described here, including adding +@samp{HTML} and @samp{Hsb} color models. + +@menu +* Color package options:: Options when you load the standard package. +* Color models:: How colors are represented. +* Commands for color:: The available commands. +@end menu + + +@node Color package options +@section Color package options + +@cindex color package options +@cindex options, color package + +Synopsis (must be in the document preamble): + +@example +\usepackage[@var{comma-separated option list}]@{color@} +@end example + +When you load the @file{color} package there are two kinds of available +options. + +The first specifies the @dfn{printer driver}. @LaTeX{} doesn't contain +information about different output systems but instead depends on +information stored in a file. Normally you should not specify the +driver option in the document, and instead rely on your system's +default. One advantage of this is that it makes the document portable +across systems. For completeness we include a list of the drivers. The +currently relevant ones are: @file{dvipdfmx}, @file{dvips}, +@file{dvisvgm}, @file{luatex}, @file{pdftex}, @file{xetex}. The two +@file{xdvi} and @file{oztex} are essentially aliases for @file{dvips} +(and @file{xdvi} is monochrome). Ones that should not be used for new +systems are: @file{dvipdf}, @file{dvipdfm}, @file{dviwin}, +@file{dvipsone}, @file{emtex}, @file{pctexps}, @file{pctexwin}, +@file{pctexhp}, @file{pctex32}, @file{truetex}, @file{tcidvi}, +@file{vtex} (and @file{dviwindo} is an alias for @file{dvipsone}). + +The second kind of options, beyond the drivers, are below. + +@table @code + +@item monochrome +Disable the color commands, so that they do not generate errors but do +not generate color either. + +@item dvipsnames +Make available a list of 68 color names that are often used, +particularly in legacy documents. These color names were originally +provided by the @file{dvips} driver, giving the option name. + +@item nodvipsnames +Do not load that list of color names, saving @LaTeX{} a tiny amount of +memory space. + +@end table + + +@node Color models +@section Color models + +@cindex color models + +A @dfn{color model} is a way of representing colors. @LaTeX{}'s +capabilities depend on the printer driver. However, the @file{pdftex}, +@file{xetex}, and @file{luatex} printer drivers are today by far the +most commonly used. The models below work for those drivers. All but +one of these is also supported by essentially all other printer drivers +used today. + +Note that color combination can be additive or subtractive. Additive +mixes colors of light, so that for instance combining full intensities +of red, green, and blue produces white. Subtractive mixes pigments, +such as with inks, so that combining full intensity of cyan, magenta, +and yellow makes black. + +@table @code +@item cmyk +A comma-separated list with four real numbers between 0 and 1, +inclusive. The first number is the intensity of cyan, the second is +magenta, and the others are yellow and black. A number value of 0 means +minimal intensity, while a 1 is for full intensity. This model is often +used in color printing. It is a subtractive model. + +@item gray +A single real number between 0 and 1, inclusive. The colors are shades +of grey. The number 0 produces black while 1 gives white. + +@item rgb +A comma-separated list with three real numbers between 0 and 1, +inclusive. The first number is the intensity of the red component, the +second is green, and the third the blue. A number value of 0 means that +none of that component is added in, while a 1 means full intensity. +This is an additive model. + +@item RGB +(@file{pdftex}, @file{xetex}, @file{luatex} drivers) A comma-separated +list with three integers between 0 and 255, inclusive. This model is a +convenience for using @code{rgb} since outside of @LaTeX{} colors are +often described in a red-green-blue model using numbers in this range. +The values entered here are converted to the @code{rgb} model by +dividing by 255. + +@item named +Colors are accessed by name, such as @samp{PrussianBlue}. The list of +names depends on the driver, but all support the names @samp{black}, +@samp{blue}, @samp{cyan}, @samp{green}, @samp{magenta}, @samp{red}, +@samp{white}, and @samp{yellow} (See the @code{dvipsnames} option in +@ref{Color package options}). + +@end table + + +@node Commands for color +@section Commands for color + +@cindex color package commands + +These are the commands available with the @file{color} package. + +@menu +* Define colors:: Give a color a name. +* Colored text:: Text or rules in color. +* Colored boxes:: A box of color, to write over. +* Colored pages:: A whole page colored. +@end menu + + +@node Define colors +@subsection Define colors + +@cindex color +@cindex define color +@cindex color, define + +Synopsis: + +@example +\definecolor@{@var{name}@}@{@var{model}@}@{@var{specification}@} +@end example + +Give the name @var{name} to the color. For example, after +@code{\definecolor@{silver@}@{rgb@}@{0.75,0.75,0.74@}} you can use that +color name with @code{Hi ho, \textcolor@{silver@}@{Silver@}!}. + +This example gives the color a more abstract name, so it could change and +not be misleading. + +@example +\definecolor@{logocolor@}@{RGB@}@{145,92,131@} % RGB needs pdflatex +\newcommand@{\logo@}@{\textcolor@{logocolor@}@{Bob's Big Bagels@}@} +@end example + +Often a document's colors are defined in the preamble, or in the class +or style, rather than in the document body. + + +@node Colored text +@subsection Colored text + +@cindex color +@cindex colored text + +Synopses: + +@example +\textcolor@{@var{name}@}@{...@} +\textcolor[@var{color model}]@{@var{color specification}@}@{...@} +@end example + +or + +@example +\color@{@var{name}@} +\color[@var{color model}]@{@var{specification}@} +@end example + +The affected text gets the color. This line + +@example +\textcolor@{magenta@}@{My name is Ozymandias, king of kings:@} Look on my works, ye Mighty, and despair! +@end example + +causes the first half to be in magenta while the rest is in black. You +can use a color declared with @code{\definecolor} in exactly the same +way that we just used the builtin color @samp{magenta}. + +@example +\definecolor@{MidlifeCrisisRed@}@{rgb@}@{1.0,0.11,0.0@} +I'm thinking about getting a \textcolor@{MidlifeCrisisRed@}@{sports car@}. +@end example + +The two @code{\textcolor} and @code{\color} differ in that the first is +a command form, enclosing the text to be colored as an argument. Often +this form is more convenient, or at least more explicit. The second +form is a declaration, as in @code{The moon is made of @{\color@{green@} +green@} cheese}, so it is in effect until the end of the current group +or environment. This is sometimes useful when writing macros or as +below where it colors everything inside the @code{center} environment, +including the vertical and horizontal lines. + +@example +\begin@{center@} \color@{blue@} + \begin@{tabular@}@{l|r@} + UL &UR \\ \hline + LL &LR + \end@{tabular@} +\end@{center@} +@end example + +You can use color in equations. A document might have +@code{\definecolor@{highlightcolor@}@{RGB@}@{225,15,0@}} in the +preamble, and then contain this equation. + +@example +\begin@{equation@} + \int_a^b \textcolor@{highlightcolor@}@{f'(x)@}\,dx=f(b)-f(a) +\end@{equation@} +@end example + +Typically the colors used in a document are declared in a class or style +but sometimes you want a one-off. Those are the second forms in the +synopses. + +@example +Colors of \textcolor[rgb]@{0.33,0.14,0.47@}@{Purple@} and @{\color[rgb]@{0.72,0.60,0.37@} Gold@} for the team +@end example + +The format of @var{color specification } depends on the color model +(@pxref{Color models}). For instance, while @code{rgb} takes three +numbers, @code{gray} takes only one. + +@example +The selection was \textcolor[gray]@{0.5@}@{grayed out@}. +@end example + +Colors inside colors do not combine. Thus + +@example +\textcolor@{green@}@{kind of \textcolor@{blue@}@{blue@}@} +@end example + +has a final word that is blue, not a combination of blue and green. + +@c xx address coloring a line of a table? + + +@node Colored boxes +@subsection Colored boxes + +@cindex color +@cindex colored boxes +@cindex box, colored + +Synopses: + +@example +\colorbox@{@var{name}@}@{...@} +\colorbox[@var{model name}]@{@var{box background color specification}@}@{...@} +@end example + +or + +@example +\fcolorbox@{@var{frame color}@}@{@var{box background color}@}@{...@} +\fcolorbox[@var{model name}]@{@var{frame color specification}@}@{@var{box background color specification}@}@{...@} +@end example + +Make a box with the stated background color. The @code{\fcolorbox} +command puts a frame around the box. For instance this + +@example +Name:~\colorbox@{cyan@}@{\makebox[5cm][l]@{\strut@}@} +@end example + +makes a cyan-colored box that is five centimeters long and gets its +depth and height from the @code{\strut} (so the depth is +@code{-.3\baselineskip} and the height is @code{\baselineskip}). This +puts white text on a blue background. + +@example +\colorbox@{blue@}@{\textcolor@{white@}@{Welcome to the machine.@}@} +@end example + +The @code{\fcolorbox} commands use the same parameters as @code{\fbox} +(@pxref{\fbox and \framebox}), @code{\fboxrule} and @code{\fboxsep}, to +set the thickness of the rule and the boundary between the box interior +and the surrounding rule. @LaTeX{}'s defaults are @code{0.4pt} and +@code{3pt}, respectively. + +This example changes the thickness of the border to 0.8 points. Note +that it is surrounded by curly braces so that the change ends at the end +of the second line. + +@example +@{\setlength@{\fboxrule@}@{0.8pt@} +\fcolorbox@{black@}@{red@}@{Under no circumstances turn this knob.@}@} +@end example + + +@node Colored pages +@subsection Colored pages + +@cindex color +@cindex colored page +@cindex page, colored +@cindex background, colored + +Synopses: + +@example +\pagecolor@{@var{name}@} +\pagecolor[@var{color model}]@{@var{color specification}@} +\nopagecolor +@end example + +The first two set the background of the page, and all subsequent pages, +to the color. For an explanation of the specification in the second +form @pxref{Colored text}. The third returns the background to normal, +which is a transparent background. (If that is not supported use +@code{\pagecolor@{white@}}, although that will make a white background +rather than the default transparent background.) + +@example + ... +\pagecolor@{cyan@} + ... +\nopagecolor +@end example + + +@node Graphics +@chapter Graphics + +@cindex graphics +@cindex graphics package + +You can use graphics such as PNG or PDF files in your @LaTeX{} document. +You need an additional package, which comes standard with @LaTeX{}. +This example is the short how-to. + +@example +\include@{graphicx@} % goes in the preamble + ... +\includegraphics[width=0.5\linewidth]@{plot.pdf@} +@end example + +To use the commands described here your document preamble must contain +either @code{\usepackage@{graphicx@}} or +@code{\usepackage@{graphics@}}. Most of the time, @file{graphicx} is the +better choice. + +Graphics come in two main types, raster and vector. @LaTeX{} can use +both. In raster graphics the file contains an entry for each location +in an array, describing what color it is. An example is a photograph, +in JPG format. In vector graphics, the file contains a list of +instructions such as @samp{draw a circle with this radius and that +center}. An example is a line drawing produced by the Asymptote +program, in PDF format. Generally vector graphics are more useful +because you can rescale their size without pixelation or other problems, +and because they often have a smaller size. + +There are systems particularly well-suited to make graphics for a +@LaTeX{} document. For example, these allow you to use the same fonts +as in your document. @LaTeX{} comes with a @code{picture} environment +(@pxref{picture}) that has simple capabilities. Besides that, there are +other ways to include the graphic-making commands in the document. Two +such systems are the PSTricks and TikZ packages. There are also systems +external to @LaTeX{}, that generate a graphic that you include using the +commands of this chapter. Two that use a programming language are +Asymptote and MetaPost. One that uses a graphical interface is Xfig. +Full description of these systems is outside the scope of this document; +see their documentation. + +@menu +* Graphics package options:: Options when you load the package. +* Graphics package configuration:: Where to look for files, which file types. +* Commands for graphics:: The available commands. +@end menu + + +@node Graphics package options +@section Graphics package options + +@cindex graphics package options +@cindex options, graphics package + +Synopsis (must be in the document preamble): + +@example +\usepackage[@var{comma-separated option list}]@{graphics@} +@end example + +or + +@example +\usepackage[@var{comma-separated option list}]@{graphicx@} +@end example + +The @code{graphicx} package has a format for optional arguments to the +@code{\includegraphics} command that is convenient (it is the key-value +format), so it is the better choice for new documents. When you load +the @file{graphics} or @file{graphicx} package with @code{\usepackage} +there are two kinds of available options. + +The first is that @LaTeX{} does not contain information about different +output systems but instead depends on information stored in a +@dfn{printer driver} file. Normally you should not specify the driver +option in the document, and instead rely on your system's default. One +advantage of this is that it makes the document portable across systems. + +For completeness here is a list of the drivers. The currently relevant +ones are: @file{dvipdfmx}, @file{dvips}, @file{dvisvgm}, @file{luatex}, +@file{pdftex}, @file{xetex}. The two @file{xdvi} and @file{oztex} are +essentially aliases for @file{dvips} (and @file{xdvi} is monochrome). +Ones that should not be used for new systems are: @file{dvipdf}, +@file{dvipdfm}, @file{dviwin}, @file{dvipsone}, @file{emtex}, +@file{pctexps}, @file{pctexwin}, @file{pctexhp}, @file{pctex32}, +@file{truetex}, @file{tcidvi}, @file{vtex} (and @file{dviwindo} is an +alias for @file{dvipsone}). These are stored in files with a +@file{.def} extension, such as @file{pdftex.def}. + +The second kind of options are below. + +@table @code +@item demo +Instead of an image file, @LaTeX{} puts in a 150@tie{}pt by 100@tie{}pt +rectangle (unless another size is specified in the +@code{\includegraphics} command). + +@item draft +For each graphic file, it is not shown but instead the file name is +printed in a box of the correct size. In order to determine the size, +the file must be present. + +@item final +(Default) Override any previous @code{draft} option, so that the +document shows the contents of the graphic files. + +@item hiderotate +Do not show rotated text. (This allows for the possibility that a +previewer does not have the capability to rotate text.) +@c what does it show? + +@item hidescale +Do not show scaled text. (This allows for the possibility that a +previewer does not have the capability to scale.) +@c what does it show? + +@item hiresbb +In a PS or EPS file the graphic size may be specified in two ways. The +@code{%%BoundingBox} lines describe the graphic size using integer +multiples of a PostScript point, that is, integer multiples of 1/72 +inch. A later addition to the PostScript language allows decimal +multiples, such as 1.23, in @code{%%HiResBoundingBox} lines. This +option has @LaTeX{} to read the size from the latter. + +@end table + + +@node Graphics package configuration +@section Graphics package configuration + +@cindex graphics +@cindex graphics package +@cindex configuration, graphics package +@cindex EPS files +@cindex JPEG files +@cindex JPG files +@cindex PDF graphic files +@cindex PNG files + +These commands configure the way @LaTeX{} searches the file system for +the graphic. + +The behavior of file system search code is necessarily platform +dependent. In this document we cover Linux, Macintosh, and Windows, as +those systems are typically configured. For other situations consult +the documentation in @file{grfguide.pdf}, or the @LaTeX{} source, or your +@TeX{} distribution's documentation. + +@menu +* \graphicspath:: Directories to search. +* \DeclareGraphicsExtensions:: File types, such as JPG or EPS. +* \DeclareGraphicsRule:: How to handle file types. +@end menu + + +@node \graphicspath +@subsection @code{\graphicspath} + +@findex \graphicspath + +Synopsis: + +@example +\graphicspath@{@var{list of dir names inside curly brackets}@} +@end example + +Declare a list of directories to search for graphics files. This allows +you to later say something like @code{\includegraphics@{lion.png@}} +instead of having to give its path. + +@LaTeX{} always looks for graphic files first in the current directory. +The declaration below tells the system to then look in the subdirectory +@file{pix}, and then @file{../pix}. + +@example +\usepackage@{graphicx@} % or graphics; put in preamble + ... +\graphicspath@{ @{pix/@} @{../pix/@} @} +@end example + +The @code{\graphicspath} declaration is optional. If you don't include +it then @LaTeX{}'s default is to search all of the places that it +usually looks for a file (it uses @LaTeX{}'s @code{\input@@path}). In +particular, in this case one of the places it looks is the current +directory. + +Enclose each directory name in curly braces; for example, above it says +@samp{@code{@{pix@}}}. Do this even if there is only one directory. +Each directory name must end in a forward slash, @file{/}. This is true +even on Windows, where good practice is to use forward slashes for all +the directory separators since it makes the document portable to other +platforms. If you have spaces in your directory name then use double +quotes, as with @code{@{"my docs/"@}}. Getting one of these rules wrong +will cause @LaTeX{} to report @code{Error: File `@var{filename}' not +found}. + +Basically, the algorithm is that with this example, after looking in the +current directory, + +@example +\graphicspath@{ @{pix/@} @{../pix/@} @} +... +\usepackage@{lion.png@} +@end example + +for each of the listed directories, @LaTeX{} concatenates it with the +file name and searches for the result, checking for @file{pix/lion.png} +and then @file{../pix/lion.png}. This algorithm means that the +@code{\graphicspath} command does not recursively search subdirectories: +if you issue @code{\graphicspath@{@{a/@}@}} and the graphic is in +@file{a/b/lion.png} then @LaTeX{} will not find it. It also means that +you can use absolute paths such as +@code{\graphicspath@{@{/home/jim/logos/@}@}} or +@code{\graphicspath@{@{C:/Users/Albert/Pictures/@}@}}. However, using +these means that the document is not portable. (You could preserve +portability by adjusting your @TeX{} system settings configuration file +parameter @code{TEXINPUTS}; see the documentation of your system.) + +You can use @code{\graphicspath} in the preamble or in the document +body. You can use it more than once. For debugging, show its value +with @code{\makeatletter\typeout@{\Ginput@@path@}\makeatother}. + +The directories are taken with respect to the base file. That is, +suppose that you are working on a document based on @file{book/book.tex} +and it contains @code{\include@{chapters/chap1@}}. If in +@file{chap1.tex} you put @code{\graphicspath@{@{plots/@}@}} then +@LaTeX{} will not search for graphics in @file{book/chapters/plots}, but +instead in @file{book/plots}. + + +@node \DeclareGraphicsExtensions +@subsection @code{\DeclareGraphicsExtensions} + +@findex \DeclareGraphicsExtensions + +Synopses: + +@example +\DeclareGraphicsExtensions@{@var{comma-separated list of file extensions}@} +@end example + +Declare the filename extensions to try. This allows you to specify the +order in which to choose graphic formats when you include graphic files +by giving the filename without the extension, as in +@code{\includegraphics@{functionplot@}}. + +In this example, @LaTeX{} will find files in the PNG format before PDF +files. + +@example +\DeclareGraphicsExtensions@{.png,PNG,.pdf,.PDF@} + ... +\includegraphics@{lion@} % will find @file{lion.png} before @file{lion.pdf} +@end example + +Because the file name @file{lion} does not have a period, @LaTeX{} uses +the extension list. For each directory in the graphics path +(@pxref{\graphicspath}), @LaTeX{} will try the extensions in the order +given. If it does not find such a file after trying all the directories +and extensions then it reports @samp{! LaTeX Error: File `@file{lion}' +not found}. Note that you must include the periods at the start of the +extensions. + +Because Linux and Macintosh filenames are case sensitive, the list of +file extensions is case sensitive on those platforms. The Windows +platform is not case sensitive. + +You are not required to include @code{\DeclareGraphicsExtensions} in +your document; the printer driver has a sensible default. For example, +the most recent @file{pdftex.def} has the extension list +@samp{@code{.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2}}. + +You can use this command in the preamble or in the document body. You +can use it more than once. For debugging, show its value with +@code{\makeatletter\typeout@{\Gin@@extensions@}\makeatother}. + + +@node \DeclareGraphicsRule +@subsection @code{\DeclareGraphicsRule} + +@findex \DeclareGraphicsRule + +Synopsis: + +@example +\DeclareGraphicsRule@{@var{extension}@}@{@var{type}@}@{@var{size-file extension}@}@{@var{command}@} +@end example + +Declare how to handle graphic files whose names end in @var{extension}. + +This example declares that all files with names have the form +@file{filename-without-dot.mps} will be treated as output from MetaPost, +meaning that the printer driver will use its MetaPost-handling code to +input the file. + +@example +\DeclareGraphicsRule@{.mps@}@{mps@}@{.mps@}@{@} +@end example + +This + +@example +\DeclareGraphicsRule@{*@}@{mps@}@{*@}@{@} +@end example + +tells @LaTeX{} that it should handle as MetaPost output any file with an +extension not covered by another rule, so it covers @file{filename.1}, +@file{filename.2}, etc. + +This describes the four arguments. + +@table @var +@item extension +The file extension to which this rule applies. The extension is anything +after and including the first dot in the filename. Use the Kleene star, +@code{*}, to denote the default behaviour for all undeclared extensions. + +@item type +The type of file involved. This type is a string that must be defined +in the printer driver. For instance, files with extensions @file{.ps}, +@file{.eps}, or @file{.ps.gz} may all be classed as type @code{eps}. +All files of the same type will be input with the same internal command +by the printer driver. For example, the file types that @file{pdftex} +recognizes are: @code{jpg}, @code{jbig2}, @code{mps}, @code{pdf}, +@code{png}, @code{tif}. + +@item size-file extension +The extension of the file to be read to determine the size of the +graphic, if there is such a file. It may be the same as @var{extension} +but it may be different. + +As an example, consider a PostScript graphic. To make it smaller, it +might be compressed into a @file{.ps.gz} file. Compressed files are not +easily read by @LaTeX{} so you can put the bounding box information in a +separate file. If @var{size-file extension} is empty then you must +specify size information in the arguments of @code{\includegraphics}. + +If the driver file has a procedure for reading size files for +@code{type} then that will be used, otherwise it will use the procedure +for reading @file{.eps} files. (Thus you may specify the size of bitmap +files in a file with a PostScript style @code{%%BoundingBox} line if no +other format is available.) + +@item command +A command that will be applied to the +file. This is very often left blank. This command must start with a +single backward quote. Thus, +@code{\DeclareGraphicsRule@{.eps.gz@}@{eps@}@{.eps.bb@}@{`gunzip -c +#1@}} specifies that any file with the extension @file{.eps.gz} should +be treated as an @code{eps} file, with the the BoundingBox information +stored in the file with extension @file{.eps.bb}, and that the command +@code{gunzip -c} will run on your platform to decompresses the file. + +Such a command is specific to your platform. In addition, your @TeX{} +system must allow you to run external commands; as a security measure +modern systems restrict running commands unless you explicitly allow it. +See the documentation for your @TeX{} distribution. + +@end table + +@node Commands for graphics +@section Commands for graphics + +@cindex graphics package commands +@cindex commands, graphics package + +These are the commands available with the @file{graphics} and +@file{graphicx} packages. + +@menu +* \includegraphics:: Using a graphic in your document. +* \rotatebox:: Rotating boxes, including graphics. +* \scalebox:: Scaling boxes, including graphics. +* \resizebox:: Scaling boxes, including graphics, to a set size. +@end menu + + +@node \includegraphics +@subsection @code{\includegraphics} + +@cindex graphics +@cindex graphics package +@cindex including graphics +@cindex importing graphics +@cindex EPS files +@cindex JPEG files +@cindex JPG files +@cindex PDF graphic files +@cindex PNG files +@findex \includegraphics + +Synopses for @file{graphics} package: + +@example +\includegraphics@{@var{filename}@} +\includegraphics[@var{urx},@var{ury}]@{@var{filename}@} +\includegraphics[@var{llx},@var{lly}][@var{urx},@var{ury}]@{@var{filename}@} +\includegraphics*@{@var{filename}@} +\includegraphics*[@var{urx},@var{ury}]@{@var{filename}@} +\includegraphics*[@var{llx},@var{lly}][@var{urx},@var{ury}]@{@var{filename}@} +@end example + +Synopses for @file{graphicx} package: + +@example +\includegraphics@{@var{filename}@} +\includegraphics[@var{key-value list}]@{@var{filename}@} +\includegraphics*@{@var{filename}@} +\includegraphics*[@var{key-value list}]@{@var{filename}@} +@end example + +Include a graphics file. The starred form @code{\includegraphics*} will +clip the graphic to the size specified, while for the unstarred form any +part of the graphic that is outside the box of the specified size will +over-print the surrounding area. + +This + +@example +\usepackage@{graphicx@} % in preamble + ... +\begin@{center@} + \includegraphics@{plot.pdf@} +\end@{center@} +@end example + +will incorporate into the document the graphic in @file{plot.pdf}, +centered and at its nominal size. You can also give a path to the file, +as with @code{\includegraphics@{graphics/plot.pdf@}}. To specify a list +of locations to search for the file, @pxref{\graphicspath}. + +If your filename includes spaces then put it in double quotes, as with +@code{\includegraphics@{"sister picture.jpg"@}}. + +The @code{\includegraphics@{@var{filename}@}} command decides on the +type of graphic by splitting @var{filename} on the first dot. You can +use @var{filename} with no dot, as in @code{\includegraphics@{turing@}} +and then @LaTeX{} tries a sequence of extensions such as @code{.png} and +@code{.pdf} until it finds a file with that extension +(@pxref{\DeclareGraphicsExtensions}). + +If your file name contains dots before the extension then you can hide +them with curly braces, as in +@code{\includegraphics@{@{plot.2018.03.12.a@}.pdf@}}. Or, if you use +the @file{graphicx} package then you can use the options @code{type} and +@code{ext}; see below. This and other filename issues are also handled +with the package @file{grffile}. + +This example puts a graphic in a figure environment so @LaTeX{} can +move it to the next page if fitting it on the current page is awkward +(@pxref{figure}). + +@example +\begin@{figure@} + \centering + \includegraphics[width=3cm]@{lungxray.jpg@} + \caption@{The evidence is overwhelming: don't smoke.@} \label@{fig:xray@} +\end@{figure@} +@end example + +This places a graphic that will not float, so it is sure to appear at +this point in the document even if makes @LaTeX{} stretch the text or +resort to blank areas on the page. It will be centered and will have a +caption. + +@example +\usepackage@{caption@} % in preamble + ... +\begin@{center@} + \includegraphics@{pix/nix.png@} + \captionof@{figure@}@{The spirit of the night@} \label@{pix:nix@} % if you want a caption +\end@{center@} +@end example + +This example puts a box with a graphic side by side with one having +text, with the two vertically centered. + +@example +\newcommand*@{\vcenteredhbox@}[1]@{\begingroup + \setbox0=\hbox@{#1@}\parbox@{\wd0@}@{\box0@}\endgroup@} + ... +\begin@{center@} + \vcenteredhbox@{\includegraphics[width=0.4\textwidth]@{plot@}@} + \hspace@{1em@} + \vcenteredhbox@{\begin@{minipage@}@{0.4\textwidth@} + \begin@{displaymath@} + f(x)=x\cdot \sin (1/x) + \end@{displaymath@} + \end@{minipage@}@} +\end@{center@} +@end example + +If you use the @file{graphics} package then the only options involve the +size of the graphic (but see @ref{\rotatebox} and @ref{\scalebox}). +When one optional argument is present then it is +@code{[@var{urx},@var{ury}]} and it gives the coordinates of the top +right corner of the image, as a pair of @TeX{} dimensions (@pxref{Units +of length}). If the units are omitted they default to @code{bp}. In +this case, the lower left corner of the image is assumed to be at (0,0). +If two optional arguments are present then the leading one is +@code{[@var{llx},@var{lly}]}, specifying the coordinates of the image's +lower left. Thus, @code{\includegraphics[1in,0.618in]@{...@}} calls for +the graphic to be placed so it is 1@tie{}inch wide and 0.618@tie{}inches +tall and so its origin is at (0,0). + +The @file{graphicx} package gives you many more options. Specify them +in a key-value form, as here. + +@example +\begin@{center@} + \includegraphics[width=1in,angle=90]@{lion@} + \hspace@{2em@} + \includegraphics[angle=90,width=1in]@{lion@} +\end@{center@} +@end example + +The options are read left-to-right. So the first graphic above is made +one inch wide and then rotated, while the second is rotated and then +made one inch wide. Thus, unless the graphic is perfectly square, the +two will end with different widths and heights. + +There are many options. The primary ones are listed first. + +Note that a graphic is placed by @LaTeX{} into a box, which is +traditionally referred to as its bounding box (distinct from the +PostScript BoundingBox described below). The graphic's printed area may +go beyond this box, or sit inside this box, but when @LaTeX{} makes up a +page it puts together boxes and this is the box allocated for the +graphic. + +@table @code +@item width +The graphic will be shown so its bounding box is this width. An example +is @code{\includegraphics[width=1in]@{plot@}}. You can use the standard +@TeX{} dimensions (@pxref{Units of length}) and also convenient is +@code{\linewidth}, or in a two-column document, @code{\columnwidth} +(@pxref{Page layout parameters}). An example is that by using the +@file{calc} package you can make the graphic be 1@tie{}cm narrow than +the width of the text with +@code{\includegraphics[width=\linewidth-1.0cm]@{hefferon.jpg@}}. + +@item height +The graphic will be shown so its bounding box is this height. You can +use the standard @TeX{} dimensions (@pxref{Units of length}), and also +convenient are @code{\pageheight} and @code{\textheight} (@pxref{Page +layout parameters}). For instance, +@code{\includegraphics[height=0.25\textheight]@{godel@}} will make the +graphic be a quarter of the height of the text area. + +@item totalheight +The graphic will be shown so its bounding box has this height plus +depth. This differs from the height if the graphic was rotated. For +instance, if it has been rotated by -90 then it will have zero height +but a large depth. + +@item keepaspectratio +If set to @code{true}, or just specified as with +@code{\includegraphics[...,keepaspectratio,...]@{...@}} and you give as +options both @code{width} and @code{height} (or @code{totalheight}), +then @LaTeX{} will make the graphic is as large as possible without +distortion. That is, @LaTeX{} will ensure that neither is the graphic +wider than @code{width} nor taller than @code{height} (or +@code{totalheight}). + +@item scale +Factor by which to scale the graphic. Specifying +@code{\includegraphics[scale=2.0]@{...@}} makes the graphic twice its +nominal size. This number may be any value; a number between 1 +and@tie{}0 will shrink the graphic and a negative number will reflect +it. + +@item angle +Rotate the picture. The angle is taken in degrees and counterclockwise. +The graphic is rotated about its @code{origin}; see that option. For a +complete description of how rotated material is typeset, +@pxref{\rotatebox}. + +@item origin +The point of the graphic about which the rotation happens. Possible +values are any string containing one or two of: @code{l} for left, +@code{r} for right, @code{b} for bottom, @code{c} for center, @code{t} +for top, and @code{B} for baseline. Thus, +@code{\includegraphics[angle=180,origin=c]@{moon@}} will turn the +picture upside down from the center, while +@code{\includegraphics[angle=180,origin=lB]@{LeBateau@}} will turn its +picture upside down about its left baseline. (The character @code{c} +gives the horizontal center in @code{bc} or @code{tc}, but gives the +vertical center in @code{lc} or @code{rc}.) The default is @code{lB}. + +To rotate about an arbitrary point, @pxref{\rotatebox}. + +@end table + +These are lesser-used options. + +@table @code +@item viewport +Pick out a subregion of the graphic to show. Takes four arguments, +separated by spaces and given in @TeX{} dimensions, as with +@code{\includegraphics[.., viewport=0in 0in 1in 0.618in]@{...@}}. The +dimensions default to big points,@tie{}@code{bp}. They are taken +relative to the origin specified by the bounding box. See also the +@code{trim} option. + +@item trim +Gives parts of the graphic to not show. Takes four arguments, separated +by spaces, that are given in @TeX{} dimensions, as with +@code{\includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]@{...@}}. +These give the amounts of the graphic not to show, that is, @LaTeX{} +will crop the picture by 0@tie{}inches on the left, 0.1@tie{}inches on +the bottom, 0.2@tie{}inches on the right, and 0.3@tie{}inches on the +top. See also the @code{viewport} option. + +@item clip +If set to @code{true}, or just specified as with +@code{\includegraphics[...,clip,...]@{...@}}, then the graphic is +cropped to the bounding box. You can get this effect by instead using +the starred form of the command, as +@code{\includegraphics*[...]@{...@}}. + +@item page +Give the page number of a multi-page PDF file. The default is +@code{page=1}. + +@item pagebox +Specifies which bounding box to use for PDF files from among +@code{mediabox}, @code{cropbox}, @code{bleedbox}, @code{trimbox}, or +@code{artbox}. PDF files do not have the BoundingBox that PostScript +files have, but may specify up to four predefined rectangles. The +MediaBox gives the boundaries of the physical medium. The CropBox is the +region to which the contents of the page are to be clipped when +displayed. The BleedBox is the region to which the contents of the page +should be clipped in production. The TrimBox is the intended dimensions +of the finished page. The ArtBox is the extent of the page's meaningful +content. The driver will set the image size based on CropBox if +present, otherwise it will not use one of the others, with a +driver-defined order of preference. MediaBox is always present. + +@item interpolate +Enable or disable interpolation of raster images by the viewer. Can be +set with @code{interpolate=true} or just specified as with +@code{\includegraphics[...,interpolate,...]@{...@}}. + +@item quiet +Do not write information to the log. You can set it with +@code{quiet=true} or just specified it with +@code{\includegraphics[...,quite,...]@{...@}}, + +@item draft +If you set it with @code{draft=true} or just specified it with +@code{\includegraphics[...,draft,...]@{...@}}, then the graphic will not +appear in the document, possibly saving color printer ink. Instead, +@LaTeX{} will put an empty box of the correct size with the filename +printed in it. + +@end table + +These options address the bounding box for Encapsulated PostScript +graphic files, which have a size specified with a line +@code{%%BoundingBox} that appears in the file. It has four values, +giving the lower @math{x} coordinate, lower @math{y} coordinate, upper +@math{x} coordinate, and upper @math{y} coordinate. The units are +PostScript points, equivalent to @TeX{}'s big points, 1/72@tie{}inch. +For example, if an @file{.eps} file has the line @code{%%BoundingBox 10 +20 40 80} then its natural size is 30/72@tie{}inch wide by +60/72@tie{}inch tall. + +@table @code +@item bb +Specify the bounding box of the displayed region. The argument is four +dimensions separated by spaces, as with @code{\includegraphics[.., bb= +0in 0in 1in 0.618in]@{...@}}. Usually @code{\includegraphics} reads the +BoundingBox numbers from the EPS file automatically, so this option is +only useful if the bounding box is missing from that file or if you want +to change it. + +@item bbllx, bblly, bburx, bbury +Set the bounding box. These four are obsolete, but are retained for +compatibility with old packages. + +@item natwidth, natheight +An alternative for @code{bb}. Setting +@code{\includegraphics[...,natwidth=1in,natheight=0.618in,...]@{...@}} +is the same as setting @code{bb=0 0 1in 0.618in}. + +@item hiresbb +If set to @code{true}, or just specified as with +@code{\includegraphics[...,hiresbb,...]@{...@}}, then @LaTeX{} will look +for @code{%%HiResBoundingBox} lines instead of @code{%%BoundingBox} +lines. (The @code{BoundingBox} lines use only natural numbers while the +@code{HiResBoundingBox} lines use decimals; both use units equivalent to +@TeX{}'s big points, 1/72@tie{}inch.) To override a prior setting of +@code{true}, you can set it to @code{false}. + +@end table + +These following options allow a user to override @LaTeX{}'s method of +choosing the graphic type based on the filename extension. An example +is that @code{\includegraphics[type=png,ext=.xxx,read=.xxx]@{lion@}} +will read the file @file{lion.xxx} as though it were +@file{lion.png}. For more on these, @pxref{\DeclareGraphicsRule}. + +@table @code +@item type +Specify the graphics type. + +@item ext +Specify the graphics extension. +Only use this in conjunction with the option @code{type}. + +@item read +Specify the file extension of the read file. +Only use this in conjunction with the option @code{type}. + +@item command +Specify a command to be applied to this file. +Only use this in conjunction with the option @code{type}. +@c write18 and restricted execution. + +@end table + + +@node \rotatebox +@subsection @code{\rotatebox} + +@cindex rotation +@cindex rotating graphics +@cindex rotating text +@findex \rotatebox + +Synopsis for @file{graphics} package: + +@example +\rotatebox@{@var{angle}@}@{@var{material}@} +@end example + +Synopses for @file{graphicx} package: + +@example +\rotatebox@{@var{angle}@}@{@var{material}@} +\rotatebox[@var{key-value list}]@{@var{angle}@}@{@var{material}@} +@end example + +Put @var{material} in a box and rotate it @var{angle} degrees counterclockwise. + +This example rotates the table column heads forty five degrees. + +@example +\begin@{tabular@}@{ll@} + \rotatebox@{45@}@{Character@} &\rotatebox@{45@}@{NATO phonetic@} \\ + A &AL-FAH \\ + B &BRAH-VOH +\end@{tabular@} +@end example + +The @var{material} can be anything that goes in a box, including a graphic. + +@example + \rotatebox[origin=c]@{45@}@{\includegraphics[width=1in]@{lion@}@} +@end example + +To place the rotated material, the first step is that @LaTeX{} sets +@var{material} in a box, with a reference point on the left baseline. +The second step is the rotation, by default about the reference point. +The third step is that @LaTeX{} computes a box to bound the rotated +material. Fourth, @LaTeX{} moves this box horizontally so that the left +edge of this new bounding box coincides with the left edge of the box +from the first step (they need not coincide vertically). This new +bounding box, in its new position, is what @LaTeX{} uses as the box when +typesetting this material. + +If you use the @file{graphics} package then the rotation is about the +reference point of the box. If you use the @file{graphicx} package then +then these are the options that can go in the @var{key-value list}, but +note that you can get the same effect without needing this package, +except for the @code{x} and @code{y} options (@pxref{\includegraphics}). + +@table @code +@item origin +The point of the @var{material}'s box about which the rotation happens. +Possible values are any string containing one or two of: @code{l} for +left, @code{r} for right, @code{b} for bottom, @code{c} for center, +@code{t} for top, and @code{B} for baseline. Thus, +@code{\includegraphics[angle=180,origin=c]@{moon@}} will turn the +picture upside down from the center, while +@code{\includegraphics[angle=180,origin=lB]@{LeBateau@}} will turn its +picture upside down about its left baseline. (The character @code{c} +gives the horizontal center in @code{bc} or @code{tc} but gives the +vertical center in @code{lc} or @code{rc}.) The default is @code{lB}. + +@item x, y +Specify an arbitrary point of rotation with +@code{\rotatebox[x=@var{@TeX{} dimension},y=@var{@TeX{} +dimension}]@{...@}} (@pxref{Units of length}). These give the offset +from the box's reference point. + +@item units +This key allows you to change the default of degrees counterclockwise. +Setting @code{units=-360} changes the direction to degrees clockwise and +setting @code{units=6.283185} changes to radians counterclockwise. + +@end table + + +@node \scalebox +@subsection @code{\scalebox} + +@cindex graphics, scaling +@cindex graphics, resizing +@cindex scaling +@cindex resizing +@cindex text, scaling +@cindex text, resizing +@findex \scalebox +@findex \reflectbox + +Synopses: + +@example +\scalebox@{@var{horizontal factor}@}@{@var{material}@} +\scalebox@{@var{horizontal factor}@}[@var{vertical factor}]@{@var{material}@} +\reflectbox@{@var{material}@} +@end example + +Scale the @var{material}. + +This example halves the size, both horizontally and vertically, of the +first text and doubles the size of the second. + +@example +\scalebox@{0.5@}@{DRINK ME@} and \scalebox@{2.0@}@{Eat Me@} +@end example + +If you do not specify the optional @var{vertical factor} then it +defaults to the same value as the @var{horizontal factor}. + +You can use this command to resize a graphic, as with +@code{\scalebox@{0.5@}@{\includegraphics@{lion@}@}}. If you use the +@file{graphicx} package then you can accomplish the same thing with +optional arguments to @code{\includegraphics} +(@pxref{\includegraphics}). + +The @code{\reflectbox} command abbreviates +@code{\scalebox@{-1@}[1]@{@var{material}@}}. Thus, @code{Able was +I\reflectbox@{Able was I@}} will show the phrase @samp{Able was I} +immediately followed by its mirror reflection. + + +@node \resizebox +@subsection @code{\resizebox} + +@cindex graphics, scaling +@cindex graphics, resizing +@cindex scaling +@cindex resizing +@cindex text, scaling +@cindex text, resizing +@findex \resizebox + +Synopses: + +@example +\resizebox@{@var{horizontal length}@}@{@var{vertical length}@}@{@var{material}@} +\resizebox*@{@var{horizontal length}@}@{@var{vertical length}@}@{@var{material}@} +@end example + +Given a size, such as @code{3cm}, transform @var{material} to make it +that size. If either @var{horizontal length} or @var{vertical length} +is an exclamation point@tie{}@code{!} then the other argument is used +to determine a scale factor for both directions. + +This example makes the graphic be a half inch wide and scales it +vertically by the same factor to keep it from being distorted. + +@example +\resizebox@{0.5in@}@{!@}@{\includegraphics@{lion@}@} +@end example + +The unstarred form @code{\resizebox} takes @var{vertical length} to be +the box's height while the starred form @code{\resizebox*} takes it to +be height+depth. For instance, make the text have a height+depth of a +quarter inch with @code{\resizebox*@{!@}@{0.25in@}@{\parbox@{1in@}@{This +box has both height and depth.@}@}}. + +You can use @code{\depth}, @code{\height}, @code{\totalheight}, and +@code{\width} to refer to the original size of the box. Thus, make the +text two inches wide but keep the original height with +@code{\resizebox@{2in@}@{\height@}@{Two inches@}}. + + @node Special insertions @chapter Special insertions @@ -9578,10 +11459,10 @@ moving arguments (@pxref{\protect}). These commands do not change the case of letters used in the name of a command within @var{text}. But they do change the case of every other -latin character inside the argument @var{text}. Thus, -@code{\MakeUppercase@{Let $y=f(x)$}@} produces ``LET Y=F(X)''. Another +Latin letter inside the argument @var{text}. Thus, +@code{\MakeUppercase@{Let $y=f(x)$}@} produces @samp{LET Y=F(X)}. Another example is that the name of an environment will be changed, so that -@code{\MakeUppercase@{\begin@{tabular@} ... \end@{tabular@}} will +@code{\MakeUppercase@{\begin@{tabular@} ... \end@{tabular@}@}} will produce an error because the first half is changed to @code{\begin@{TABULAR@}}. @@ -9590,16 +11471,23 @@ document, The table used is designed for the font encoding T1; this works well with the standard @TeX{} fonts for all Latin alphabets but will cause problems when using other alphabets. -To change the case of text that results from a command inside @var{text} +To change the case of text that results from a macro inside @var{text} you need to do expansion. Here the @code{\Schoolname} produces -``COLLEGE OF MATHEMATICS''. +@samp{COLLEGE OF MATHEMATICS}. @example \newcommand@{\schoolname@}@{College of Mathematics@} -\newcommand@{\Schoolname@}@{\expandafter\MakeUppercase\expandafter@{\schoolname@}@} +\newcommand@{\Schoolname@}@{\expandafter\MakeUppercase +@w{ }\expandafter@{\schoolname@}@} @end example -To uppercase only the first letter of words use the package +@PkgIndex{textcase} +The @file{textcase} package brings some of the missing feature of the +standard @LaTeX{} commands @code{\MakeUppercase} and +@code{\MakeLowerCase}. + +@PkgIndex{mfirstuc} +To uppercase only the first letter of words, you can use the package @file{mfirstuc}. |