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 | 908 |
1 files changed, 534 insertions, 374 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 afd657383e5..d4f0726deb0 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 678 2018-07-02 20:51:26Z karl $ +@c $Id: latex2e.texi 710 2018-10-14 14:32:52Z karl $ @comment %**start of header (This is for running Texinfo on a region.) @setfilename latex2e.info -@set UPDATED July 2018 +@set UPDATED October 2018 @include common.texi @settitle @LaTeX{}2e unofficial reference manual (@value{UPDATED}) @comment %**end of header (This is for running Texinfo on a region.) @@ -29,6 +29,7 @@ @c xx JH \baselineskip https://texfaq.org/FAQ-baselinepar @c xx JH \contentsline, \@@dottedtocline? @c xx JH more on \write18, beyond what's mentioned in Command line. +@c xx JH \numexpr, \dimexpr, \glueexpr, \muexpr @c @c xx The typeset source2e has an index with all kernel @c xx commands, though some are internal and shouldn't be included. @@ -39,8 +40,8 @@ This document is an unofficial reference manual for @LaTeX{}, a document preparation system, version of @value{UPDATED}. -This manual was originally translated from @file{LATEX.HLP} v1.0a in -the VMS Help Library. The pre-translation version was written by +This manual was originally translated from @file{LATEX.HLP} v1.0a in the +VMS Help Library. The pre-translation version was written by George@tie{}D. Greenwade of Sam Houston State University. The @LaTeX{}@tie{}2.09 version was written by Stephen Gilmore. The @LaTeX{}2e version was adapted from this by Torsten Martinsen. Karl @@ -48,8 +49,10 @@ Berry made further updates and additions, and gratefully acknowledges using @cite{Hypertext Help with @LaTeX{}}, by Sheldon Green, and @cite{@LaTeX{} Command Summary} (for @LaTeX{}@tie{}2.09) by L.@tie{}Botway and C.@tie{}Biemesderfer (published by the @TeX{} Users -Group as @cite{@TeX{}niques} number 10), as reference material (no -text was directly copied). +Group as @cite{@TeX{}niques} number 10), as reference material. We also +gratefully acknowledge additional material appearing in +latex2e-reference by Martin Herbert Dietze. (From these references no +text was directly copied.) Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 Karl Berry.@* @@ -180,10 +183,17 @@ This document is an unofficial reference manual (version of @cindex home page for manual This is an unofficial reference manual for the @LaTeX{}2e document preparation system, which is a macro package for the @TeX{} -typesetting program (@pxref{Overview}). This document's home page is -@url{@value{LTXREFMAN_HOME_PAGE}}. That page has links to the -current output in various formats, sources, mailing list archives and -subscriptions, and other infrastructure. +typesetting program (@pxref{Overview}). + +This document's home page is @url{@value{LTXREFMAN_HOME_PAGE}}. There +you can get the sources, subscribe to the mailing list or read its +archives, see other infrastructure, and get the current output in +various formats. In particular, the output comes in two web formats. +Probably the most convenient one, shown at @url{http://latexref.xyz/}, +has pages for each topic and so is good for a quick lookup; see also the +note there about easy-to-remember links. The other, shown at +@url{http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co}, +has all the information on single page. @cindex @LaTeX{} vs.@: @LaTeX{}2e In this document, we will mostly just use `@LaTeX{}' rather than @@ -268,10 +278,11 @@ produce the logo with @code{\LaTeX}. Where use of the logo is not sensible, such as in plain text, write it as @samp{LaTeX}. @menu -* Starting and ending:: The standard beginning and end of a document. +* Starting and ending:: The standard beginning and end of a document. * Output files:: Files produced. * @TeX{} engines:: Programs that can compile @TeX{} and @LaTeX{}. * @LaTeX{} command syntax:: General syntax of @LaTeX{} commands. +* Environment:: Area of the source giving distinct behavior. * CTAN:: Our repository. @end menu @@ -511,6 +522,12 @@ argument comes last, with no required argument after it, then to make the first character of the following text be an open square bracket, hide it inside curly braces. +Some of @LaTeX{}'s commands are a @dfn{declaration}. Such a command +changes the value the meaning of some other command or parameter. For +instance, the @code{\mainmatter} declaration changes the typesetting of +page numbers from roman numerals to arabic (@pxref{\frontmatter & +\mainmatter & \backmatter}). + @LaTeX{} has the convention that some commands have a @code{*} form that is related to the form without a @code{*}, such as @code{\chapter} and @code{\chapter*}. The exact difference in behavior varies from command @@ -519,15 +536,9 @@ to command. This manual describes all accepted options and @code{*}-forms for the commands it covers (barring unintentional omissions, a.k.a.@: bugs). -@menu -* Environment:: Area of the source with distinct behavior. -* Declaration:: Change the value or meaning of a command. -* \makeatletter & \makeatother:: Change the status of the at-sign character. -@end menu - @node Environment -@subsection Environments +@section Environment Synopsis: @@ -548,7 +559,9 @@ behavior. For instance, for poetry in @LaTeX{} put the lines between \end@{verse@} @end example -@xref{Environments} for a list of environments. +@xref{Environments} for a list of environments. Particularly notable is +that every @LaTeX{} document must have a @code{document} environment, +a @code{\begin@{document@} ... \end@{document@}} pair. The @var{environment name} at the beginning must exactly match that at the end. This includes the case where @var{environment name} ends in a @@ -567,151 +580,8 @@ required (it specifies the formatting of columns). @end example -@node Declaration -@subsection Command declarations - -A command that changes the value, or changes the meaning, of some other -command or parameter. For instance, the @code{\mainmatter} command -changes the setting of page numbers from roman numerals to arabic. - - -@node \makeatletter & \makeatother -@subsection @code{\makeatletter} & @code{\makeatother} - -Synopsis: - -@example -\makeatletter - ... definition of commands with @@ in their name .. -\makeatother -@end example - -Used to redefine internal @LaTeX{} commands. @code{\makeatletter} makes -the at-sign character@tie{}@code{@@} have the category code of a letter, -11. @code{\makeatother} sets the category code of@tie{}@code{@@} to 12, -its original value. - -As each character is read by @TeX{} for @LaTeX{}, it is assigned a -character category code, or -@cindex catcode -@cindex character category code -@cindex category code, character -@dfn{catcode} for short. For instance, the backslash@tie{}@code{\} is -assigned the catcode 0, for characters that start a command. These two -commands alter the catcode assigned to @code{@@}. - -The alteration is needed because many of @LaTeX{}'s commands use -@code{@@} in their name, to prevent users from accidentally defining a -command that replaces one of @LaTeX{}'s own. Command names consist of a -category@tie{}0 character, ordinarily backslash, followed by letters, -category@tie{}11 characters (except that a command name can also consist -of a category@tie{}0 character followed by a single non-letter symbol). -So under the default category codes, user-defined commands cannot -contain an @code{@@}. But @code{\makeatletter} and @code{\makeatother} -allow users to define or redefine commands named with @code{@@}. - -Use these two commands inside a @file{.tex} file, in the preamble, when -defining or redefining a command with @code{@@} in its name. Don't use -them inside @file{.sty} or @file{.cls} files since the -@code{\usepackage} and @code{\documentclass} commands set the at sign to -have the character code of a letter. - -@PkgIndex{macros2e} -For a comprehensive list of macros with an at-sign -in their names see @url{http://ctan.org/pkg/macros2e}. These macros are -mainly intended to package or class authors. - -In this example the class file has a command -@code{\thesis@@universityname} that the user wants to change. These -three lines should go in the preamble, before the -@code{\begin@{document@}}. - -@example -\makeatletter -\renewcommand@{\thesis@@universityname@}@{Saint Michael's College@} -\makeatother -@end example - -@menu -* \@@ifstar:: Define your own commands with *-variants. -@end menu - - -@node \@@ifstar -@subsubsection @code{\@@ifstar} - -@findex \@@ifstar -@cindex commands, star-variants -@cindex star-variants, commands - -Synopsis: - -@example -\newcommand@{\mycmd@}@{\@@ifstar@{\mycmd@@star@}@{\mycmd@@nostar@}@} -\newcommand@{\mycmd@@nostar@}[@var{nostar-num-args}]@{@var{nostar-body}@} -\newcommand@{\mycmd@@star@}[@var{star-num-args}]@{@var{star-body}@} -@end example - -Many standard @LaTeX{} environments or commands have a variant with the -same name but ending with a star character@tie{}@code{*}, an asterisk. -Examples are the @code{table} and @code{table*} environments and the -@code{\section} and @code{\section*} commands. - -When defining environments, following this pattern is straightforward -because @code{\newenvironment} and @code{\renewenvironment} allow the -environment name to contain a star. For commands the situation is more -complex. As in the synopsis above, there will be a user-called command, -given above as @code{\mycmd}, which peeks ahead to see if it is followed -by a star. For instance, @LaTeX{} does not really have a -@code{\section*} command; instead, the @code{\section} command peeks -ahead. This command does not accept arguments but instead expands to -one of two commands that do accept arguments. In the synopsis these two -are @code{\mycmd@@nostar} and @code{\mycmd@@star}. They could take the -same number of arguments or a different number, or no arguments at all. -As always, in a @LaTeX{} document a command using at-sign@tie{}@code{@@} -must be enclosed inside a @code{\makeatletter ... \makeatother} block -(@pxref{\makeatletter & \makeatother}). - -This example of @code{\@@ifstar} defines the command @code{\ciel} and a -variant @code{\ciel*}. Both have one required argument. A call to -@code{\ciel@{night@}} will return "starry night sky" while -@code{\ciel*@{blue@}} will return "starry not blue sky". - -@example -\newcommand*@{\ciel@@unstarred@}[1]@{starry #1 sky@} -\newcommand*@{\ciel@@starred@}[1]@{starry not #1 sky@} -\newcommand*@{\ciel@}@{\@@ifstar@{\ciel@@starred@}@{\ciel@@unstarred@}@} -@end example - -In the next example, the starred variant takes a different number of -arguments than the unstarred one. With this definition, Agent 007's -@code{``My name is \agentsecret*@{Bond@}, -\agentsecret@{James@}@{Bond@}.''} is equivalent to entering the commands -@code{``My name is \textsc@{Bond@}, \textit@{James@} textsc@{Bond@}.''} - -@example -\newcommand*@{\agentsecret@@unstarred@}[2]@{\textit@{#1@} \textsc@{#2@}@} -\newcommand*@{\agentsecret@@starred@}[1]@{\textsc@{#1@}@} -\newcommand*@{\agentsecret@}@{% - \@@ifstar@{\agentsecret@@starred@}@{\agentsecret@@unstarred@}@} -@end example - -There are two sometimes more convenient ways to accomplish the work of -@code{\@@ifstar}. The @file{suffix} package allows the construct -@code{\newcommand\mycommand@{@var{unstarred version}@}} followed by -@code{\WithSuffix\newcommand\mycommand*@{@var{starred version}@}}. And -@LaTeX{}3 has the @file{xparse} package that allows this code. - -@example -\NewDocumentCommand\foo@{s@}@{\IfBooleanTF#1 - @{@var{starred version}@}% - @{@var{unstarred version}@}% - @} -@end example - - @node CTAN -@section CTAN: Comprehensive @TeX{} Archive Network +@section CTAN: the Comprehensive @TeX{} Archive Network @cindex CTAN @@ -1033,9 +903,11 @@ others. For instance, the class @code{smcmemo} might have commands A class file or package file typically has four parts. @enumerate +@item In the @dfn{identification part}, the file says that it is a @LaTeX{} package or class and describes itself, using the @code{\NeedsTeXFormat} and @code{\ProvidesClass} or @code{\ProvidesPackage} commands. + @item The @dfn{preliminary declarations part} declares some commands and can also load other files. Usually these commands will be those needed @@ -1045,6 +917,7 @@ people for the to-head, as @code{\documentclass[mathto]@{smcmemo@}}, and therefore needs to define a command @code{\newcommand@{\setto@}[1]@{\def\@@tolist@{#1@}@}} used in that file. + @item In the @dfn{handle options part} the class or package declares and processes its options. Class options allow a user to start their @@ -1052,6 +925,7 @@ document as @code{\documentclass[@var{option list}]@{@var{class name}@}}, to modify the behavior of the class. An example is when you declare @code{\documentclass[11pt]@{article@}} to set the default document font size. + @item Finally, in the @dfn{more declarations part} the class or package usually does most of its work: declaring new variables, commands and fonts, and @@ -5244,7 +5118,7 @@ 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 +have to hide the bracket inside curly braces, as in: @code{\item @{[@} is an open square bracket}; otherwise, @LaTeX{} will think it marks the start of an optional label. @@ -5446,7 +5320,7 @@ stretchable space. @end table -The @var{inner-pos} argument makes sense when the @var{height} options +The @var{inner-pos} argument makes sense when the @var{height} option is set to a value larger than the @code{minipage}'s natural height. To see the effect of the options, run this example with the various choices in place of @code{b}. @@ -6589,8 +6463,8 @@ ampersand, @code{&}. The end of each row is marked with a double backslash, @code{\\}. Put a horizontal rule below a row, after a double backslash, with @code{\hline}. @findex \\ @r{for @code{tabular}} -This @code{\\} is optional after the last row unless an @code{\hline} -command follows, to put a rule below the table. +After the last row the @code{\\} is optional, unless an @code{\hline} +command follows to put a rule below the table. The required and optional arguments to @code{tabular} consist of: @@ -6643,9 +6517,9 @@ If you override the default and use an @@-expression then @LaTeX{} does not insert @code{\tabcolsep} so you must insert any desired space yourself, as in @code{@@@{\hspace@{1em@}@}}. -An empty expression @code{@@@{@}} will eliminate the space. In -particular, sometimes you want to eliminate the the space before the -first column or after the last one, as in the example below where the +An empty expression @code{@@@{@}} will eliminate the space. In +particular, sometimes you want to eliminate the space before the first +column or after the last one, as in the example below where the tabular lines need to lie on the left margin. @example @@ -6855,10 +6729,10 @@ range en-dash. @end example @noindent -Note that although the @code{tabular} specification by default puts a -vertical rule between the first and second columns, because there is no -vertical bar in the @var{cols} of either of the first row's -@code{\multicolumn} commands, no rule appears in the first row. +Although the @code{tabular} specification by default puts a vertical +rule between the first and second columns, no such vertical rule appears +in the first row here. That's because there is no vertical bar in the +@var{cols} part of the first row's first @code{\multicolumn} command. @node \vline @@ -7126,12 +7000,21 @@ The ultimate source is \cite@{texbook@}. @end example @noindent -produces the output @samp{... source is [1]}. +produces output like @samp{... source is [1]}. (You can change the +appearance of the citation with bibliography styles. More is in +@ref{Using BibTeX}.) The optional argument @var{subcite} is appended to the citation. For example, @code{See 14.3 in \cite[p.~314]@{texbook@}} might produce @samp{See 14.3 in [1, p.@tie{}314]}. +In addition to what appears in the output, @code{\cite} writes +information to the auxiliary file @file{@var{filename}.aux}. For +instance, @code{\cite@{latexdps@}} writes @samp{\citation@{latexdps@}} +to that file. This information is used by Bib@TeX{} to include in your +reference list only those works that you have actually cited; see +@ref{\nocite} also. + If @var{keys} is not in your bibliography information then you get @samp{LaTeX Warning: There were undefined references}, and in the output the citation shows as a boldface question mark between square brackets. @@ -7139,14 +7022,7 @@ There are two possible causes. If you have mistyped something, as in @code{\cite@{texbok@}} then you need to correct the spelling. On the other hand, if you have just added or modified the bibliographic information and so changed the @file{.aux} file (@pxref{\bibitem}) then -the fix may be to just run @LaTeX{} again. - -In addition to what appears in the output, @code{\cite} writes -information to the auxiliary file @file{@var{filename}.aux}. For -instance, @code{\cite@{latexdps@}} writes @samp{\citation@{latexdps@}} -to that file. This information is used by Bib@TeX{} to include in your -reference list only those works that you have actually cited; see -@ref{\nocite} also. +the fix may be to run @LaTeX{} again. @node \nocite @@ -8501,15 +8377,17 @@ second.\footnotefrom@{% @LaTeX{} has support for making new commands of many different kinds. @menu -* \newcommand & \renewcommand:: (Re)define a new command. -* \providecommand:: Define a new command, if name not used. -* \newcounter:: Define a new counter. -* \newlength:: Define a new length. -* \newsavebox:: Define a new box. +* \newcommand & \renewcommand:: (Re)define a new command. +* \providecommand:: Define a new command, if name not used. +* \makeatletter & \makeatother:: Change the status of the at-sign character. +* \@@ifstar:: Define your own commands with *-variants. +* \newcounter:: Define a new counter. +* \newlength:: Define a new length. +* \newsavebox:: Define a new box. * \newenvironment & \renewenvironment:: Define a new environment. -* \newtheorem:: Define a new theorem-like environment. -* \newfont:: Define a new font name. -* \protect:: Using tricky commands. +* \newtheorem:: Define a new theorem-like environment. +* \newfont:: Define a new font name. +* \protect:: Using tricky commands. * \ignorespaces & \ignorespacesafterend:: Discard extra spaces. @end menu @@ -8713,6 +8591,137 @@ outputs @samp{From Saint Michael's College}. Unlike @code{\newcommand}, the repeated use of @code{\providecommand} does not give an error. +@node \makeatletter & \makeatother +@section @code{\makeatletter} & @code{\makeatother} + +Synopsis: + +@example +\makeatletter + ... definition of commands with @@ in their name .. +\makeatother +@end example + +Use this pair when you redefine @LaTeX{} commands that are named with an +at-sign character@tie{}@samp{@code{@@}}. The @code{\makeatletter} +declaration makes the at-sign character have the category code of a +letter, code@tie{}11. The @code{\makeatother} declaration sets the +category code of the at-sign to code@tie{}12, its default value. + +As @TeX{} reads characters, it assigns each one a category code, or +@cindex catcode +@cindex character category code +@cindex category code, character +@dfn{catcode}. For instance, it assigns the backslash +character@tie{}@samp{@code{\}} the catcode@tie{}0. Command names +consist of a category@tie{}0 character, ordinarily backslash, followed +by letters, category@tie{}11 characters (except that a command name can +also consist of a category@tie{}0 character followed by a single +non-letter symbol). + +@LaTeX{}'s source code has the convention that some commands use +@code{@@} in their name. These commands are mainly intended for package +or class writers. The convention prevents authors who are just using a +package or class from accidentally replacing such a command with one of +their own, because by default the at-sign has catcode@tie{}12. + +The pair @code{\makeatletter} and @code{\makeatother} changes the +default code and then changes it back. Use them inside a @file{.tex} +file, in the preamble, when you are defining or redefining commands +named with @code{@@}, by having them surround your definition. Don't +use these inside @file{.sty} or @file{.cls} files since the +@code{\usepackage} and @code{\documentclass} commands already arrange +that the at-sign has the character code of a letter, catcode@tie{}11. + +@PkgIndex{macros2e} +For a comprehensive list of macros with an at-sign in their names see +@url{http://ctan.org/pkg/macros2e}. + +In this example the class file has a command +@code{\thesis@@universityname} that the user wants to change. These +three lines should go in the preamble, before the +@code{\begin@{document@}}. + +@example +\makeatletter +\renewcommand@{\thesis@@universityname@}@{Saint Michael's College@} +\makeatother +@end example + + +@node \@@ifstar +@section @code{\@@ifstar} + +@findex \@@ifstar +@cindex commands, star-variants +@cindex star-variants, commands + +Synopsis: + +@example +\newcommand@{\mycmd@}@{\@@ifstar@{\mycmd@@star@}@{\mycmd@@nostar@}@} +\newcommand@{\mycmd@@nostar@}[@var{nostar-num-args}]@{@var{nostar-body}@} +\newcommand@{\mycmd@@star@}[@var{star-num-args}]@{@var{star-body}@} +@end example + +Many standard @LaTeX{} environments or commands have a variant with the +same name but ending with a star character@tie{}@code{*}, an asterisk. +Examples are the @code{table} and @code{table*} environments and the +@code{\section} and @code{\section*} commands. + +When defining environments, following this pattern is straightforward +because @code{\newenvironment} and @code{\renewenvironment} allow the +environment name to contain a star. For commands the situation is more +complex. As in the synopsis above, there will be a user-called command, +given above as @code{\mycmd}, which peeks ahead to see if it is followed +by a star. For instance, @LaTeX{} does not really have a +@code{\section*} command; instead, the @code{\section} command peeks +ahead. This command does not accept arguments but instead expands to +one of two commands that do accept arguments. In the synopsis these two +are @code{\mycmd@@nostar} and @code{\mycmd@@star}. They could take the +same number of arguments or a different number, or no arguments at all. +As always, in a @LaTeX{} document a command using at-sign@tie{}@code{@@} +must be enclosed inside a @code{\makeatletter ... \makeatother} block +(@pxref{\makeatletter & \makeatother}). + +This example of @code{\@@ifstar} defines the command @code{\ciel} and a +variant @code{\ciel*}. Both have one required argument. A call to +@code{\ciel@{night@}} will return "starry night sky" while +@code{\ciel*@{blue@}} will return "starry not blue sky". + +@example +\newcommand*@{\ciel@@unstarred@}[1]@{starry #1 sky@} +\newcommand*@{\ciel@@starred@}[1]@{starry not #1 sky@} +\newcommand*@{\ciel@}@{\@@ifstar@{\ciel@@starred@}@{\ciel@@unstarred@}@} +@end example + +In the next example, the starred variant takes a different number of +arguments than the unstarred one. With this definition, Agent 007's +@code{``My name is \agentsecret*@{Bond@}, +\agentsecret@{James@}@{Bond@}.''} is equivalent to entering the commands +@code{``My name is \textsc@{Bond@}, \textit@{James@} textsc@{Bond@}.''} + +@example +\newcommand*@{\agentsecret@@unstarred@}[2]@{\textit@{#1@} \textsc@{#2@}@} +\newcommand*@{\agentsecret@@starred@}[1]@{\textsc@{#1@}@} +\newcommand*@{\agentsecret@}@{% + \@@ifstar@{\agentsecret@@starred@}@{\agentsecret@@unstarred@}@} +@end example + +There are two sometimes more convenient ways to accomplish the work of +@code{\@@ifstar}. The @file{suffix} package allows the construct +@code{\newcommand\mycommand@{@var{unstarred version}@}} followed by +@code{\WithSuffix\newcommand\mycommand*@{@var{starred version}@}}. And +@LaTeX{}3 has the @file{xparse} package that allows this code. + +@example +\NewDocumentCommand\foo@{s@}@{\IfBooleanTF#1 + @{@var{starred version}@}% + @{@var{unstarred version}@}% + @} +@end example + + @node \newcounter @section @code{\newcounter}: Allocating a counter @@ -8808,16 +8817,17 @@ Or name \end... illegal, see p.192 of the manual}. Synopsis: @example -\newsavebox@{@var{cmd}@} +\newsavebox@{\@var{cmd}@} @end example -Define @code{\@var{cmd}} to refer to a new ``bin'' for storing boxes. -Such a box is for holding typeset material, to use multiple times or to -measure or manipulate (@pxref{Boxes}). The required bin name -@code{@var{cmd}} must start with a backslash, @code{\}, and must not -already be defined. This command is fragile (@pxref{\protect}). +Define \@var{cmd}, the string consisting of a backslash followed by +@var{cmd}, to refer to a new bin for storing material. These bins hold +material that has been typeset, to use multiple times or to measure or +manipulate (@pxref{Boxes}). The bin name \@var{cmd} is required, must +start with a backslash, \, and must not already be a defined command. +This command is fragile (@pxref{\protect}). -The first line here sets you up to save the material for later use. +This allocates a bin and then puts typeset material into it. @example \newsavebox@{\logobox@} @@ -9155,8 +9165,8 @@ Synopsis: @end example Define a command @code{\@var{cmd}} that will change the current font. -The control sequence must must not already be defined. It must begin -with a backslash, @code{\}. +The control sequence must not already be defined. It must begin with a +backslash, @code{\}. @cindex at clause, in font definitions @cindex design size, in font definitions @@ -9438,7 +9448,7 @@ Here are the symbols: @multitable @columnfractions .10 .30 .30 .30 @headitem Number@tab Name@tab Command@tab Symbol @item -1@tab asterisk@tab@code{\ast}@tab@iftexthenelse{@math{@ast},*} +1@tab asterisk@tab@code{\ast}@tab@iftexthenelse{@math{\ast},*} @item 2@tab dagger@tab@code{\dagger}@tab@BES{2020,\dagger} @item @@ -9450,7 +9460,7 @@ Here are the symbols: @item 6@tab double-vert@tab@code{\parallel}@tab@BES{2016,\parallel} @item -7@tab double-asterisk@tab@code{\ast\ast}@tab@iftexthenelse{@math{@ast@ast},**} +7@tab double-asterisk@tab@code{\ast\ast}@tab@iftexthenelse{@math{\ast\ast},**} @item 8@tab double-dagger@tab@code{\dagger\dagger}@tab@BES{2020,\dagger}@BES{2020,\dagger} @@ -9670,30 +9680,37 @@ bogus month value produces no output). A @dfn{length} is a measure of distance. Many @LaTeX{} commands take a length as an argument. -This shows a box of the given length. +Lengths come in two types. A @dfn{rigid length} such as @code{10pt} +does not contain a @code{plus} or @code{minus} component. (Plain @TeX{} +calls this a @dfn{dimen}.) A @dfn{rubber length} (what Plain @TeX{} +calls a @dfn{skip}) such as as with @code{1cm plus0.05cm minus0.01cm} +can contain either or both of those components. In that rubber length, +the @code{1cm} is the @dfn{natural length} while the other two, the +@code{plus} and @code{minus} components, allow @TeX{} to stretch or +shrink the length to optimize placement. + +The illustrations below use these two commands. @example -\newcommand@{\blackbar@}[1]@{\rule@{#1@}@{10pt@}@} % make a bar -\newcommand@{\showhbox@}[2]@{\fboxsep=0pt\fbox@{\hbox to #1@{#2@}@}@} % box it -XXX\showhbox@{100pt@}@{\blackbar@{100pt@}@}YYY +% make a black bar 10pt tall and #1 wide +\newcommand@{\blackbar@}[1]@{\rule@{#1@}@{10pt@}@} + +% Make a box around #2 that is #1 wide (excluding the border) +\newcommand@{\showhbox@}[2]@{% + \fboxsep=0pt\fbox@{\hbox to #1@{#2@}@}@} @end example @noindent -It produces a black bar 100@tie{}points long between @samp{XXX} and -@samp{YYY}. - -Lengths come in two types. A @dfn{rigid length} (what Plain @TeX{} -calls a @dfn{dimen}) such as @code{10pt} does not contain a @code{plus} -or @code{minus} component. The above example shows a rigid length. A -@dfn{rubber length} (what Plain @TeX{} calls a @dfn{skip}) can contain -those components, as with @code{1cm plus0.05cm minus0.01cm}. Here the -@code{1cm} is the @dfn{natural length} while the other two, the -@code{plus} and @code{minus} components, allow the length to stretch or -shrink. - -Shrinking is simpler: with @code{1cm minus 0.05cm}, the natural length -is 1@dmn{cm} but if smaller is needed then @TeX{} can shrink it down as -far as 0.95@dmn{cm}. Beyond that, @TeX{} refuses to shrink any more. +This example uses those commands to show a black bar 100@tie{}points +long between @samp{XXX} and @samp{YYY}. This length is rigid. + +@example +XXX\showhbox@{100pt@}@{\blackbar@{100pt@}@}YYY +@end example + +As for rubber lengths, shrinking is simpler one: with @code{1cm minus +0.05cm}, the natural length is 1@dmn{cm} but @TeX{} can shrink it down +as far as 0.95@dmn{cm}. Beyond that, @TeX{} refuses to shrink any more. Thus, below the first one works fine, producing a space of 98@tie{}points between the two bars. @@ -9713,7 +9730,7 @@ wider than the 300@dmn{pt} allocated, as @TeX{} has refused to shrink the total to less than 309@tie{}points. Stretching is like shrinking except that if @TeX{} is asked to stretch -beyond the given amount, it won't refuse. Here the first line is fine, +beyond the given amount, it will do it. Here the first line is fine, producing a space of 110@tie{}points between the bars. @example @@ -9726,11 +9743,9 @@ XXX\showhbox@{300pt@}@{% @noindent In the second line @TeX{} needs a stretch of 10@tie{}points and only -1@tie{}point was specified. In this situation, @TeX{} stretches the -space to the required length, but it complains with a warning like -@samp{Underfull \hbox (badness 10000) detected at line 22}. (We won't -discuss badness; the point is that the system was not given as much -stretch as needed.) +1@tie{}point was specified. @TeX{} stretches the space to the required +length but it gives you a warning like @samp{Underfull \hbox (badness +10000) detected at line 22}. (We won't discuss badness.) You can put both stretch and shrink in the same length, as in @code{1ex plus 0.05ex minus 0.02ex}. @@ -9739,17 +9754,18 @@ If @TeX{} is setting two or more rubber lengths then it allocates the stretch or shrink in proportion. @example -XXX\showhbox@{300pt@}@{\blackbar@{100pt@}% left +XXX\showhbox@{300pt@}@{% + \blackbar@{100pt@}% left \hspace@{0pt plus 50pt@}\blackbar@{80pt@}\hspace@{0pt plus 10pt@}% middle \blackbar@{100pt@}@}YYY % right @end example @noindent -The outside bars take up 100@tie{}points, so the middle needs another -100. In the middle the bar takes up 80@tie{}points, so the two -@code{\hspace}'s must stretch 20@tie{}points. Because the two say -@code{plus 50pt} and @code{plus 10pt}, @TeX{} gets 5/6 of the -stretch from the first space and 1/6 from the second. +The left and right bars take up 100@tie{}points, so the middle needs +another 100. The middle bar is 80@tie{}points so the two +@code{\hspace}'s must stretch 20@tie{}points. Because the two are +@code{plus 50pt} and @code{plus 10pt}, @TeX{} gets 5/6 of the stretch +from the first space and 1/6 from the second. The @code{plus} or @code{minus} component of a rubber length can contain a @dfn{fill} component, as in @code{1in plus2fill}. This gives the @@ -9765,10 +9781,10 @@ the page. \end@{minipage@} @end example -@TeX{} actually has three infinite glue components @code{fil}, -@code{fill}, and @code{filll}. The later ones are more infinite than -the earlier ones. Ordinarily document authors only use the middle one -(@pxref{\hfill} and @pxref{\vfill}). +@TeX{} actually has three levels of infinity for glue components: +@code{fil}, @code{fill}, and @code{filll}. The later ones are more +infinite than the earlier ones. Ordinarily document authors only use +the middle one (@pxref{\hfill} and @pxref{\vfill}). Multiplying a rubber length by a number turns it into a rigid length, so that after @code{\setlength@{\ylength@}@{1in plus 0.2in@}} and @@ -9799,7 +9815,7 @@ math mode. @findex pt @cindex Point @anchor{units of length pt} -Point 1/72.27 inch. The conversion to metric units, to two decimal +Point, 1/72.27 inch. The conversion to metric units, to two decimal places, is 1@dmn{point} = 2.85@dmn{mm} = 28.45@dmn{cm}. @item pc @@ -9912,8 +9928,13 @@ I told the doctor I broke my leg in two places. He said stop going to those places. @end example -If there is no such length @var{len} then you get something like -@samp{Undefined control sequence. <argument> \praindent}. +If you did not declare @var{len} with @code{\newlength}, for example if +you mistype the above as +@code{\newlength@{\specparindent@}\setlength@{\sepcparindent@}@{...@}}, +then you get an error like @samp{Undefined control sequence. <argument> +\sepcindent}. If you omit the backslash at the start of the length name +then you get an error like @samp{Missing number, treated as zero. <to be +read again> \relax l.19 \setlength@{specparindent@}@{0.6\parindent@}} @node \addtolength @@ -9937,8 +9958,8 @@ length}). Below, if @code{\parskip} starts with the value @code{0pt plus 1pt} @example -\addtolength@{\parskip@}@{1pt@} Doctor: how is the boy who swallowed the silver dollar? +\addtolength@{\parskip@}@{1pt@} Nurse: no change. @end example @@ -9946,9 +9967,11 @@ Nurse: no change. @noindent then it has the value @code{1pt plus 1pt} for the second paragraph. -If there is no such length @var{len} then you get something like -@samp{Undefined control sequence. <argument> \praindent}. If you leave -off the backslash at the start of @var{len}, as in +If you did not declare the length @var{len} with @code{\newlength}, if +for example you mistype the above as +@code{\addtolength@{\specparindent@}@{0.6\praindent@}}, then you get +something like @samp{Undefined control sequence. <argument> \praindent}. +If you leave off the backslash at the start of @var{len}, as in @code{\addtolength@{parindent@}@{1pt@}}, then you get something like @samp{You can't use `the letter p' after \advance}. @@ -9976,9 +9999,10 @@ This will show how low the character descenders go. \the\alphabetdepth @end example -If there is no such length @var{len} then you get something like -@samp{Undefined control sequence. <argument> \alphabetdepth}. If you -leave the backslash out of @var{len}, as in +If you did not set aside the length @var{len}, if for example you +mistype the above as @code{\settodepth@{\aplhabetdepth@}@{abc...@}}, +then you get something like @samp{Undefined control sequence. <argument> +\aplhabetdepth}. If you leave the backslash out of @var{len}, as in @code{\settodepth@{alphabetdepth@}@{...@}} then you get something like @samp{Missing number, treated as zero. <to be read again> \setbox}. @@ -10006,9 +10030,11 @@ This will show how high the characters go. \the\alphabetheight @end example -If there is no such length @var{len} then you get something like -@samp{Undefined control sequence. <argument> \alphabetheight}. If you -leave the backslash out of @var{len}, as in +If no such length @var{len} has been declared with @code{\newlength}, if +for example you mistype as +@code{\settoheight@{\aplhabetheight@}@{abc...@}}, then you get something +like @samp{Undefined control sequence. <argument> \alphabetheight}. If +you leave the backslash out of @var{len}, as in @code{\settoheight@{alphabetheight@}@{...@}} then you get something like @samp{Missing number, treated as zero. <to be read again> \setbox}. @@ -10036,51 +10062,23 @@ This measures the width of the lowercase ASCII alphabet. \the\alphabetwidth @end example -If there is no such length @var{len} then you get something like -@samp{Undefined control sequence. <argument> \alphabetwidth}. If you -leave the backslash out of @var{len}, as in +If no such length @var{len} has been set aside, if for example you +mistype the above as @code{\settowidth@{\aplhabetwidth@}@{abc...@}}, +then you get something like @samp{Undefined control sequence. <argument> +\aplhabetwidth}. If you leave the backslash out of @var{len}, as in @code{\settoheight@{alphabetwidth@}@{...@}} then you get something like @samp{Missing number, treated as zero. <to be read again> \setbox}. -@c @node Predefined lengths -@c @section Predefined lengths - -@c @cindex lengths, predefined -@c @cindex predefined lengths - -@c @code{\width} -@c @findex \width - -@c @code{\height} -@c @findex \height - -@c @code{\depth} -@c @findex \depth - -@c @code{\totalheight} -@c @findex \totalheight - -@c These length parameters can be used in the arguments of the box-making -@c commands (@pxref{Boxes}). They specify the natural width, etc., of the -@c text in the box. @code{\totalheight} equals -@c @math{@code{@backslashchar{}height} + @code{@backslashchar{}depth}}. To -@c make a box with the text stretched to double the natural size, e.g., say - -@c @example -@c \makebox[2\width]@{Get a stretcher@} -@c @end example - - @node Making paragraphs @chapter Making paragraphs @cindex making paragraphs @cindex paragraphs -Once @LaTeX{} has all of a paragraph's contents it divides it into -lines, in a way that is optimized over the entire paragraph (@pxref{Line -breaking}). To end the current paragraph, put an empty line. +To start a paragraph, just type some text. To end the current +paragraph, put an empty line. This is three paragraphs, separated by +two empty lines. @example It is a truth universally acknowledged, that a single man in possession @@ -10098,6 +10096,10 @@ of some one or other of their daughters. The separator lines must be empty, including not containing a comment character, @code{%}. +Once @LaTeX{} has gathered all of a paragraph's contents it divides that +content into lines in a way that is optimized over the entire paragraph +(@pxref{Line breaking}). + There are places where a new paragraph is not permitted. Don't put a blank line in math mode (@pxref{Modes}); here the line before the @code{\end@{equation@}} @@ -10138,7 +10140,7 @@ complete}. @findex \par @cindex paragraph, ending -Synopsis (note that while reading the input @TeX{}, converts two +Synopsis (note that while reading the input @TeX{} converts two consecutive newlines to a @code{\par}): @example @@ -10157,22 +10159,25 @@ readability. \whatCheatingIs\par\whatHappensWhenICatchYou@} @end example -The @code{\par} command does nothing in LR mode or a vertical mode but -it terminates paragraph mode, bringing @LaTeX{} to vertical mode +In LR mode or a vertical mode the @code{\par} command does nothing but +it terminates paragraph mode, switching @LaTeX{} to vertical mode (@pxref{Modes}). -You cannot use the @code{\par} command in math mode or in the argument -of many commands, such as the @code{\section} command (@pxref{Making -paragraphs} and @pxref{\newcommand & \renewcommand}). +You cannot use the @code{\par} command in a math mode. You also cannot +use it in the argument of many commands, such as the @code{\section} +command (@pxref{Making paragraphs} and @ref{\newcommand & +\renewcommand}). -The @code{\par} command differs from the @code{\paragraph} command in -that the latter is, like @code{\section} or @code{\subsection}, a -sectioning unit used by the standard @LaTeX{} documents. +The @code{\par} command is not the same as the @code{\paragraph} +command. The latter is, like @code{\section} or @code{\subsection}, a +sectioning unit used by the standard @LaTeX{} documents +(@pxref{\subsubsection & \paragraph & \subparagraph}). -The @code{\par} command differs from @code{\newline} and the line break -double backslash, @code{\\}, in that \par ends the paragraph not just -the line. It also triggers the addition of the between-paragraph -vertical space @code{\parskip} (@pxref{\parindent & \parskip}). +The @code{\par} command is not the same as @code{\newline} or the line +break double backslash, @code{\\}. The difference is that @code{\par} +ends the paragraph, not just the line, and also triggers the addition of +the between-paragraph vertical space @code{\parskip} (@pxref{\parindent +& \parskip}). The output from this example @@ -10331,9 +10336,9 @@ subsequent marginal notes in the opposite margin to that given in the prior paragraph. Revert that to the default position with @code{\normalmarginpar}. -When you specify the optional argument @var{left} then it is used for a -note in the left margin, while the mandatory argument @var{right} is -used for a note in the the right margin. +When you specify the optional argument @var{left} then it is used for +a note in the left margin, while the mandatory argument @var{right} is +used for a note in the right margin. Normally, a note's first word will not be hyphenated. You can enable hyphenation there by beginning @var{left} or @var{right} with @@ -10606,7 +10611,7 @@ said otherwise, the commands for these symbols can be used only in math mode. To redefine a command so that it can be used whatever the current mode, see @ref{\ensuremath}. -@c xx Add Negation: @code{} for negations of relevant symbols +@c xx Add Negation: for negations of relevant symbols @c Useful: http://www.w3.org/TR/WD-math-970515/section6.html @ftable @code @@ -12216,6 +12221,158 @@ A length of 2 quads, that is, 36@dmn{mu} = 2@dmn{em}. It is available in both text and math mode. @end table +@menu +* \smash:: Eliminate height or depth of a subformula. +* \phantom & \vphantom & \hphantom:: Make empty box with the same size as the argument. +@end menu + + +@node \smash +@subsection @code{\smash} + +@cindex vertical spacing, math mode +@cindex math mode, vertical space + +Synopsis: + +@example +\smash@{@var{subformula}@} +@end example + +Typeset @var{subformula} as if its height and depth were zero. + +In this example the exponential is so tall that without the +@code{\smash} command @LaTeX{} would separate its line from the line +above it, and the uneven line spacing might be unsightly. + +@example +To compute the tetration $\smash@{2^@{2^@{2^2@}@}@}$, +evaluate from the top down, as $2^@{2^4@}=2^@{16@}=65536$. +@end example + +(Because of the @code{\smash} the printed expression could run into the +line above so you may want to wait until the final version of the +document to make such adjustments.) + +This pictures the effect of @code{\smash} by using @code{\fbox} to +surround the box that @LaTeX{} will put on the line. The +@code{\blackbar} command makes a bar extending from 10@tie{}points below +the baseline to 20@tie{}points above. + +@example +\newcommand@{\blackbar@}@{\rule[-10pt]@{5pt@}@{30pt@}@} +\fbox@{\blackbar@} +\fbox@{\smash@{\blackbar@}@} +@end example + +The first box that @LaTeX{} places is 20@tie{}points high and +10@tie{}points deep. But the second box is treated by @LaTeX{} as +having zero height and zero depth, despite that the ink printed on the +page still extends well above and below the line. + +The @code{\smash} command appears often in mathematics to adjust the +size of an element that surrounds a subformula. Here the first radical +extends below the baseline while the second lies just on the baseline. + +@example +\begin@{equation@} +\sqrt@{\sum_@{0\leq k< n@} f(k)@} +\sqrt@{\vphantom@{\sum@}\smash@{\sum_@{0\leq k< n@}@} f(k)@} +\end@{equation@} +@end example + +Note the use of @code{\vphantom} to give the @code{\sqrt} command an +argument with the height of the @code{\sum} (@pxref{\phantom & \vphantom +& \hphantom}). + +While most often used in mathematics, the @code{\smash} command can +appear in other contexts. However, it doesn't change into horizontal +mode. So if it starts a paragraph then you should first put a +@code{\leavevmode}, as in the bottom line below. + +@example +xxx xxx xxx + +\smash@{yyy@} % no paragraph indent + +\leavevmode\smash@{zzz@} % usual paragraph indent +@end example + +@PkgIndex{mathtools} +The package @code{mathtools} has operators that provide even finer +control over smashing a subformula box. + + +@node \phantom & \vphantom & \hphantom +@subsection @code{\phantom} & @code{\vphantom} & @code{\hphantom} + +@cindex spacing, math mode +@cindex horizontal spacing +@cindex vertical spacing +@cindex math mode, spacing +@cindex invisible character +@cindex character, invisible + +Synopsis: + +@example +\phantom@{@var{subformula}@} +@end example + +or + +@example +\vphantom@{@var{subformula}@} +@end example + +or + +@example +\hphantom@{@var{subformula}@} +@end example + +The @code{\phantom} command creates a box with the same height, depth, +and width as @var{subformula}, but empty. That is, this command causes +@LaTeX{} to typeset the box but not its ink. The @code{\vphantom} +variant also produces an invisible box with the same height and depth as +@var{subformula}, but it has width zero. And @code{\hphantom} makes a +box with the same width as @var{subformula} but with height and depth +zero. + +Without the @code{\vphantom} in this example, the top bars of the two +square roots would be at different heights. + +@example +\( \sqrt@{\vphantom@{a^3@}a@}\cdot\sqrt@{a^3@} \) +@end example + +The @code{\vphantom@{a^3@}} causes the first @code{\sqrt} to have inside +it a box of the same height as the second @code{\sqrt}, so @LaTeX{} +makes the bars align. + +These commands often are combined with @code{\smash}. @xref{\smash} +for another example of the use of @code{\vphantom}. + +@PkgIndex{mathtools} +The three phantom commands appear often but note that @LaTeX{} provides +a suite of other commands to work with box sizes that may be more +convenient, including @code{\makebox} (@pxref{\mbox & \makebox}) as well +as @code{\settodepth} (@pxref{\settodepth}), @code{\settoheight} +(@pxref{\settoheight}), and @code{\settowidth} (@pxref{\settowidth}). +In addition, the @file{mathtools} package has many commands that offer +fine-grained control over spacing. + +@PkgIndex{amsmath} +All three commands produce an ordinary box, without any special +mathematics status. So to do something like attaching a superscript you +should give it such a status, for example with the @code{\operatorname} +command from the package @file{amsmath}. + +While most often used in mathematics, these three can appear in other +contexts. However, they don't cause @LaTeX{} to change into horizontal +mode. So if one of these starts a paragraph then you should prefix it +with @code{\leavevmode}. + @node Math miscellany @section Math miscellany @@ -12480,7 +12637,7 @@ back to paragraph mode. @cindex outer paragraph mode @anchor{modes inner paragraph mode} @anchor{modes outer paragraph mode} -Paragraph mode has two subcases. If you use a @code{\parbox} command or +Paragraph mode has two subcases. If you use a @code{\parbox} command or a @code{minipage} then @LaTeX{} is put into paragraph mode. But it will not put a page break here. Inside one of these boxes, called a @dfn{parbox}, @LaTeX{} is in @dfn{inner paragraph mode}. Its more usual @@ -12488,7 +12645,7 @@ situation, where it can put page breaks, is @dfn{outer paragraph mode} (@pxref{Page breaking}). @menu -* \ensuremath:: Ensure that math mode is active +* \ensuremath:: Ensure that math mode is active. @end menu @node \ensuremath @@ -12615,9 +12772,10 @@ To have no date, instead use @code{\date@{@}}. @cindex thanks, for titlepage @cindex credit footnote Optional. Produce a footnote. You can use it in the author information -for acknowledgements, as illustrated below, but you can also use it in -the title, or any place a footnote makes sense. It can be any text so -you can use it to print an email address, or for any purpose. +for acknowledgements as illustrated above, but you can also use it in +the title, or any place a footnote makes sense. It can be any text at +all so you can use it for any purpose, such as to print an email +address. @item \title@{@var{text}@} @cindex title, for titlepage @@ -12629,11 +12787,11 @@ omit the @code{\title} declaration then you get @samp{LaTeX Error: No @end ftable -Many publishers will provide a class to use in place of @code{article} -in that example, that formats the title according to their house -requirements. To make your own, see@tie{}@ref{titlepage}. You can -either create this as a one-off or you can include it as part of a -renewed @code{\maketitle} command. +To make your own title page, see@tie{}@ref{titlepage}. You can either +create this as a one-off or you can include it as part of a renewed +@code{\maketitle} command. (Many publishers will provide a class to use +in place of @code{article} that formats the title according to their +house requirements.) @node \pagenumbering @@ -12669,7 +12827,7 @@ also@tie{}@ref{\alph \Alph \arabic \roman \Roman \fnsymbol}). @table @code @item arabic -arabic numerals: 1, 2, @dots{} +Arabic numerals: 1, 2, @dots{} @item roman lowercase Roman numerals: i, ii, @dots{} @@ -12828,7 +12986,7 @@ or environments. Often the first page of a chapter or section has a different style. For example, this @LaTeX{} book document has the first page of the first -chapter in in @code{plain} style, as is the default (@pxref{Page +chapter in @code{plain} style, as is the default (@pxref{Page styles}). @example @@ -13257,35 +13415,35 @@ backslash followed by a space. Synopsis: Produce a space. By default it produces white space of length 3.33333@dmn{pt} plus 1.66666@dmn{pt} minus 1.11111@dmn{pt}. -A blank is not a space. When you type a blank between words, @LaTeX{} -produces white space. That's different from an explicit space. This -illustrates. +When you type one or more blanks between words, @LaTeX{} produces white +space. But that is different than an explicit space. This illustrates. @example \begin@{tabular@}@{l@} +One blank: makes some space \\ Three blanks: in a row \\ Three spaces:\ \ \ in a row \\ \end@{tabular@} @end example @noindent -On the first line @LaTeX{} collapses the three blanks to output one -whitespace (it would be the same with a single blank or, for instance, -with a blank and an tab and a blank, or a blank and a newline and a -blank). But the second line asks for three spaces so the white area is -wider. Thus, the backslash-space command will create some horizontal -space. (But the best way to create horizontal space is with -@code{\hspace}; @xref{\hspace}.) - -The backslash-space command has two main uses. First, it is often used -after control sequences to keep them from gobbling the space that -follows, as in @code{\TeX\ is nice}. (But the approach of using curly -parentheses, as in @code{\TeX@{@} is nice}, has the advantage of still -working if the next character is a period.) - -The second common use is that -it mark a period as ending an abbreviation instead of ending -a sentence, as in @code{So says Prof.\ Smith} (@pxref{\@@}). +On the first line @LaTeX{} puts some space after the colon. On the +second line @LaTeX{} collapses the three blanks to output one +whitespace, so you end with the same space after the colon as in the +first line. @LaTeX{} would similarly collapse a blank followed by a +tab, or a blank and a newline and a blank. However, the bottom line +asks for three spaces so the white area is wider. That is, the +backslash-space command creates a fixed amount of horizontal space. +(Note that you can define a horizontal space of any width at all with +@code{\hspace}; see@tie{}@ref{\hspace}.) + +The backslash-space command has two main uses. It is often used after +control sequences to keep them from gobbling the space that follows, as +in @code{\TeX\ is nice}. (But using curly parentheses, as in +@code{\TeX@{@} is best}, has the advantage of still working if the next +character is a period.) The other common use is that it marks a period +as ending an abbreviation instead of ending a sentence, as in @code{So +says Prof.\ Smith} (@pxref{\@@}). Under normal circumstances, @code{\}@key{tab} and @code{\}@key{newline} are equivalent to backslash-space, @code{\ }. @@ -13684,11 +13842,11 @@ item's second line. @end example @noindent -The final two lists use @code{fbox} to show what's happening. The third -list's @code{\parbox} goes only to the bottom of its second @samp{test}, -which happens not have any characters that descend below the baseline. -The fourth list adds the strut that gives the needed extra -below-baseline space. +The final two lists use @code{\fbox} to show what's happening. The +third list's @code{\parbox} goes only to the bottom of its second +@samp{test}, which happens not have any characters that descend below +the baseline. The fourth list adds the strut that gives the needed +extra below-baseline space. @PkgIndex{TikZ} @PkgIndex{Asymptote} The @code{\strut} command is often useful in graphics, such as in @@ -13891,6 +14049,7 @@ with a @code{\par} command (@pxref{\par}), as in the above example. @cindex boxes +@c xx Expand on boxes and glue, for xref from elsewhere. At its core, @LaTeX{} puts things in boxes and then puts the boxes on a page. So these commands are central. @@ -13926,7 +14085,7 @@ Synopsis, one of: \makebox[@var{width}][@var{position}]@{@var{text}@} @end example -Create a box, a container for material. The @var{text} is is typeset in +Create a box, a container for material. The @var{text} is typeset in LR mode (@pxref{Modes}) so it is not broken into lines. The @code{\mbox} command is robust, while @code{\makebox} is fragile (@pxref{\protect}). @@ -14410,9 +14569,9 @@ robust (@pxref{\protect}). 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. +Color support comes as an additional package. So put +@code{\usepackage@{color@}} in your document preamble to use the +commands described here. Many other packages also supplement @LaTeX{}'s color abilities. Particularly worth mentioning is @file{xcolor}, which is widely used and @@ -15131,7 +15290,7 @@ 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 +be treated as an @code{eps} file, with the BoundingBox information stored in the file with extension @file{.eps.bb}, and that the command @code{gunzip -c} will run on your platform to decompresses the file. @@ -15565,13 +15724,13 @@ external commands. @cindex rotating text @findex \rotatebox -Synopsis for @file{graphics} package: +Synopsis if you use the @file{graphics} package: @example \rotatebox@{@var{angle}@}@{@var{material}@} @end example -Synopses for @file{graphicx} package: +Synopses if you use the @file{graphicx} package: @example \rotatebox@{@var{angle}@}@{@var{material}@} @@ -15608,10 +15767,11 @@ 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}). +reference point of the box. If you use the @file{graphicx} package +then these are the options that can go in the @var{key-value list}, +but note that you can get the same effect without needing this +package, except for the @code{x} and @code{y} options +(@pxref{\includegraphics}). @table @code @item origin @@ -15621,16 +15781,16 @@ left, @code{r} for right, @code{b} for bottom, @code{c} for center, @code{t} for top, and @code{B} for baseline. Thus, the first line here @example -\includegraphics[angle=180,origin=c]@{moon@} -\includegraphics[angle=180,origin=lB]@{LeBateau@} +\rotatebox[origin=c]@{180@}@{moon@} +\rotatebox[origin=lB]@{180@}@{LeBateau@} @end example @noindent will turn the picture upside down from the center while the second will turn its picture upside down about its left baseline. (The character @code{c} gives the horizontal center in @code{bc} or @code{tc} but gives -the vertical center in @code{lc} or @code{rc}.) The default is -@code{lB}. +the vertical center in @code{lc} or @code{rc}, and gives both in +@code{c}.) The default is @code{lB}. @item x, y Specify an arbitrary point of rotation with @@ -17352,7 +17512,7 @@ multiple indices and contains a command The @code{\index} command writes the indexing information to the file @file{@var{root-name}.idx} file. Specifically, it writes text of the command -@code{\indexentry@{@var{index-entry-string}@}@{@var{page-num}@}}, where +@code{\indexentry@{@var{index-entry-string}@}@{@var{page-num}@}}, where @var{page-num} is the value of the @code{\thepage} counter. On occasion, when the @code{\printindex} command is confused, you have to delete this file to start with a fresh slate. @@ -17450,7 +17610,7 @@ plus5pt minus3pt}). @item lethead_flag An integer. It governs what is inserted for a new group or letter. If it is 0 (which is the default) then other than @code{group_skip} nothing -will be inserted before the group. If it is is positive then at a new +will be inserted before the group. If it is positive then at a new letter the @code{lethead_prefix} and @code{lethead_suffix} will be inserted, with that letter in uppercase between them. If it is negative then what will be inserted is the letter in lowercase. The default @@ -17557,12 +17717,12 @@ roman @code{R}, and uppercase alphabetic @code{A}. Default: @findex xindy @cindex @command{xindy} program -There are a number of other programs that do the job @command{makeindex} -does. One is @command{xindy}, which does internationalization and can -process indexes for documents marked up using @LaTeX{} and a number of -other languages. It is is highly configurable, both in markup terms and -in terms of the collating order of the text. See the documentation on -CTAN. +There are a number of other programs that do the job +@command{makeindex} does. One is @command{xindy}, which does +internationalization and can process indexes for documents marked up +using @LaTeX{} and a number of other languages. It is highly +configurable, both in markup terms and in terms of the collating order +of the text, as described in its documentation. @node \printindex @@ -18426,9 +18586,9 @@ When you run @code{@command{pdflatex} @var{options} @var{argument}}, if @var{argument} does not start with a backslash then @TeX{} considers it the name of a file to input. Otherwise it waits for the first @code{\input} instruction and the name of the input file will be the job -name. This is used to name the log file the output file. This option -overrides that process and directly specifies the name. @xref{Command -line input} for an example of its use. +name. This is used to name the log file the output file. The +@code{jobname} option overrides that process and directly specifies the +name. @xref{Command line input} for an example of its use. @findex --output-directory @r{command-line option} @item -output-directory=@var{directory} @@ -18438,10 +18598,10 @@ Write files in the directory @var{directory}. It must already exist. @findex --no-shell-escape @r{command-line option} @findex --enable-write18 @r{command-line option} @findex --disable-write18 @r{command-line option} -@item shell-escape -@itemx no-shell-escape -@itemx enable-write18 -@itemx disable-write18 +@item --shell-escape +@itemx --no-shell-escape +@itemx --enable-write18 +@itemx --disable-write18 Enable or disable @code{\write18@{@var{shell command}@}}. The first two options are for with @TeX{} Live or Mac@TeX{} while the second two are for MiK@TeX{}. @@ -18505,8 +18665,8 @@ PDF. @noindent Compiling this document @file{book.tex} with the command line -@code{pdflatex test} will give the @samp{CTAN} link in blue. But -compiling it with @code{pdflatex "\def\paperversion@{@}\input test.tex"} +@code{pdflatex book} will give the @samp{CTAN} link in blue. But +compiling it with @code{pdflatex "\def\paperversion@{@}\input book.tex"} has the link in black. (Note the use of double quotes to prevent interpretation of the symbols by the command line shell; your system may do this differently.) @@ -18534,7 +18694,7 @@ pdflatex -jobname=aa "\RequirePackage[draft]@{graphicx@}\input@{aa.tex@}" @noindent so the graphic files are read for their size information but not -incorporated into the PDF. (The @code{jobname} option is needed because +incorporated into the PDF. (The @code{jobname} option is there because otherwise the output file would be @file{graphicx.pdf}, as @code{\RequirePackage} does an @code{\input} of its own.) @@ -18586,8 +18746,8 @@ Please type another input file name: @end example @noindent -The simplest thing is to enter @code{<Contol>} and @samp{d} (holding -them down at the same time), and just fix the command line. +The simplest thing is to enter @code{<Control>} and @samp{d} (holding +them down at the same time), and then retype the correct command line. @node Document templates |