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 | 2962 |
1 files changed, 2169 insertions, 793 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 d4c8da471e9..e1c96ee6755 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,9 @@ \input texinfo -@c $Id: latex2e.texi 459 2015-10-12 11:33:10Z jhefferon $ +@c $Id: latex2e.texi 578 2017-08-06 00:04:43Z jimhefferon $ @comment %**start of header (This is for running Texinfo on a region.) @setfilename latex2e.info -@set UPDATED October 2015 +@set UPDATED August 2017 +@include common.texi @settitle @LaTeX{}2e unofficial reference manual (@value{UPDATED}) @comment %**end of header (This is for running Texinfo on a region.) @@ -10,12 +11,15 @@ @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 @c -@c xx merge http://mirror.ctan.org/info/latex-info/ (alt-latex-info) -@c xx merge http://mirror.ctan.org/latex2e-reference.tar.gz +@c xx merge http://ctan.org/pkg/latex-info (CTAN package latex-info) +@c xx merge http://ctan.org/pkg/latex2e-reference @c xx merge permuted-index @c xx merge latex-manual from savannah @c xx merge display style math @@ -43,10 +47,11 @@ 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 Karl Berry.@* +2014, 2015, 2016, 2017 Karl Berry.@* Copyright 1988, 1994, 2007 Stephen Gilmore.@* Copyright 1994, 1995, 1996 Torsten Martinsen. +@comment start of License Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @@ -65,6 +70,7 @@ notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. +@comment end of License @end copying @dircategory TeX @@ -79,7 +85,7 @@ into another language, under the above conditions for modified versions. @titlepage @title @LaTeX{}2e: An unofficial reference manual @subtitle @value{UPDATED} -@author @url{http://home.gna.org/latexrefman} +@author @url{@value{LTXREFMAN_HOME_PAGE}} @page @vskip 0pt plus 1filll @insertcopying @@ -96,6 +102,9 @@ 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} @@ -104,7 +113,27 @@ 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 @@ -148,31 +177,31 @@ This document is an unofficial reference manual (version of @node About this document @chapter About this document -@cindex bug reporting -@cindex reporting bugs -@findex @url{http://home.gna.org/latexrefman} @r{home page} +@findex @url{@value{LTXREFMAN_HOME_PAGE}} @r{home page} 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{http://home.gna.org/latexrefman}. That page has links to the +@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. @cindex @LaTeX{} vs.@: @LaTeX{}2e In this document, we will mostly just use `@LaTeX{}' rather than `@LaTeX{}2e', since the previous version of @LaTeX{}@tie{}(2.09) was -retired many years ago. +frozen decades ago. @cindex unofficial nature of this manual @cindex @LaTeX{} Project team -@findex @email{latexrefman-discuss@@gna.org} @r{email address} +@findex @email{@value{LTXREFMAN_BUGS}} @r{email address} @LaTeX{} is currently maintained by a group of volunteers (@url{http://latex-project.org}). The official documentation written by the @LaTeX{} project is available from their web site. This document is completely unofficial and has not been reviewed by the @LaTeX{} -maintainers. Do not send bug reports or anything else about this -document to them. Instead, please send all comments to -@email{latexrefman-discuss@@gna.org}. +maintainers. +@cindex bug reporting +@cindex reporting bugs +Do not send bug reports or anything else about this document to them. +Instead, please send all comments to @email{@value{LTXREFMAN_BUGS}}. This document is a reference. There is a vast array of other sources of information about @LaTeX{}, at all levels. Here are a few @@ -189,8 +218,9 @@ Writing your first document, with a bit of both text and math. @item http://ctan.org/pkg/usrguide @findex usrguide @r{official documentation} -The guide for document authors that is maintained as part of @LaTeX{}; -there are plenty of others available elsewhere. +The guide for document authors that is maintained as part of @LaTeX{}. +Many other guides by many other people are also available, independent +of @LaTeX{} itself; one such is the next item: @item http://ctan.org/pkg/lshort @findex lshort @r{document} @@ -307,7 +337,7 @@ it to a PostScript @code{.ps} file with @command{dvips} or to a Portable Document Format @code{.pdf} file with @command{dvipdfmx}. The contents of the file can be dumped in human-readable form with @command{dvitype}. A vast array of other DVI utility programs are -available (@url{http://mirror.ctan.org/tex-archive/dviware}). +available (@url{http://mirror.ctan.org/dviware}). @item .pdf @findex .pdf @r{file} @@ -478,16 +508,18 @@ 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 and \makeatother:: Change the status of the at-sign character. @end menu @node Environment +@subsection Environments Synopsis: @example \begin@{@var{environment name}@} - .. + ... \end@{@var{environment name}@} @end example @@ -497,11 +529,13 @@ behavior. For instance, for poetry in @LaTeX{} put the lines between @example \begin@{verse@} - There once was a man from Nantucket \\ - .. + There once was a man from Nantucket \\ + ... \end@{verse@} @end example +See@tie{}@ref{Environments} for a list of environments. + The @var{environment name} at the beginning must exactly match that at the end. This includes the case where @var{environment name} ends in a star@tie{}(@code{*}); both the @code{\begin} and @code{\end} texts must @@ -514,18 +548,153 @@ required (it specifies the formatting of columns). @example \begin@{tabular@}[t]@{r|l@} - .. rows of table .. + ... rows of table ... \end@{tabular@} @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 and \makeatother +@subsection @code{\makeatletter} and @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. + +The example below is typical. In the user's class file is a command +@code{\thesis@@universityname}. The user wants to change the +definition. 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{non-starred command number of args}]@{@var{body of non-starred command}@} +\newcommand@{\mycmd@@star@}[@var{starred command number of args}]@{@var{body of starred command}@} +@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 and \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 does the unstarred one. With this definition, Agent +007's @code{``My name is \agentsecret*@{Bond@}, +\agentsecret@{James@}@{Bond@}.''} is equivalent to @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 Document classes @chapter Document classes @@ -577,6 +746,8 @@ Standard @var{options} are described in the next section. @menu * Document class options:: Global options. +* Additional packages:: Bring in packages. +* Class and package construction:: Create new classes and packages. @end menu @@ -619,24 +790,27 @@ size (these show height by width): @table @code @item a4paper -210 by 297 mm (about 8.25 by 11.75 inches) +210 by 297@dmn{mm} (about 8.25 by 11.75@tie{}inches) + +@item a5paper +148 by 210@dmn{mm} (about 5.8 by 8.3@tie{}inches) @item b5paper -176 by 250 mm (about 7 by 9.875 inches) +176 by 250@dmn{mm} (about 6.9 by 9.8@tie{}inches) @item executivepaper -7.25 by 10.5 inches +7.25 by 10.5@tie{}inches @item legalpaper -8.5 by 14 inches +8.5 by 14@tie{}inches @item letterpaper -8.5 by 11 inches (the default) +8.5 by 11@tie{}inches (the default) @end table @findex \pdfpagewidth @findex \pdfpageheight -@cindex @code{geometry} package +@PkgIndex{geometry} When using one of the engines pdf@LaTeX{}, Lua@LaTeX{}, or Xe@LaTeX{} (@pxref{@TeX{} engines}), options other than @code{letterpaper} set the print area but you must also set the physical paper size. One way @@ -686,7 +860,10 @@ Use ``open'' bibliography format. @item titlepage @itemx notitlepage @cindex title page, separate or run-in -Specifies whether the title page is separate; default depends on the class. +Specifies whether there is a separate page for the title information and +for the abstract also, if there is one. The default for the +@code{report} class is @code{titlepage}, for the other classes it is +@code{notitlepage}. @end table The following options are not available with the @code{slides} class. @@ -726,27 +903,538 @@ Determines if a chapter should start on a right-hand page; default is The @code{slides} class offers the option @code{clock} for printing the time at the bottom of each note. + +@node Additional packages +@section Additional packages + @cindex loading additional packages @cindex packages, loading additional @cindex additional packages, loading @findex \usepackage -Additional packages are loaded like this: +Load a package @var{pkg}, with the package options given in the comma-separated +list @var{options}, as here. @example -\usepackage[@var{options}]@{@var{pkg}@} +\usepackage[@var{options}]@{@var{pkg}@}. @end example -To specify more than one package, you can separate them with a comma, +To specify more than one package you can separate them with a comma, as in @code{\usepackage@{@var{pkg1},@var{pkg2},...@}}, or use multiple @code{\usepackage} commands. @cindex global options @cindex options, global Any options given in the @code{\documentclass} command that are unknown -by the selected document class are passed on to the packages loaded with +to the selected document class are passed on to the packages loaded with @code{\usepackage}. +@node Class and package construction +@section Class and package construction + +@cindex document class commands +@cindex commands, document class +@cindex new class commands + +You can create new document classes and new packages. For instance, if +your memos must satisfy some local requirements, such as a +standard header for each page, then you could create a new class +@code{smcmemo.cls} and begin your documents with +@code{\documentclass@{smcmemo@}}. + +What separates a package from a document class is that the commands in a +package are useful across classes while those in a document class are +specific to that class. Thus, a command to set page headers is for a +package while a command to make the page headers say @code{Memo from the +SMC Math Department} is for a class. +@cindex class and package difference +@cindex difference between class and package + +Inside of a class or package file you can use the at-sign @code{@@} as a +character in command names without having to surround the code +containing that command with @code{\makeatletter} and +@code{\makeatother}. @xref{\makeatletter and \makeatother}. This allow +you to create commands that users will not accidentally redefine. +Another technique is to preface class- or package-specific commands with +some string to prevent your class or package from interfering with +others. For instance, the class @code{smcmemo} might have commands +@code{\smc@@tolist}, @code{\smc@@fromlist}, etc. + + +@menu +* Class and package structure:: Layout of the file. +* Class and package commands:: List of commands. +@end menu + + +@node Class and package structure +@subsection Class and package structure + +@cindex class and package structure +@cindex class file layout +@cindex package file layout +@cindex options, document class +@cindex options, package +@cindex class options +@cindex package options + +A class file or package file typically has four parts. +@enumerate +In the @dfn{identification part}, the file says that it is a @LaTeX{} +package or class and describes itself, using the @code{\NeedsTeXFormat} +and @code{\ProvidesClass} or @code{\ProvidesPackage} commands. +@item +The @dfn{preliminary declarations part} declares some commands and +can also load other files. Usually these commands will be those needed +for the code used in the next part. For example, an @code{smcmemo} +class might be called with an option to read in a file with a list of +people for the to-head, as @code{\documentclass[mathto]@{smcmemo@}}, and +therefore needs to define a command +@code{\newcommand@{\setto@}[1]@{\def\@@tolist@{#1@}@}} used in that +file. +@item +In the @dfn{handle options part} the class or package declares +and processes its options. Class options allow a user to start their +document as @code{\documentclass[@var{option list}]@{@var{class +name}@}}, to modify the behavior of the class. An example is when you +declare @code{\documentclass[11pt]@{article@}} to set the default +document font size. +@item +Finally, in the @dfn{more declarations part} the class or package usually does +most of its work: declaring new variables, commands and fonts, and +loading other files. +@end enumerate + + +Here is a starting class file, which should be saved as @file{stub.cls} +where @LaTeX{} can find it, for example in the same directory as the +@file{.tex} file. + +@example +\NeedsTeXFormat@{LaTeX2e@} +\ProvidesClass@{stub@}[2017/07/06 stub to start building classes from] +\DeclareOption*@{\PassOptionsToClass@{\CurrentOption@}@{article@}@} +\ProcessOptions\relax +\LoadClass@{article@} +@end example +@cindex class file example + +It identifies itself, handles the class options via the default of +passing them all to the @code{article} class, and then loads the +@code{article} class to provide the basis for this class's code. + +For more, see the official guide for class and package writers, the +Class Guide, at +@url{http://www.latex-project.org/help/documentation/clsguide.pdf} (much +of the descriptions here derive from this document), or the tutorial +@url{https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf}. + +@node Class and package commands +@subsection Class and package commands +@cindex class and package commands +@cindex commands, class and package + +These are the commands designed to help writers of classes or packages. + +@table @code +@item \AtBeginDvi@{specials@} +@findex \AtBeginDvi +Save in a box register things that are written to the @file{.dvi} file +at the beginning of the shipout of the first page of the document. + +@item \AtEndOfClass@{@var{code}@} +@item \AtEndOfPackage@{@var{code}@} +@findex \AtEndOfClass +@findex \AtEndOfPackage +Hook to insert @var{code} to be executed when @LaTeX{} finishes +processing the current class or package. You can use these hooks +multiple times; the @code{code} will be executed in the order that you +called it. See also @ref{\AtBeginDocument}. + +@item \CheckCommand@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@item \CheckCommand*@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@findex \CheckCommand +@findex \CheckCommand* +@cindex new command, check +Like @code{\newcommand} (@pxref{\newcommand & \renewcommand}) but does +not define @var{cmd}; instead it checks that the current definition of +@var{cmd} is exactly as given by @var{definition} and is or is not +@cindex long command +@dfn{long} as expected. A long command is a command that accepts +@code{\par} within an argument. The @var{cmd} command is expected to be +long with the unstarred version of @code{\CheckCommand}. Raises an +error when the check fails. This allows you to check before you start +redefining @code{cmd} yourself that no other package has already +redefined this command. + +@item \ClassError@{@var{class name}@}@{@var{error text}@}@{@var{help text}@} +@item \PackageError@{@var{package name}@}@{@var{error text}@}@{@var{help text}@} +@item \ClassWarning@{@var{class name}@}@{@var{warning text}@} +@item \PackageWarning@{@var{package name}@}@{@var{warning text}@} +@item \ClassWarningNoLine@{@var{class name}@}@{@var{warning text}@} +@item \PackageWarningNoLine@{@var{package name}@}@{@var{warning text}@} +@item \ClassInfo@{@var{class name}@}@{@var{info text}@} +@item \PackageInfo@{@var{package name}@}@{@var{info text}@} +@item \ClassInfoNoLine@{@var{class name}@}@{@var{info text}@} +@item \PackageInfoNoLine@{@var{package name}@}@{@var{info text}@} +@findex \ClassError +@findex \PackageError +@findex \ClassWarning +@findex \PackageWarning +@findex \ClassWarningNoLine +@findex \PackageWarningNoLine +@findex \ClassInfo +@findex \PackageInfo +@findex \ClassInfoNoLine +@findex \PackageInfoNoLine +Produce an error message, or warning or informational messages. + +For @code{\ClassError} and @code{\PackageError} the message is +@var{error text}, followed by @TeX{}'s @code{?} error prompt. If the +user then asks for help by typing @code{h}, they see the @var{help +text}. + +The four warning commands are similar except that they write +@var{warning text} on the screen with no error prompt. The four info +commands write @var{info text} only in the transcript file. The +@code{NoLine} versions do not show the number of the line generating the +message, while the other versions do show that number. + +To format the messages, including the @var{help text}: use +@code{\protect} to stop a command from expanding, get a line break with +@code{\MessageBreak}, and get a space with @code{\space} when a space +character does not allow it, like after a command. Note that @LaTeX{} +appends a period to the messages. + +@item \CurrentOption +@findex \CurrentOption +Expands to the name of the currently-being-processed option. Can only +be used within the @var{code} argument of either @code{\DeclareOption} +or @code{\DeclareOption*}. + +@item \DeclareOption@{@var{option}@}@{@var{code}@} +@item \DeclareOption*@{@var{code}@} +@findex \DeclareOption +@findex \DeclareOption* +@cindex class options +@cindex package options +@cindex options, class +@cindex options, package +Make an option available to a user, for invoking in their +@code{\documentclass} command. For example, the @code{smcmemo} class +could have an option allowing users to put the institutional logo on the +first page with @code{\documentclass[logo]@{smcmemo@}}. The class file +must contain @code{\DeclareOption@{logo@}@{@var{code}@}} (and later, +@code{\ProcessOptions}). + +If you request an option that has not been declared, by default this +will produce a warning like @code{Unused global option(s): [badoption].} +Change this behaviour with the starred version +@code{\DeclareOption*@{@var{code}@}}. For example, many classes extend +an existing class, using a declaration such as +@code{\LoadClass@{article@}}, and for passing extra options to the +underlying class use code such as this. + +@example +\DeclareOption*@{% +\PassOptionsToClass@{\CurrentOption@}@{article@}% +@} +@end example + +Another example is that the class @code{smcmemo} may allow users to keep +lists of memo recipients in external files. Then the user could invoke +@code{\documentclass[math]@{smcmemo@}} and it will read the file +@code{math.memo}. This code handles the file if it exists and otherwise +passes the option to the @code{article} class. + +@example +\DeclareOption*@{\InputIfFileExists@{\CurrentOption.memo@}@{@}@{% + \PassOptionsToClass@{\CurrentOption@}@{article@}@}@} +@end example + +@item \DeclareRobustCommand@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@item \DeclareRobustCommand*@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@} +@findex \DeclareRobustCommand +@findex \DeclareRobustCommand* +@cindex new command, definition +Like @code{\newcommand} and @code{\newcommand*} (@pxref{\newcommand & +\renewcommand}) but these declare a robust command, even if some code +within the @var{definition} is fragile. (For a discussion of robust and +fragile commands @pxref{\protect}.) Use this command to define new +robust commands or to redefine existing commands and make them +robust. Unlike @code{\newcommand} these do not give an error if macro +@var{cmd} already exists; instead, a log message is put into the +transcript file if a command is redefined. + +Commands defined this way are a bit less efficient than those defined +using @code{\newcommand} so unless the command's data is fragile and the +command is used within a moving argument, use @code{\newcommand}. + +@PkgIndex{etoolbox} +The @code{etoolbox} package offers commands @code{\newrobustcmd}, +@code{\newrobustcmd*}, @code{\renewrobustcmd}, @code{\renewrobustcmd*}, +@code{\providerobustcmd}, and @code{\providerobustcmd*} which are similar +to @code{\newcommand}, @code{\newcommand*}, @code{\renewcommand}, +@code{\renewcommand*}, @code{\providecommand}, and +@code{\providecommand*}, but define a robust @var{cmd} with two advantages +as compared to @code{\DeclareRobustCommand}: +@enumerate +@item +They use the low-level e-@TeX{} protection mechanism rather than the +higher level @LaTeX{} @code{\protect} mechanism, so they do not incur +the slight loss of performance mentioned above, and +@item +They make the same distinction between @code{\new@dots{}}, +@code{\renew@dots{}}, and @code{\provide@dots{}}, as the standard +commands, so they do not just make a log message when you redefine +@var{cmd} that already exists, in that case you need to use either +@code{\renew@dots{}} or @code{\provide@dots{}} or you get an error. +@end enumerate + + +@item \IfFileExists@{@var{file name}@}@{@var{true code}@}@{@var{false code}@} +@item \InputIfFileExists@{@var{file name}@}@{@var{true code}@}@{@var{false code}@} +@findex \IfFileExists +@findex \InputIfFileExists +Execute @var{true code} if @LaTeX{} can find the file @file{@var{file +name}} and @var{false code} otherwise. In the second case it inputs the +file immediately after executing @var{true code}. Thus +@code{\IfFileExists@{img.pdf@}@{\includegraphics@{img.pdf@}@}@{\typeout@{WARNING: +img.pdf not found@}@}} will include the graphic @file{img.pdf} if it is +found but otherwise just give a warning. + +This command looks for the file in all search paths that @LaTeX{} uses, +not only in the current directory. To look only in the current +directory do something like @code{\IfFileExists@{./filename@}@{@var{true +code}@}@{@var{false code}@}}. If you ask for a filename without a +@code{.tex} extension then @LaTeX{} will first look for the file by +appending the @code{.tex}; for more on how @LaTeX{} handles file +extensions see @ref{\input}. + +@item \LoadClass[@var{options list}]@{@var{class name}@}[@var{release date}] +@item \LoadClassWithOptions@{@var{class name}@}[@var{release date}] +@findex \LoadClass +@findex \LoadClassWithOptions +Load a class, as with @code{\documentclass[@var{options +list}]@{@var{class name}@}[@var{release info}]}. An example is +@code{\LoadClass[twoside]@{article@}}. + +The @var{options list}, if present, is a comma-separated list. The +@var{release date} is optional. If present it must have the form +@var{YYYY/MM/DD}. +@c BTW, there are at-macros documented in macros2e.pdf to check the version +@c and do some actions conditionnally on version later or not to some +@c date. + +If you request a @var{release date} and the date of +the package installed on your system is earlier, then you get a warning +on the screen and in the log like @code{You have requested, on input +line 4, version `2038/01/19' of document class article, but only version +`2014/09/29 v1.4h Standard LaTeX document class' is available.} + +The command version @code{\LoadClassWithOptions} uses the list of +options for the current class. This means it ignores any options passed +to it via @code{\PassOptionsToClass}. This is a convenience command +that lets you build classes on existing ones, such as the standard +@code{article} class, without having to track which options were passed. + +@item \ExecuteOptions@{@var{options-list}@} +@findex \ExecuteOptions +For each option @var{option} in the @var{options-list}, in order, this command +executes the command @code{\ds@@@var{option}}. If this command is not +defined then that option is silently ignored. + +It can be used to provide a default option list before +@code{\ProcessOptions}. For example, if in a class file you want the +default to be 11pt fonts then you could specify +@code{\ExecuteOptions@{11pt@}\ProcessOptions\relax}. + +@item \NeedsTeXFormat@{@var{format}@}[@var{format date}] +@findex \NeedsTeXFormat +Specifies the format that this class must be run under. Often issued +as the first line of a class file, and most often used as: +@code{\NeedsTeXFormat@{LaTeX2e@}}. When a document using that class is +processed, the format name given here must match the format that is +actually being run (including that the @var{format} string is case +sensitive). If it does not match then execution stops with an error +like @samp{This file needs format `LaTeX2e' but this is `xxx'.} + +To specify a version of the format that you know to have certain +features, include the optional @var{format date} on which those features +were implemented. If present it must be in the form @code{YYYY/MM/DD}. +If the format version installed on your system is earlier than +@var{format date} then you get a warning like @samp{You have requested +release `2038/01/20' of LaTeX, but only release `2016/02/01' is +available.} + +@item \OptionNotUsed +@findex \OptionNotUsed +Adds the current option to the list of unused options. Can only be used +within the @var{code} argument of either @code{\DeclareOption} or +@code{\DeclareOption*}. + +@c I cannot reproduce this behavior as it is documented in clsguide. +@c In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues +@c on the console a warning like @code{LaTeX Warning: Unused global +@c option(s): [unusedoption].} with the list of not-used options when it +@c reaches @code{\begin@{document@}}. + +@item \PassOptionsToClass@{@var{option list}@}@{@var{class name}@} +@item \PassOptionsToPackage@{@var{option list}@}@{@var{package name}@} +@findex \PassOptionsToClass +@findex \PassOptionsToPackage +Adds the options in the comma-separated list @var{option list} to the +options used by any future @code{\RequirePackage} or @code{\usepackage} +command for package @var{package name} or the class @var{class name}. + +The reason for these commands is: you may load a package any number of +times with no options but if you want options then you may only supply +them when you first load the package. Loading a package with options +more than once will get you an error like @code{Option clash for package +foo.} (@LaTeX{} throws an error even if there is no conflict between the +options.) + +If your own code is bringing in a package twice then you can collapse +that to once, for example replacing the two +@code{\RequirePackage[landscape]@{geometry@}\RequirePackage[margins=1in]@{geometry@}} +with the single +@code{\RequirePackage[landscape,margins=1in]@{geometry@}}. But if you +are loading a package that in turn loads another package then you need +to queue up the options you desire for this other package. For +instance, suppose the package @code{foo} loads the package +@code{geometry}. Instead of +@code{\RequirePackage@{foo@}\RequirePackage[draft]@{graphics@}} you must +write @code{\PassOptionsToPackage@{draft@}@{graphics@} +\RequirePackage@{foo@}}. (If @code{foo.sty} loads an option in conflict +with what you want then you may have to look into altering its source.) + +These commands are useful for general users as well as class and package +writers. For instance, suppose a user wants to load the @code{graphicx} +package with the option @code{draft} and also wants to use a class +@code{foo} that loads the @code{graphicx} package, but without that +option. The user could start their @LaTeX{} file with +@code{\PassOptionsToPackage@{draft@}@{graphicx@}\documentclass@{foo@}}. + +@item \ProcessOptions +@item \ProcessOptions*@var{\@@options} +@findex \ProcessOptions +@findex \ProcessOptions* +Execute the code for each option that the user has invoked. Include it +in the class file as @code{\ProcessOptions\relax} (because of the +existence of the starred command). + +Options come in two types. @dfn{Local options} have been specified for this +particular package in the @var{options} argument of +@code{\PassOptionsToPackage@{@var{options}@}}, +@code{\usepackage[@var{options}]}, or +@code{\RequirePackage[@var{options}]}. @dfn{Global options} are those given +by the class user in @code{\documentclass[@var{options}]} (If an option +is specified both locally and globally then it is local.) + +When @code{\ProcessOptions} is called for a package @file{pkg.sty}, the +following happens: +@enumerate +@item +For each option @var{option} so far declared +with @code{\DeclareOption}, it looks to see if that option is either a +global or a local option for @code{pkg}. If so then it executes the +declared code. This is done in the order in which these options were +given in @file{pkg.sty}. +@item +For each remaining local option, it executes the command +@code{\ds@@}@var{option} if it has been defined somewhere (other than by +a @code{\DeclareOption}); otherwise, it executes the default option code +given in @code{\DeclareOption*}. If no default option code has been +declared then it gives an error message. This is done in the order in +which these options were specified. +@end enumerate + +When @code{\ProcessOptions} is called for a class it works in the same +way except that all options are local, and the default @var{code} for +@code{\DeclareOption*} is @code{\OptionNotUsed} rather than an error. + +The starred version @code{\ProcessOptions*} executes the +options in the order specified in the calling commands, rather than in +the order of declaration in the class or package. For a package this +means that the global options are processed first. + + +@item \ProvidesClass@{@var{class name}@}[@var{release date} @var{brief additional information}] +@item \ProvidesClass@{@var{class name}@}[@var{release date}] +@item \ProvidesPackage@{@var{package name}@}[@var{release date} @var{brief additional information}] +@item \ProvidesPackage@{@var{package name}@}[@var{release date}] +@findex \ProvidesClass +@findex \ProvidesPackage +Identifies the class or package, printing a message to the screen and the log file. + +When a user writes @code{\documentclass@{smcmemo@}} then @LaTeX{} loads +the file @file{smcmemo.cls}. Similarly, a user writing +@code{\usepackage@{test@}} prompts @LaTeX{} to load the file +@code{test.sty}. If the name of the file does not match the declared +class or package name then you get a warning. Thus, if you invoke +@code{\documentclass@{smcmemo@}}, and the file @file{smcmemo.cls} has +the statement @code{\ProvidesClass@{xxx@}} then you get a warning like +@code{You have requested document class `smcmemo', but the document +class provides 'xxx'.} This warning does not prevent @LaTeX{} from +processing the rest of the class file normally. + +If you include the optional argument, then you must include the date, before +the first space if any, and it must have the form @code{YYYY/MM/DD}. The rest +of the optional argument is free-form, although it traditionally identifies +the class, and is written to the screen during compilation and to the +log file. Thus, if your file @file{smcmemo.cls} contains the line +@code{\ProvidesClass@{smcmemo@}[2008/06/01 v1.0 SMC memo class]} and your +document's first line is @code{\documentclass@{smcmemo@}} then you will +see @code{Document Class: smcmemo 2008/06/01 v1.0 SMC memo class}. + +The date in the optional argument allows class and package users to ask +to be warned if the version of the class or package installed on their +system is earlier than @var{release date}, by using the optional arguments +such as @code{\documentclass@{smcmemo@}[2018/10/12]} or +@code{\usepackage@{foo@}[[2017/07/07]]}. (Note that package users only +rarely include a date, and class users almost never do.) + +@item \ProvidesFile@{@var{file name}@}[@var{additional information}] +@findex \ProvidesFile +Declare a file other than the main class and package files, such as +configuration files or font definition files. Put this command in that +file and you get in the log a string like @code{File: test.config +2017/10/12 config file for test.cls} for @var{file name} equal to +@samp{test.config} and @var{additional information} equal to +@samp{2017/10/12 config file for test.cls}. + +@item \RequirePackage[@var{option list}]@{@var{package name}@}[@var{release date}] +@item \RequirePackageWithOptions@{@var{package name}@}[@var{release date}] +@findex \RequirePackage +@findex \RequirePackageWithOptions +Load a package, like the document author command @code{\usepackage}. +@xref{Additional packages}. An example is +@code{\RequirePackage[landscape,margin=1in]@{geometry@}}. Note that the +@LaTeX{} development team strongly recommends use of these commands over +Plain@tie{}@TeX{}'s @code{\input}; see the Class Guide. + +The @var{option list}, if present, is a comma-separated list. The +@var{release date}, if present, must have the form @var{YYYY/MM/DD}. If +the release date of the package as installed on your system is earlier +than @var{release date} then you get a warning like @code{You have +requested, on input line 9, version `2017/07/03' of package jhtest, but +only version `2000/01/01' is available}. + +The @code{\RequirePackageWithOptions} version uses the list of options +for the current class. This means it ignores any options passed to it +via @code{\PassOptionsToClass}. This is a convenience command to allow +easily building classes on existing ones without having to track which +options were passed. + +The difference between @code{\usepackage} and @code{\RequirePackage} is +small. The @code{\usepackage} command is intended for the document file +while @code{\RequirePackage} is intended for package and class files. +Thus, using @code{\usepackage} before the @code{\documentclass} command +causes @LaTeX{} to give error like @code{\usepackage before +\documentclass}, but you can use @code{\RequirePackage} there. +@end table + + @node Fonts @chapter Fonts @anchor{Typefaces}@c old name @@ -962,7 +1650,7 @@ formulas. @code{\mathversion@{normal@}} restores the default. @cindex numerals, old-style @cindex old-style numerals @cindex lining numerals -@cindex @code{textcomp} package +@PkgIndex{textcomp} Finally, the command @code{\oldstylenums@{@var{numerals}@}} will typeset so-called ``old-style'' numerals, which have differing heights and depths (and sometimes widths) from the standard ``lining'' numerals, @@ -1174,7 +1862,7 @@ 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. -@cindex @code{setspace} package +@PkgIndex{setspace} @cindex double spacing However, the best way to double-space a document is to use the @file{setspace} package. In addition to offering a number of spacing @@ -1235,10 +1923,9 @@ Commands for controlling the general page layout. @findex \onecolumn @cindex one-column output -The @code{\onecolumn} declaration starts a new page and produces -single-column output. If the document is given the class option -@code{onecolumn} then this is the default behavior (@pxref{Document -class options}). +Start a new page and produce single-column output. If the document is +given the class option @code{onecolumn} then this is the default +behavior (@pxref{Document class options}). This command is fragile (@pxref{\protect}). @@ -1250,16 +1937,16 @@ This command is fragile (@pxref{\protect}). @cindex multicolumn text @cindex two-column output -Synopsis: +Synopses: @example +\twocolumn \twocolumn[@var{prelim one column text}] @end example -The @code{\twocolumn} declaration starts a new page and produces -two-column output. If the document is given the class option -@code{twocolumn} then this is the default (@pxref{Document class -options}). +Start a new page and produce two-column output. If the document is given +the class option @code{twocolumn} then this is the default +(@pxref{Document class options}). If the optional @var{prelim one column text} argument is present, it is typeset in one-column mode before the two-column @@ -1303,7 +1990,7 @@ The maximum fraction at the top of a two-column page that may be occupied by two-column wide floats. The default is 0.7, meaning that the height of a @code{table*} or @code{figure*} environment must not exceed @code{0.7\textheight} . If the height of your starred float -environment exceeeds this then you can take one of the following actions +environment exceeds this then you can take one of the following actions to prevent it from floating all the way to the back of the document: @itemize @bullet @@ -1348,25 +2035,25 @@ default is @code{2}. @end ftable @c From egreg at http://tex.stackexchange.com/a/142232/339 -This example shows the use of the optional argument of @code{\twocolumn} -to create a title that spans the two-column article: +This example uses @code{\twocolumn}'s optional argument of to create a +title that spans the two-column article: @example \documentclass[twocolumn]@{article@} \newcommand@{\authormark@}[1]@{\textsuperscript@{#1@}@} \begin@{document@} \twocolumn[@{% inside this optional argument goes one-column text - \centering - \LARGE The Title \\[1.5em] - \large Author One\authormark@{1@}, - Author Two\authormark@{2@}, - Author Three\authormark@{1@} \\[1em] - \normalsize - \begin@{tabular@}@{p@{.2\textwidth@}@@@{\hspace@{2em@}@}p@{.2\textwidth@}@} - \authormark@{1@}Department one &\authormark@{2@}Department two \\ - School one &School two - \end@{tabular@}\\[3em] % space below title part -@}] + \centering + \LARGE The Title \\[1.5em] + \large Author One\authormark@{1@}, + Author Two\authormark@{2@}, + Author Three\authormark@{1@} \\[1em] + \normalsize + \begin@{tabular@}@{p@{.2\textwidth@}@@@{\hspace@{2em@}@}p@{.2\textwidth@}@} + \authormark@{1@}Department one &\authormark@{2@}Department two \\ + School one &School two + \end@{tabular@}\\[3em] % space below title part + @}] Two column text here. @end example @@ -1377,22 +2064,23 @@ Two column text here. @findex \flushbottom -The @code{\flushbottom} command can go at any point in the document -body. It makes all later pages the same height, stretching the vertical -space where necessary to fill out the page. +Make all pages in the documents after this declaration have the same +height, by stretching the vertical space where necessary to fill out the +page. This is most often used when making two-sided documents since the +differences in facing pages can be glaring. If @TeX{} cannot satisfactorily stretch the vertical space in a page then you get a message like @samp{Underfull \vbox (badness 10000) has -occurred while \output is active}. You can change to -@code{\raggedbottom} (see below). Alternatively, you can try to adjust -the @code{textheight} to be compatible, or you can add some vertical -stretch glue between lines or between paragraphs, as in -@code{\setlength@{\parskip@}@{0ex plus0.1ex@}}. In a final editing -stage you can adjust the height of individual pages +occurred while \output is active}. If you get that, one option is to +change to @code{\raggedbottom} (@pxref{\raggedbottom}). Alternatively, +you can adjust the @code{textheight} to make compatible pages, or you +can add some vertical stretch glue between lines or between paragraphs, +as in @code{\setlength@{\parskip@}@{0ex plus0.1ex@}}. Your last option +is to, in a final editing stage, adjust the height of individual pages (@pxref{\enlargethispage}). -This is the default only if you select the @code{twoside} document class -option (@pxref{Document class options}). +The @code{\flushbottom} state is the default only if you select the +@code{twoside} document class option (@pxref{Document class options}). @node \raggedbottom @@ -1401,11 +2089,10 @@ option (@pxref{Document class options}). @findex \raggedbottom @cindex stretch, omitting vertical -The @code{\raggedbottom} command can go at any point in the document -body. It makes all later pages the natural height of the material on -that page; no rubber lengths will be stretched. Thus, in a two-sided -document the facing pages may be different heights. See also -@code{\flushbottom} above. +Make all later pages the natural height of the material on that page; no +rubber vertical lengths will be stretched. Thus, in a two-sided +document the facing pages may be different heights. This command can go +at any point in the document body. See @ref{\flushbottom}. This is the default unless you select the @code{twoside} document class option (@pxref{Document class options}). @@ -1597,14 +2284,14 @@ while the first table appears in the source before the first figure, it appears in the output after it. The placement of floats is subject to parameters, given below, that -limit the number of floats that can appear at the top of a page, and the -bottom, etc. If so many floats are queued up that the limits prevent +limit the number of floats that can appear at the top of a page, and +the bottom, etc. If so many floats are queued that the limits prevent them all from fitting on a page then @LaTeX{} places what it can and -defers the rest to the next page. In this way, floats may be typset far -from their place in the source. In particular, a float that is big can -migrate to the end of the document. But then because all floats in a -class must appear in sequential order, every subsequent float in that -class also appears at the end. +defers the rest to the next page. In this way, floats may end up +being typeset far from their place in the source. In particular, a +float that is big may migrate to the end of the document. In which +event, because all floats in a class must appear in sequential order, +every following float in that class also appears at the end. @cindex placement of floats @cindex specifier, float placement @@ -1631,7 +2318,7 @@ appears. However, @code{h} is not allowed by itself; @code{t} is automatically added. @cindex here, putting floats -@cindex @code{float} package +@PkgIndex{float} To absolutely force a float to appear ``here'', you can @code{\usepackage@{float@}} and use the @code{H} specifier which it defines. For further discussion, see the FAQ entry at @@ -1666,12 +2353,13 @@ use the @file{afterpage} package and issue @code{\afterpage@{\clearpage@}}. This will wait until the current page is finished and then flush all outstanding floats. +@PkgIndex{flafter} @LaTeX{} can typeset a float before where it appears in the source -(although on the same output page) if there is a @code{t} specifier in the -@var{placement} paramater. If this is not desired, and deleting the -@code{t} is not acceptable as it keeps the float from being placed at -the top of the next page, then you can prevent it by either using the -@file{flafter} package or using the command +(although on the same output page) if there is a @code{t} specifier in +the @var{placement} parameter. If this is not desired, and deleting +the @code{t} is not acceptable as it keeps the float from being placed +at the top of the next page, then you can prevent it by either using +the @file{flafter} package or using the command @findex \suppressfloats @code{\suppressfloats[t]}, which causes floats for the top position on this page to moved to the next page. @@ -1751,10 +2439,11 @@ Maximum number of floats that can appear on a text page; default 3. The principal @TeX{}@tie{}FAQ entry relating to floats @url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats} contains suggestions for relaxing @LaTeX{}'s default parameters to reduce the -problem of floats being pushed to the end. A full explaination of the -float placement algorithm is Frank Mittelbach's article ``How to -infuence the position of float environments like figure and table in -@LaTeX{}?'' @url{http://latex-project.org/papers/tb111mitt-float.pdf}. +problem of floats being pushed to the end. A full explanation of the +float placement algorithm is in Frank Mittelbach's article ``How to +influence the position of float environments like figure and table in +@LaTeX{}?'' +(@url{http://latex-project.org/papers/tb111mitt-float.pdf}). @node Sectioning @@ -1821,6 +2510,7 @@ command is something like @findex secnumdepth @r{counter} @cindex section numbers, printing +@anchor{Sectioning/secnumdepth} The @code{secnumdepth} counter controls printing of section numbers. The setting @@ -1832,14 +2522,240 @@ The setting suppresses heading numbers at any depth @math{> @var{level}}, where @code{chapter} is level zero. (@xref{\setcounter}.) +@menu +* \@@startsection:: Redefine layout of start of sections, subsections, etc. +@end menu + + +@node \@@startsection +@section @code{\@@startsection} + +@findex \@@startsection +@cindex section, redefining + +Synopsis: + +@example +\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}@{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@} +@end example + +Redefine the behavior of commands that start sectioning divisions such +as @code{\section} or @code{\subsection}. + +Note that the @file{titlesec} package makes manipulation of sectioning +easier. Further, while most requirements for sectioning commands can be +satisfied with @code{\@@startsection}, some cannot. For instance, in +the standard @LaTeX{} @code{book} and @code{report} classes the commands +@code{\chapter} and @code{\report} are not constructed in this way. To +make such a command you may want to use the @code{\secdef} command. +@c xx define, and make a cross reference to, secdef. + +Technically, this command has the form: +@example +\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}@{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@} + *[@var{toctitle}]@{@var{title}@} +@end example +@noindent so that issuing: +@example +\renewcommand@{\section@}@{\@@startsection@{@var{name}@}@{@var{level}@}@{@var{indent}@}% + @{@var{beforeskip}@}@{@var{afterskip}@}@{@var{style}@}@} +@end example +@noindent redefine @code{\section} while keeping its standard calling form +@code{\section*[@var{toctitle}]@{@var{title}@}}. @xref{Sectioning} and +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. + +Then @code{\the}@var{name} displays the title number and +@code{\}@var{name}@code{mark} is for the page headers. + +@item level +@anchor{\@@startsection/level} An integer giving the depth of the +sectioning command: 0 for @code{chapter} (only applies to the standard +@code{book} and @code{report} classes), 1 for @code{section}, 2 for +@code{subsection}, 3 for @code{subsubsection}, 4 for @code{paragraph}, +and 5 for @code{subparagraph}. In the @code{book} and @code{report} +classes @code{part} has level -1, while in the @code{article} class +@code{part} has level 0. + +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}. + +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. +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. + +@item beforeskip +@anchor{\@@startsection/beforeskip} The absolute value of this length is +the amount of vertical space that is inserted before this sectioning +unit's title. This space will be discarded if the sectioning unit +happens to start at the top of a fresh page. If this number is negative +then the first paragraph following the header is not indented, if it is +non-negative then the first paragraph is indented. (Note that the +negative of @code{1pt plus 2pt minus 3pt} is @code{-1pt plus -2pt minus +-3pt}.) + +For example, if @var{beforeskip} is @code{-3.5ex plus -1ex minus -0.2ex} +then to start the new sectioning unit, @LaTeX{} will add about 3.5 times +the height of a letter x in vertical space, and the first paragraph in +the section will not be indented. Using a rubber length, with +@code{plus} and @code{minus}, is good practice here since it gives +@LaTeX{} more flexibility in making up the page. + +The full accounting of the vertical space between the baseline of the +line prior to this sectioning unit's header and the baseline of the +header is that it is the sum of the @code{\parskip} of the text font, +the @code{\baselineskip} of the title font, and the absolute value of +the @var{beforeskip}. This space is typically rubber so it may stretch +or shrink. (If the sectioning unit starts on a fresh page so that the +vertical space is discarded then the baseline of the header text will be +where @LaTeX{} would put the baseline of the first text line on that +page.) + +@item afterskip +@anchor{\@@startsection/afterskip} This is a length. If @var{afterskip} +is non-negative then this is the vertical space inserted after the +sectioning unit's title header. If it is negative then the title header +becomes a run-in header, so that it becomes part of the next paragraph. +In this case the absolute value of the length gives the horizontal space +between the end of the title and the beginning of the following +paragraph. (Note that the negative of @code{1pt plus 2pt minus 3pt} is +@code{-1pt plus -2pt minus -3pt}.) + +As with @var{beforeskip}, using a rubber length with @code{plus} and +@code{minus} components is good practice here since it gives @LaTeX{} +more flexibility in putting the page together. + +If @code{afterskip} is non-negative then the full accounting of the +vertical space between the baseline of the sectioning unit's header and +the baseline of the first line of the following paragraph is that it is +the sum of the @code{\parskip} of the title font, the +@code{\baselineskip} of the text font, and the value of @var{after}. +That space is typically rubber so it may stretch or shrink. (Note that +because the sign of @code{afterskip} changes the sectioning unit +header's from standalone to run-in, you cannot use a negative +@code{afterskip} to cancel part of the @code{\parskip}.) + +@item style +@anchor{\@@startsection/style} Controls the styling of the title. See +the examples below. Typical commands to use here are @code{\centering}, +@code{\raggedright}, @code{\normalfont}, @code{\hrule}, or +@code{\newpage}. The last command in @var{style} may be one such as +@code{\MakeUppercase} or @code{\fbox} that takes one argument. The +section title will be supplied as the argument to this command. For +instance, setting @var{style} to @code{\bfseries\MakeUppercase} would +produce titles that are bold and 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}. + +This will put section titles in large boldface type, centered. + +@example +\renewcommand\section@{% + \@@startsection@{section@}% @ref{\@@startsection/name,@var{name},@var{name}}. + @{1@}% @ref{\@@startsection/level,@var{level},@var{level}}. + @{0pt@}% @ref{\@@startsection/indent,@var{indent},@var{indent}}. + @{-3.5ex plus -1ex minus -.2ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}}. + @{2.3ex plus.2ex@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}}. + @{\centering\normalfont\Large\bfseries@}% @ref{\@@startsection/style,@var{style},@var{style}}. + @} +@end example + +This will put @code{subsection} titles in small caps type, inline with the paragraph. + +@example +\renewcommand\subsection@{% + \@@startsection@{subsection@}% @ref{\@@startsection/name,@var{name},@var{name}}. + @{2@}% @ref{\@@startsection/level,@var{level},@var{level}}. + @{0em@}% @ref{\@@startsection/indent,@var{indent},@var{indent}}. + @{-1ex plus 0.1ex minus -0.05ex@}% @ref{\@@startsection/beforeskip,@var{beforeskip},@var{beforeskip}}. + @{-1em plus 0.2em@}% @ref{\@@startsection/afterskip,@var{afterskip},@var{afterskip}}. + @{\scshape@}% @ref{\@@startsection/style,@var{style},@var{style}}. + @} +@end example + +The prior examples redefined existing sectional unit title commands. This defines a new one, illustrating the needed counter and macros to display that counter. + +@c From https://groups.google.com/forum/#!searchin/comp.text.tex/startsection%7Csort:relevance/comp.text.tex/sB-nTS-oL08/ZZeKYdG0llMJ +@example +\setcounter@{secnumdepth@}@{6@}% show counters this far down +\newcounter@{subsubparagraph@}[subparagraph]% counter for numbering +\renewcommand@{\thesubsubparagraph@}% how to display + @{\thesubparagraph.\@@arabic\c@@subsubparagraph@}% numbering +\newcommand@{\subsubparagraph@}@{\@@startsection + @{subsubparagraph@}% + @{6@}% + @{0em@}% + @{\baselineskip@}% + @{0.5\baselineskip@}% + @{\normalfont\normalsize@}@} +\newcommand*\l@@subsubparagraph@{\@@dottedtocline@{6@}@{10em@}@{5em@}@}% for toc +\newcommand@{\subsubparagraphmark@}[1]@{@}% for page headers +@end example + @node Cross references @chapter Cross references @cindex cross references -One reason for numbering things like figures and equations is to refer -the reader to them, as in ``See Figure 3 for more details.'' +One reason for numbering things such as figures and equations is to +refer the reader to them, as in ``See Figure~3 for more details.'' + +@cindex label +Including the figure number in the source is poor practice since if that +number changes as the document evolves then you must remember to update +this reference by hand. Instead, @LaTeX{} has you write a @dfn{label} +like @code{\label@{eq:GreensThm@}} and refer to it with @code{See +equation~\ref@{eq:GreensThm@}}. + +@LaTeX{} writes the information from the labels to a file with the same +name as the file containing the @code{\label@{...@}} but with an +@file{.aux} extension. (The information has the format +@code{\newlabel@{@var{label}@}@{@{@var{currentlabel}@}@{@var{pagenumber}@}@}} +where @var{currentlabel} is the current value of the macro +@code{\@@currentlabel} that is usually updated whenever you call +@code{\refstepcounter@{@var{counter}@}}.) + +@cindex forward reference +@cindex reference, forward +The most common side effect of the prior paragraph happens when your +document has a @dfn{forward reference}, a @code{\ref@{@var{key}@}} that +appears earlier than the associated @code{\label@{@var{key}@}}; see the +example in the @code{\pageref@{...@}} description. @LaTeX{} gets the +information for references from the @file{.aux} file. If this is the +first time you are compiling the document then you will get a message +@code{LaTeX Warning: Label(s) may have changed. Rerun to get +cross references right.} and in the output the reference will appear as +two question marks@tie{}@samp{??}, in boldface. Or, if you change some +things so the references change then you get the same warning and the +output contains the old reference information. The solution in either +case is just to compile the document a second time. @menu * \label:: Assign a symbolic name to a piece of text. @@ -1859,37 +2775,22 @@ Synopsis: \label@{@var{key}@} @end example -A @code{\label} command appearing in ordinary text assigns to -@var{key} the number of the current sectional unit; one appearing -inside a numbered environment assigns that number to @var{key}. The -assigned number can be retrieved with the @code{\ref@{@var{key}@}} -command (@pxref{\ref}). - -Thus, in the example below the key @code{sec:test} holds the number of -the current section and the key @code{fig:test} that of the figure. -(Incidentally, labels must appear after captions in figures and -tables.) - -@example -\section@{section name@} -\label@{sec:test@} -This is Section~\ref@{sec:test@}. -\begin@{figure@} - ... - \caption@{caption text@} - \label@{fig:test@} -\end@{figure@} -See Figure~\ref@{fig:test@}. -@end example +Assign a reference number to @var{key}. In ordinary text +@code{\label@{@var{key}@}} assigns to @var{key} the number of the +current sectional unit. Inside an environment with numbering, such as a +@code{table} or @code{theorem} environment, @code{\label@{@var{key}@}} +assigns to @var{key} the number of that environment. Retrieve the +assigned number with the @code{\ref@{@var{key}@}} command +(@pxref{\ref}). A key name can consist of any sequence of letters, digits, or common punctuation characters. Upper and lowercase letters are distinguished, as usual. -Although the name can be more or less anything, a common convention is -to use labels consisting of a prefix and a suffix separated by a colon -or period. This helps to avoid accidentally creating two labels with -the same name. Some commonly-used prefixes: +A common convention is to use labels consisting of a prefix and a suffix +separated by a colon or period. This helps to avoid accidentally +creating two labels with the same name, and makes your source more +readable. Some commonly-used prefixes: @table @code @item ch @@ -1904,8 +2805,25 @@ for tables for equations @end table -Thus, a label for a figure would look like @code{fig:test} or -@code{fig.test}. +Thus, @code{\label@{fig:Euler@}} is a label for a figure with a portrait +of the great man. + +In this example below the key @code{sec:test} will get the number of the +current section and the key @code{fig:test} will get the number of the +figure. (Incidentally, put labels after captions in figures and +tables.) + +@example +\section@{section name@} +\label@{sec:test@} +This is Section~\ref@{sec:test@}. +\begin@{figure@} + ... + \caption@{caption text@} + \label@{fig:test@} +\end@{figure@} +See Figure~\ref@{fig:test@}. +@end example @node \pageref @@ -1921,10 +2839,22 @@ Synopsis: \pageref@{@var{key}@} @end example -The @code{\pageref}@{@var{key}@} command produces the page number of -the place in the text where the corresponding +Produce the page number of the place in the text where the corresponding @code{\label}@{@var{key}@} command appears. +In this example the @code{\label@{eq:main@}} is used both for the +formula number and for the page number. (Note that the two references +are forward references, so this document would need to be compiled twice +to resolve those.) + +@example +The main result is formula~\ref@{eq:main@} on page~\pageref@{eq:main@}. + ... +\begin@{equation@} \label@{eq:main@} + \mathbf@{P@}=\mathbf@{NP@} +\end@{equation@} +@end example + @node \ref @section @code{\ref@{@var{key}@}} @@ -1942,11 +2872,24 @@ Synopsis: \ref@{@var{key}@} @end example -The @code{\ref} command produces the number of the sectional unit, +Produces the number of the sectional unit, equation, footnote, figure, @dots{}, of the corresponding @code{\label} command (@pxref{\label}). It does not produce any text, such as the word `Section' or `Figure', just the bare number itself. +In this example, the @code{\ref@{popular@}} produces @samp{2}. Note +that it is a forward reference since it comes before +@code{\label@{popular@}}. + +@example +The most widely-used format is item number~\ref@{popular@}. +\begin@{enumerate@} +\item Plain \TeX +\item \label@{popular@} \LaTeX +\item Con\TeX t +\end@{enumerate@} +@end example + @node Environments @chapter Environments @@ -1955,15 +2898,25 @@ such as the word `Section' or `Figure', just the bare number itself. @findex \begin @findex \end -@LaTeX{} provides many environments for marking off certain text. -Each environment begins and ends in the same manner: +@LaTeX{} provides many environments for delimiting certain behavior. +An environment begins with @code{\begin} and ends with @code{\end}, +like this: @example -\begin@{@var{envname}@} -... -\end@{@var{envname}@} +\begin@{@var{environment-name}@} + ... +\end@{@var{environment-name}@} @end example +The @var{environment-name} at the beginning must exactly match that at +the end. For instance, the input +@code{\begin@{table*@}...\end@{table@}} will cause an error like: +@samp{! LaTeX Error: \begin@{table*@} on input line 5 ended by +\end@{table@}.} + +@cindex group, and environments +Environments are executed within a group. + @menu * abstract:: Produce an abstract. * array:: Math arrays. @@ -1999,7 +2952,7 @@ Each environment begins and ends in the same manner: @node abstract @section @code{abstract} -@findex abstract @r{environment} +@EnvIndex{abstract} @cindex abstracts Synopsis: @@ -2010,21 +2963,61 @@ Synopsis: \end@{abstract@} @end example -Environment for producing an abstract, possibly of multiple paragraphs. +Produce an abstract, possibly of multiple paragraphs. This environment +is only defined in the @code{article} and @code{report} document classes +(@pxref{Document classes}). + +Using the example below in the @code{article} class produces a displayed +paragraph. Document class option @code{titlepage} causes the abstract +to be on a separate page (@pxref{Document class options}); this is the +default only in the @code{report} class. + +@example +\begin@{abstract@} + We compare all known accounts of the proposal made by Porter Alexander + to Robert E Lee at the Appomattox Court House that the army continue + in a guerrilla war, which Lee refused. +\end@{abstract@} +@end example + +The next example produces a one column abstract in a two column document (for +a more flexible solution, use the package @file{abstract}). + +@c Adopted from http://www.tex.ac.uk/FAQ-onecolabs.html +@example +\documentclass[twocolumn]@{article@} + ... +\begin@{document@} +\title@{Babe Ruth as Cultural Progenitor: a Atavistic Approach@} +\author@{Smith \\ Jones \\ Robinson\thanks@{Railroad tracking grant.@}@} +\twocolumn[ + \begin@{@@twocolumnfalse@} + \maketitle + \begin@{abstract@} + Ruth was not just the Sultan of Swat, he was the entire swat + team. + \end@{abstract@} + \end@{@@twocolumnfalse@} + ] +@{ % by-hand insert a footnote at page bottom + \renewcommand@{\thefootnote@}@{\fnsymbol@{footnote@}@} + \footnotetext[1]@{Thanks for all the fish.@} +@} +@end example @node array @section @code{array} -@findex array @r{environment} +@EnvIndex{array} @cindex arrays, math Synopsis: @example \begin@{array@}@{@var{cols}@} -@var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ -... + @var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ + ... \end@{array@} @end example @@ -2032,8 +3025,8 @@ or @example \begin@{array@}[@var{pos}]@{@var{cols}@} -@var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ -... + @var{column 1 entry} &@var{column 2 entry} ... &@var{column n entry} \\ + ... \end@{array@} @end example @@ -2041,7 +3034,7 @@ Produce a mathematical array. This environment can only be used in math mode, and normally appears within a displayed mathematics environment such as @code{equation} (@pxref{equation}). Column entries are separated by an ampersand@tie{}(@code{&}). Rows are terminated with -double-backslashes@tie{}(@code{\\}) (@pxref{\\}). +double-backslashes (@pxref{\\}). The required argument @var{cols} describes the number of columns, their alignment, and the formatting of the intercolumn regions. See @@ -2050,24 +3043,25 @@ other common features of the two environments, including the optional @var{pos} argument. There are two ways that @code{array} diverges from @code{tabular}. The -first is that @code{array} entries are typeset in mathematics mode, in +first is that @code{array} entries are typeset in math mode, in textstyle (except if the @var{cols} definition specifies the column with -@code{@@p@{..@}}, which causes the entry to be typeset in text mode). +@code{p@{...@}}, which causes the entry to be typeset in text mode). The second is that, instead of @code{tabular}'s parameter -@code{\tabcolsep}, @LaTeX{}'s intercolumn space in an array is governed +@code{\tabcolsep}, @LaTeX{}'s intercolumn space in an @code{array} is governed by @findex \arraycolsep -@code{\arraycolsep} which gives half the width between columns. The +@code{\arraycolsep}, which gives half the width between columns. The default for this is @samp{5pt}. +@PkgIndex{amsmath} To obtain arrays with braces the standard is to use the @file{amsmath} package. It comes with environments @code{pmatrix} for an array -surrounded by parentheses@tie{}@code{(..)}, @code{bmatrix} for an array -surrounded by square brackets@tie{}@code{[..]}, @code{Bmatrix} for an -array surrounded by curly braces@tie{}@code{@{..@}}, @code{vmatrix} for -an array surrounded by vertical bars@tie{}@code{|..|}, and +surrounded by parentheses@tie{}@code{(...)}, @code{bmatrix} for an array +surrounded by square brackets@tie{}@code{[...]}, @code{Bmatrix} for an +array surrounded by curly braces@tie{}@code{@{...@}}, @code{vmatrix} for +an array surrounded by vertical bars@tie{}@code{|...|}, and @code{Vmatrix} for an array surrounded by double vertical -bars@tie{}@code{||..||}, along with a number of other array constructs. +bars@tie{}@code{||...||}, along with a number of other array constructs. Here is an example of an array: @@ -2080,36 +3074,61 @@ Here is an example of an array: \end@{equation@} @end example +The next example works if @code{\usepackage@{amsmath@}} is in the +preamble: + +@example +\begin@{equation@} + \begin@{vmatrix@}@{cc@} + a &b \\ + c &d + \end@{vmatrix@}=ad-bc +\end@{equation@} +@end example + @node center @section @code{center} -@findex center @r{environment} +@EnvIndex{center} @cindex centering text, environment for Synopsis: @example \begin@{center@} - .. text .. + ... text ... \end@{center@} @end example -Environment to create a sequence of lines that are centered within the -left and right margins on the current page. If the text in the -environment body is too long to fit on a line, @LaTeX{} will insert line -breaks that avoid hyphenation and avoid stretching or shrinking any -interword space. To force a line break at a particular spot use -double-backslash@tie{}@code{\\} (@pxref{\\}). +Create a new paragraph consisting of a sequence of lines that are +centered within the left and right margins on the current page. Use +double-backslash to get a line break at a particular spot (@pxref{\\}). @findex \\ @r{(for @code{center})} +If some text environment body is too long to fit on a line, @LaTeX{} +will insert line breaks that avoid hyphenation and avoid stretching or +shrinking any interword space. This environment inserts space above and below the text body. See @ref{\centering} to avoid such space, for example inside a @code{figure} environment. -In this example, depending on the line width, @LaTeX{} may choose a break -for the part before the double backslash, will center the line or two, -then will break at the double backslash, and will center the ending. +This example produces three centered lines. There is extra vertical +space between the last two lines. + +@example +\begin@{center@} + A Thesis Submitted in Partial Fufillment \\ + of the Requirements of \\[0.5ex] + the School of Environmental Engineering +\end@{center@} +@end example + +In this example, depending on the page's line width, @LaTeX{} may choose +a line break for the part before the double backslash. If so, it will +center each of the two lines and if not it will center the single line. +Then @LaTeX{} will break at the double backslash, and will center the +ending. @example \begin@{center@} @@ -2132,7 +3151,7 @@ A double backslash after the final line is optional. @findex \centering @cindex centering text, declaration for -Declaration that causes material in its scope to be centered. It is +A declaration that causes material in its scope to be centered. It is most often used inside an environment such as @code{figure}, or in a @code{parbox}. @@ -2168,7 +3187,7 @@ The scope of the @code{\centering} ends with the @code{\end@{figure@}}. @node description @section @code{description} -@findex description @r{environment} +@EnvIndex{description} @cindex labelled lists, creating @cindex description lists, creating @@ -2182,26 +3201,26 @@ Synopsis: \end@{description@} @end example -@findex \item 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. @findex \item -The list consists of at least one item; see@tie{}@ref{\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. +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}). @cindex bold typewriter, avoiding @cindex typewriter labels in lists Since the labels are in bold style, if the label text calls for a font -change given in argument style (see @ref{Font styles}) then it will come -out bold. For instance, if the label text calls for typewriter with -@code{\item[\texttt@{label text@}]} then it will appear in bold -typewriter, if that is available. The simplest way to get non-bolded -typewriter is to use declaritive style @code{\item[@{\tt label text@}]}. -Similarly, get normal text use @code{\item[@{\rm label text@}]}. +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@}]}. For other major @LaTeX{} labelled list environments, see @ref{itemize} and @ref{enumerate}. For information about customizing list layout, see @@ -2221,13 +3240,13 @@ This example shows the environment used for a sequence of definitions. @section @code{displaymath} @c http://tex.stackexchange.com/questions/40492/what-are-the-differences-between-align-equation-and-displaymath -@findex displaymath @r{environment} +@EnvIndex{displaymath} Synopsis: @example \begin@{displaymath@} - .. math text .. +@var{math text} \end@{displaymath@} @end example @@ -2235,29 +3254,29 @@ Environment to typeset the math text on its own line, in display style and centered. To make the text be flush-left use the global option @code{fleqn}; see @ref{Document class options}. -@LaTeX{} will not break the math text across lines. - In the @code{displaymath} environment no equation number is added to the math text. One way to get an equation number is to use the @code{equation} environment (@pxref{equation}). -Note that the @file{amsmath} package has extensive displayed equation -facilities. Those facilities are the best approach for such output in -new documents. For example, there are a number of options in that -package for having math text broken across lines. +@LaTeX{} will not break the @var{math text} across lines. + +@PkgIndex{amsmath} +Note that the @file{amsmath} package has significantly more extensive +displayed equation facilities. For example, there are a number of +ways in that package for having math text broken across lines. -The construct @code{\[..math text..\]} is essentially a synonym for -@code{\begin@{displaymath@}..math text..\end@{displaymath@}} but the +The construct @code{\[@var{math text}\]} is essentially a synonym for +@code{\begin@{displaymath@}@var{math text}\end@{displaymath@}} but the latter is easier to work with in the source file; for instance, searching for a square bracket may get false positives but the word -@code{displaymath} will likely be unique. (The construct @code{$$..math -text..$$} from Plain@tie{}@TeX{} is sometimes mistakenly used as a -synonym for @code{displaymath}. It is not a synonym, because the -@code{displaymath} environment checks that it isn't started in math mode -and that it ends in math mode begun by the matching environment start, -because the @code{displaymath} environment has different vertical -spacing, and because the @code{displaymath} environment honors the -@code{fleqn} option.) +@code{displaymath} will likely be unique. (The construct +@code{$$@var{math text}$$} from Plain@tie{}@TeX{} is sometimes +mistakenly used as a synonym for @code{displaymath}. It is not a +synonym, because the @code{displaymath} environment checks that it isn't +started in math mode and that it ends in math mode begun by the matching +environment start, because the @code{displaymath} environment has +different vertical spacing, and because the @code{displaymath} +environment honors the @code{fleqn} option.) The output from this example is centered and alone on its line. @example @@ -2272,7 +3291,7 @@ Also, the integral sign is larger than the inline version @node document @section @code{document} -@findex document @r{environment} +@EnvIndex{document} The @code{document} environment encloses the entire body of a document. It is required in every @LaTeX{} document. @xref{Starting and ending}. @@ -2329,7 +3348,7 @@ will be executed in the order that you gave them. @node enumerate @section @code{enumerate} -@findex enumerate @r{environment} +@EnvIndex{enumerate} @cindex lists of items, numbered Synopsis: @@ -2414,7 +3433,7 @@ For more on customizing the layout see @ref{list}. Also, the package @node eqnarray @section @code{eqnarray} -@findex eqnarray @r{environment} +@EnvIndex{eqnarray} @cindex equations, aligning @cindex aligning equations @@ -2488,7 +3507,7 @@ while the third line has not entry on the left side. @node equation @section @code{equation} -@findex equation @r{environment} +@EnvIndex{equation} @cindex equations, environment for @cindex formulas, environment for @@ -2513,7 +3532,7 @@ new documents. @node figure @section @code{figure} -@findex figure +@EnvIndex{figure} @cindex inserting figures @cindex figures, inserting @@ -2554,7 +3573,7 @@ in @ref{Floats}. The figure body is typeset in a @code{parbox} of width @code{\textwidth} and so it can contain text, commands, etc. -The label is optional; it is used for cross-references (@pxref{Cross +The label is optional; it is used for cross references (@pxref{Cross references}). @findex \caption The optional @code{\caption} command specifies caption text for the @@ -2579,7 +3598,8 @@ end of the document, on a page of floats. @node filecontents @section @code{filecontents}: Write an external file -@findex filecontents +@EnvIndex{filecontents} +@EnvIndex{filecontents*} @cindex external files, writing @cindex writing external files @@ -2643,7 +3663,7 @@ produces this file @file{JH.sty}. @node flushleft @section @code{flushleft} -@findex flushleft @r{environment} +@EnvIndex{flushleft} @cindex left-justifying text, environment for @cindex ragged right text, environment for @@ -2687,7 +3707,7 @@ command that ends the paragraph unit. @node flushright @section @code{flushright} -@findex flushright @r{environment} +@EnvIndex{flushright} @cindex ragged left text, environment for @cindex right-justifying text, environment for @@ -2731,7 +3751,7 @@ command that ends the paragraph unit. @node itemize @section @code{itemize} -@findex itemize @r{environment} +@EnvIndex{itemize} @findex \item @cindex lists of items @cindex unordered lists @@ -2748,7 +3768,7 @@ Synopsis: @end example The @code{itemize} environment produces an ``unordered'', ``bulleted'' -list. Itemizations can be nested within one another, up to four +list. Itemized lists can be nested within one another, up to four levels deep. They can also be nested within other paragraph-making environments, such as @code{enumerate} (@pxref{enumerate}). @@ -2876,7 +3896,7 @@ within a single item (@code{\parskip} is not list-specific, @node letter @section @code{letter} environment: writing letters -@findex letter @r{environment} +@EnvIndex{letter} This environment is used for creating letters. @xref{Letters}. @@ -2884,7 +3904,7 @@ This environment is used for creating letters. @xref{Letters}. @node list @section @code{list} -@findex list +@EnvIndex{list} @cindex lists of items, generic The @code{list} environment is a generic environment which is used for @@ -2917,6 +3937,7 @@ The width used for typesetting the list items is specified by @node \item +@subsection @code{\item}: An entry in a list. Synopsis: @@ -2960,7 +3981,7 @@ not get a @samp{3.}). @node math @section @code{math} -@findex math @r{environment} +@EnvIndex{math} @cindex in-line formulas Synopsis: @@ -2979,7 +4000,7 @@ running text. @code{\(...\)} and @code{$...$} are synonyms. @node minipage @section @code{minipage} -@findex minipage @r{environment} +@EnvIndex{minipage} @cindex minipage, creating a @example @@ -3019,7 +4040,7 @@ footnotes; they may wind up at the bottom of the wrong minipage. @node picture @section @code{picture} -@findex picture +@EnvIndex{picture} @cindex creating pictures @cindex pictures, creating @@ -3044,6 +4065,13 @@ You should only change the value of @code{\unitlength}, using the @code{\setlength} command, outside of a @code{picture} environment. The default value is @code{1pt}. +@PkgIndex{picture} +The @code{picture} package redefine the @code{picture} environment so +that everywhere a number is used in a @var{picture commands} to specify +a coordinate, one can use alternatively a length. Be aware however that +this will prevent scaling those lengths by changing @code{\unitlength}. + + @cindex position, in picture A @dfn{position} is a pair of coordinates, such as @code{(2.4,-5)}, specifying the point with x-coordinate @code{2.4} and y-coordinate @code{-5}. @@ -3400,11 +4428,11 @@ values must lie between @minus{}4 and +4, inclusive. @node quotation and quote @section @code{quotation} and @code{quote} -@findex quotation +@EnvIndex{quotation} @cindex quoted text with paragraph indentation, displaying @cindex displaying quoted text with paragraph indentation @cindex paragraph indentations in quoted text -@findex quote +@EnvIndex{quote} @cindex quoted text without paragraph indentation, displaying @cindex displaying quoted text without paragraph indentation @cindex paragraph indentations in quoted text, omitting @@ -3444,7 +4472,7 @@ quotations. @example \begin@{quotation@} \it Four score and seven years ago - .. shall not perish from the earth. + ... shall not perish from the earth. \hspace@{1em plus 1fill@}---Abraham Lincoln \end@{quotation@} @end example @@ -3453,7 +4481,7 @@ quotations. @node tabbing @section @code{tabbing} -@findex tabbing @r{environment} +@EnvIndex{tabbing} @cindex tab stops, using @cindex lining text up using tab stops @cindex alignment via tabbing @@ -3563,7 +4591,7 @@ function \= fact(n : integer) : integer;\\ @node table @section @code{table} -@findex table +@EnvIndex{table} @cindex tables, creating @cindex creating tables @@ -3588,7 +4616,7 @@ float placement algorithm, see @ref{Floats}. The table body is typeset in a @code{parbox} of width @code{\textwidth} and so it can contain text, commands, etc. -The label is optional; it is used for cross-references (@pxref{Cross +The label is optional; it is used for cross references (@pxref{Cross references}). @findex \caption The optional @code{\caption} command specifies caption text for the @@ -3616,7 +4644,7 @@ unless it is pushed to a float page at the end. @node tabular @section @code{tabular} -@findex tabular @r{environment} +@EnvIndex{tabular} @cindex lines in tables @cindex lining text up in tables @@ -3671,7 +4699,7 @@ the width of the @code{tabular*} environment. The space between columns should be rubber, as with @code{@@@{\extracolsep@{\fill@}@}}, to allow the table to stretch or shrink to make the specified width, or else you are likely to get the @code{Underfull \hbox (badness 10000) in alignment -..} warning. +...} warning. @item pos Optional. Specifies the table's vertical position. The default is to @@ -3707,14 +4735,14 @@ This inserts @var{text or space} at this location in every row. The @var{text or space} material is typeset in LR mode. This text is fragile (@pxref{\protect}). -This specifier is optional: unless you put in your own @@-expression -then @LaTeX{}'s book, article, and report classes will put on either -side of each column a space of length @code{\tabcolsep}, which by -default is @samp{6pt}. That is, by default adjacent columns are +This specifier is optional: with no @@-expression, @LaTeX{}'s +@code{book}, @code{article}, and @code{report} classes will put on +either side of each column a space of length @code{\tabcolsep}, which +by default is @samp{6pt}. That is, by default adjacent columns are separated by 12pt (so @code{\tabcolsep} is misleadingly-named since it -is not the separation between tabular columns). Also by default a space -of 6pt comes before the first column as well as after the final column, -unless you put a @code{@@@{..@}} or @code{|} there. +is not the separation between tabular columns). By implication, a +space of 6pt also comes before the first column and after the final +column, unless you put a @code{@@@{...@}} or @code{|} there. If you override the default and use an @@-expression then you must insert any desired space yourself, as in @code{@@@{\hspace@{1em@}@}}. @@ -3726,7 +4754,7 @@ lines need to lie on the left margin. @example \begin@{flushleft@} \begin@{tabular@}@{@@@{@}l@} - .. + ... \end@{tabular@} \end@{flushleft@} @end example @@ -3782,7 +4810,7 @@ Equivalent to @var{num} copies of @var{cols}, where @var{num} is a positive integer and @var{cols} is a list of specifiers. Thus @code{\begin@{tabular@}@{|*@{3@}@{l|r@}|@}} is equivalent to @code{\begin@{tabular@}@{|l|rl|rl|r|@}}. Note that @var{cols} may -contain another @code{*-expression}. +contain another @code{*}-expression. @end table @end table @@ -3849,7 +4877,7 @@ spanned by the single heading @samp{Name}. \begin@{tabular@}@{lccl@} \textit@{ID@} &\multicolumn@{2@}@{c@}@{\textit@{Name@}@} &\textit@{Age@} \\ \hline % row one 978-0-393-03701-2 &O'Brian &Patrick &55 \\ % row two - .. + ... \end@{tabular@} @end example @@ -3863,7 +4891,7 @@ and@tie{}@code{p@{1.5in@}|}. The @var{cols} argument overrides the @code{array} or @code{tabular} environment's intercolumn area default adjoining this multicolumn entry. To affect that area, this argument can contain vertical bars -@code{|} indicating the placement of vertical rules, and @code{@@@{..@}} +@code{|} indicating the placement of vertical rules, and @code{@@@{...@}} expressions. Thus if @var{cols} is @samp{|c|} then this multicolumn entry will be centered and a vertical rule will come in the intercolumn area before it and after it. This table details the exact behavior. @@ -3876,6 +4904,7 @@ area before it and after it. This table details the exact behavior. &z % entry four \end@{tabular@} @end example + Before the first entry the output will not have a vertical rule because the @code{\multicolumn} has the @var{cols} specifier @samp{r} with no initial vertical bar. Between entry one and entry two there will be a @@ -3923,13 +4952,13 @@ vertical bar in the @var{cols} of either of the first row's @subsection @code{\vline} @findex \vline - Draw a vertical line in a @code{tabular} or @code{array} environment -extending the full height and depth of an entry's row. Can also be used -in an @@-expression, although its synonym vertical bar@tie{}@code{|} is -more common. This command is rarely used; typically a table's vertical -lines are specified in @code{tabular}'s @var{cols} argument and -overriden as needed with @code{\multicolumn}. +extending the full height and depth of an entry's row. Can also be +used in an @@-expression, although its synonym vertical +bar@tie{}@code{|} is more common. This command is rarely used in the +body of a table; typically a table's vertical lines are specified in +@code{tabular}'s @var{cols} argument and overridden as needed with +@code{\multicolumn}. This example illustrates some pitfalls. In the first line's second entry the @code{\hfill} moves the @code{\vline} to the left edge of the @@ -4006,7 +5035,7 @@ is required. @node thebibliography @section @code{thebibliography} -@findex thebibliography @r{environment} +@EnvIndex{thebibliography} @cindex bibliography, creating (manually) Synopsis: @@ -4055,18 +5084,19 @@ Synopsis: \bibitem[@var{label}]@{@var{cite_key}@} @end example -The @code{\bibitem} command generates an entry labelled by -@var{label}. If the @var{label} argument is missing, a number is -automatically generated using the @code{enumi} counter. The -@var{cite_key} is any sequence of letters, numbers, and punctuation -symbols not containing a comma. +The @code{\bibitem} command generates an entry labelled by @var{label}. +If the @var{label} argument is missing, a number is automatically +generated using the @code{enumi} counter. The @var{cite_key} is a +@cindex citation key +@dfn{citation key} consisting in any sequence of +letters, numbers, and punctuation symbols not containing a comma. This command writes an entry to the @file{.aux} file containing the -item's @var{cite_key} and label. When the @file{.aux} file is read by -the @code{\begin@{document@}} command, the item's @code{label} is +item's @var{cite_key} and @var{label}. When the @file{.aux} file is +read by the @code{\begin@{document@}} command, the item's @var{label} is associated with @code{cite_key}, causing references to @var{cite_key} -with a @code{\cite} command (see next section) to produce the -associated label. +with a @code{\cite} command (@pxref{\cite}) to produce the associated +@var{label}. @node \cite @@ -4080,14 +5110,14 @@ Synopsis: \cite[@var{subcite}]@{@var{keys}@} @end example -The @var{keys} argument is a list of one or more citation keys, -separated by commas. This command generates an in-text citation to -the references associated with @var{keys} by entries in the -@file{.aux} file. +The @var{keys} argument is a list of one or more citation keys +(@pxref{\bibitem}), separated by commas. This command generates an +in-text citation to the references associated with @var{keys} by entries +in the @file{.aux} file. The text of the optional @var{subcite} argument appears after the citation. For example, @code{\cite[p.~314]@{knuth@}} might produce -`[Knuth, p.@tie{}314]'. +@samp{[Knuth, p.@tie{}314]}. @node \nocite @@ -4095,7 +5125,11 @@ citation. For example, @code{\cite[p.~314]@{knuth@}} might produce @findex \nocite +Synopsis: + +@example @code{\nocite@{@var{keys}@}} +@end example The @code{\nocite} command produces no text, but writes @var{keys}, which is a list of one or more citation keys, to the @file{.aux} file. @@ -4125,7 +5159,7 @@ The @code{\bibliographystyle} command does not produce any output of its own. Rather, it defines the style in which the bibliography will be produced: @var{bibstyle} refers to a file @var{bibstyle}@file{.bst}, which defines how your citations will look. -The standard @var{style} names distributed with Bib@TeX{} are: +The standard @var{bibstyle} names distributed with Bib@TeX{} are: @table @code @item alpha @@ -4145,7 +5179,8 @@ the demands of various publications. See The @code{\bibliography} command is what actually produces the bibliography. The argument to @code{\bibliography} refers to files -named @file{@var{bibfile}.bib}, which should contain your database in +named @file{@var{bibfile1}.bib}, @file{@var{bibfile2}.bib}, @dots{}, +which should contain your database in Bib@TeX{} format. Only the entries referred to via @code{\cite} and @code{\nocite} will be listed in the bibliography. @@ -4153,7 +5188,7 @@ Bib@TeX{} format. Only the entries referred to via @code{\cite} and @node theorem @section @code{theorem} -@findex theorem @r{environment} +@EnvIndex{theorem} @cindex theorems, typesetting Synopsis: @@ -4173,7 +5208,7 @@ possibilities for @var{n} are described under @code{\newtheorem} @node titlepage @section @code{titlepage} -@findex titlepage @r{environment} +@EnvIndex{titlepage} @cindex making a title page @cindex title pages, creating @@ -4181,24 +5216,47 @@ Synopsis: @example \begin@{titlepage@} -@var{text} + ... text and spacing ... \end@{titlepage@} @end example -The @code{titlepage} environment creates a title page, i.e., a page -with no printed page number or heading. It also causes the following -page to be numbered page one. Formatting the title page is left to -you. The @code{\today} command may be useful on title pages -(@pxref{\today}). +Create a title page, a page with no printed page number or heading. The +following page will be numbered page one. -You can use the @code{\maketitle} command (@pxref{\maketitle}) to -produce a standard title page without a @code{titlepage} environment. +To instead produce a standard title page without a @code{titlepage} +environment you can use @code{\maketitle} (@pxref{\maketitle}). + +Notice in this example that all formatting, including vertical spacing, +is left to the author. + +@example +\begin@{titlepage@} +\vspace*@{\stretch@{1@}@} +\begin@{center@} + @{\huge\bfseries Thesis \\[1ex] + title@} \\[6.5ex] + @{\large\bfseries Author name@} \\ + \vspace@{4ex@} + Thesis submitted to \\[5pt] + \textit@{University name@} \\[2cm] + in partial fulfilment for the award of the degree of \\[2cm] + \textsc@{\Large Doctor of Philosophy@} \\[2ex] + \textsc@{\large Mathematics@} \\[12ex] + \vfill + Department of Mathematics \\ + Address \\ + \vfill + \today +\end@{center@} +\vspace@{\stretch@{2@}@} +\end@{titlepage@} +@end example @node verbatim @section @code{verbatim} -@findex verbatim @r{environment} +@EnvIndex{verbatim} @cindex verbatim text @cindex simulating typed text @cindex typed text, simulating @@ -4255,7 +5313,7 @@ The @code{*}-form differs only in that spaces are printed with a @node verse @section @code{verse} -@findex verse @r{environment} +@EnvIndex{verse} @cindex poetry, an environment for Synopsis: @@ -4297,6 +5355,7 @@ you but in some environments you manually force line breaks. * \obeycr & \restorecr:: Make each input line start a new output line. * \newline:: Break the line * \- (hyphenation):: Insert explicit hyphenation. +* \discretionary:: Insert explicit hyphenation with control of hyphen character. * \fussy:: Be fussy about line breaking. * \sloppy:: Be sloppy about line breaking. * \hyphenation:: Tell @LaTeX{} how to hyphenate a word. @@ -4333,7 +5392,7 @@ particular, to start a new paragraph instead leave a blank line. This command is mostly used outside of the main flow of text such as in a @code{tabular} or @code{array} environment. -Under ordinary circumstances (e.g., outside of a @code{p@{..@}} column +Under ordinary circumstances (e.g., outside of a @code{p@{...@}} column in a @code{tabular} environment) the @code{\newline} command is a synonym for @code{\\} (@pxref{\newline}). @@ -4372,7 +5431,7 @@ In ordinary text this is equivalent to double-backslash (@pxref{\\}); it breaks a line, with no stretching of the text before it. Inside a @code{tabular} or @code{array} environment, in a column with a -specifier producing a paragraph box, like typically @code{p@{..@}}, +specifier producing a paragraph box, like typically @code{p@{...@}}, @code{\newline} will insert a line break inside of the column, that is, it does not break the entire row. To break the entire row use @code{\\} or its equivalent @code{\tabularnewline}. @@ -4405,6 +5464,18 @@ When you insert @code{\-} commands in a word, the word will only be hyphenated at those points and not at any of the hyphenation points that @LaTeX{} might otherwise have chosen. +@node \discretionary +@section @code{\discretionary} (generalized hyphenation point) +@cindex hyphenation, discretionary +@cindex discretionary hyphenation + +Synopsis: + +@example +\discretionary@{@var{pre-break-text}@}@{@var{post-break-text}@}@{@var{no-break-text}@} +@end example + +@c xxx TODO, complete this node, see LaTeX-fr @node \fussy @section @code{\fussy} @@ -4416,7 +5487,7 @@ picky about line breaking. This usually avoids too much space between words, at the cost of an occasional overfull box. This command cancels the effect of a previous @code{\sloppy} command -(@pxref{\sloppy}. +(@pxref{\sloppy}). @node \sloppy @@ -4744,7 +5815,8 @@ but nothing is set at the bottom of the page. \textit@{HMS Sophie@} &Master and Commander \\ \textit@{HMS Polychrest@} &Post Captain \\ \textit@{HMS Lively@} &Post Captain \\ - \textit@{HMS Surprise@} &A number of books\footnote@{Starting with HMS Surprise.@} + \textit@{HMS Surprise@} &A number of books\footnote@{Starting with + HMS Surprise.@} \end@{tabular@} \end@{center@} @end example @@ -4755,7 +5827,7 @@ The solution is to surround the @code{tabular} environment with a @example \begin@{center@} \begin@{minipage@}@{.5\textwidth@} - .. tabular material .. + ... tabular material ... \end@{minipage@} \end@{center@} @end example @@ -4784,26 +5856,32 @@ sequence with other footnotes. @node Footnotes in section headings @section Footnotes in section headings -Putting a footnote in a section heading +@cindex footnotes, in section headings +@cindex table of contents, avoiding footnotes +Putting a footnote in a section heading, as in: @example -\section@{Full sets\protect\footnote@{This material is due to R~Jones.@}@} +\section@{Full sets\protect\footnote@{This material due to ...@}@} @end example -causes the footnote to appear both at the bottom of the page where the -section starts and at the bottom of the table of contents page. To have -it not appear on the table of contents use the package @file{footmisc} -with the @code{stable} option. +@PkgIndex{footmisc} +@cindex @code{stable} option to @code{footmisc} package +@noindent +causes the footnote to appear at the bottom of the page where the +section starts, as usual, but also at the bottom of the table of +contents, where it is not likely to be desired. To have it not appear +on the table of contents use the package @file{footmisc} with the +@code{stable} option. @example \usepackage[stable]@{footmisc@} - .. +... \begin@{document@} - .. -\section@{Full sets\footnote@{This material is due to R~Jones.@}@} +... +\section@{Full sets\footnote@{This material due to ...@}@} @end example -Note that the @code{\protect} is gone; putting it in causes the +Note that the @code{\protect} is gone; including it would cause the footnote to reappear on the table of contents. @@ -4819,12 +5897,12 @@ ways, including allow these two, as in this example. \usepackage@{bigfoot@} \DeclareNewFootnote@{Default@} \DeclareNewFootnote@{from@}[alph] % create class \footnotefrom@{@} - .. + ... \begin@{document@} - .. +... The third theorem is a partial converse of the second.\footnotefrom@{First noted in Wilson.\footnote@{Second edition only.@}@} - .. +... @end example @@ -4838,13 +5916,13 @@ uses the package @file{cleverref}. @example \usepackage@{cleveref@}[2012/02/15] % this version of package or later \crefformat@{footnote@}@{#2\footnotemark[#1]#3@} - .. +... \begin@{document@} - .. +... The theorem is from Evers.\footnote@{\label@{fn:TE@}Tinker and Evers, 1994.@} The corollary is from Chance.\footnote@{Evers and Chance, 1990.@} But the key lemma is from Tinker.\cref@{fn:TE@} - .. +... @end example This solution will work with the package @file{hyperref}. @@ -4883,6 +5961,7 @@ footnotes. This is @samp{6.65pt} for @samp{10pt}, @samp{7.7pt} for @LaTeX{} has support for making new commands of many different kinds. @c xx everything in this chapter needs examples. +@c xx Add DeclareRobustCommand (see clsguide.pdf) @menu * \newcommand & \renewcommand:: (Re)define a new command. @@ -4910,80 +5989,85 @@ footnotes. This is @samp{6.65pt} for @samp{10pt}, @samp{7.7pt} for command, respectively. Synopses: @example - \newcommand@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} - \newcommand*@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} -\renewcommand@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} -\renewcommand*@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} + \newcommand@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} + \newcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +\renewcommand@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} +\renewcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@} @end example -The @code{*}-form of these two commands requires that the arguments -not contain multiple paragraphs of text (not @code{\long}, in plain -@TeX{} terms). +@cindex starred form, defining new commands +@cindex *-form, defining new commands +The starred form of these two commands requires that the arguments not +contain multiple paragraphs of text (not @code{\long}, in plain @TeX{} +terms). @table @var @item cmd -Required; the command name. It must begin with @code{\}. For -@code{\newcommand}, it must not be already defined and must not begin -with @code{\end}. For @code{\renewcommand}, it must already be -defined. +Required; @code{\@var{cmd}} is the command name. For @code{\newcommand}, it +must not be already defined and must not begin with @code{\end}. For +@code{\renewcommand}, it must already be defined. @item nargs Optional; an integer from 0 to 9, specifying the number of arguments -that the command will take. If this argument is not present, the -default is for the command to have no arguments. When redefining a -command, the new version can have a different number of arguments than -the old version. +that the command can take, including any optional argument. If this +argument is not present, the default is for the command to have no +arguments. When redefining a command, the new version can have a +different number of arguments than the old version. @item optargdefault Optional; if this argument is present then the first argument of defined -command @var{\cmd} is optional, with default value @var{optargdefault} +command @code{\@var{cmd}} is optional, with default value @var{optargdefault} (which may be the empty string). If this argument is not present then -@var{\cmd} does not take an optional argument. - -That is, if @var{\cmd} is used with square brackets following, as in -@code{\@var{cmd}[@var{myval}]}, then within @var{defn} @code{#1} expands -@var{myval}. While if @var{\cmd} is called without square brackets -following, then within @var{defn} the @code{#1} expands to the default -@var{optargdefault}. In either case, any required arguments will be -referred to starting with @code{#2}. - -Omitting @code{[@var{myval}]} in the call is different from having the +@code{\@var{cmd}} does not take an optional argument. + +@cindex positional parameter +That is, if @code{\@var{cmd}} is used with square brackets following, +as in @code{\@var{cmd}[@var{myval}]}, then within @var{defn} the first +@dfn{positional parameter} @code{#1} expands @var{myval}. On the +other hand, if @code{\@var{cmd}} is called without square brackets +following, then within @var{defn} the positional parameter @code{#1} +expands to the default @var{optargdefault}. In either case, any +required arguments will be referred to starting with @code{#2}. + +Omitting @code{[@var{myval}]} in a call is different from having the square brackets with no contents, as in @code{[]}. The former results in @code{#1} expanding to @var{optargdefault}; the latter results in @code{#1} expanding to the empty string. @item defn -The text to be substituted for every occurrence of @code{cmd}; a -construct of the form @code{#@var{n}} in @var{defn} is replaced by the -text of the @var{n}th argument. +The text to be substituted for every occurrence of @code{\@var{cmd}}; the +positional parameter @code{#@var{n}} in @var{defn} is replaced by +the text of the @var{n}th argument. @end table -A command with no arguments that is followed in the source by a space -will swallow that space. The solution is to type @code{@{@}} after the -command and before the space. +@TeX{} ignores spaces in the source following an alphabetic control +sequence, as in @samp{\cmd }. If you actually want a space there, one +solution is to type @code{@{@}} after the command (@samp{\cmd@{@} }; +another solution is to use an explicit control space (@samp{\cmd\ }). A simple example of defining a new command: -@code{\newcommand@{\JH@}@{Jim Hef@{@}feron@}} causes the abbreviation -@code{\JH} to be replaced by the longer text. +@code{\newcommand@{\RS@}@{Robin Smith@}} results in +@code{\RS} being replaced by the longer text. -Redefining a command is basically the same: +Redefining an existing command is similar: @code{\renewcommand@{\qedsymbol@}@{@{\small QED@}@}}. -Here's a command definition that uses arguments: +Here's a command definition with one required argument: @example -\newcommand@{\defreference@}[1]@{Definition~\ref@{#1@}@} +\newcommand@{\defref@}[1]@{Definition~\ref@{#1@}@} @end example -@noindent Then, @code{\defreference@{def:basis@}} will expand to +@noindent Then, @code{\defref@{def:basis@}} expands to +@code{Definition~\ref@{def:basis@}}, which will ultimately expand to something like @samp{Definition~3.14}. -An example with two arguments: -@code{\newcommand@{\nbym@}[2]@{#1\!\times\!#2@}} is invoked as +An example with two required arguments: +@code{\newcommand@{\nbym@}[2]@{$#1 \times #2$@}} is invoked as @code{\nbym@{2@}@{k@}}. -An example with optional arguments: +An example with an optional argument: @example \newcommand@{\salutation@}[1][Sir or Madam]@{Dear #1:@} @@ -4993,17 +6077,19 @@ An example with optional arguments: @code{\salutation[John]} gives @samp{Dear John:}. And @code{\salutation[]} gives @samp{Dear :}. -The braces around @var{defn} do not delimit the scope of the result of -expanding @var{defn}. So @code{\newcommand@{\shipname@}[1]@{\it #1@}} -is wrong since in the sentence +The braces around @var{defn} do not define a group, that is, they do +not delimit the scope of the result of expanding @var{defn}. So +@code{\newcommand@{\shipname@}[1]@{\it #1@}} is problematic; in this +sentence, @example -The \shipname@{Monitor@} met the \shipname@{Virginia@}. +The \shipname@{Monitor@} met the \shipname@{Merrimac@}. @end example -@noindent the words @samp{met the} will incorrectly be in italics. An -extra pair of braces @code{\newcommand@{\shipname@}[1]@{@{\it #1@}@}} -fixes it. +@noindent the words @samp{met the} would incorrectly be in italics. Another +pair of braces in the definition is needed, like this: +@code{\newcommand@{\shipname@}[1]@{@{\it #1@}@}}. Those braces are +part of the definition and thus do define a group. @node \providecommand @@ -5035,21 +6121,24 @@ loaded more than once. @findex \newcounter @cindex counters, defining new -Synopsis: +Synopsis, one of: @example +\newcounter@{@var{countername}@} \newcounter@{@var{countername}@}[@var{supercounter}] @end example -The @code{\newcounter} command globally defines a new counter named -@var{countername}. The name consists of letters only and does not begin -with a backslash (@samp{\}). The name must not already be used by -another counter. The new counter is initialized to zero. +Globally defines a new counter named @var{countername} and initialize +the new counter to zero. + +The name @var{countername} must consists of letters only, and does not +begin with a backslash. This name must not already be in use by another +counter. -If the optional argument @code{[@var{supercounter}]} appears, then +When you use the optional argument @code{[@var{supercounter}]} then @var{countername} will be numbered within, or subsidiary to, the existing counter @var{supercounter}. For example, ordinarily -@code{subsection} is numbered within @code{section}. Any time +@code{subsection} is numbered within @code{section} so that any time @var{supercounter} is incremented with @code{\stepcounter} (@pxref{\stepcounter}) or @code{\refstepcounter} (@pxref{\refstepcounter}) then @var{countername} is reset to zero. @@ -5114,22 +6203,24 @@ The allocation of a box is global. This command is fragile @cindex redefining environments These commands define or redefine an environment @var{env}, that is, -@code{\begin@{@var{env}@} @dots{} \end@{@var{env}@}}. Synopses: +@code{\begin@{@var{env}@} @var{body} \end@{@var{env}@}}. Synopses: @example - \newenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdefn}@}@{@var{enddefn}@} + \newenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdefn}@}@{@var{enddefn}@} \newenvironment*@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdefn}@}@{@var{enddefn}@} -\renewenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdefn}@}@{@var{enddefn}@} + \renewenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdefn}@}@{@var{enddefn}@} \renewenvironment*@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdefn}@}@{@var{enddefn}@} @end example -Unlike @code{\newcommand} and @code{\renewcommand}, the @code{*}-forms -@code{\newenvironment*} and @code{\renewcommand*} have the same effect -as the forms with no @code{*}. +@cindex @code{*}-form of environment commands +The starred form of these commands requires that the arguments not +contain multiple paragraphs of text. The body of these environments can +still contain multiple paragraphs. @table @var @item env -Required; the environment name. It does not begin with backslash +Required; the environment name. It consists only of letters or the +@code{*} character, and thus does not begin with backslash (@code{\}). It must not begin with the string @code{end}. For @code{\newenvironment}, the name @var{env} must not be the name of an already existing environment, and also the command @code{\@var{env}} @@ -5138,8 +6229,8 @@ name of an existing environment. @item nargs Optional; an integer from 0 to 9 denoting the number of arguments of -that the environment will take. These arguments appear after the -@code{\begin}, as in +that the environment will take. When the environment is used these +arguments appear after the @code{\begin}, as in @code{\begin@{@var{env}@}@{@var{arg1}@}@dots{}@{@var{argn}@}}. If this argument is not present then the default is for the environment to have no arguments. When redefining an environment, the new version can have @@ -5151,15 +6242,15 @@ defined environment is optional, with default value @var{optargdefault} (which may be the empty string). If this argument is not present then the environment does not take an optional argument. -That is, when @code{[@var{optargdefault}]} is present in the environment -definition, if @code{\begin@{@var{env}@}} is used with square brackets -following, as in @code{\begin@{@var{env}@}[@var{myval}]}, then within -the environment @code{#1} expands @var{myval}. If -@code{\begin@{@var{env}@}} is called without square brackets following, -then within the environment the @code{#1} expands to the default -@var{optargdefault}. In either case, any required arguments will be -referred to starting with @code{#2}. - +That is, when @code{[@var{optargdefault}]} is present in the +environment definition, if @code{\begin@{@var{env}@}} is used with +square brackets following, as in +@code{\begin@{@var{env}@}[@var{myval}]}, then, within @var{begdefn}, +the positional parameter @code{#1} expands to @var{myval}. If +@code{\begin@{@var{env}@}} is called without square brackets +following, then, within within @var{begdefn}, the positional parameter +@code{#1} expands to the default @var{optargdefault}. In either case, +any required arguments will be referred to starting with @code{#2}. Omitting @code{[@var{myval}]} in the call is different from having the square brackets with no contents, as in @code{[]}. The former results @@ -5168,23 +6259,25 @@ in @code{#1} expanding to @var{optargdefault}; the latter results in @item begdefn Required; the text expanded at every occurrence of -@code{\begin@{@var{env}@}}; a construct of the form @code{#@var{n}} in -@var{begdef} is replaced by the text of the @var{n}th argument. +@code{\begin@{@var{env}@}}. Within @var{begdef}, the @var{n}th +positional parameter (i.e., @code{#@var{n}}) is replaced by the text +of the @var{n}th argument. @item enddefn Required; the text expanded at every occurrence of -@code{\end@{@var{env}@}}. Note that it may not contain any argument -parameters, so @code{#@var{n}} cannot be used here. +@code{\end@{@var{env}@}}. This may not contain any positional +parameters, so @code{#@var{n}} cannot be used here (but see the final +example below). @end table -The environment @var{env} delimits the scope of the result of expanding -@var{begdefn} and @var{enddefn}. Thus, in the first example below, the -effect of the @code{\small} is limited to the quote and does not extend -to material following the environment. +All environments, that is to say the @var{begdefn} code, the environment +body and the @var{enddefn} code, are processed within a group. Thus, in +the first example below, the effect of the @code{\small} is limited to +the quote and does not extend to material following the environment. -This example gives an environment like @LaTeX{}'s @code{quotation} except that -it will be set in smaller type. +This example gives an environment like @LaTeX{}'s @code{quotation} +except that it will be set in smaller type: @example \newenvironment@{smallquote@}@{% @@ -5194,8 +6287,8 @@ it will be set in smaller type. @} @end example -This shows the use of arguments; it gives a quotation environment that -cites the author. +This one shows the use of arguments; it gives a quotation environment +that cites the author: @example \newenvironment@{citequote@}[1][Shakespeare]@{% @@ -5206,17 +6299,17 @@ cites the author. @} @end example -@noindent The author's name is optional, and defaults to Shakespeare. -In the document, use the environment as here: +@noindent The author's name is optional, and defaults to @samp{Shakespeare}. +In the document, use the environment like this: @example \begin@{citequote@}[Lincoln] - .. + ... \end@{citequote@} @end example The final example shows how to save the value of an argument to use in -@var{enddefn}. +@var{enddefn}, in this case in a box (@pxref{\sbox}): @example \newsavebox@{\quoteauthor@} @@ -5239,42 +6332,38 @@ The final example shows how to save the value of an argument to use in @cindex theorem-like environment @cindex environment, theorem-like -Define a new @dfn{theorem-like environment}. Synopses: +Define a new theorem-like environment. Synopses: @example +\newtheorem@{@var{name}@}@{@var{title}@} \newtheorem@{@var{name}@}@{@var{title}@}[@var{numbered_within}] \newtheorem@{@var{name}@}[@var{numbered_like}]@{@var{title}@} @end example -Both create a theorem-like environment @var{name}. Using the first -form, - -@example -\newtheorem@{@var{name}@}@{@var{title}@}[@var{numbered_within}] -@end example +Using the first form, @code{\newtheorem@{@var{name}@}@{@var{title}@}} +creates an environment that will be labelled with @var{title}. See the +first example below. -@noindent with the optional argument after the second required argument, +The second form +@code{\newtheorem@{@var{name}@}@{@var{title}@}[@var{numbered_within}]} creates an environment whose counter is subordinate to the existing -counter @var{numbered_within}: it will be reset when +counter @var{numbered_within} (its counter will be reset when @var{numbered_within} is reset). -Using the second form, -@example -\newtheorem@{@var{name}@}[@var{numbered_like}]@{@var{title}@} -@end example - -@noindent with the optional argument between the two required -arguments, will create an environment whose counter will share the -previously defined counter @var{numbered_like}. +The third form +@code{\newtheorem@{@var{name}@}[@var{numbered_like}]@{@var{title}@}}, +with optional argument between the two required arguments, will create +an environment whose counter will share the previously defined counter +@var{numbered_like}. You can specify one of @var{numbered_within} and @var{numbered_like}, or neither, but not both. This command creates a counter named @var{name}. In addition, unless -the optional argument @var{numbered_like} is used, the current -@code{\ref} value will be that of @code{\the@var{numbered_within}} -(@pxref{\ref}). +the optional argument @var{numbered_like} is used, inside of the +theorem-like environment the current @code{\ref} value will be that of +@code{\the@var{numbered_within}} (@pxref{\ref}). This declaration is global. It is fragile (@pxref{\protect}). @@ -5306,8 +6395,9 @@ new environment will be numbered in sequence with @var{numbered_like}. @end table Without any optional arguments the environments are numbered -sequentially. This example has a declaration in the preamble that -results in @samp{Definition@tie{}1} and @samp{Definition@tie{}2} in the output. +sequentially. The example below has a declaration in the preamble that +results in @samp{Definition@tie{}1} and @samp{Definition@tie{}2} in the +output. @example \newtheorem@{defn@}@{Definition@} @@ -5323,7 +6413,7 @@ results in @samp{Definition@tie{}1} and @samp{Definition@tie{}2} in the output. \end@{defn@} @end example -Because this example specifies the optional argument +Because the next example specifies the optional argument @var{numbered_within} to @code{\newtheorem} as @code{section}, the example, with the same document body, gives @samp{Definition@tie{}1.1} and @samp{Definition@tie{}2.1}. @@ -5342,8 +6432,8 @@ and @samp{Definition@tie{}2.1}. \end@{defn@} @end example -In this example there are two declarations in the preamble, the second -of which calls for the new @code{thm} environment to use the same +In the next example there are two declarations in the preamble, the +second of which calls for the new @code{thm} environment to use the same counter as @code{defn}. It gives @samp{Definition@tie{}1.1}, followed by @samp{Theorem@tie{}2.1} and @samp{Definition@tie{}2.2}. @@ -5410,7 +6500,7 @@ characters in each: @example \newfont@{\testfontat@}@{cmb10 at 11pt@} -\newfont@{\testfontscaled@}@{cmb10 scaled 11pt@} +\newfont@{\testfontscaled@}@{cmb10 scaled 1100@} \testfontat abc \testfontscaled abc @end example @@ -5422,23 +6512,28 @@ characters in each: @findex \protect @cindex fragile commands @cindex robust commands -@cindex moving arguments -All @LaTeX{} commands are either @dfn{fragile} or @dfn{robust}. -Footnotes, line breaks, any command that has an optional argument, and -many more, are fragile. A fragile command can break when it is used in -the argument to certain commands. To prevent such commands from -breaking they must be preceded by the command @code{\protect}. +All @LaTeX{} commands are either @dfn{fragile} or @dfn{robust}. A +fragile command can break when it is used in the argument to certain +other commands. Commands that contain data that @LaTeX{} writes to an +auxiliary file and re-reads later are fragile. This includes material +that goes into a table of contents, list of figures, list of tables, +etc. Fragile commands also include line breaks, any command that has an +optional argument, and many more. To prevent such commands from +breaking, one solution is to preceded them with the command +@code{\protect}. For example, when @LaTeX{} runs the @code{\section@{@var{section name}@}} command it writes the @var{section name} text to the @file{.aux} auxiliary file, moving it there for use elsewhere in the document such as in the table of contents. Any argument that is internally expanded by @LaTeX{} without typesetting it directly is -referred to as a @dfn{moving argument}. A command is fragile if it can +referred to as a +@cindex moving arguments +@dfn{moving argument}. A command is fragile if it can expand during this process into invalid @TeX{} code. Some examples of -moving arguments are those that appear in the @code{\caption@{..@}} -command (@pxref{figure}), in the @code{\thanks@{..@}} command +moving arguments are those that appear in the @code{\caption@{...@}} +command (@pxref{figure}), in the @code{\thanks@{...@}} command (@pxref{\maketitle}), and in @@-expressions in the @code{tabular} and @code{array} environments (@pxref{tabular}). @@ -5451,13 +6546,13 @@ commands are robust and should not be preceded by a @code{\protect} command. Nor can a @code{\protect} command be used in the argument to @code{\addtocounter} or @code{\setcounter} command. -In this example the @code{caption} command gives a mysterious error +In this example the @code{\caption} command gives a mysterious error about an extra curly brace. Fix the problem by preceding each @code{\raisebox} command with @code{\protect}. @example \begin@{figure@} - .. + ... \caption@{Company headquarters of A\raisebox@{1pt@}@{B@}\raisebox@{-1pt@}@{C@}@} \end@{figure@} @end example @@ -5470,9 +6565,9 @@ to @code{\protect\(..\protect\)}. @example \begin@{document@} \tableofcontents - .. +... \section@{Einstein's \( e=mc^2 \)@} - .. +... @end example @@ -5484,11 +6579,13 @@ to @code{\protect\(..\protect\)}. Everything @LaTeX{} numbers for you has a counter associated with it. The name of the counter is often the same as the name of the -environment or command associated with the number, except with no -backslash (@code{\}). Thus the @code{\chapter} command starts a -chapter and the @code{chapter} counter keeps track of the chapter -number. Below is a list of the counters used in @LaTeX{}'s standard -document classes to control numbering. +environment or command associated with the number, except that the +counter's name has no backslash@tie{}@code{\}. Thus, associated with +the @code{\chapter} command is the @code{chapter} counter that keeps +track of the chapter number. + +Below is a list of the counters used in @LaTeX{}'s standard document +classes to control numbering. @example part paragraph figure enumi @@ -5499,24 +6596,22 @@ subsubsection @end example The @code{mpfootnote} counter is used by the @code{\footnote} command -inside of a minipage (@pxref{minipage}). - -The @code{enumi} through @code{enumiv} counters are used in the -@code{enumerate} environment, for up to four nested levels -(@pxref{enumerate}). +inside of a minipage (@pxref{minipage}). The counters @code{enumi} +through @code{enumiv} are used in the @code{enumerate} environment, for +up to four levels of nesting (@pxref{enumerate}). New counters are created with @code{\newcounter}. @xref{\newcounter}. @menu -* \alph \Alph \arabic \roman \Roman \fnsymbol:: Print value of a counter. -* \usecounter:: Use a specified counter in a list environment. -* \value:: Use the value of a counter in an expression. -* \setcounter:: Set the value of a counter. -* \addtocounter:: Add a quantity to a counter. -* \refstepcounter:: Add to counter, resetting subsidiary counters. -* \stepcounter:: Add to counter, resetting subsidiary counters. -* \day \month \year:: Numeric date values. +* \alph \Alph \arabic \roman \Roman \fnsymbol:: Print value of a counter. +* \usecounter:: Use a specified counter in a list environment. +* \value:: Use the value of a counter in an expression. +* \setcounter:: Set the value of a counter. +* \addtocounter:: Add a quantity to a counter. +* \refstepcounter:: Add to a counter. +* \stepcounter:: Add to a counter, resetting subsidiary counters. +* \day \month \year:: Numeric date values. @end menu @@ -5525,38 +6620,59 @@ New counters are created with @code{\newcounter}. @xref{\newcounter}. @cindex counters, printing +Print the value of a counter, in a specified style. For instance, if +the counter @var{counter} has the value 1 then a +@code{\alph@{@var{counter}@}} in your source will result in a lower case +letter@tie{}a appearing in the output. + All of these commands take a single counter as an argument, for instance, @code{\alph@{enumi@}}. Note that the counter name does not start with a backslash. @ftable @code -@item \alph -prints @var{counter} using lowercase letters: `a', `b', @enddots{} +@item \alph@{@var{counter}@} +Print the value of @var{counter} in lowercase letters: `a', `b', @enddots{} -@item \Alph -uses uppercase letters: `A', `B', @enddots{} +@item \Alph@{@var{counter}@} +Print in uppercase letters: `A', `B', @enddots{} -@item \arabic -uses Arabic numbers: `1', `2', @enddots{} +@item \arabic@{@var{counter}@} +Print in Arabic numbers: `1', `2', @enddots{} -@item \roman -uses lowercase roman numerals: `i', `ii', @enddots{} +@item \roman@{@var{counter}@} +Print in lowercase roman numerals: `i', `ii', @enddots{} -@item \Roman -uses uppercase roman numerals: `I', `II', @enddots{} +@item \Roman@{@var{counter}@} +Print in uppercase roman numerals: `I', `II', @enddots{} -@item \fnsymbol -prints the value of @var{counter} in a specific sequence of nine +@item \fnsymbol@{@var{counter}@} +Prints the value of @var{counter} in a specific sequence of nine symbols (conventionally used for labeling footnotes). The value of @var{counter} must be between@tie{}1 and@tie{}9, inclusive. -Here are the symbols (as Unicode code points in ASCII output): +Here are the symbols: -@display -asterisk(*) dagger(@U{2021}) ddagger(@U{2021}) -section-sign(@U{00A7}) paragraph-sign(@U{00B6}) parallel(@U{2225}) -double-asterisk(**) double-dagger(@U{2020}@U{2020}) double-ddagger(@U{2021}@U{2021}) -@end display +@multitable @columnfractions .33 .33 .33 +@headitem Name@tab Command@tab@iftexthenelse{Symbol,Equivalent Unicode symbol and/or numeric code point} +@item +asterisk@tab@code{\ast}@tab@iftexthenelse{@math{@ast},*} +@item +dagger@tab@code{\dagger}@tab@BES{2020,\dagger} +@item +ddagger@tab@code{\ddagger}@tab@BES{2021,\ddagger} +@item +section-sign@tab@code{\S}@tab@BES{00A7,\S} +@item +paragraph-sign@tab@code{\P}@tab@BES{00B6,\P} +@item +double-vert@tab@code{\parallel}@tab@BES{2016,\parallel} +@item +double-asterisk@tab@code{\ast\ast}@tab@iftexthenelse{@math{@ast@ast},**} +@item +double-dagger@tab@code{\dagger\dagger}@tab@BES{2020,\dagger}@BES{2020,\dagger} +@item +double-ddagger@tab@code{\ddagger\ddagger}@tab@BES{2021,\ddagger}@BES{2021,\ddagger} +@end multitable @end ftable @@ -5653,6 +6769,13 @@ The @code{\setcounter} command globally sets the value of @var{counter} to the @var{value} argument. Note that the counter name does not start with a backslash. +In this example the section value appears as @samp{V}. + +@example +\setcounter@{section@}@{5@} +Here it is in Roman: \Roman@{section@}. +@end example + @node \addtocounter @section @code{\addtocounter@{@var{counter}@}@{@var{value}@}} @@ -5662,6 +6785,14 @@ with a backslash. The @code{\addtocounter} command globally increments @var{counter} by the amount specified by the @var{value} argument, which may be negative. +In this example the section value appears as @samp{VII}. + +@example +\setcounter@{section@}@{5@} +\addtocounter@{section@}@{2@} +Here it is in Roman: \Roman@{section@}. +@end example + @node \refstepcounter @section @code{\refstepcounter@{@var{counter}@}} @@ -5835,26 +6966,40 @@ math symbols family. @xref{Spacing in math mode}. @node \setlength -@section @code{\setlength@{\@var{len}@}@{@var{value}@}} +@section @code{\setlength} @findex \setlength @cindex lengths, setting -The @code{\setlength} sets the value of @var{\len} to the @var{value} -argument, which can be expressed in any units that @LaTeX{} -understands, i.e., inches (@code{in}), millimeters (@code{mm}), points -(@code{pt}), big points (@code{bp}, etc. +Synopsis: + +@example +\setlength@{@var{\len}@}@{@var{amount}@} +@end example + +The @code{\setlength} sets the value of @dfn{length command} +@cindex length command +@code{\@var{len}} to the @var{value} argument which can be expressed in any +units that @LaTeX{} understands, i.e., inches (@code{in}), millimeters +(@code{mm}), points (@code{pt}), big points (@code{bp}), etc. @node \addtolength -@section @code{\addtolength@{@var{\len}@}@{@var{amount}@}} +@section @code{\addtolength} @findex \addtolength @cindex lengths, adding to -The @code{\addtolength} command increments a ``length command'' -@var{\len} by the amount specified in the @var{amount} argument, which -may be negative. +Synopsis: + +@example +\addtolength@{@var{\len}@}@{@var{amount}@} +@end example + + +The @code{\addtolength} command increments a length command @code{\@var{len}} +by the amount specified in the @var{amount} argument, which may be +negative. @node \settodepth @@ -5862,10 +7007,14 @@ may be negative. @findex \settodepth -@code{\settodepth@{\gnat@}@{text@}} +Synopsis: + +@example +\settodepth@{\@var{len}@}@{@var{text}@} +@end example -The @code{\settodepth} command sets the value of a @code{length} command -equal to the depth of the @code{text} argument. +The @code{\settodepth} command sets the value of a length command +@code{\@var{len}} equal to the depth of the @var{text} argument. @node \settoheight @@ -5873,9 +7022,13 @@ equal to the depth of the @code{text} argument. @findex \settoheight -@code{\settoheight@{\gnat@}@{text@}} +Synopsis: + +@example +\settoheight@{\@var{len}@}@{text@} +@end example -The @code{\settoheight} command sets the value of a @code{length} command +The @code{\settoheight} command sets the value of a length command @code{\@var{len}} equal to the height of the @code{text} argument. @@ -5885,6 +7038,12 @@ equal to the height of the @code{text} argument. @findex \settowidth +Synopsis: + +@example +\settowidth@{\@var{len}@}@{@var{text}@} +@end example + The @code{\settowidth} command sets the value of the command @var{\len} to the width of the @var{text} argument. @@ -5909,11 +7068,13 @@ to the width of the @var{text} argument. These length parameters can be used in the arguments of the box-making commands (@pxref{Boxes}). They specify the natural width, etc., of -the text in the box. @code{\totalheight} equals @code{\height} + -@code{\depth}. To make a box with the text stretched to double the +the text in the box. @code{\totalheight} equals @math{@code{@backslashchar{}height} + +@code{@backslashchar{}depth}}. To make a box with the text stretched to double the natural size, e.g., say -@code{\makebox[2\width]@{Get a stretcher@}} +@example +\makebox[2\width]@{Get a stretcher@} +@end example @node Making paragraphs @@ -5961,7 +7122,7 @@ When used at the beginning of the paragraph, this command suppresses any paragraph indentation, as in this example. @example -.. end of the prior paragraph. +... end of the prior paragraph. \noindent This paragraph is not indented. @end example @@ -6056,9 +7217,9 @@ notes from falling off the bottom of the page. @cindex math formulas @cindex formulas, math @cindex math mode, entering -@findex math @r{environment} -@findex displaymath @r{environment} -@findex equation @r{environment} +@EnvIndex{math} +@EnvIndex{displaymath} +@EnvIndex{equation} There are three environments that put @LaTeX{} in math mode: @@ -6133,7 +7294,7 @@ $\displaystyle \sum_@{n=0@}^\infty x_n $ @findex ^ In math mode, use the caret character@tie{}@code{^} to make the -@var{exp} appear as a superscript, ie.@: type @code{^@{@var{exp}@}}. +@var{exp} appear as a superscript: @code{^@{@var{exp}@}}. Similarly, in math mode, underscore@tie{}@code{_@{@var{exp}@}} makes a subscript out of @var{exp}. @@ -6184,8 +7345,12 @@ the pi symbol @BES{03C0,\pi}. Below is a list of commonly-available symbols. It is by no means an exhaustive list. Each symbol here is described with a short phrase, and its symbol class (which determines the spacing around it) is given in -parenthesis. The commands for these symbols can be used only in math -mode. +parenthesis. Unless said otherwise, the commands for these symbols can +be used only in math mode. + +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 Useful: http://www.w3.org/TR/WD-math-970515/section6.html @@ -6218,7 +7383,7 @@ five-pointed, and is sometimes used as a general binary operation, and sometimes reserved for cross-correlation. @item \asymp -@BES{224D,\asymp} Asymptomatically equivalent (relation). +@BES{224D,\asymp} Asymptotically equivalent (relation). @item \backslash \ Backslash (ordinary). Similar: set minus@tie{}@code{\setminus}, and @@ -6270,16 +7435,15 @@ union@tie{}@code{\cup}. @BES{22C0,\bigwedge} Variable-sized, or n-ary, logical-or (operator). @item \bot -@BESU{22A5,bot} Up tack, bottom, least element of a poset, or a contradiction -(ordinary). See also@tie{}@code{\top}. +@BESU{22A5,bot} Up tack, bottom, least element of a partially ordered +set, or a contradiction (ordinary). See also@tie{}@code{\top}. @item \bowtie @BES{22C8,\bowtie} Natural join of two relations (relation). @item \Box -@BESU{25A1,Box} Modal operator for necessity; square open box (ordinary). This -is not available in Plain @TeX{}. In @LaTeX{} you need to load the -@file{amssymb} package. +@BESU{25A1,Box} Modal operator for necessity; square open box +(ordinary). @value{NeedsAMSSymb} @c bb Best Unicode equivalent? @item \bullet @@ -6307,8 +7471,7 @@ variable-sized operator@tie{}@code{\bigcirc}. @item \complement @BESU{2201,complement} Set complement, used as a superscript as in -@code{$S^\complement$} (ordinary). This is not available in Plain -@TeX{}. In @LaTeX{} you should load the @file{amssymb} package. Also +@code{$S^\complement$} (ordinary). @value{NeedsAMSSymb} Also used: @code{$S^@{\mathsf@{c@}@}$} or@tie{}@code{$\bar@{S@}$}. @item \cong @@ -6338,8 +7501,7 @@ turnstile@tie{}@code{\vdash}. @BES{03B4,\delta} Greek lower case delta (ordinary). @item \Diamond -@BESU{25C7,Diamond} Large diamond operator (ordinary). This is not available in -Plain @TeX{}. In @LaTeX{} you must load the @file{amssymb} package. +@BESU{25C7,Diamond} Large diamond operator (ordinary). @value{NeedsAMSSymb} @c bb Best Unicode equivalent? @item \diamond @@ -6368,15 +7530,15 @@ arrow@tie{}@code{\downarrow}. @BES{2113,\ell} Lower-case cursive letter l (ordinary). @item \emptyset -@BES{2205,\emptyset} Empty set symbol (ordinary). Similar: reversed empty -set@tie{}@code{\varnothing}. +@BES{2205,\emptyset} Empty set symbol (ordinary). The variant form is +@code{\varnothing}. @c bb Why Unicode has \revemptyset but no \emptyset? - + @item \epsilon -@BES{03F5,\epsilon} Lower case Greek-text letter (ordinary). More widely used in -mathematics is the curly epsilon -@code{\varepsilon}@tie{}@BES{03B5,\varepsilon}. Related: the set membership relation -@code{\in}@tie{}@BES{2208,\in}. +@BES{03F5,\epsilon} Lower case lunate epsilon (ordinary). Similar to +Greek text letter. More widely used in mathematics is the script small +letter epsilon @code{\varepsilon}@tie{}@BES{03B5,\varepsilon}. Related: +the set membership relation @code{\in}@tie{}@BES{2208,\in}. @c src: David Carlisle http://tex.stackexchange.com/a/98018/339 and @c Unicode referenced there asserts varepsilon is much more widely used. @@ -6440,8 +7602,8 @@ with a @code{\thickmuskip} on either side. @BES{2111,\Im} Imaginary part (ordinary). See: real part@tie{}@code{\Re}. @item \in -@BES{2208,\in} Set element (relation). See also: lower case Greek letter -epsilon@tie{}@code{\epsilon}@BES{03F5,\epsilon} and rounded small +@BES{2208,\in} Set element (relation). See also: lower case lunate +epsilon@tie{}@code{\epsilon}@BES{03F5,\epsilon} and small letter script epsilon@tie{}@code{\varepsilon}. @item \infty @@ -6491,8 +7653,7 @@ shaved off (opening). Matches@tie{}@code{\rceil}. for@tie{}@code{\leq}. @item \leadsto -@BESU{21DD,leadsto} Squiggly right arrow (relation). This is not available in -Plain @TeX{}. In @LaTeX{} you should load the @file{amssymb} package. +@BESU{21DD,leadsto} Squiggly right arrow (relation). @value{NeedsAMSSymb} To get this symbol outside of math mode you can put @code{\newcommand*@{\Leadsto@}@{\ensuremath@{\leadsto@}@}} in the preamble and then use @code{\Leadsto} instead. @@ -6526,12 +7687,11 @@ double-line double headed arrow@tie{}@code{\Leftrightarrow}. for@tie{}@code{\le}. @item \lfloor -@BES{230A,\lfloor} Left floor bracket (opening). +@BES{230A,\lfloor} Left floor bracket (opening). Matches:@tie{}@code{\floor}. @item \lhd -@BESU{25C1,lhd} Arrowhead, that is, triangle, pointing left (binary). This is -not available in Plain @TeX{}. In @LaTeX{} you should load the -@file{amssymb} package. For the normal subgroup symbol you should load +@BESU{25C1,lhd} Arrowhead, that is, triangle, pointing left (binary). +@value{NeedsAMSSymb} For the normal subgroup symbol you should load @file{amssymb} and use@tie{}@code{\vartriangleleft} (which is a relation and so gives better spacing). @@ -6567,8 +7727,7 @@ Similar: longer version@tie{}@code{\longmapsto}. @item \mho @BESU{2127,mho} Conductance, half-circle rotated capital omega (ordinary). -This is not available in Plain @TeX{}. In @LaTeX{} you should load the -@file{amssymb} package. +@value{NeedsAMSSymb} @item \mid @BES{2223,\mid} Single-line vertical bar (relation). A typical use of @@ -6692,21 +7851,21 @@ ordinary. @BES{00B1,\pm} Plus or minus (binary). @item \prec -@BES{227A,\prec} Preceeds (relation). Similar: less than@tie{}@code{<}. +@BES{227A,\prec} Precedes (relation). Similar: less than@tie{}@code{<}. @item \preceq -@BES{2AAF,\preceq} Preceeds or equals (relation). Similar: less than or +@BES{2AAF,\preceq} Precedes or equals (relation). Similar: less than or equals@tie{}@code{\leq}. @item \prime -@BES{2032,\prime} Prime, or minute in a time expression (ordinary). Typically -used as a superscript @code{$A^\prime$}. Note that @code{$f^\prime$} -and @code{$f'$} produce the same result. An advantage of the second is -that @code{$f'''$} produces the the desired symbol, that is, the same -result as @code{$f^@{\prime\prime\prime@}$}, but uses somewhat less -typing. Note that you can only use @code{\prime} in math mode but you -can type right single quote@tie{}@code{'} in text mode also, although it -resuts in a different look than in math mode. +@BES{2032,\prime} Prime, or minute in a time expression (ordinary). +Typically used as a superscript: @code{$f^\prime$}; @code{$f^\prime$} +and @code{$f'$} produce the same result. An advantage of the second +is that @code{$f'''$} produces the desired symbol, that is, the same +result as @code{$f^@{\prime\prime\prime@}$}, but uses rather less +typing. You can only use @code{\prime} in math mode. Using the right +single quote@tie{}@code{'} in text mode produces a different character +(apostrophe). @item \prod @BES{220F,\prod} Product (operator). @@ -6721,7 +7880,7 @@ resuts in a different look than in math mode. @BES{03C8,\psi} Lower case Greek letter (ordinary). @item \rangle -@BES{27B9,\rangle} Right angle, or sequence, bracket (closing). Similar: greater +@BES{27E9,\rangle} Right angle, or sequence, bracket (closing). Similar: greater than@tie{}@code{>}. Matches:@code{\langle}. @item \rbrace @@ -6742,18 +7901,20 @@ this, load the @file{amsfonts} package. @item \restriction @BESU{21BE,restriction} Restriction of a function -(relation). Synonym:@tie{}@code{\upharpoonright}. Not available in -Plain @TeX{}. In @LaTeX{} you should load the @file{amssymb} package. +(relation). Synonym:@tie{}@code{\upharpoonright}. @value{NeedsAMSSymb} + +@item \revemptyset +@BESU{29B0,revemptyset} Reversed empty set symbol (ordinary). Related: +@code{\varnothing}. @value{NeedsSTIX} @item \rfloor @BES{230B,\rfloor} Right floor bracket, a right square bracket with the top cut off (closing). Matches@tie{}@code{\lfloor}. @item \rhd -@BESU{25C1,rhd} Arrowhead, that is, triangle, pointing right (binary). This is -not available in Plain @TeX{}. In @LaTeX{} you should load the -@file{amssymb} package. For the normal subgroup symbol you should -instead load @file{amssymb} and use@tie{}@code{\vartriangleright} (which +@BESU{25C1,rhd} Arrowhead, that is, triangle, pointing right (binary). +@value{NeedsAMSSymb} For the normal subgroup symbol you should instead +load @file{amssymb} and use@tie{}@code{\vartriangleright} (which is a relation and so gives better spacing). @item \rho @@ -6805,7 +7966,7 @@ right single-line arrow@tie{}@code{\rightarrow}. display (operator). @item \smile -@BES{2323,\smile} Upward curving arc (ordinary). +@BES{2323,\smile} Upward curving arc, smile (ordinary). @item \spadesuit @BES{2660,\spadesuit} Spade card suit (ordinary). @@ -6821,8 +7982,7 @@ operator@tie{}@code{\bigsqcup}. @item \sqsubset @BESU{228F,sqsubset} Square subset symbol (relation). Similar: -subset@tie{}@code{\subset}. This is not available in Plain @TeX{}. In -@LaTeX{} you should load the @file{amssymb} package. +subset@tie{}@code{\subset}. @value{NeedsAMSSymb} @item \sqsubseteq @BES{2291,\sqsubseteq} Square subset or equal symbol (binary). Similar: subset or @@ -6830,8 +7990,7 @@ equal to@tie{}@code{\subseteq}. @item \sqsupset @BESU{2290,sqsupset} Square superset symbol (relation). Similar: -superset@tie{}@code{\supset}. This is not available in Plain @TeX{}. In -@LaTeX{} you should load the @file{amssymb} package. +superset@tie{}@code{\supset}. @value{NeedsAMSSymb} @item \sqsupseteq @BES{2292,\sqsupseteq} Square superset or equal symbol (binary). Similar: superset or @@ -6870,7 +8029,7 @@ sigma@tie{}@code{\Sigma}. @item \surd @BES{221A,\surd} Radical symbol (ordinary). The @LaTeX{} command -@code{\sqrt@{..@}} typesets the square root of the argument, with a bar +@code{\sqrt@{...@}} typesets the square root of the argument, with a bar that extends to cover the argument. @item \swarrow @@ -6892,8 +8051,8 @@ also@tie{}@code{\cdot}. Synonym:@tie{}@code{\rightarrow}. @item \top -@BESU{22A4,top} Top, greatest element of a poset (ordinary). See -also@tie{}@code{\bot}. +@BESU{22A4,top} Top, greatest element of a partially ordered set +(ordinary). See also@tie{}@code{\bot}. @item \triangle @BES{25B3,\triangle} Triangle (ordinary). @@ -6905,36 +8064,39 @@ should load @file{amssymb} and use@tie{}@code{\vartriangleleft} (which is a relation and so gives better spacing). @item \triangleright -@BES{25B7,\triangleright} Not-filled triangle pointing right (binary). For the normal -subgroup symbol you should instead load @file{amssymb} and -use@tie{}@code{\vartriangleright} (which is a relation and so gives -better spacing). +@BES{25B7,\triangleright} Not-filled triangle pointing right +(binary). For the normal subgroup symbol you should instead load +@file{amssymb} and use@tie{}@code{\vartriangleright} (which is a +relation and so gives better spacing). @item \unlhd -@BESU{22B4,unlhd} Left-pointing not-filled arrowhead, that is, triangle, with a -line under (binary). This is not available in Plain @TeX{}. In @LaTeX{} -you should load the @file{amssymb} package. For the normal subgroup -symbol load @file{amssymb} and use@tie{}@code{\vartrianglelefteq} (which -is a relation and so gives better spacing). +@BESU{22B4,unlhd} Left-pointing not-filled underlined arrowhead, that +is, triangle, with a line under (binary). @value{NeedsAMSSymb} For +the normal subgroup symbol load @file{amssymb} and +use@tie{}@code{\vartrianglelefteq} (which is a relation and so gives +better spacing). @item \unrhd -@BESU{22B5,unrhd} Right-pointing not-filled arrowhead, that is, triangle, with a -line under (binary). This is not available in Plain @TeX{}. In @LaTeX{} -you should load the @file{amssymb} package. For the normal subgroup -symbol load @file{amssymb} and use@tie{}@code{\vartrianglerighteq} -(which is a relation and so gives better spacing). +@BESU{22B5,unrhd} Right-pointing not-filled underlined arrowhead, that +is, triangle, with a line under (binary). @value{NeedsAMSSymb} For +the normal subgroup symbol load @file{amssymb} and +use@tie{}@code{\vartrianglerighteq} (which is a relation and so gives +better spacing). @item \Uparrow -@BES{21D1,\Uparrow} Double-line upward-pointing arrow (relation). Similar: -single-line up-pointing arrow@tie{}@code{\uparrow}. +@BES{21D1,\Uparrow} Double-line upward-pointing arrow +(relation). Similar: single-line up-pointing +arrow@tie{}@code{\uparrow}. @item \uparrow -@BES{2191,\uparrow} Single-line upward-pointing arrow, diverges (relation). Similar: -double-line up-pointing arrow@tie{}@code{\Uparrow}. +@BES{2191,\uparrow} Single-line upward-pointing arrow, diverges +(relation). Similar: double-line up-pointing +arrow@tie{}@code{\Uparrow}. @item \Updownarrow -@BES{21D5,\Updownarrow} Double-line upward-and-downward-pointing arrow (relation). Similar: -single-line upward-and-downward-pointing arrow@tie{}@code{\updownarrow}. +@BES{21D5,\Updownarrow} Double-line upward-and-downward-pointing arrow +(relation). Similar: single-line upward-and-downward-pointing +arrow@tie{}@code{\updownarrow}. @item \updownarrow @BES{2195,\updownarrow} Single-line upward-and-downward-pointing arrow (relation). Similar: @@ -6942,13 +8104,12 @@ double-line upward-and-downward-pointing arrow@tie{}@code{\Updownarrow}. @item \upharpoonright @BESU{21BE,upharpoonright} Up harpoon, with barb on right side -(relation). Synonym:@tie{}@code{@backslashchar{}restriction}. Not available in Plain -@TeX{}. In @LaTeX{} you should load the @file{amssymb} package. +(relation). Synonym:@tie{}@code{@backslashchar{}restriction}. @value{NeedsAMSSymb} @item \uplus -@BES{228E,\uplus} Multiset union, a union symbol with a plus symbol in the middle -(binary). Similar: union@tie{}@code{\cup}. Related: variable-sized -operator@tie{}@code{\biguplus}. +@BES{228E,\uplus} Multiset union, a union symbol with a plus symbol in +the middle (binary). Similar: union@tie{}@code{\cup}. Related: +variable-sized operator@tie{}@code{\biguplus}. @item \Upsilon @BES{03A5,\Upsilon} Upper case Greek letter (ordinary). @@ -6957,53 +8118,62 @@ operator@tie{}@code{\biguplus}. @BES{03C5,\upsilon} Lower case Greek letter (ordinary). @item \varepsilon -@BES{03B5,\varepsilon} Rounded small epsilon (ordinary). This is more widely used in -mathematics than the non-variant lower case Greek-text letter form -@code{\epsilon}@tie{}@BES{03F5,\epsilon}. Related: set membership@tie{}@code{\in}. +@BES{03B5,\varepsilon} Small letter script epsilon (ordinary). This is +more widely used in mathematics than the non-variant lunate epsilon form +@code{\epsilon}@tie{}@BES{03F5,\epsilon}. Related: set +membership@tie{}@code{\in}. + +@item \vanothing +@BESU{2205,varnothing} Empty set symbol. Similar: +@code{\emptyset}. Related: @code{\revemptyset}. @value{NeedsAMSSymb} @item \varphi -@BES{03C6,\varphi} Variant on the lower case Greek letter (ordinary). The -non-variant form is @code{\phi}@tie{}@BES{03D5,\phi}. +@BES{03C6,\varphi} Variant on the lower case Greek letter (ordinary). +The non-variant form is @code{\phi}@tie{}@BES{03D5,\phi}. @item \varpi -@BES{03D6,\varpi} Variant on the lower case Greek letter (ordinary). The -non-variant form is @code{\pi}@tie{}@BES{03C0,\pi}. +@BES{03D6,\varpi} Variant on the lower case Greek letter (ordinary). +The non-variant form is @code{\pi}@tie{}@BES{03C0,\pi}. @item \varrho -@BES{03F1,\varrho} Variant on the lower case Greek letter (ordinary). The -non-variant form is @code{\rho}@tie{}@BES{03C1,\rho}. +@BES{03F1,\varrho} Variant on the lower case Greek letter (ordinary). +The non-variant form is @code{\rho}@tie{}@BES{03C1,\rho}. @item \varsigma -@BES{03C2,\varsigma} Variant on the lower case Greek letter (ordinary). The -non-variant form is @code{\sigma}@tie{}@BES{03C3,\sigma}. +@BES{03C2,\varsigma} Variant on the lower case Greek letter +(ordinary). The non-variant form is +@code{\sigma}@tie{}@BES{03C3,\sigma}. @item \vartheta -@BES{03D1,\vartheta} Variant on the lower case Greek letter (ordinary). The -non-variant form is @code{\theta}@tie{}@BES{03B8,\theta}. +@BES{03D1,\vartheta} Variant on the lower case Greek letter +(ordinary). The non-variant form is +@code{\theta}@tie{}@BES{03B8,\theta}. @item \vdash -@BES{22A2,\vdash} Provable; turnstile, vertical and a dash (relation). Similar: -turnstile rotated a half-circle@tie{}@code{\dashv}. +@BES{22A2,\vdash} Provable; turnstile, vertical and a dash +(relation). Similar: turnstile rotated a +half-circle@tie{}@code{\dashv}. @item \vee -@BES{2228,\vee} Logical or; a downwards v shape (binary). Related: logical -and@tie{}@code{\wedge}. Similar: variable-sized +@BES{2228,\vee} Logical or; a downwards v shape (binary). Related: +logical and@tie{}@code{\wedge}. Similar: variable-sized operator@tie{}@code{\bigvee}. @item \Vert @BES{2016,\Vert} Vertical double bar (ordinary). Similar: vertical single bar@tie{}@code{\vert}. -For a norm you can use the @file{mathtools} package and add +For a norm symbol, you can use the @file{mathtools} package and add @code{\DeclarePairedDelimiter\norm@{\lVert@}@{\rVert@}} to your -preamble. This gives you three command variants for double-line vertical -bars that are correctly horizontally spaced: if in the document body you -write the starred version @code{$\norm*@{M^\perp@}$} then the height of -the vertical bars will match the height of the argument, whereas with -@code{\norm@{M^\perp@}} the bars do not grow with the height of the -argument but instead are the default height, and @code{\norm[@var{size -command}]@{M^\perp@}} also gives bars that do not grow but are set to -the size given in the @var{size command}, e.g., @code{\Bigg}. +preamble. This gives you three command variants for double-line +vertical bars that are correctly horizontally spaced: if in the +document body you write the starred version @code{$\norm*@{M^\perp@}$} +then the height of the vertical bars will match the height of the +argument, whereas with @code{\norm@{M^\perp@}} the bars do not grow +with the height of the argument but instead are the default height, +and @code{\norm[@var{size command}]@{M^\perp@}} also gives bars that +do not grow but are set to the size given in the @var{size command}, +e.g., @code{\Bigg}. @item \vert @BES{007C,\vert} Single line vertical bar (ordinary). Similar: double-line @@ -7149,10 +8319,15 @@ parenthesized modulus, as in (@math{\pmod 2^n - 1}) @math{\sinh} @item \sup -sup -@c don't try to use \sup since that turned into a Texinfo command -@c and it's not worth hassling with different versions when it's -@c just three roman letters anyway. +@iftex +@math{\mathop {\rm sup}} +@end iftex +@ifnottex +@math{\sup} +@end ifnottex +@c don't try to use \sup with dvi/pdf output since that turned into a +@c Texinfo command and it's not worth hassling with different versions +@c when it's just three roman letters anyway. @item \tan @math{\tan} @@ -7275,7 +8450,7 @@ Normally @code{4.0mu plus 2.0mu minus 4.0mu}. The longer name is @findex \, @findex \thinspace Normally @code{3mu}. The longer name is @code{\thinspace}. This can -be used in both math mode and text mode. +be used in both math mode and text mode. @xref{\thinspace}. @item \! @findex \! @@ -7312,8 +8487,39 @@ infinitesimal. @item \* @cindex discretionary multiplication @cindex multiplication symbol, discretionary line break -A ``discretionary'' multiplication symbol, at which a line break is -allowed. +A @dfn{discretionary} multiplication symbol, at which a line break is +allowed. Without the break multiplication is implicitly indicated by a +space, while in the case of a break a @BES{00D7,\times} symbol is +printed immediately before the break. So + +@example +\documentclass@{article@} +\begin@{document@} +Now \(A_3 = 0\), hence the product of all terms \(A_1\) +through \(A_4\), that is \(A_1\* A_2\* A_3 \* A_4\), is +equal to zero. +\end@{document@} +@end example + +will make that sort of output@c +@ifnottex +@w{ }(the ellipsis @samp{[@dots{}]} is here to show the line break at +the same place as in a @TeX{} output)@c +@end ifnottex +: + +@indentedblock +Now @math{A_3 = 0}, +@iftex +hence the product of all terms +@end iftex +@ifnottex +[@dots{}] +@end ifnottex +@math{A_1} +through @math{A_4}, that is @math{A_1 A_2 \times}@*@math{A_3 A_4}, is +equal to zero. +@end indentedblock @item \cdots A horizontal ellipsis with the dots raised to the center of the line. @@ -7324,73 +8530,88 @@ As in: `$\cdots$'. @item \ddots A diagonal ellipsis: @math{\ddots}. -@item \frac@{num@}@{den@} +@item \frac@{@var{num}@}@{@var{den}@} @findex \frac -Produces the fraction @code{num} divided by @code{den}. +Produces the fraction @var{num} divided by @var{den}. -@iftex -eg. -@tex -${1}\over{4}$ -@end tex -@end iftex +@ifset HAS-MATH +eg. @math{{1}\over{4}} +@end ifset @item \left @var{delim1} ... \right @var{delim2} @findex \right @cindex null delimiter -The two delimiters need not match; @samp{.} acts as a null delimiter, +The two delimiters need not match; @samp{.} acts as a @dfn{null delimiter}, producing no output. The delimiters are sized according to the math -in between. Example: @code{\left( \sum_i=1^10 a_i \right]}. +in between. Example: @code{\left( \sum_@{i=1@}^@{10@} a_i \right]}. -@item \overbrace@{@var{text}@} -Generates a brace over @var{text}. -For example, @math{\overbrace{x+\cdots+x}^{k \rm\;times}}. +@item \mathdollar +Dollar sign in math mode: $. +@item \mathellipsis +Ellipsis (spaced for text) in math mode: @dots{}. + +@item \mathparagraph +Paragraph sign (pilcrow) in math mode: @BES{00B6,\P}. + +@item \mathsection +Section sign in math mode. + +@item \mathsterling +Sterling sign in math mode: @pounds{}. + +@item \mathunderscore +Underscore in math mode: _. + +@item \overbrace@{@var{math}@} +Generates a brace over @var{math}. +For example, @code{\overbrace@{x+\cdots+x@}^@{k \;\textrm@{times@}@}}. +@ifset HAS-MATH +The result looks like: @math{\overbrace{x+\cdots+x}^{k \rm\;times}} +@end ifset + @item \overline@{@var{text}@} Generates a horizontal line over @var{tex}. -For example, @math{\overline{x+y}}. +For example, @code{\overline@{x+y@}}. +@ifset HAS-MATH +The result looks like: @math{\overline{x+y}}. +@end ifset -@item \sqrt[@var{root}]@{arg@} +@item \sqrt[@var{root}]@{@var{arg}@} Produces the representation of the square root of @var{arg}. The optional argument @var{root} determines what root to produce. For example, the cube root of @code{x+y} would be typed as -@code{$\sqrt[3]@{x+y@}$}. -@tex -In @TeX{}, the result looks like this: -$\root 3 \of x+y$. -@end tex +@code{\sqrt[3]@{x+y@}}. +@ifset HAS-MATH +The result looks like this: @math{\root 3 \of {x+y}}. +@end ifset @item \stackrel@{@var{text}@}@{@var{relation}@} Puts @var{text} above @var{relation}. For example, @code{\stackrel@{f@}@{\longrightarrow@}}. -@tex -In @TeX{}, the result looks like this: -$\buildrel f \over \longrightarrow$. -@end tex +@ifset HAS-MATH + The result looks like this: @math{\buildrel f \over \longrightarrow}. +@end ifset -@item \underbrace@{math@} -Generates @var{math} with a brace underneath. -@tex -In @TeX{}, the result looks like this: -$\underbrace{x+y+z}_{>\,0}$. -@end tex +@item \underbrace@{@var{math}@} +Generates @var{math} with a brace underneath. For example, @code{\underbrace@{x+y+z@}_@{>\,0@}} +@ifset HAS-MATH +The result looks like this: @math{\underbrace{x+y+z}_{>\,0}}. +@end ifset -@item \underline@{text@} +@item \underline@{@var{text}@} Causes @var{text}, which may be either math mode or not, to be underlined. The line is always below the text, taking account of descenders. -@tex -In @TeX{}, the result looks like this: -$\underline{xyz}$ -@end tex +@ifset HAS-MATH +The result looks like this: @math{\underline{xyz}} +@end ifset @item \vdots -@findex \vdots Produces a vertical ellipsis. -@tex -In @TeX{}, the result looks like this: -$\vdots$. -@end tex +@ifset HAS-MATH +The result looks like this: @math{\vdots}. +@end ifset @end ftable @@ -7446,6 +8667,50 @@ When @LaTeX{} is in paragraph mode while making a box, it is said to be in ``inner paragraph mode'' (no page breaks). Its normal paragraph mode, which it starts out in, is called ``outer paragraph mode''. +@menu +* \ensuremath:: Ensure that math mode is active +@end menu + +@node \ensuremath +@section @code{\ensuremath} + +Synopsis: + +@example +\ensuremath@{@var{formula}@} +@end example + +The @code{\ensuremath} command ensures that @var{formula} is typeset in +math mode whatever the current mode in which the command is used. + +For instance: + +@example +\documentclass@{report@} +\newcommand@{\ab@}@{\ensuremath@{(\delta, \varepsilon)@}@} +\begin@{document@} +Now, the \ab\ pair is equal to \(\ab = (\frac@{1@}@{\pi@}, 0)\), ... +\end@{document@} +@end example + +One can redefine commands that can be used only in math mode so that +they ca be used in any mode like in the following example given for +@code{\leadsto}: + +@c Vincent 2 Karl : "Tous les chemins mènent à Rome" is a French saying +@c meaning that there are many different ways to get the same result. I +@c am not sure whether in English the given example is also funny. +@example +\documentclass@{report@} +\usepackage@{amssymb@} +\newcommand@{\originalMeaningOfLeadsTo@}@{@} +\let\originalMeaningOfLeadsTo\leadsto +\renewcommand\leadsto@{\ensuremath@{\originalMeaningOfLeadsTo@}@} +\begin@{document@} +All roads \leadsto\ Rome. +\end@{document@} +@end example + @node Page styles @chapter Page styles @@ -7613,11 +8878,11 @@ 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. -* \(SPACE) after CS:: Controlling space gobbling after a control sequence. -* \frenchspacing:: Make interword and intersentence space equal. +* \(SPACE) and \@@:: Space after a period. +* \(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. +* \/:: Insert italic correction. * \hrulefill \dotfill:: Stretchable horizontal rule or dots. Vertical space @@ -7650,7 +8915,7 @@ space is like backspacing. Normally when @TeX{} breaks a paragraph into lines it discards white space (glues and kerns) that would come at the start of a line, so you get an inter-word space or a line break between words but not both. This -command's starred version @code{\hspace*@{..@}} puts a non-discardable +command's starred version @code{\hspace*@{...@}} puts a non-discardable invisible item in front of the space, so the space appears in the output. @@ -7698,7 +8963,7 @@ colon) more than the space between words sentence unless it is preceded by a capital letter, in which case it takes that period for part of an abbreviation. Note that if a sentence-ending period is immediately followed by a right parenthesis or -bracket, or right single or double quote, then the intersentence space +bracket, or right single or double quote, then the inter-sentence space follows that parenthesis or quote. If you have a period ending an abbreviation whose last letter is not a @@ -7707,63 +8972,42 @@ 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 other use of @code{\ }, see also @ref{\(SPACE) after CS}. +For another use of @code{\ }, @pxref{\(SPACE) after control sequence}. In the opposite situation, if you have a capital letter followed by a -period that ends the sentence, then put @code{\@@} on the left of that -period. For example, @code{book by the MAA\@@.} will have intersentence +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. -In contrast, putting @code{\@@} on the right of 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). +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 \(SPACE) after CS -@section @code{\ } after a control sequence +@node \(SPACE) after control sequence +@section @code{\ } after control sequence -The @code{\ } command is often used after control sequences to keep them -from gobbling the space that follows, as in @code{\TeX\ is a nice -system.} And, under normal circumstances @code{\}@key{tab} and -@code{\}@key{newline} are equivalent to @code{\ }. For other use of +The @code{\ } command is often used after control sequences to keep +them from gobbling the space that follows, as in @samp{\TeX\ is nice}. +And, under normal circumstances, @code{\}@key{tab} and +@code{\}@key{newline} are equivalent to @code{\ }. For another use of @code{\ }, see also @ref{\(SPACE) and \@@}. Some people prefer to use @code{@{@}} for the same purpose, as in -@code{\TeX@{@} is a nice system.} This has the advantage that you can -always write it the same way, like @code{\TeX@{@}}, whether it is -followed by a space or by a punctuation mark. Please compare: +@code{\TeX@{@} is nice}. This has the advantage that you can always +write it the same way, namely @code{\TeX@{@}}, whether it is followed +by a space or by a punctuation mark. Compare: @example \TeX\ is a nice system. \TeX, a nice system.@* \TeX@{@} is a nice system. \TeX@{@}, a nice system. @end example - -When you define user commands (@pxref{\newcommand & \renewcommand}) you -can prevent the space gobbling after the command by using the package -@code{xspace} and inserting @code{\xspace} at the end of the definition -For instance: -@example -\documentclass@{minimal@} -\usepackage@{xspace@} -\newcommand*@{\Loup@}@{Grand Cric\xspace@} -\begin@{document@} -Que le \Loup me croque ! -\end@{document@} -@end example - -A quick hack to use @code{\xspace} for existing command is as follows: -@example -\documentclass@{minimal@} -\usepackage@{xspace@} -\newcommand*@{\SansXspaceTeX@}@{@} -\let\SansXspaceTeX\TeX -\renewcommand@{\TeX@}@{\SansXspaceTeX\xspace@} -\begin@{document@} -\TeX is a nice system. -\end@{document@} -@end example +@PkgIndex{xspace} +Some individual commands, notably those defined with the @code{xspace}, +package do not follow the standard behavior. @node \frenchspacing @@ -7771,10 +9015,10 @@ A quick hack to use @code{\xspace} for existing command is as follows: @findex \frenchspacing @findex \nonfrenchspacing -@cindex spacing, intersentence +@cindex spacing, inter-sentence This declaration (from Plain @TeX{}) causes @LaTeX{} to treat -intersentence spacing in the same way as interword spacing. +inter-sentence spacing in the same way as interword spacing. In justifying the text in a line, some typographic traditions, including English, prefer to adjust the space between sentences (or after other @@ -7882,10 +9126,10 @@ then this command will not add more space than what is needed to make the natural length of the total vertical space equal to @var{length}. Use this command to adjust the vertical space above or below an -environment that starts a new paragraph. (For instance, a Theorem -environment is defined to begin and end in @code{\addvspace@{..@}} so -that two consecutive Theorem's are separated by one vertical space, not -two.) +environment that starts a new paragraph. For instance, a Theorem +environment is defined to begin and end with @code{\addvspace@{...@}} +so that two consecutive Theorem's are separated by one vertical space, +not two. This command is fragile (@pxref{\protect}). @@ -7900,30 +9144,27 @@ change that is to precede this command with a @code{\par} command. These commands produce a given amount of space, specified by the document class. -@table @code +@ftable @code @item \bigskip -@findex \bigskip @findex \bigskipamount The same as @code{\vspace@{\bigskipamount@}}, ordinarily about one line space, with stretch and shrink (the default for the @code{book} and @code{article} classes is @code{12pt plus 4pt minus 4pt}). @item \medskip -@findex \medskip @findex \medskipamount The same as @code{\vspace@{\medskipamount@}}, ordinarily about half of a line space, with stretch and shrink (the default for the @code{book} and @code{article} classes is @code{6pt plus 2pt minus 2pt}). @item \smallskip -@findex \smallskip @findex \smallskipamount The same as @code{\vspace@{\smallskipamount@}}, ordinarily about a quarter of a line space, with stretch and shrink (the default for the @code{book} and @code{article} classes is @code{3pt plus 1pt minus 1pt}). -@end table +@end ftable @node \vfill @@ -7976,9 +9217,13 @@ Synopsis, one of these two: Add the vertical space @var{length}. This can be negative or positive, and is a rubber length (@pxref{Lengths}). -@LaTeX{} removes the vertical space from @code{\vfill} at a page break, -that is, at the top or bottom of a page. The starred version -@code{\vspace*@{..@}} causes the space to stay. +@LaTeX{} removes the vertical space from @code{\vspace} at a page +break, that is, at the top or bottom of a page. The starred version +@code{\vspace*@{...@}} causes the space to stay. + +If @code{\vspace} is used in the middle of a paragraph (i.e., in +horizontal mode), the space is inserted @emph{after} the line with +the @code{\vspace} command. A new paragraph is not started. In this example the two questions will be evenly spaced vertically on the page, with at least one inch of space below each. @@ -8062,12 +9307,18 @@ Both commands produce a rule of thickness @code{\fboxrule} (default @findex lrbox -@code{\begin@{lrbox@}@{cmd@} text \end@{lrbox@}} +Synopsis: -This is the environment form of @code{\sbox}. +@example +\begin@{lrbox@}@{\@var{cmd}@} + @var{text } +\end@{lrbox@} +@end example -The text inside the environment is saved in the box @code{cmd}, which -must have been declared with @code{\newsavebox}. +This is the environment form of @ref{\sbox,@code{\sbox}}. + +The @var{text} inside the environment is saved in the box @code{\@var{cmd}}, +which must have been declared with @code{\newsavebox}. @node \makebox @@ -8114,8 +9365,9 @@ Synopsis: \parbox[@var{position}][@var{height}][@var{inner-pos}]@{@var{width}@}@{@var{text}@} @end example +@cindex paragraph mode The @code{\parbox} command produces a box whose contents are created -in @code{paragraph} mode. It should be used to make a box small +in @dfn{paragraph mode}. It should be used to make a box small pieces of text, with nothing fancy inside. In particular, you shouldn't use any paragraph-making environments inside a @code{\parbox} argument. For larger pieces of text, including ones @@ -8131,9 +9383,13 @@ the width of the parbox; the text that goes inside the parbox. @end table -The optional @var{position} argument allows you to align either the -top or bottom line in the parbox with the baseline of the surrounding -text (default is top). +By default @LaTeX{} will position vertically a parbox so its center +lines up with the center of the surrounding text line. When the +optional @var{position} argument is present and equal either to @samp{t} +or @samp{b}, this allows you respectively to align either the top or +bottom line in the parbox with the baseline of the surrounding text. You +may also specify @samp{m} for @var{position} to get the default +behaviour. The optional @var{height} argument overrides the natural height of the box. @@ -8161,7 +9417,7 @@ for this to work. Synopsis: @example -\raisebox@{distance@}[@var{height}][@var{depth}]@{text@} +\raisebox@{@var{distance}@}[@var{height}][@var{depth}]@{@var{text}@} @end example The @code{\raisebox} command raises or lowers @var{text}. The first @@ -8169,9 +9425,9 @@ mandatory argument specifies how high @var{text} is to be raised (or lowered if it is a negative amount). @var{text} itself is processed in LR mode. -The optional arguments @var{height} and @var{depth} are dimensions. -If they are specified, @LaTeX{} treats @var{text} as extending a -certain distance above the baseline (height) or below (depth), +The optional arguments @var{height} and @var{depth} are dimensions. If +they are specified, @LaTeX{} treats @var{text} as extending a certain +distance above the baseline (@var{height}) or below (@var{depth}), ignoring its natural height and depth. @@ -8235,12 +9491,14 @@ Synopsis: special meaning do not correspond to simple characters you can type. @menu -* Reserved characters:: Inserting @samp{# $ % & ~ _ ^ \ @{ @}} -* Text symbols:: Inserting other non-letter symbols in text. -* Accents:: Inserting accents. -* Non-English characters:: Inserting other non-English characters. -* \rule:: Inserting lines and rectangles. -* \today:: Inserting today's date. +* Reserved characters:: Inserting @samp{# $ % & @{ @} _ ~ ^ \} +* Upper and lower case:: Make text upper or lower case. +* Symbols by font position:: Inserting font symbols by number. +* Text symbols:: Inserting other non-letter symbols in text. +* Accents:: Inserting accents. +* Additional Latin letters:: Inserting other non-English characters. +* \rule:: Inserting lines and rectangles. +* \today:: Inserting today's date. @end menu @@ -8249,12 +9507,14 @@ special meaning do not correspond to simple characters you can type. @cindex reserved characters @cindex characters, reserved - -The following characters play a special role in @LaTeX{} and are called -``reserved characters'' or ``special characters''. +@cindex special characters +@cindex characters, special +@LaTeX{} sets aside the following characters for special purposes (for +example, the percent sign@tie{}@code{%} is for comments) so they are +called @dfn{reserved characters} or @dfn{special characters}. @example -# $ % & ~ _ ^ \ @{ @} +# $ % & @{ @} _ ~ ^ \ @end example @findex \# @@ -8264,35 +9524,101 @@ The following characters play a special role in @LaTeX{} and are called @findex \_ @findex \@{ @findex \@} -Whenever you write one of these characters into your file, @LaTeX{} -will do something special. If you simply want the character to be -printed as itself, include a @code{\} in front of the character. For -example, @code{\$} will produce @code{$} in your output. - -@findex \backslash -One exception to this rule is @code{\} itself, because @code{\\} has -its own special (context-dependent) meaning. A roman \ is produced by -typing @code{$\backslash$} in your file, and a typewriter @code{\} is -produced by using @samp{\} in a verbatim command (@pxref{verbatim}). +If you want a reserved character to be printed as itself, in the text +body font, for all but the final three characters in that list simply +put a backslash@tie{}@code{\} in front of the character. Thus, +@code{\$1.23} will produce@tie{}@code{$1.23} in your output. @findex \~ -@findex \^ -Also, @code{\~} and @code{\^} place tilde and circumflex accents over -the following letter, as in @~{o} and @^{o} (@pxref{Accents}); to get -a standalone @code{~} or @code{^}, you can again use a verbatim -command. +@findex \^ +@findex \textbackslash +As to the last three characters, to get a tilde in the text body font +use @code{\~@{@}} (omitting the curly braces would result in the next +character receiving a tilde accent). Similarly, to get a get a text +body font circumflex use @code{\^@{@}}. A text body font backslash +results from @code{\textbackslash@{@}}. + +To produce the reserved characters in a typewriter font use +@code{\verb!!}, as below. + +@example +\begin@{center@} + \# \$ \% \& \@{ \@} \_ \~@{@} \^@{@} \textbackslash \\ + \verb!# $ % & @{ @} _ ~ ^ \! +\end@{center@} +@end example + +In that example the double backslash@tie{}@code{\\} is only there to +split the lines. + + +@node Upper and lower case +@section Upper and lower case + +@cindex Upper case +@cindex Lower case +@cindex characters, case + +Synopsis: + +@example +\uppercase@{@var{text}@} +\lowercase@{@var{text}@} +\MakeUppercase@{@var{text}@} +\MakeLowercase@{@var{text}@} +@end example + +Change the case of characters. The @TeX{} primitives commands +@code{\uppercase} and @code{\lowercase} only work for American +characters. The @LaTeX{} commands @code{\MakeUppercase} and +@code{\MakeLowercase} commands also change characters accessed by +commands such as @code{\ae} or @code{\aa}. The commands +@code{\MakeUppercase} and @code{\MakeLowercase} are robust but they have +moving arguments (@pxref{\protect}). + +These commands do not change the case of letters used in the name of a +command within @var{text}. But they do change the case of every other +latin character inside the argument @var{text}. Thus, +@code{\MakeUppercase@{Let $y=f(x)$}@} produces ``LET Y=F(X)''. Another +example is that the name of an environment will be changed, so that +@code{\MakeUppercase@{\begin@{tabular@} ... \end@{tabular@}} will +produce an error because the first half is changed to +@code{\begin@{TABULAR@}}. + +@LaTeX{} uses the same fixed table for changing case throughout a +document, The table used is designed for the font encoding T1; this +works well with the standard @TeX{} fonts for all Latin alphabets but +will cause problems when using other alphabets. + +To change the case of text that results from a command inside @var{text} +you need to do expansion. Here the @code{\Schoolname} produces +``COLLEGE OF MATHEMATICS''. + +@example +\newcommand@{\schoolname@}@{College of Mathematics@} +\newcommand@{\Schoolname@}@{\expandafter\MakeUppercase\expandafter@{\schoolname@}@} +@end example + +To uppercase only the first letter of words use the package +@file{mfirstuc}. + + +@node Symbols by font position +@section Symbols by font position @findex \symbol @cindex accessing any character of a font +@cindex font symbols, by number -Finally, you can access any character of the current font once you -know its number by using the @code{\symbol} command. For example, the -visible space character used in the @code{\verb*} command has the code -decimal 32, so it can be typed as @code{\symbol@{32@}}. +You can access any character of the current font using its number with +the @code{\symbol} command. For example, the visible space character +used in the @code{\verb*} command has the code decimal 32, so it can be +typed as @code{\symbol@{32@}}. -You can also specify octal numbers with @code{'} or hexadecimal numbers -with @code{"}, so the previous example could also be written as -@code{\symbol@{'40@}} or @code{\symbol@{"20@}}. +You can also specify numbers in octal (base 8) by using a @code{'} +prefix, or hexadecimal (base 16) with a @code{"} prefix, so the previous +example could also be written as @code{\symbol@{'40@}} or +@code{\symbol@{"20@}}. @node Text symbols @@ -8361,7 +9687,7 @@ Left (opening) quote: `. @itemx \textparagraph @cindex paragraph symbol @cindex pilcrow -Paragraph sign (pilcrow). +Paragraph sign (pilcrow): @BES{00B6,\P}. @item \pounds @itemx \textsterling @@ -8383,8 +9709,9 @@ Double and single quotation marks on the baseline: Right (closing) quote: '. @item \S +\itemx \textsection @cindex section symbol -Section symbol. +Section sign: @BES{00A7,\S}. @item \TeX @cindex @TeX{} logo @@ -8445,8 +9772,8 @@ Bullet: @bullet{}. @var{letter} in a circle, as in @registeredsymbol{}. @item \textcompwordmark -@itemx \textcapitalwordmark -@itemx \textascenderwordmark +@itemx \textcapitalcompwordmark +@itemx \textascendercompwordmark @cindex composite word mark, in text @cindex cap height @cindex ascender height @@ -8463,7 +9790,7 @@ Dagger: @math{\dag}. @cindex double dagger, in text Double dagger: @math{\ddag}. -@item \textdollar @r{(or @code{$})} +@item \textdollar @r{(or @code{\$})} @cindex dollar sign @cindex currency, dollar Dollar sign: $. @@ -8509,7 +9836,7 @@ Feminine and masculine ordinal symbols: @ordf{}, @ordm{}. @item \textperiodcentered @cindex period, centered, in text @cindex centered period, in text -Centered period: @math{\cdot}. +Centered period: @BES{00B7,\cdot}. @item \textquestiondown @r{(or @code{?`})} @cindex question mark, upside-down @@ -8520,7 +9847,7 @@ Upside down question mark: @questiondown{}. @cindex double left quote Double left quote: ``. -@item \textquotedblright @r{(or @code{'})} +@item \textquotedblright @r{(or @code{''})} @cindex right quote, double @cindex double right quote Double right quote: ''. @@ -8535,6 +9862,12 @@ Single left quote: `. @cindex single right quote Single right quote: '. +@item \textquotesingle +@cindex quote, single straight +@cindex straight single quote +@cindex single quote, straight +Straight single quote. (From TS1 encoding.) + @item \textquotestraightbase @itemx \textquotestraightdblbase @cindex quote, straight base @@ -8559,7 +9892,7 @@ Right arrow. @item \texttrademark @cindex trademark symbol -Trademark symbol: @math{^{\hbox{TM}}}. +Trademark symbol: @BES{2122,^{\hbox{TM}}}. @item \texttwelveudash @cindex two-thirds em-dash @@ -8584,7 +9917,7 @@ Visible space symbol. @cindex characters, accented @cindex letters, accented -@cindex @code{babel} package +@PkgIndex{babel} @cindex multilingual support @LaTeX{} has wide support for many of the world's scripts and languages, through the @code{babel} package and related support. This @@ -8743,16 +10076,20 @@ Produces a h@'a@v{c}ek (check, caron) accent, as in `@v{o}'. @end table -@node Non-English characters -@section Non-English characters +@node Additional Latin letters +@section Additional Latin letters +@anchor{Non-English characters} +@cindex Latin letters, additional +@cindex letters, additional Latin +@cindex extended Latin @cindex special characters @cindex non-English characters @cindex characters, non-English -@cindex letters, non-English -Here are the basic @LaTeX{} commands for inserting characters commonly -used in languages other than English. +Here are the basic @LaTeX{} commands for inserting letters (beyond +A--Z) extending the Latin alphabet, used primarily in languages other +than English. @table @code @item \aa @@ -8775,13 +10112,17 @@ used in languages other than English. @findex \DH (@DH{}) @cindex Icelandic eth @cindex eth, Icelandic letter -Icelandic letter eth: @dh{} and @DH{}. +Icelandic letter eth: @dh{} and @DH{}. Not available with @sc{OT1} +encoding, you need the @file{fontenc} package to select an alternate +font encoding, such as @sc{T1}. @item \dj @itemx \DJ @findex \dj @findex \DJ -Crossed d and D, a.k.a.@: capital and small letter d with stroke. +Crossed d and D, a.k.a.@: capital and small letter d with stroke. Not +available with @sc{OT1} encoding, you need the @file{fontenc} package to +select an alternate font encoding, such as @sc{T1}. @item \ij @itemx \IJ @@ -8801,7 +10142,7 @@ ij and IJ (except somewhat closer together than appears here). @itemx \NG @findex \ng @findex \NG -Latin letter eng, also used in phonetics. +Lappish letter eng, also used in phonetics. @item \o @itemx \O @@ -8831,7 +10172,9 @@ Latin letter eng, also used in phonetics. @findex \TH (@TH{}) @cindex Icelandic thorn @cindex thorn, Icelandic letter -Icelandic letter thorn: @th{} and @TH{}. +Icelandic letter thorn: @th{} and @TH{}. Not available with @sc{OT1} +encoding, you need the @file{fontenc} package to select an alternate +font encoding, such as @sc{T1}. @end table @@ -8869,12 +10212,25 @@ The thickness of the rule (mandatory). @cindex date, today's The @code{\today} command produces today's date, in the format -@samp{@var{month} @var{dd}, @var{yyyy}}; for example, `July 4, 1976'. +@samp{@var{month} @var{dd}, @var{yyyy}}; for example, @samp{July 4, 1976}. It uses the predefined counters @code{\day}, @code{\month}, and @code{\year} (@pxref{\day \month \year}) to do this. It is not updated as the program runs. -@cindex @code{datetime} package +Multilingual packages like @file{babel} or classes like @file{lettre}, +among others, will localize @code{\today}. For example, the following +will output @samp{4 juillet 1976}: + +@example +\year=1976 \month=7 \day=4 +\documentclass@{minimal@} +\usepackage[french]@{babel@} +\begin@{document@} +\today +\end@{document@} +@end example + +@PkgIndex{datetime} The @code{datetime} package, among others, can produce a wide variety of other date formats. @@ -8888,7 +10244,10 @@ of other date formats. A large document requires a lot of input. Rather than putting the whole input in a single large file, it's more efficient to split it into several smaller ones. Regardless of how many separate files you use, -there is one that is the root file; it is the one whose name you type +there is one that is the +@cindex root file +@cindex file, root +@dfn{root file}; it is the one whose name you type when you run @LaTeX{}. @xref{filecontents}, for an environment that allows bundling an @@ -8919,7 +10278,7 @@ command executes @code{\clearpage} to start a new page Given an @code{\includeonly} command, the @code{\include} actions are only run if @var{file} is listed as an argument to -@code{\includeonly}. See the next section. +@code{\includeonly}. See @ref{\includeonly}. @cindex nested @code{\include}, not allowed The @code{\include} command may not appear in the preamble or in a file @@ -8927,7 +10286,7 @@ read by another @code{\include} command. @node \includeonly -@section \@code{includeonly} +@section @code{\includeonly} @findex \includeonly @@ -8939,9 +10298,9 @@ Synopsis: The @code{\includeonly} command controls which files will be read by subsequent @code{\include} commands. The list of filenames is -comma-separated. Each @var{file} must exactly match a filename -specified in a @code{\include} command for the selection to be -effective. +comma-separated. Each element @var{file1}, @var{file2}, @dots{} must +exactly match a filename specified in a @code{\include} command for the +selection to be effective. This command can only appear in the preamble. @@ -9016,15 +10375,21 @@ The command @code{\nofiles} overrides these commands, and @node \addcontentsline @subsection @code{\addcontentsline} -@findex \addcontentsline@{@var{ext}@}@{@var{unit}@}@{@var{text}@} +@findex \addcontentsline @cindex table of contents entry, manually adding -The @code{\addcontentsline}@{@var{ext}@}@{@var{unit}@}@{@var{text}@} -command adds an entry to the specified list or table where: +Synopsis: + +@example +\addcontentsline@{@var{ext}@}@{@var{unit}@}@{@var{text}@} +@end example + +The @code{\addcontentsline} command adds an entry to the specified list +or table where: @table @var @item ext -The extension of the file on which information is to be written, +The filename extension of the file on which information is to be written, typically one of: @code{toc} (table of contents), @code{lof} (list of figures), or @code{lot} (list of tables). @@ -9037,18 +10402,19 @@ following, matching the value of the @var{ext} argument: The name of the sectional unit: @code{part}, @code{chapter}, @code{section}, @code{subsection}, @code{subsubsection}. @item lof -For the list of figures. +For the list of figures: @code{figure}. @item lot -For the list of tables. +For the list of tables: @code{table}. @end table -@item entry +@item text The text of the entry. @end table @findex \contentsline -What is written to the @file{.@var{ext}} file is the -command @code{\contentsline@{@var{unit}@}@{@var{name}@}}. +What is written to the @file{.@var{ext}} file is the command +@code{\contentsline@{@var{unit}@}@{@var{text}@}@{@var{num}@}}, where +@code{@var{num}} is the current value of counter @code{@var{unit}}. @c xx how hardwired are these values? other unit names? @@ -9108,7 +10474,7 @@ the preamble. @findex \index @cindex @file{.idx} file The command @code{\index@{@var{text}@}} writes an index entry for -@var{text} to an auxiliary file with the @file{.idx} extension. +@var{text} to an auxiliary file named with the @file{.idx} extension. @findex \indexentry Specifically, what gets written is the command @@ -9137,23 +10503,23 @@ multi-lingual) @command{xindy} (@url{http://xindy.sourceforge.net}). This results in a @file{.ind} file, which can then be read to typeset the index. -@findex printindex -@cindex @code{makeidx} package +@findex \printindex +@PkgIndex{makeidx} The index is usually generated with the @code{\printindex} command. This is defined in the @code{makeidx} package, so @code{\usepackage@{makeidx@}} needs to be in the preamble. -@findex indexspace +@findex \indexspace The rubber length @code{\indexspace} is inserted before each new letter in the printed index; its default value is @samp{10pt plus5pt minus3pt}. -@cindex @code{showidx} package +@PkgIndex{showidx} The @code{showidx} package causes each index entries to be shown in the margin on the page where the entry appears. This can help in preparing the index. -@cindex @code{multind} package +@PkgIndex{multind} The @code{multind} package supports multiple indexes. See also the @TeX{} FAQ entry on this topic, @url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind}. @@ -9177,7 +10543,7 @@ Synopsis: @var{letter body} \closing@{@var{closing text}@} \end@{letter@} - ... more letters ... +... more letters ... \end@{document@} @end example @@ -9206,13 +10572,13 @@ backslash@tie{}(@code{\\}). @LaTeX{} will put the @var{sender name} under the closing, after a vertical space for the traditional hand-written signature; it also can contain multiple lines. -Each letter environment begins with a required @code{\opening} command +Each @code{letter} environment body begins with a required @code{\opening} command such as @code{\opening@{Dear Madam or Sir:@}}. The @var{letter body} -text is ordinary @LaTeX{} so it can contain everything from from +text is ordinary @LaTeX{} so it can contain everything from enumerated lists to displayed math, except that commands such as @code{\chapter} that make no sense in a letter are turned off. Each -letter environment typically ends with a @code{\closing} command such as -@code{\closing@{Yours,@}}. +@code{letter} environment body typically ends with a @code{\closing} +command such as @code{\closing@{Yours,@}}. @findex \\ @r{for letters} Additional material may come after the @code{\closing}. You can say who @@ -9309,13 +10675,13 @@ Synopsis: @example \cc@{@var{first name} \\ - .. @} + ... @} @end example Produce a list of names to which copies of the letter were sent. This command is optional. If it appears then typically it comes after @code{\closing}. Separate multiple lines with a double -backslash@tie{}@code{\\}. +backslash@tie{}@code{\\}, as in: @example \cc@{President \\ @@ -9333,7 +10699,7 @@ backslash@tie{}@code{\\}. Synopsis: @example -\closing@{text@} +\closing@{@var{text}@} @end example Usually at the end of a letter, above the handwritten signature, there @@ -9354,7 +10720,7 @@ Synopsis: @example \encl@{@var{first enclosed object} \\ - .. @} + ... @} @end example Produce a list of things included with the letter. This command is @@ -9409,6 +10775,8 @@ address}). The @var{sender address} is the value returned by the macro in the argument to the @code{letter} environment. By default @code{\mlabel} ignores the first argument, the @var{sender address}. +@c xxx TODO, align on latex2e-fr.texi, see https://mail.gna.org/public/latexrefman-discuss/2015-10/msg00000.html + @node \name @section @code{\name} @@ -9437,7 +10805,7 @@ Synopsis: @end example This command is required. It starts a letter, following the -@code{\begin@{letter@}@{..@}}. The mandatory argument @var{text} is the +@code{\begin@{letter@}@{...@}}. The mandatory argument @var{text} is the text that starts your letter. For instance: @example @@ -9460,7 +10828,7 @@ Add a postscript. This command is optional and usually is used after @code{\closing}. @example -\ps@{P.S. After you have read this letter, burn it. Or eat it.@} +\ps@{P.S. After you have read this letter, burn it. Or eat it.@} @end example @@ -9471,7 +10839,7 @@ Synopsis: @example \signature@{@var{first line} \\ - .. @} + ... @} @end example @findex \signature @@ -9558,14 +10926,14 @@ page. Synopsis: @example -\typein[@var{\cmd}]@{@var{msg}@} +\typein[\@var{cmd}]@{@var{msg}@} @end example @code{\typein} prints @var{msg} on the terminal and causes @LaTeX{} to stop and wait for you to type a line of input, ending with return. If -the optional @var{\cmd} argument is omitted, the typed input is +the optional @code{\@var{cmd}} argument is omitted, the typed input is processed as if it had been included in the input file in place of the -@code{\typein} command. If the @var{\cmd} argument is present, it +@code{\typein} command. If the @code{\@var{cmd}} argument is present, it must be a command name. This command name is then defined or redefined to be the typed input. @@ -9716,6 +11084,7 @@ The end. @verbatim \documentclass{ltugboat} + \usepackage{graphicx} \usepackage{ifpdf} \ifpdf @@ -9724,6 +11093,8 @@ The end. \usepackage{url} \fi +%%% Start of metadata %%% + \title{Example \TUB\ article} % repeat info for each author. @@ -9732,51 +11103,56 @@ The end. \netaddress{user (at) example dot org} \personalURL{http://example.org/~user/} +%%% End of metadata %%% + \begin{document} \maketitle \begin{abstract} This is an example article for \TUB{}. +Please write an abstract. \end{abstract} \section{Introduction} -This is an example article for \TUB, from +This is an example article for \TUB, linked from \url{http://tug.org/TUGboat/location.html}. We recommend the \texttt{graphicx} package for image inclusions, and the -\texttt{hyperref} package for active urls in the \acro{PDF} output. -Nowadays \TUB\ is produced using \acro{PDF} files exclusively. - -The \texttt{ltugboat} class provides these abbreviations and many more: +\texttt{hyperref} package if active urls are desired (in the \acro{PDF} +output). Nowadays \TUB\ is produced using \acro{PDF} files exclusively. +The \texttt{ltugboat} class provides these abbreviations (and many more): % verbatim blocks are often better in \small \begin{verbatim}[\small] \AllTeX \AMS \AmS \AmSLaTeX \AmSTeX \aw \AW \BibTeX \CTAN \DTD \HTML \ISBN \ISSN \LaTeXe -\Mc \mf \MFB \mtex \PCTeX \pcTeX -\PiC \PiCTeX \plain \POBox \PS -\SC \SGML \SliTeX \TANGLE \TB \TP +\mf \MFB +\plain \POBox \PS +\SGML \TANGLE \TB \TP \TUB \TUG \tug -\UG \UNIX \VAX \XeT \WEB \WEAVE +\UNIX \XeT \WEB \WEAVE -\Dash \dash \vellipsis \bull \cents \Dag -\careof \thinskip +\, \bull \Dash \dash \hyph \acro{FRED} -> {\small[er] fred} % please use! \cs{fred} -> \fred -\env{fred} -> \begin{fred} \meta{fred} -> <fred> \nth{n} -> 1st, 2nd, ... \sfrac{3/4} -> 3/4 \booktitle{Book of Fred} \end{verbatim} -For more information, see the ltubguid document at: -\url{http://mirror.ctan.org/macros/latex/contrib/tugboat} -(we recommend using \verb|mirror.ctan.org| for \CTAN\ references). +For references to other \TUB\ issue, please use the format +\textsl{volno:issno}, e.g., ``\TUB\ 32:1'' for our \nth{100} issue. + +This file is just a template. The \TUB\ style documentation is the +\texttt{ltubguid} document at \url{http://ctan.org/pkg/tugboat}. (For +\CTAN\ references, where sensible we recommend that form of url, using +\texttt{/pkg/}; or, if you need to refer to a specific file location, +\texttt{http://mirror.ctan.org/\textsl{path}}.) Email \verb|tugboat@tug.org| if problems or questions. |