[latexrefman-commits] [SCM] latexrefman updated: r1159 - trunk
Karl Berry
INVALID.NOREPLY at gnu.org.ua
Sat Sep 30 18:43:58 CEST 2023
Author: karl
Date: 2023-09-30 16:43:58 +0000 (Sat, 30 Sep 2023)
New Revision: 1159
Modified:
trunk/ChangeLog
trunk/NEWS
trunk/aspell.en.pws
trunk/latex2e.texi
Log:
split table of clsguide commands into sections; mention \DocumentMetadata
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2023-08-28 01:05:56 UTC (rev 1158)
+++ trunk/ChangeLog 2023-09-30 16:43:58 UTC (rev 1159)
@@ -1,3 +1,15 @@
+2023-09-30 Karl Berry <karl at freefriends.org>
+
+ * latex2e.texi (Overview): give mailing list url.
+ (Environment): rename to Environment syntax.
+ (\DocumentMetadata): new node.
+ (Class and package structure): use ctan.org/pkg/clsguide.
+ (Class and package commands): move to Definitions chapter;
+ rewrite as separate sections.
+ (Graphics): move chapter to before Color.
+ Throughout: avoid xxx as example string, since we use xx
+ as the todo marker.
+
2023-08-27 Karl Berry <karl at freefriends.org>
* latex2e.texi (\thepage): simplify, as it turns out that
Modified: trunk/NEWS
===================================================================
--- trunk/NEWS 2023-08-28 01:05:56 UTC (rev 1158)
+++ trunk/NEWS 2023-09-30 16:43:58 UTC (rev 1159)
@@ -7,10 +7,15 @@
Updates are welcome.
Additions:
+* \DocumentMetadata for experimental tagging support.
* \thepage for page number representation.
* \nobreakspace and U+00A0 synonyms for ties.
* The (simple) \slash command.
+Changes:
+* The lengthy list of commands for class and package writers, from
+clsguide, now split into sections instead of being one long table.
+
Notable changes in January 2023 release:
Additions:
Modified: trunk/aspell.en.pws
===================================================================
--- trunk/aspell.en.pws 2023-08-28 01:05:56 UTC (rev 1158)
+++ trunk/aspell.en.pws 2023-09-30 16:43:58 UTC (rev 1159)
@@ -290,3 +290,7 @@
vitalism
tablefootnote
Infimum
+atenddvi
+envname
+un
+documentmetadata
Modified: trunk/latex2e.texi
===================================================================
--- trunk/latex2e.texi 2023-08-28 01:05:56 UTC (rev 1158)
+++ trunk/latex2e.texi 2023-09-30 16:43:58 UTC (rev 1159)
@@ -2,7 +2,7 @@
@c $Id$
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename latex2e.info
- at set UPDATED July 2023
+ at set UPDATED September 2023
@include common.texi
@settitle @LaTeX{}2e unofficial reference manual (@value{UPDATED})
@comment %**end of header (This is for running Texinfo on a region.)
@@ -206,8 +206,8 @@
* Page styles:: Various styles of page layout.
* Spaces:: Horizontal and vertical space.
* Boxes:: Making boxes.
+* Graphics:: Importing graphics from outside @LaTeX{}.
* Color:: Defining and using colors.
-* Graphics:: Importing graphics from outside @LaTeX{}.
* Special insertions:: Inserting reserved and special characters.
* Splitting the input:: Dealing with big files by splitting.
* Front/back matter:: Tables of contents, glossaries, indexes.
@@ -249,6 +249,8 @@
@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 is a public list; you can (un)subscribe, view the archives, etc.,
+at @url{https://lists.tug.org/latexrefman}.
This document is a reference, not a tutorial. There is a vast array
of other information available about @LaTeX{}, at all levels. Here
@@ -268,8 +270,7 @@
A longer introduction to @LaTeX{}, translated to many languages.
@item https://tug.org/begin.html
-Introduction to the @TeX{} system, including @LaTeX{}, with further
-references.
+Overview of getting started with @TeX{} and @LaTeX{}.
@end table
@@ -317,8 +318,8 @@
* Output files:: Files produced.
* @TeX{} engines:: Programs that can compile @TeX{} and @LaTeX{}.
* @LaTeX{} command syntax:: General syntax of @LaTeX{} commands.
-* Environment:: An area of the source with distinct behavior.
-* CTAN:: Our repository.
+* Environment syntax:: \begin@{envname@} ... \end@{envname@}.
+* CTAN:: The TeX world's general repository.
@end menu
@@ -613,8 +614,8 @@
syntax. We won't try to cover them in this document; see the related
package documentation and other @LaTeX{} manuals.
- at node Environment
- at section Environment
+ at node Environment syntax
+ at section Environment syntax
Synopsis:
@@ -656,6 +657,44 @@
@end example
+ at node \DocumentMetadata
+ at section @code{\DocumentMetadata}: Producing tagged PDF output
+
+ at findex \DocumentMetadata
+ at cindex tagged PDF
+ at cindex PDF, tagged
+ at cindex metadata, adding
+ at cindex accessibility
+
+The @code{\DocumentMetadata} command was added to @LaTeX{} in 2022.
+It enables so-called ``tagging'' of the PDF output, aiding
+accessibility of the PDF.
+
+It is unlike nearly any other command in @LaTeX{} in that it must
+occur before the @code{\documentclass} command that starts a @LaTeX{}
+document proper (@pxref{\documentclass}). Therefore it must be
+called with @code{\RequirePackage} rather than @code{\usepackage}
+(@pxref{\RequirePackage}).
+
+ at PkgIndex{latex-lab}
+ at findex documentmetadata-support-doc @r{document}
+This support is still in development, so we will not try to list all
+the possible settings. Please see the
+ at code{documentmetadata-support-doc} document, part of the
+ at code{latex-lab} package (@url{https://ctan.org/pkg/latex-lab}). Here
+is a simple example which enables most tagging currently implemented:
+
+ at example
+\DocumentMetadata@{testphase=@{phase-III,firstaid@}@}
+\documentclass@{article@}
+...
+ at end example
+
+As you can see from the key name @code{testphase}, this is all still
+in an experimental phase. But the @LaTeX{} developers strongly
+encourage users to give it a try and report problems.
+
+
@node CTAN
@section CTAN: The Comprehensive @TeX{} Archive Network
@@ -693,12 +732,14 @@
@node Document classes
@chapter Document classes
+ at anchor{\documentclass}
@cindex document classes
@cindex classes of documents
@findex \documentclass
-The document's overall class is defined with this command, which is
-normally the first command in a @LaTeX{} source file.
+The document's overall class is defined with the @code{\documentclass}
+command, which is normally the first command in a @LaTeX{} source
+file.
@example
\documentclass[@var{options}]@{@var{class}@}
@@ -710,8 +751,8 @@
@findex letter @r{class}
@findex slides @r{class}
The following document @var{class} names are built into @LaTeX{}.
-(Many other document classes are available as separate packages;
- at pxref{Overview}.)
+Many other document classes are available as separate packages
+(@pxref{Overview}).
@table @code
@item article
@@ -737,7 +778,7 @@
@item slides
@anchor{document classes slides}
For slide presentations---rarely used nowadays. The
- at package{beamer} package is perhaps the most prevalent
+ at package{beamer} package is perhaps the most prevalent replacement
(@url{https://ctan.org/pkg/beamer}). @xref{beamer template}, for a
small template for a beamer document.
@@ -746,9 +787,9 @@
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.
+* Document class options:: Global options.
+* \usepackage:: Bring in additional packages.
+* Class and package creation:: Writing new classes and packages.
@end menu
@@ -768,6 +809,10 @@
\documentclass[@var{option1}, at var{option2},...]@{@var{class}@}
@end example
+ at LaTeX{} automatically passes options specified for
+ at code{\documentclass} on to any other loaded classes that can handle
+them.
+
Here is the list of the standard class options.
@findex 10pt @r{option}
@@ -774,7 +819,7 @@
@findex 11pt @r{option}
@findex 12pt @r{option}
All of the standard classes except @code{slides} accept the following
-options for selecting the typeface size (default is @code{10pt}):
+options for selecting the typeface size; the default is @code{10pt}:
@example
10pt 11pt 12pt
@@ -787,7 +832,7 @@
@findex legalpaper @r{option}
@findex letterpaper @r{option}
All of the standard classes accept these options for selecting the paper
-size (these show height by width):
+size (dimensions are listed height by width):
@table @code
@item a4paper
@@ -815,7 +860,7 @@
When using one of the engines pdf at LaTeX{}, Lua at LaTeX{}, or Xe at LaTeX{}
(@pxref{@TeX{} engines}), options other than @code{letterpaper} set
the print area but you must also set the physical paper size. Usually,
-The @package{geometry} package is the best way to do that; it
+the @package{geometry} package is the best way to do that; it
provides flexible ways of setting the print area and physical page size.
Otherwise, setting the paper size is engine-dependent. For example,
with pdf at LaTeX{}, you could include @code{\pdfpagewidth=\paperwidth} and
@@ -907,18 +952,19 @@
the time at the bottom of each note.
- at node Additional packages
- at section Additional packages
+ at node \usepackage
+ at section @code{\usepackage}: Additional packages
+ at anchor{Additional packages}@c original node name
@cindex loading additional packages
@cindex packages, loading additional
@cindex additional packages, loading
@findex \usepackage
-Load a package @var{pkg}, with the package options given in the comma-separated
-list @var{options}, as here.
+To load a package @var{pkg}, with the package options given in the
+comma-separated list @var{options}:
@example
-\usepackage[@var{options}]@{@var{pkg}@}.
+\usepackage[@var{options}]@{@var{pkg}@}[@var{mindate}]
@end example
To specify more than one package you can separate them with a comma,
@@ -925,15 +971,26 @@
as in @code{\usepackage@{@var{pkg1}, at var{pkg2},...@}}, or use multiple
@code{\usepackage} commands.
+If the @var{mindate} optional argument is given, @LaTeX{} gives a
+warning if the loaded package has an earlier date, i.e., is too old.
+The @var{mindate} argument must be in the form @code{YYYY/MM/DD}.
+More info on this: @url{https://tex.stackexchange.com/questions/47743}.
+
+ at code{\usepackage} must be used in the document preamble, between the
+ at code{\documentclass} declaration and the @code{\begin@{document@}}.
+Occasionally it is necessary to load packages before the
+ at code{\documentclass}; see @code{\RequirePackage} for that
+(@pxref{\RequirePackage}).
+
@cindex global options
@cindex options, global
-Any options given in the @code{\documentclass} command that are unknown
-to the selected document class are passed on to the packages loaded with
- at code{\usepackage}.
+Any options given in the global @code{\documentclass} command that are
+unknown to the selected document class are passed on to the packages
+loaded with @code{\usepackage}.
- at node Class and package construction
- at section Class and package construction
+ at node Class and package creation
+ at section Class and package creation
@cindex document class commands
@cindex commands, document class
@@ -945,28 +1002,29 @@
@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
+What separates a package from a document class is that the commands in
+a package are useful across classes while those in a document class
+are specific to that class. Thus, a command to set page headers is
+for a package while a command to make the page headers be
+ at code{Memo from the SMC Math Department} is for a class.
-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
- at code{\makeatother}. @xref{\makeatletter & \makeatother}. This allow
-you to create commands that users will not accidentally redefine.
-Another technique is to preface class- or package-specific commands with
-some string to prevent your class or package from interfering with
-others. For instance, the class @code{smcmemo} might have commands
+Inside of a class or package definition you can use the at-sign
+ at code{@@} as a character in command names without having to surround
+the code containing that command with @code{\makeatletter} and
+ at code{\makeatother} (@pxref{\makeatletter & \makeatother}). This
+allows you to create commands that users will not accidentally
+redefine.
+
+It is also highly desirable to prefix class- or package-specific
+commands with your package name or similar string, to prevent your
+definitions from clashing with those from other packages. For
+instance, the class @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
@@ -982,6 +1040,7 @@
@cindex package options
A class file or package file typically has four parts.
+
@enumerate
@item
In the @dfn{identification part}, the file says that it is a @LaTeX{}
@@ -1012,6 +1071,7 @@
fonts, and loading other files.
@end enumerate
+ at cindex class file example
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.
@@ -1023,7 +1083,6 @@
\ProcessOptions\relax
\LoadClass@{article@}
@end example
- at cindex class file example
@noindent
It identifies itself, handles the class options via the default of
@@ -1030,438 +1089,18 @@
passing them all to the @code{article} class, and then loads the
@code{article} class to provide the basis for this class's code.
+ at findex clsguide @r{document}
+ at cindex Class Guide, document
+ at cindex class writing tutorial document
For more, see the official guide for class and package writers, the
-Class Guide, at
- at url{https://www.latex-project.org/help/documentation/clsguide.pdf} (much
-of the descriptions here derive from this document), or the tutorial
- at url{https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf}.
+Class Guide, at @url{https://ctan.org/pkg/clsguide} (much of the
+description here derives from this document), or the tutorial at
+ at url{https://tug.org/TUGboat/tb26-3/tb84heff.pdf}.
+ at xref{Class and package commands}, for some of the commands
+specifically intended for class and package writers.
- at node Class and package commands
- at subsection Class and package commands
- at cindex class and package commands
- at cindex commands, class and package
-These are the commands designed to help writers of classes or packages.
-
- at table @code
- at item \AtBeginDvi@{specials@}
- at 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.
-
- at item \AtEndOfClass@{@var{code}@}
- at itemx \AtEndOfPackage@{@var{code}@}
- at findex \AtEndOfClass
- at 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}.
-
- at item \CheckCommand@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@}
- at itemx \CheckCommand*@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@}
- at findex \CheckCommand
- at findex \CheckCommand*
- at cindex new command, checking
-Like @code{\newcommand} (@pxref{\newcommand & \renewcommand}) but does
-not define @var{cmd}; instead it checks that the current definition of
- at var{cmd} is exactly as given by @var{definition} and is or is not
- at cindex long command
- at dfn{long} as expected. A long command is a command that accepts
- at 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.
-
- at item \ClassError@{@var{class name}@}@{@var{error text}@}@{@var{help text}@}
- at itemx \ClassWarning@{@var{class name}@}@{@var{warning text}@}
- at itemx \ClassWarningNoLine@{@var{class name}@}@{@var{warning text}@}
- at itemx \ClassInfo@{@var{class name}@}@{@var{info text}@}
- at itemx \ClassInfoNoLine@{@var{class name}@}@{@var{info text}@}
- at itemx \PackageError@{@var{package name}@}@{@var{error text}@}@{@var{help text}@}
- at itemx \PackageWarning@{@var{package name}@}@{@var{warning text}@}
- at itemx \PackageWarningNoLine@{@var{package name}@}@{@var{warning text}@}
- at itemx \PackageInfo@{@var{package name}@}@{@var{info text}@}
- at itemx \PackageInfoNoLine@{@var{package name}@}@{@var{info text}@}
- at findex \ClassError
- at findex \PackageError
- at findex \ClassWarning
- at findex \PackageWarning
- at findex \ClassWarningNoLine
- at findex \PackageWarningNoLine
- at findex \ClassInfo
- at findex \PackageInfo
- at findex \ClassInfoNoLine
- at findex \PackageInfoNoLine
-Produce an error message, or warning or informational messages.
-
-For @code{\ClassError} and @code{\PackageError} the message is
- at 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
- at var{warning text} on the screen with no error prompt. The four info
-commands write @var{info text} only in the transcript file. The
- at 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
- at code{\protect} to stop a command from expanding, get a line break with
- at 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.
-
- at item \CurrentOption
- at 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*}.
-
- at item \DeclareOption@{@var{option}@}@{@var{code}@}
- at itemx \DeclareOption*@{@var{code}@}
- at findex \DeclareOption
- at findex \DeclareOption*
- at cindex class options
- at cindex package options
- at cindex options, class
- at cindex options, package
-Make an option available to a user to invoke in their
- at code{\documentclass} command. For example, the @code{smcmemo} class
-could have an option @code{\documentclass[logo]@{smcmemo@}} allowing
-users to put the institutional logo on the first page. The class file
-must contain @code{\DeclareOption@{logo@}@{@var{code}@}} (and later,
- at 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 behavior with the starred version
- at code{\DeclareOption*@{@var{code}@}}. For example, many classes
-extend an existing class, using a command such as
- at code{\LoadClass@{article@}}, and for passing extra options to the
-underlying class use code such as this.
-
- at example
-\DeclareOption*@{%
-\PassOptionsToClass@{\CurrentOption@}@{article@}%
-@}
- at 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
- at code{\documentclass[math]@{smcmemo@}} and it will read the file
- at code{math.memo}. This code handles the file if it exists and otherwise
-passes the option to the @code{article} class.
-
- at example
-\DeclareOption*@{\InputIfFileExists@{\CurrentOption.memo@}@{@}@{%
- \PassOptionsToClass@{\CurrentOption@}@{article@}@}@}
- at end example
-
- at item \DeclareRobustCommand@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@}
- at item* \DeclareRobustCommand*@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@}
- at findex \DeclareRobustCommand
- at findex \DeclareRobustCommand*
- at 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
- at 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}.
-
- at PkgIndex{etoolbox} The @package{etoolbox} package offers the commands
- at code{\newrobustcmd}, @code{\newrobustcmd*}, as well as the commands
- at code{\renewrobustcmd}, @code{\renewrobustcmd*}, and the commands
- at code{\providerobustcmd}, and @code{\providerobustcmd*}. These are
-similar to @code{\newcommand}, @code{\newcommand*},
- at code{\renewcommand}, @code{\renewcommand*}, @code{\providecommand}, and
- at code{\providecommand*}, but define a robust @var{cmd} with two
-advantages as compared to @code{\DeclareRobustCommand}:
- at enumerate
- at item
-They use the low-level e- at 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
- at item
-They make the same distinction between @code{\new at dots{}},
- at code{\renew at dots{}}, and @code{\provide at dots{}}, as the standard
-commands, so they do not just make a log message when you redefine
- at var{cmd} that already exists, in that case you need to use either
- at code{\renew at dots{}} or @code{\provide at dots{}} or you get an error.
- at end enumerate
-
- at item \IfFileExists@{@var{filename}@}@{@var{true code}@}@{@var{false code}@}
- at itemx \InputIfFileExists@{@var{filename}@}@{@var{true code}@}@{@var{false code}@}
- at findex \IfFileExists
- at findex \InputIfFileExists
-Execute @var{true code} if @LaTeX{} finds the file @file{@var{file
-name}} or @var{false code} otherwise. In the first case it executing
- at var{true code} and then inputs the file. Thus the command
-
- at example
-\IfFileExists@{img.pdf@}@{%
- \includegraphics@{img.pdf@}@}@{\typeout@{!! img.pdf not found@}
- at end example
-
- at noindent
-will include the graphic @file{img.pdf} if it is found and otherwise
-give a warning.
-
-This command looks for the file in all search paths that @LaTeX{} uses,
-not only in the current directory. To look only in the current
-directory do something like @code{\IfFileExists@{./filename@}@{@var{true
-code}@}@{@var{false code}@}}. If you ask for a filename without a
- at 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}.
-
- at item \LoadClass[@var{options list}]@{@var{class name}@}[@var{release date}]
- at itemx \LoadClassWithOptions@{@var{class name}@}[@var{release date}]
- at findex \LoadClass
- at findex \LoadClassWithOptions
-Load a class, as with @code{\documentclass[@var{options
-list}]@{@var{class name}@}[@var{release info}]}. An example is
- at code{\LoadClass[twoside]@{article@}}.
-
-The @var{options list}, if present, is a comma-separated list. The
- at var{release date} is optional. If present it must have the form
- at var{YYYY/MM/DD}.
- at c BTW, there are at-macros documented in macros2e.pdf to check the version
- at c and do some actions conditionnally on version later or not to some
- at c date.
-
-If you request a @var{release date} and the date of the package
-installed on your system is earlier, then you get a warning on the
-screen and in the log like this.
-
- at example
-You have requested, on input line 4, version `2038/01/19' of
-document class article, but only version `2014/09/29 v1.4h
-Standard LaTeX document class' is available.
- at end example
-
-The command version @code{\LoadClassWithOptions} uses the list of
-options for the current class. This means it ignores any options passed
-to it via @code{\PassOptionsToClass}. This is a convenience command
-that lets you build classes on existing ones, such as the standard
- at code{article} class, without having to track which options were passed.
-
- at item \ExecuteOptions@{@var{options-list}@}
- at 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
- at code{\ProcessOptions}. For example, if in a class file you want the
-default to be 11pt fonts then you could specify
- at code{\ExecuteOptions@{11pt@}\ProcessOptions\relax}.
-
- at item \NeedsTeXFormat@{@var{format}@}[@var{format date}]
- at 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:
- at 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
- at var{format date} then you get a warning like this.
-
- at example
-You have requested release `2038/01/20' of LaTeX, but only
-release `2016/02/01' is available.
- at end example
-
- at item \OptionNotUsed
- at 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
- at code{\DeclareOption*}.
-
- at c I cannot reproduce this behavior as it is documented in clsguide.
- at c In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues
- at c on the console a warning like @code{LaTeX Warning: Unused global
- at c option(s): [unusedoption].} with the list of not-used options when it
- at c reaches @code{\begin@{document@}}.
-
- at item \PassOptionsToClass@{@var{option list}@}@{@var{class name}@}
- at itemx \PassOptionsToPackage@{@var{option list}@}@{@var{package name}@}
- at findex \PassOptionsToClass
- at 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
- at code{\RequirePackage[landscape]@{geometry@}} and
- at code{\RequirePackage[margins=1in]@{geometry@}} with the single command
- at code{\RequirePackage[landscape,margins=1in]@{geometry@}}.
-
-However, imagine that you are loading @file{firstpkg} and inside that
-package it loads @file{secondpkg}, and you need the second package to be
-loaded with option @code{draft}. Then before doing the first package
-you must queue up the options for the second package, like this.
-
- at example
-\PassOptionsToPackage@{draft@}@{secondpkg@}
-\RequirePackage@{firstpkg@}
- at end example
-
- at noindent
-(If @code{firstpkg.sty} loads an option in conflict with what you want
-then you may have to alter its source.)
-
-These commands are useful for general users as well as class and package
-writers. For instance, suppose a user wants to load the @code{graphicx}
-package with the option @code{draft} and also wants to use a class
- at code{foo} that loads the @code{graphicx} package, but without that
-option. The user could start their @LaTeX{} file with
- at code{\PassOptionsToPackage@{draft@}@{graphicx@}\documentclass@{foo@}}.
-
- at item \ProcessOptions
- at itemx \ProcessOptions*@var{\@@options}
- at findex \ProcessOptions
- at 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
- at code{\PassOptionsToPackage@{@var{options}@}},
- at code{\usepackage[@var{options}]}, or
- at 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:
- at enumerate
- at 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}.
- at item
-For each remaining local option, it executes the command
- at 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.
- at 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
- at 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.
-
- at item \ProvidesClass@{@var{class name}@}[@var{release date} @var{brief additional information}]
- at itemx \ProvidesClass@{@var{class name}@}[@var{release date}]
- at itemx \ProvidesPackage@{@var{package name}@}[@var{release date} @var{brief additional information}]
- at itemx \ProvidesPackage@{@var{package name}@}[@var{release date}]
- at findex \ProvidesClass
- at findex \ProvidesPackage
-Identifies the class or package, printing a message to the screen and
-the log file.
-
-When you load a class or package, for example with
- at code{\documentclass@{smcmemo@}} or @code{\usepackage@{test@}}, @LaTeX{}
-inputs a file. If the name of the file does not match the class or
-package name declared in it then you get a warning. Thus, if you invoke
- at code{\documentclass@{smcmemo@}}, and the file @file{smcmemo.cls} has
-the statement @code{\ProvidesClass@{xxx@}} then you get a warning like
- at code{You have requested document class `smcmemo', but the document
-class provides 'xxx'.} This warning does not prevent @LaTeX{} from
-processing the rest of the class file normally.
-
-If you include the optional argument then you must include a date,
-before any spaces, of the form @code{YYYY/MM/DD}. The rest of the
-optional argument is free-form, although it traditionally identifies the
-class, and is written to the screen during compilation and to the log
-file. Thus, if your file @file{smcmemo.cls} contains the line
- at code{\ProvidesClass@{smcmemo@}[2008/06/01 v1.0 SMC memo class]} and
-your document's first line is @code{\documentclass@{smcmemo@}} then you
-will see @code{Document Class: smcmemo 2008/06/01 v1.0 SMC memo class}.
-
-The date in the optional argument allows class and package users to ask
-to be warned if the version of the class or package is earlier than
- at var{release date}. For instance, a user could enter
- at code{\documentclass@{smcmemo@}[2018/10/12]} or
- at code{\usepackage@{foo@}[[2017/07/07]]} to require a class or package
-with certain features by specifying that it must be released no earlier
-than the given date. (Although, in practice package users only rarely
-include a date, and class users almost never do.)
-
- at item \ProvidesFile@{@var{filename}@}[@var{additional information}]
- at 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{filename} equal to
- at samp{test.config} and @var{additional information} equal to
- at samp{2017/10/12 config file for test.cls}.
-
- at item \RequirePackage[@var{option list}]@{@var{package name}@}[@var{release date}]
- at itemx \RequirePackageWithOptions@{@var{package name}@}[@var{release date}]
- at findex \RequirePackage
- at findex \RequirePackageWithOptions
-Load a package, like the command @code{\usepackage} (@pxref{Additional
-packages}). The @LaTeX{} development team strongly recommends use of
-these commands over Plain at tie{}@TeX{}'s @code{\input}; see the Class
-Guide. An example is
- at code{\RequirePackage[landscape,margin=1in]@{geometry@}}.
-
-The @var{option list}, if present, is a comma-separated list. The
- at 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.
- at end table
-
-
@node Fonts
@chapter Fonts
@anchor{Typefaces}@c old name
@@ -4123,7 +3762,7 @@
@node \@@startsection
- at section @code{\@@startsection}, typesetting sectional unit headings
+ at section @code{\@@startsection}: Typesetting sectional unit headings
@findex \@@startsection
@cindex section, redefining
@@ -9594,7 +9233,7 @@
Little is known other than her death.@}%
\stepcounter@{mpFootnoteValueSaver@}%
\footnotetext[\value@{mpFootnoteValueSaver@}]@{%
- Relationship is unresolved in XXI.@}
+ Relationship is unresolved.@}
\end@{center@}
@end example
@@ -9694,7 +9333,7 @@
@end example
@noindent
-or all the same possibilities with @code{\renewcommand} instead of
+or the same six possibilities with @code{\renewcommand} instead of
@code{\newcommand}:
@example
@@ -9712,11 +9351,11 @@
@cindex starred form, defining new commands
@cindex *-form, defining new commands
- at findex \long
+ at findex \long at r{, not defining a command as}
The starred form of these two forbids the arguments from containing
-multiple paragraphs of text (in plain @TeX{} terms: the commands
-are not @code{\long}). With the default form, arguments can be
-multiple paragraphs.
+multiple paragraphs of text (i.e., a @code{\par} token; in plain
+ at TeX{} terms: the commands are not @code{\long}). With the default
+form, arguments can be multiple paragraphs.
These are the parameters (examples follow):
@@ -10735,7 +10374,7 @@
@node xspace package
- at section xspace package
+ at section @code{xspace} package
@findex \xspace
@PkgIndex{xspace}
@@ -10742,7 +10381,7 @@
@cindex spaces, ignore around commands
@cindex commands, ignore spaces
-Synopsis:
+This is an add-on package, not part of core @LaTeX{}. Synopsis:
@example
\usepackage@{xspace@}
@@ -10754,16 +10393,16 @@
adds a space unless the command is followed by certain punctuation
characters.
-After a command control sequence that is a control word (@pxref{Control
+After a control sequence that is a control word (@pxref{Control
sequences}, as opposed to control symbols such as @code{\$}), @TeX{}
-gobbles blank characters. Thus, in the first sentence below, the output
-has @samp{Vermont} placed snugly against the period, without any
-intervening space.
+gobbles blank characters. Thus, in the first sentence below, the
+output has @samp{Vermont} placed snugly against the period, without
+any intervening space, despite the space in the input.
@example
\newcommand@{\VT@}@{Vermont@}
Our college is in \VT .
-The \VT@{@} summers are nice.
+\VT@{@} summers are nice.
@end example
But because of the gobbling, the second sentence needs the empty curly
@@ -10785,10 +10424,10 @@
The default exception list contains the characters @code{,.'/?;:!~-)},
the open curly brace and the backslash-space command discussed above,
-and the commands @code{\footnote} or @code{\footnotemark}. Add to that
-list as with @code{\xspaceaddexceptions@{\myfni \myfnii@}} which adds
- at code{\myfni} and at tie{}@code{\myfnii} to the list, and remove from that
-list as with @code{\xspaceremoveexception@{!@}}.
+and the commands @code{\footnote} or @code{\footnotemark}. You can
+add to that list as with @code{\xspaceaddexceptions@{\myfni \myfnii@}}
+which adds @code{\myfni} and at tie{}@code{\myfnii} to the list; and you
+can remove from that list as with @code{\xspaceremoveexception@{!@}}.
@c David Carlisle https://tex.stackexchange.com/a/86620/339
A comment: many experts prefer not to use @code{\xspace}. Putting it in
@@ -10796,9 +10435,722 @@
But it isn't easy to predict when to enter empty braces because
@code{\xspace} will get it wrong, such as when it is followed by another
command, and so @code{\xspace} can make editing material harder and more
-error-prone than instead always inserting the empty braces.
+error-prone than instead of always inserting the empty braces.
+ at node Class and package commands
+ at section Class and package commands
+
+ at cindex class and package commands
+ at cindex package and class commands
+ at cindex commands, class and package
+
+These are commands designed to help writers of classes or packages.
+
+ at menu
+ at end menu
+
+ at node \AtBeginDvi & \AtEndDvi
+ at subsection @code{\AtBeginDvi} & @code{\AtEndDvi}
+
+ at anchor{\AtBeginDvi}
+ at anchor{\AtEndDvi}
+ at findex \AtBeginDvi
+ at findex \AtEndDvi
+
+Synopsis:
+
+ at example
+\AtBeginDvi@{@var{code}@}
+\AtEndDvi@{@var{code}@}
+ at end example
+
+ at code{\AtBeginDvi} saves, in a box register, @var{code} to be executed
+at the beginning of the shipout of the first page of the document.
+Despite the name, it applies to DVI, PDF, and XDV output. It fills
+the @code{shipout/firstpage} hook; new code should use that hook
+directly.
+
+ at PkgIndex{atenddvi}
+Similarly, @code{\AtEndDvi} (previously available only with the
+ at code{atenddvi} package) is code executed when finalizing the main
+output document.
+
+
+ at node \AtEndOfClass & \AtEndOfPackage
+ at subsection @code{\AtEndOfClass} & @code{\AtEndOfPackage}
+
+ at anchor{\AtEndOfClass}
+ at anchor{\AtEndOfPackage}
+ at findex \AtEndOfClass
+ at findex \AtEndOfPackage
+
+Synopses:
+
+ at example
+\AtEndOfClass@{@var{code}@}
+\AtEndOfPackage@{@var{code}@}
+ at end example
+
+Hooks to insert @var{code} to be executed when @LaTeX{} finishes
+processing the current class resp.@: package.
+
+These hooks can be used multiple times; each @code{code} segment will
+be executed in the order called. Many packages and classes use these
+commands.
+
+See also @ref{\AtBeginDocument}.
+
+
+ at node \CheckCommand
+ at subsection @code{\CheckCommand}
+
+ at findex \CheckCommand
+ at cindex new command, checking definition of
+ at cindex long command
+ at cindex @code{\long} command, checking for
+
+Synopsis:
+
+ at example
+\CheckCommand@{@var{cmd}@}[@var{num}][@var{default}]@{@var{definition}@}
+\CheckCommand* @r{(same parameters)}
+ at end example
+
+Like @code{\newcommand} (@pxref{\newcommand & \renewcommand}) but does
+not define @var{cmd}; instead it checks that the current definition of
+ at var{cmd} is exactly as given by @var{definition} and is or is not
+ at dfn{@code{\long}} as expected. A long command is a command that
+accepts @code{\par} within an argument.
+
+With the unstarred version of @code{\CheckCommand}, @var{cmd} is
+expected to be @code{\long}; with the starred version, @var{cmd} must
+not be @code{\long}
+
+ at 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.
+
+
+ at node \ClassError and \PackageError and others
+ at subsection @code{\ClassError} and @code{\PackageError} and others
+
+ at anchor{\ClassError}
+ at anchor{\ClassWarning}
+ at anchor{\ClassWarningNoLine}
+ at anchor{\ClassInfo}
+ at anchor{\ClassInfoNoLine}
+ at anchor{\PackageError}
+ at anchor{\PackageWarning}
+ at anchor{\PackageWarningNoLine}
+ at anchor{\PackageInfo}
+ at anchor{\PackageInfoNoLine}
+
+Produce error, warning, and informational messages for classes:
+
+ at table @code
+ at item \ClassError@{@var{class name}@}@{@var{error-text}@}@{@var{help-text}@}
+ at itemx \ClassWarning@{@var{class name}@}@{@var{warning-text}@}
+ at itemx \ClassWarningNoLine@{@var{class name}@}@{@var{warning-text}@}
+ at itemx \ClassInfo@{@var{class name}@}@{@var{info-text}@}
+ at itemx \ClassInfoNoLine@{@var{class name}@}@{@var{info-text}@}
+ at findex \ClassError
+ at findex \ClassWarning
+ at findex \ClassWarningNoLine
+ at findex \ClassInfo
+ at findex \ClassInfoNoLine
+ at end table
+
+ at noindent and the same for packages:
+ at table @code
+ at item \PackageError@{@var{package name}@}@{@var{error-text}@}@{@var{help-text}@}
+ at itemx \PackageWarning@{@var{package name}@}@{@var{warning-text}@}
+ at itemx \PackageWarningNoLine@{@var{package name}@}@{@var{warning-text}@}
+ at itemx \PackageInfo@{@var{package name}@}@{@var{info-text}@}
+ at itemx \PackageInfoNoLine@{@var{package name}@}@{@var{info-text}@}
+ at findex \PackageError
+ at findex \PackageWarning
+ at findex \PackageWarningNoLine
+ at findex \PackageInfo
+ at findex \PackageInfoNoLine
+ at end table
+
+For @code{\ClassError} and @code{\PackageError} the message is
+ at 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 @code{Warning} commands are similar except that they write
+ at var{warning-text} on the screen with no error prompt. The four
+ at code{Info} commands write @var{info-text} only in the transcript
+file. The @code{NoLine} versions omit the number of the line
+generating the message, while the other versions do show that number.
+
+ at cindex @code{\protect}, and message text
+ at cindex @code{\space}, and message text
+ at cindex @code{\MessageBreak}, and message text
+To format the messages, including the @var{help-text}: use
+ at 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 is ignore, most commonly after a command.
+
+ at LaTeX{} appends a period to the messages.
+
+
+ at node \CurrentOption
+ at subsection @code{\CurrentOption}
+
+ at findex \CurrentOption
+ at cindex option, currently being processed
+
+Expands to the name of the option currently being processed. This can
+only be used within the @var{code} argument of either
+ at code{\DeclareOption} or @code{\DeclareOption*}.
+
+
+ at node \DeclareOption
+ at subsection @code{\DeclareOption}
+
+ at findex \DeclareOption
+ at cindex class options
+ at cindex package options
+ at cindex options, class
+ at cindex options, package
+
+Synopsis:
+
+ at example
+\DeclareOption@{@var{option}@}@{@var{code}@}
+\DeclareOption*@{@var{option}@}@{@var{code}@}
+ at end example
+
+Define an option a user can include in their @code{\documentclass}
+command. For example, a class @code{smcmemo} could have an option
+ at code{logo} allowing users to put the institutional logo on the first
+page. The document would start with
+ at code{\documentclass[logo]@{smcmemo@}}. To enable this, the class file
+must contain @code{\DeclareOption@{logo@}@{@var{code}@}} (and later,
+ at code{\ProcessOptions}).
+
+ at cindex default option processing
+ at cindex option processing by default
+ at cindex @code{Unused global option} warning, handling
+If you request an option that has not been declared, by default this
+will produce a warning like @code{Unused global option(s):
+[badoption].} This can be changed by using
+ at code{\DeclareOption*@{@var{code}@}}, which executes @var{code} for
+any unknown option.
+
+For example, many classes extend an existing class, using code such as
+ at code{\LoadClass@{article@}} (@pxref{\LoadClass}). In this case, it
+makes sense to pass any otherwise-unknown options to the underlying
+class, like this:
+
+ at example
+\DeclareOption*@{%
+ \PassOptionsToClass@{\CurrentOption@}@{article@}%
+@}
+ at end example
+
+As another example, our class @code{smcmemo} might allow users to keep
+lists of memo recipients in external files, so the user could invoke
+ at code{\documentclass[math]@{smcmemo@}} and it will read the file
+ at code{math.memo}. This code inputs the file if it exists, while if it
+doesn't, the option is passed to the @code{article} class:
+
+ at example
+\DeclareOption*@{\InputIfFileExists@{\CurrentOption.memo@}
+ @{@}@{%
+ \PassOptionsToClass@{\CurrentOption@}@{article@}@}@}
+ at end example
+
+
+ at node \DeclareRobustCommand
+ at subsection @code{\DeclareRobustCommand}
+
+ at findex \DeclareRobustCommand
+ at cindex new command, definition
+ at cindex robust command, defining
+
+Synopsis:
+
+ at example
+\DeclareRobustCommand@{@var{cmd}@}[@var{num}][@var{default}]@/@{@var{definition}@}
+\DeclareRobustCommand* @r{(same parameters}
+ at end example
+
+ at code{\DeclareRobustCommand} and its starred form are generally like
+ at code{\newcommand} and @code{\newcommand*} (@pxref{\newcommand &
+\renewcommand}), with the addition that they define a so-called
+ at dfn{robust} command, even if some code within the @var{definition} is
+fragile. (For a discussion of robust and fragile commands,
+ at pxref{\protect}.)
+
+Also unlike @code{\newcommand}, these do not give an error if macro
+ at var{cmd} already exists; instead, a log message is put into the
+transcript file if a command is redefined. Thus,
+ at code{\DeclareRobustCommand} can be used to define new robust commands
+or to redefine existing commands, making them robust.
+
+The starred form, @code{\DeclareRobustCommand*}, disallows the
+arguments from containing multiple paragraphs, just like the starred
+form of @code{\newcommand} and @code{\renewcommand}. The meaning of
+the arguments is the same.
+
+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}.
+
+ at PkgIndex{etoolbox}
+ at cindex e- at TeX{}, and robust commands
+ at findex \newrobustcmd @r{(@t{etoolbox} package)}
+ at findex \renewrobustcmd @r{(@t{etoolbox} package)}
+ at findex \providerobustcmd @r{(@t{etoolbox} package)}
+
+Related to this, the @package{etoolbox} package offers three commands
+and their starred forms: @code{\newrobustcmd}(@code{*})
+ at code{\renewrobustcmd}(@code{*}), and
+ at code{\providerobustcmd}(@code{*}). They are similar to
+ at code{\newcommand}, @code{\renewcommand}, and @code{\providecommand}
+and their own starred forms, but define a robust @var{cmd}. They have
+two possible advantages compared to @code{\DeclareRobustCommand}:
+
+ at enumerate
+ at item
+They use the low-level e- at 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
+
+ at item
+They make the same distinction between @code{\new at dots{}},
+ at code{\renew at dots{}}, and @code{\provide at dots{}}, as the standard
+commands. That is, they do not just write a log message when you
+redefine @var{cmd} that already exists; you need to use either
+ at code{\renew at dots{}} or @code{\provide at dots{}}, or you get an error.
+This may or may not be a benefit.
+ at end enumerate
+
+
+ at node \ExecuteOptions
+ at subsection @code{\ExecuteOptions}
+
+ at findex \ExecuteOptions
+
+Synopsis:
+
+ at example
+\ExecuteOptions@{@var{option-list}@}
+ at end example
+
+ at findex \ds@@@var{option}
+For each option @var{option} in @var{option-list}, in order, this
+command executes the command @code{\ds@@@var{option}}. If this
+command is not defined then that option is silently ignored.
+
+This can be used to provide a default option list before
+ at code{\ProcessOptions}. For example, if in a class file you want the
+default to be 11pt fonts then you could specify
+ at code{\ExecuteOptions@{11pt@}\ProcessOptions\relax}.
+
+
+ at node \IfFileExists & \InputIfFileExists
+ at subsection @code{\IfFileExists} & @code{\InputIfFileExists}
+
+ at anchor{\IfFileExists}
+ at anchor{\InputIfFileExists}
+ at findex \IfFileExists
+ at findex \InputIfFileExists
+
+Synopses:
+
+ at example
+\IfFileExists@{@var{filename}@}@{@var{true-code}@}@{@var{false-code}@}
+\InputIfFileExists@{@var{filename}@}@{@var{true-code}@}@{@var{false-code}@}
+ at end example
+
+ at code{\IfFileExists} executes @var{true-code} if @LaTeX{} finds the
+file @file{@var{filename}} or @var{false-code} otherwise. In the
+first case it executing @var{true-code} and then inputs the file.
+Thus the command
+
+ at example
+\IfFileExists@{img.pdf@}@{%
+ \includegraphics@{img.pdf@}@}
+ @{\typeout@{!! img.pdf not found@}
+ at end example
+
+ at noindent
+will include the graphic @file{img.pdf} if it is found and otherwise
+give a warning.
+
+This command looks for the file in all search paths that @LaTeX{}
+uses, not only in the current directory. To look only in the current
+directory do something like
+ at code{\IfFileExists@{./@var{filename}@}@{@var{true-code}@}@{@var{false-code}@}}.
+If you ask for a filename without a @code{.tex} extension then
+ at LaTeX{} will first look for the file by appending the @code{.tex};
+for more on how @LaTeX{} handles file extensions see @ref{\input}.
+
+ at code{\InputIfFileExists} is similar, but, as the name states,
+automatically @code{\input}s @var{filename} if it exists. The
+ at var{true-code} is executed just before the @code{\input}; if the file
+doesn't exist, the @var{false-code} is executed. An example:
+
+ at example
+\InputIfFileExists@{mypkg.cfg@}
+ @{\PackageInfo@{Loading mypkg.cfg for configuration information@}@}
+ @{\PackageInfo@{No mypkg.cfg found@}@}
+ at end example
+
+
+ at node \LoadClass & \LoadClassWithOptions
+ at subsection @code{\LoadClass} & @code{\LoadClassWithOptions}
+
+ at anchor{\LoadClass}
+ at anchor{\LoadClassWithOptions}
+ at findex \LoadClass
+ at findex \LoadClassWithOptions
+
+Synopses:
+
+ at example
+\LoadClass[@var{options-list}]@{@var{class-name}@}[@var{release-date}]
+\LoadClassWithOptions@{@var{class-name}@}[@var{release-date}]
+ at end example
+
+Load a class, as with
+ at code{\documentclass[@var{options-list}]@{@var{class-name}@}[@var{release-date}]}.
+An example: @code{\LoadClass[twoside]@{article@}}.
+
+The @var{options-list}, if present, is a comma-separated list. The
+ at var{release-date} is also optional. If present it must have the form
+ at code{YYYY/MM/DD}.
+ at c BTW, there are at-macros documented in macros2e.pdf to check the version
+ at c and do some actions conditionnally on version later or not to some
+ at c date.
+
+If you request @var{release-date} and the date of the package
+installed on your system is earlier, then you get a warning on the
+screen and in the log like this:
+
+ at example
+You have requested, on input line 4, version `2038/01/19' of
+document class article, but only version `2014/09/29 v1.4h
+Standard LaTeX document class' is available.
+ at end example
+
+ at findex \PassOptionsToClass at r{, ignoring}
+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
+ at code{article} class, without having to track which options were passed.
+
+
+ at node \NeedsTeXFormat
+ at subsection @code{\NeedsTeXFormat}
+
+ at findex \NeedsTeXFormat
+ at cindex format, requiring
+ at cindex version of format, requiring
+ at cindex date of format, requiring
+
+Synopsis:
+
+ at example
+\NeedsTeXFormat@{@var{format}@}[@var{format-date}]
+ at end example
+
+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:
+ at code{\NeedsTeXFormat@{LaTeX2e@}}. When a document using that class
+is processed, the format being run must exactly match the @var{format}
+name given, including case. If it does not match then execution stops
+with an error like @samp{This file needs format `LaTeX2e' but this is
+`plain'.}.
+
+To require 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
+ at code{YYYY/MM/DD}. If the format version installed on your system is
+earlier than @var{format date} then you get a warning like this.
+
+ at example
+You have requested release `2038/01/20' of LaTeX, but only
+release `2016/02/01' is available.
+ at end example
+
+
+ at node \OptionNotUsed
+ at subsection @code{\OptionNotUsed}
+
+ at findex \OptionNotUsed
+
+ at cindex unused options, adding to list
+ at cindex options, list of unused
+Adds the current option to the list of unused options. Can only be used
+within the @var{code} argument of either @code{\DeclareOption} or
+ at code{\DeclareOption*}.
+
+ at c xx I cannot reproduce this behavior as it is documented in clsguide.
+ at c In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues
+ at c on the console a warning like @code{LaTeX Warning: Unused global
+ at c option(s): [unusedoption].} with the list of not-used options when it
+ at c reaches @code{\begin@{document@}}.
+
+
+ at node \PassOptionsToClass & \PassOptionsToPackage
+ at subsection @code{\PassOptionsToClass} & @code{\PassOptionsToPackage}
+
+ at anchor{\PassOptionsToClass}
+ at anchor{\PassOptionsToPackage}
+ at findex \PassOptionsToClass
+ at findex \PassOptionsToPackage
+
+Synopses:
+
+ at example
+\PassOptionsToClass@{@var{options}@}@{@var{clsname}@}
+\PassOptionsToPackage@{@var{option}@}@{@var{pkgname}@}
+ at end example
+
+Adds the options in the comma-separated list @var{options} to the
+options used by any future @code{\RequirePackage} or
+ at code{\usepackage} command for the class @var{clsname} or the package
+ at var{pkgname}, respectively.
+
+ at cindex option clash
+ at cindex conflict between package options
+The reason for these commands is that although you may load a package
+any number of times with no options, if you can specify options only
+the first time you 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 combine
+the calls; for example, replacing the two
+
+ at example
+\RequirePackage[landscape]@{geometry@}
+\RequirePackage[margins=1in]@{geometry@}
+ at end example
+
+ at noindent with the single command
+
+ at example
+\RequirePackage[landscape,margins=1in]@{geometry@}
+ at end example
+
+However, suppose you are loading @file{firstpkg} and inside that
+package it loads @file{secondpkg}, and you need @code{secondpkg} to be
+loaded with option @code{draft}. Then before load the first package
+you must tell @LaTeX{} about the desired options for the second
+package, like this:
+
+ at example
+\PassOptionsToPackage@{draft@}@{secondpkg@}
+\RequirePackage@{firstpkg@}
+ at end example
+
+ at noindent
+If @code{firstpkg.sty} loads an option in conflict with what you want
+then you may have to alter its source, or yours.
+
+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
+ at code{foo} that loads the @code{graphicx} package, but without that
+option. The user could start their @LaTeX{} file with
+ at code{\PassOptionsToPackage@{draft@}@{graphicx@} \documentclass@{foo@}}.
+
+
+ at node \ProcessOptions
+ at subsection @code{\ProcessOptions}
+
+ at findex \ProcessOptions
+ at cindex processing options
+ at cindex options, processing
+
+Synopsis:
+
+ at example
+\ProcessOptions at var{\@@options}
+\ProcessOptions*@var{\@@options}
+ at end example
+
+Execute the code for each option that the user has invoked. Invoke it
+in the class file as @code{\ProcessOptions\relax} (because of the
+existence of the starred version, described below).
+
+ at cindex options, global and local
+ at cindex local options
+ at cindex global options
+Options come in two types. @dfn{Local options} have been specified
+for this particular package in @code{\usepackage[@var{options}]},
+ at code{\RequirePackage[@var{options}]}, or the @var{options} argument
+of @code{\PassOptionsToPackage@{@var{options}@}}. @dfn{Global options}
+are those given by the class user in
+ at 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:
+
+ at enumerate
+ at item
+For each option @var{option} so far declared with
+ at code{\DeclareOption}, @code{\ProcessOptions} looks to see if that
+option is either global or local 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}.
+
+ at item
+For each remaining local option, it executes the command
+ at 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.
+ at 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
+ at 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.
+
+
+ at node \ProvidesClass & \ProvidesPackage
+ at subsection @code{\ProvidesClass} & @code{\ProvidesPackage}
+
+ at anchor{\ProvidesClass}
+ at anchor{\ProvidesPackage}
+ at findex \ProvidesClass
+ at findex \ProvidesPackage
+
+Synopses:
+
+ at example
+\ProvidesClass@{@var{clsname}@}[@var{release-date} @r{[}@var{info-text}@r{]}]
+\ProvidesPackage@{@var{pkgname}@}[@var{release-date} @r{[}@var{info-text}@r{]}]
+ at end example
+
+Identifies the class or package being defined, printing a message to
+the screen and the log file.
+
+When you load a class or package, for example with
+ at code{\documentclass@{smcmemo@}} or @code{\usepackage@{test@}},
+ at LaTeX{} inputs a file (@file{smcmemo.cls} and @file{test.sty},
+respectively). If the name of the file does not match the class or
+package name declared in it then you get a warning. Thus, if you
+invoke @code{\documentclass@{smcmemo@}}, and the file
+ at file{smcmemo.cls} has the statement @code{\ProvidesClass@{foo@}} then
+you get a warning like @code{You have requested document class
+`smcmemo', but the document class provides 'foo'.} This warning does
+not prevent @LaTeX{} from processing the rest of the class file
+normally.
+
+If you include the optional argument then you must include a date,
+before any spaces, of the form @code{YYYY/MM/DD}. The rest of the
+optional argument is free-form, although it traditionally identifies
+the class. It is written to the screen during compilation and to the
+log file. Thus, if your file @file{smcmemo.cls} contains the line
+ at code{\ProvidesClass@{smcmemo@}[2008/06/01 v1.0 SMC memo class]} and
+your document's first line is @code{\documentclass@{smcmemo@}} then
+you will see @code{Document Class: smcmemo 2008/06/01 v1.0 SMC memo
+class}.
+
+The date in the optional argument allows class and package users to
+ask to be warned if the version of the class or package is earlier
+than @var{release date}. For instance, a user could enter
+ at code{\documentclass@{smcmemo@}[2018/10/12]} or
+ at code{\usepackage@{foo@}[[2017/07/07]]} to require a class or package
+with certain features by specifying that it must be released no
+earlier than the given date. Perhaps more importantly, the date
+serves as documentation of the last release. (In practice, package
+users rarely include a date, and class users almost never do.)
+
+
+ at node \ProvidesFile
+ at subsection @code{\ProvidesFile}
+
+ at findex \ProvidesFile
+
+Synopsis:
+
+ at example
+\ProvidesFile@{@var{filename}@}[@var{info-text}]
+ at end example
+
+Declare a file other than the main class and package files, such as a
+configuration or font definition file. It writes the given
+information to the log file, essentially like @code{\ProvidesClass}
+and @code{\ProvidesPackage} (see the previous section).
+
+For example:
+
+ at example
+\ProvidesFile@{smcmemo.cfg@}[2017/10/12 config file for smcmemo.cls]
+ at end example
+
+ at noindent writes this into the log:
+
+ at example
+File: smcmemo.cfg 2017/10/12 config file for smcmemo.cls
+ at end example
+
+
+ at node \RequirePackage & \RequirePackageWithOptions
+ at subsection @code{\RequirePackage} & @code{\RequirePackageWithOptions}
+
+ at anchor{\RequirePackage}
+ at anchor{\RequirePackageWithOptions}
+ at findex \RequirePackage
+ at findex \RequirePackageWithOptions
+
+Synopsis:
+
+ at example
+\RequirePackage[@var{option-list}]@{@var{pkgname}@}[@var{release-date}]
+\RequirePackageWithOptions@{@var{pkgname}@}[@var{release-date}]
+ at end example
+
+Load a package, like the command @code{\usepackage} (@pxref{Additional
+packages}). An example:@*
+ at code{\RequirePackage[landscape,margin=1in]@{geometry@}}
+
+The initial optional argument @var{option-list}, if present, must be a
+comma-separated list. The trailing optional argument
+ at var{release-date}, if present, must have the form @code{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 @samp{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} variant 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 to be used in
+documents, while @code{\RequirePackage} is intended for package and
+class files. The most significant difference in practice is that
+ at code{\RequirePackage} can be used in a document before the
+ at code{\documentclass} command, while @code{\usepackage} gives an error
+there. The most common need for this nowadays is for the
+ at code{\DocumentMetadata} command (@pxref{\DocumentMetadata}).
+
+The @LaTeX{} development team strongly recommends use of these and
+related commands over Plain at tie{}@TeX{}'s @code{\input}; see the Class
+Guide (@url{https://ctan.org/pkg/clsguide}).
+
+
@node Counters
@chapter Counters
@@ -11178,10 +11530,10 @@
@noindent
This next example uses those commands to show a black bar 100 at tie{}points
-long between @samp{XXX} and @samp{YYY}. This length is rigid.
+long between @samp{ABC} and @samp{XYZ}. This length is rigid.
@example
-XXX\showhbox@{100pt@}@{\blackbar@{100pt@}@}YYY
+ABC\showhbox@{100pt@}@{\blackbar@{100pt@}@}XYZ
@end example
As for rubber lengths, shrinking is simpler one: with @code{1cm minus
@@ -11191,10 +11543,10 @@
98 at tie{}points between the two bars.
@example
-XXX\showhbox@{300pt@}@{%
+ABC\showhbox@{300pt@}@{%
\blackbar@{101pt@}\hspace@{100pt minus 2pt@}\blackbar@{101pt@}@}YYY
-XXX\showhbox@{300pt@}@{%
+ABC\showhbox@{300pt@}@{%
\blackbar@{105pt@}\hspace@{100pt minus 1pt@}\blackbar@{105pt@}@}YYY
@end example
@@ -11210,10 +11562,10 @@
producing a space of 110 at tie{}points between the bars.
@example
-XXX\showhbox@{300pt@}@{%
+ABC\showhbox@{300pt@}@{%
\blackbar@{95pt@}\hspace@{100pt plus 10pt@}\blackbar@{95pt@}@}YYY
-XXX\showhbox@{300pt@}@{%
+ABC\showhbox@{300pt@}@{%
\blackbar@{95pt@}\hspace@{100pt plus 1pt@}\blackbar@{95pt@}@}YYY
@end example
@@ -11230,7 +11582,7 @@
stretch or shrink in proportion.
@example
-XXX\showhbox@{300pt@}@{%
+ABC\showhbox@{300pt@}@{%
\blackbar@{100pt@}% left
\hspace@{0pt plus 50pt@}\blackbar@{80pt@}\hspace@{0pt plus 10pt@}% middle
\blackbar@{100pt@}@}YYY % right
@@ -14515,11 +14867,11 @@
@code{\leavevmode}, as in the bottom line below.
@example
-xxx xxx xxx
+Text above.
-\smash@{yyy@} % no paragraph indent
+\smash@{smashed, no indent@} % no paragraph indent
-\leavevmode\smash@{zzz@} % usual paragraph indent
+\leavevmode\smash@{smashed, with indent@} % usual paragraph indent
@end example
@PkgIndex{mathtools}
@@ -15368,6 +15720,7 @@
There is some discussion of this issue at
@url{https://tex.stackexchange.com/questions/687258}.
+
@node Spaces
@chapter Spaces
@@ -17035,377 +17388,6 @@
backslash, @code{\}.) This command is robust (@pxref{\protect}).
- at node Color
- at chapter Color
-
- at cindex color
-
-You can add color to text, rules, etc. You can also have color in a box
-or on an entire page and write text on top of it.
-
-Color support comes as an additional package. So put
- at code{\usepackage@{color@}} in your document preamble to use the
-commands described here.
-
-Many other packages also supplement @LaTeX{}'s color abilities.
-Particularly worth mentioning is @file{xcolor}, which is widely used and
-significantly extends the capabilities described here, including adding
- at samp{HTML} and @samp{Hsb} color models.
-
- at menu
-* Color package options:: Options when you load the standard package.
-* Color models:: How colors are represented.
-* Commands for color:: The available commands.
- at end menu
-
-
- at node Color package options
- at section @code{color} package options
-
- at cindex color package options
- at cindex options, color package
-
-Synopsis (must be in the document preamble):
-
- at example
-\usepackage[@var{comma-separated option list}]@{color@}
- at end example
-
-When you load the @file{color} package there are two kinds of available
-options.
-
-The first specifies the @dfn{printer driver}. @LaTeX{} doesn't contain
-information about different output systems but instead depends on
-information stored in a file. Normally you should not specify the
-driver option in the document, and instead rely on your system's
-default. One advantage of this is that it makes the document portable
-across systems. For completeness we include a list of the drivers. The
-currently relevant ones are: @file{dvipdfmx}, @file{dvips},
- at file{dvisvgm}, @file{luatex}, @file{pdftex}, @file{xetex}. The two
- at file{xdvi} and @file{oztex} are essentially aliases for @file{dvips}
-(and @file{xdvi} is monochrome). Ones that should not be used for new
-systems are: @file{dvipdf}, @file{dvipdfm}, @file{dviwin},
- at file{dvipsone}, @file{emtex}, @file{pctexps}, @file{pctexwin},
- at file{pctexhp}, @file{pctex32}, @file{truetex}, @file{tcidvi},
- at file{vtex} (and @file{dviwindo} is an alias for @file{dvipsone}).
-
-The second kind of options, beyond the drivers, are below.
-
- at table @code
-
- at item monochrome
-Disable the color commands, so that they do not generate errors but do
-not generate color either.
-
- at item dvipsnames
-Make available a list of 68 color names that are often used,
-particularly in legacy documents. These color names were originally
-provided by the @file{dvips} driver, giving the option name.
-
- at item nodvipsnames
-Do not load that list of color names, saving @LaTeX{} a tiny amount of
-memory space.
-
- at end table
-
-
- at node Color models
- at section Color models
-
- at cindex color models
-
-A @dfn{color model} is a way of representing colors. @LaTeX{}'s
-capabilities depend on the printer driver. However, the @file{pdftex},
- at file{xetex}, and @file{luatex} printer drivers are today by far the
-most commonly used. The models below work for those drivers. All but
-one of these is also supported by essentially all other printer drivers
-used today.
-
-Note that color combination can be additive or subtractive. Additive
-mixes colors of light, so that for instance combining full intensities
-of red, green, and blue produces white. Subtractive mixes pigments,
-such as with inks, so that combining full intensity of cyan, magenta,
-and yellow makes black.
-
- at table @code
- at anchor{color models cmyk}
- at item cmyk
-A comma-separated list with four real numbers between 0 and 1,
-inclusive. The first number is the intensity of cyan, the second is
-magenta, and the others are yellow and black. A number value of 0 means
-minimal intensity, while a 1 is for full intensity. This model is often
-used in color printing. It is a subtractive model.
-
- at anchor{color models gray}
- at item gray
-A single real number between 0 and 1, inclusive. The colors are shades
-of grey. The number 0 produces black while 1 gives white.
-
- at anchor{color models rgb}
- at item rgb
-A comma-separated list with three real numbers between 0 and 1,
-inclusive. The first number is the intensity of the red component, the
-second is green, and the third the blue. A number value of 0 means that
-none of that component is added in, while a 1 means full intensity.
-This is an additive model.
-
- at anchor{color models RGB}
- at item RGB
-(@file{pdftex}, @file{xetex}, @file{luatex} drivers) A comma-separated
-list with three integers between 0 and 255, inclusive. This model is a
-convenience for using @code{rgb} since outside of @LaTeX{} colors are
-often described in a red-green-blue model using numbers in this range.
-The values entered here are converted to the @code{rgb} model by
-dividing by 255.
-
- at anchor{color models named}
- at item named
-Colors are accessed by name, such as @samp{PrussianBlue}. The list of
-names depends on the driver, but all support the names @samp{black},
- at samp{blue}, @samp{cyan}, @samp{green}, @samp{magenta}, @samp{red},
- at samp{white}, and @samp{yellow} (See the @code{dvipsnames} option in
- at ref{Color package options}).
-
- at end table
-
-
- at node Commands for color
- at section Commands for color
-
- at cindex color package commands
-
-These are the commands available with the @file{color} package.
-
- at menu
-* Define colors:: Give a color a name.
-* Colored text:: Text or rules in color.
-* Colored boxes:: A box of color, to write over.
-* Colored pages:: A whole page colored.
- at end menu
-
-
- at node Define colors
- at subsection Define colors
-
- at cindex color
- at cindex define color
- at cindex color, define
-
-Synopsis:
-
- at example
-\definecolor@{@var{name}@}@{@var{model}@}@{@var{specification}@}
- at end example
-
-Give the name @var{name} to the color. For example, after this
-
- at example
-\definecolor@{silver@}@{rgb@}@{0.75,0.75,0.74@}
- at end example
-
- at noindent
-you can use that color name with @code{Hi ho,
-\textcolor@{silver@}@{Silver@}!}.
-
-This example gives the color a more abstract name, so it could change and
-not be misleading.
-
- at example
-\definecolor@{logocolor@}@{RGB@}@{145,92,131@} % RGB needs pdflatex
-\newcommand@{\logo@}@{\textcolor@{logocolor@}@{Bob's Big Bagels@}@}
- at end example
-
-Often a document's colors are defined in the preamble, or in the class
-or style, rather than in the document body.
-
-
- at node Colored text
- at subsection Colored text
-
- at cindex color
- at cindex colored text
-
-Synopses:
-
- at example
-\textcolor@{@var{name}@}@{...@}
-\textcolor[@var{color model}]@{@var{color specification}@}@{...@}
- at end example
-
- at noindent
-or
-
- at example
-\color@{@var{name}@}
-\color[@var{color model}]@{@var{color specification}@}
- at end example
-
-The affected text gets the color. This line
-
- at example
-\textcolor@{magenta@}@{My name is Ozymandias, King of Kings;@}
-Look on my works, ye Mighty, and despair!
- at end example
-
- at noindent
-causes the first half to be in magenta while the rest is in black. You
-can use a color declared with @code{\definecolor} in exactly the same
-way that we just used the builtin color @samp{magenta}.
-
- at example
-\definecolor@{MidlifeCrisisRed@}@{rgb@}@{1.0,0.11,0.0@}
-I'm thinking about getting a \textcolor@{MidlifeCrisisRed@}@{sports car@}.
- at end example
-
-The two @code{\textcolor} and @code{\color} differ in that the first is
-a command form, enclosing the text to be colored as an argument. Often
-this form is more convenient, or at least more explicit. The second
-form is a declaration, as in @code{The moon is made of @{\color@{green@}
-green@} cheese}, so it is in effect until the end of the current group
-or environment. This is sometimes useful when writing macros or as
-below where it colors everything inside the @code{center} environment,
-including the vertical and horizontal lines.
-
- at example
-\begin@{center@} \color@{blue@}
- \begin@{tabular@}@{l|r@}
- UL &UR \\ \hline
- LL &LR
- \end@{tabular@}
-\end@{center@}
- at end example
-
-You can use color in equations. A document might have this definition
-in the preamble
-
- at example
-\definecolor@{highlightcolor@}@{RGB@}@{225,15,0@}
- at end example
-
- at noindent
-and then contain this equation.
-
- at example
-\begin@{equation@}
- \int_a^b \textcolor@{highlightcolor@}@{f'(x)@}\,dx=f(b)-f(a)
-\end@{equation@}
- at end example
-
-Typically the colors used in a document are declared in a class or style
-but sometimes you want a one-off. Those are the second forms in the
-synopses.
-
- at example
-Colors of \textcolor[rgb]@{0.33,0.14,0.47@}@{Purple@} and
-@{\color[rgb]@{0.72,0.60,0.37@}Gold@} for the team.
- at end example
-
-The format of @var{color specification} depends on the color model
-(@pxref{Color models}). For instance, while @code{rgb} takes three
-numbers, @code{gray} takes only one.
-
- at example
-The selection was \textcolor[gray]@{0.5@}@{grayed out@}.
- at end example
-
-Colors inside colors do not combine. Thus
-
- at example
-\textcolor@{green@}@{kind of \textcolor@{blue@}@{blue@}@}
- at end example
-
- at noindent
-has a final word that is blue, not a combination of blue and green.
-
- at c xx address coloring a line of a table?
-
-
- at node Colored boxes
- at subsection Colored boxes
-
- at cindex color
- at cindex colored boxes
- at cindex box, colored
-
-Synopses:
-
- at example
-\colorbox@{@var{name}@}@{...@}
-\colorbox[@var{model name}]@{@var{box background color}@}@{...@}
- at end example
-
- at noindent
-or
-
- at example
-\fcolorbox@{@var{frame color}@}@{@var{box background color}@}@{...@}
-\fcolorbox[@var{model name}]@{@var{frame color}@}@{@var{box background color}@}@{...@}
- at end example
-
-Make a box with the stated background color. The @code{\fcolorbox}
-command puts a frame around the box. For instance this
-
- at example
-Name:~\colorbox@{cyan@}@{\makebox[5cm][l]@{\strut@}@}
- at end example
-
- at noindent
-makes a cyan-colored box that is five centimeters long and gets its
-depth and height from the @code{\strut} (so the depth is
- at code{-.3\baselineskip} and the height is @code{\baselineskip}). This
-puts white text on a blue background.
-
- at example
-\colorbox@{blue@}@{\textcolor@{white@}@{Welcome to the machine.@}@}
- at end example
-
-The @code{\fcolorbox} commands use the same parameters as @code{\fbox}
-(@pxref{\fbox & \framebox}), @code{\fboxrule} and @code{\fboxsep}, to
-set the thickness of the rule and the boundary between the box interior
-and the surrounding rule. @LaTeX{}'s defaults are @code{0.4pt} and
- at code{3pt}, respectively.
-
-This example changes the thickness of the border to 0.8 points. Note
-that it is surrounded by curly braces so that the change ends at the end
-of the second line.
-
- at example
-@{\setlength@{\fboxrule@}@{0.8pt@}
-\fcolorbox@{black@}@{red@}@{Under no circumstances turn this knob.@}@}
- at end example
-
-
- at node Colored pages
- at subsection Colored pages
-
- at cindex color
- at cindex colored page
- at cindex page, colored
- at cindex background, colored
-
-Synopses:
-
- at example
-\pagecolor@{@var{name}@}
-\pagecolor[@var{color model}]@{@var{color specification}@}
-\nopagecolor
- at end example
-
-The first two set the background of the page, and all subsequent pages,
-to the color. For an explanation of the specification in the second
-form @pxref{Colored text}. The third returns the background to normal,
-which is a transparent background. (If that is not supported use
- at code{\pagecolor@{white@}}, although that will make a white background
-rather than the default transparent background.)
-
- at example
- ...
-\pagecolor@{cyan@}
- ...
-\nopagecolor
- at end example
-
-
@node Graphics
@chapter Graphics
@@ -18161,8 +18143,8 @@
These following options allow a user to override @LaTeX{}'s method of
choosing the graphic type based on the filename extension. An example
-is that @code{\includegraphics[type=png,ext=.xxx,read=.xxx]@{lion@}}
-will read the file @file{lion.xxx} as though it were
+is that @code{\includegraphics[type=png,ext=.xyz,read=.xyz]@{lion@}}
+will read the file @file{lion.xyz} as though it were
@file{lion.png}. For more on these, @pxref{\DeclareGraphicsRule}.
@table @code
@@ -18371,6 +18353,376 @@
@code{\resizebox@{2in@}@{\height@}@{Two inches@}}.
+ at node Color
+ at chapter Color
+
+ at cindex color
+
+You can add color to text, rules, etc. You can also have color in a box
+or on an entire page and write text on top of it.
+
+Color support comes as an additional package. So put
+ at code{\usepackage@{color@}} in your document preamble to use the
+commands described here.
+
+Many other packages also supplement @LaTeX{}'s color abilities.
+Particularly worth mentioning is @file{xcolor}, which is widely used and
+significantly extends the capabilities described here, including adding
+ at samp{HTML} and @samp{Hsb} color models.
+
+ at menu
+* Color package options:: Options when you load the standard package.
+* Color models:: How colors are represented.
+* Commands for color:: The available commands.
+ at end menu
+
+
+ at node Color package options
+ at section @code{color} package options
+
+ at cindex color package options
+ at cindex options, color package
+
+Synopsis (must be in the document preamble):
+
+ at example
+\usepackage[@var{comma-separated option list}]@{color@}
+ at end example
+
+When you load the @file{color} package there are two kinds of available
+options.
+
+The first specifies the @dfn{printer driver}. @LaTeX{} doesn't contain
+information about different output systems but instead depends on
+information stored in a file. Normally you should not specify the
+driver option in the document, and instead rely on your system's
+default. One advantage of this is that it makes the document portable
+across systems. For completeness we include a list of the drivers. The
+currently relevant ones are: @file{dvipdfmx}, @file{dvips},
+ at file{dvisvgm}, @file{luatex}, @file{pdftex}, @file{xetex}. The two
+ at file{xdvi} and @file{oztex} are essentially aliases for @file{dvips}
+(and @file{xdvi} is monochrome). Ones that should not be used for new
+systems are: @file{dvipdf}, @file{dvipdfm}, @file{dviwin},
+ at file{dvipsone}, @file{emtex}, @file{pctexps}, @file{pctexwin},
+ at file{pctexhp}, @file{pctex32}, @file{truetex}, @file{tcidvi},
+ at file{vtex} (and @file{dviwindo} is an alias for @file{dvipsone}).
+
+The second kind of options, beyond the drivers, are below.
+
+ at table @code
+ at item monochrome
+Disable the color commands, so that they do not generate errors but do
+not generate color either.
+
+ at item dvipsnames
+Make available a list of 68 color names that are often used,
+particularly in legacy documents. These color names were originally
+provided by the @file{dvips} driver, giving the option name.
+
+ at item nodvipsnames
+Do not load that list of color names, saving @LaTeX{} a tiny amount of
+memory space.
+
+ at end table
+
+
+ at node Color models
+ at section Color models
+
+ at cindex color models
+
+A @dfn{color model} is a way of representing colors. @LaTeX{}'s
+capabilities depend on the printer driver. However, the @file{pdftex},
+ at file{xetex}, and @file{luatex} printer drivers are today by far the
+most commonly used. The models below work for those drivers. All but
+one of these is also supported by essentially all other printer drivers
+used today.
+
+Note that color combination can be additive or subtractive. Additive
+mixes colors of light, so that for instance combining full intensities
+of red, green, and blue produces white. Subtractive mixes pigments,
+such as with inks, so that combining full intensity of cyan, magenta,
+and yellow makes black.
+
+ at table @code
+ at anchor{color models cmyk}
+ at item cmyk
+A comma-separated list with four real numbers between 0 and 1,
+inclusive. The first number is the intensity of cyan, the second is
+magenta, and the others are yellow and black. A number value of 0 means
+minimal intensity, while a 1 is for full intensity. This model is often
+used in color printing. It is a subtractive model.
+
+ at anchor{color models gray}
+ at item gray
+A single real number between 0 and 1, inclusive. The colors are shades
+of grey. The number 0 produces black while 1 gives white.
+
+ at anchor{color models rgb}
+ at item rgb
+A comma-separated list with three real numbers between 0 and 1,
+inclusive. The first number is the intensity of the red component, the
+second is green, and the third the blue. A number value of 0 means that
+none of that component is added in, while a 1 means full intensity.
+This is an additive model.
+
+ at anchor{color models RGB}
+ at item RGB
+(@file{pdftex}, @file{xetex}, @file{luatex} drivers) A comma-separated
+list with three integers between 0 and 255, inclusive. This model is a
+convenience for using @code{rgb} since outside of @LaTeX{} colors are
+often described in a red-green-blue model using numbers in this range.
+The values entered here are converted to the @code{rgb} model by
+dividing by 255.
+
+ at anchor{color models named}
+ at item named
+Colors are accessed by name, such as @samp{PrussianBlue}. The list of
+names depends on the driver, but all support the names @samp{black},
+ at samp{blue}, @samp{cyan}, @samp{green}, @samp{magenta}, @samp{red},
+ at samp{white}, and @samp{yellow} (See the @code{dvipsnames} option in
+ at ref{Color package options}).
+
+ at end table
+
+
+ at node Commands for color
+ at section Commands for color
+
+ at cindex color package commands
+
+These are the commands available with the @file{color} package.
+
+ at menu
+* Define colors:: Give a color a name.
+* Colored text:: Text or rules in color.
+* Colored boxes:: A box of color, to write over.
+* Colored pages:: A whole page colored.
+ at end menu
+
+
+ at node Define colors
+ at subsection Define colors
+
+ at cindex color
+ at cindex define color
+ at cindex color, define
+
+Synopsis:
+
+ at example
+\definecolor@{@var{name}@}@{@var{model}@}@{@var{specification}@}
+ at end example
+
+Give the name @var{name} to the color. For example, after this
+
+ at example
+\definecolor@{silver@}@{rgb@}@{0.75,0.75,0.74@}
+ at end example
+
+ at noindent
+you can use that color name with @code{Hi ho,
+\textcolor@{silver@}@{Silver@}!}.
+
+This example gives the color a more abstract name, so it could change and
+not be misleading.
+
+ at example
+\definecolor@{logocolor@}@{RGB@}@{145,92,131@} % RGB needs pdflatex
+\newcommand@{\logo@}@{\textcolor@{logocolor@}@{Bob's Big Bagels@}@}
+ at end example
+
+Often a document's colors are defined in the preamble, or in the class
+or style, rather than in the document body.
+
+
+ at node Colored text
+ at subsection Colored text
+
+ at cindex color
+ at cindex colored text
+
+Synopses:
+
+ at example
+\textcolor@{@var{name}@}@{...@}
+\textcolor[@var{color model}]@{@var{color specification}@}@{...@}
+ at end example
+
+ at noindent
+or
+
+ at example
+\color@{@var{name}@}
+\color[@var{color model}]@{@var{color specification}@}
+ at end example
+
+The affected text gets the color. This line
+
+ at example
+\textcolor@{magenta@}@{My name is Ozymandias, King of Kings;@}
+Look on my works, ye Mighty, and despair!
+ at end example
+
+ at noindent
+causes the first half to be in magenta while the rest is in black. You
+can use a color declared with @code{\definecolor} in exactly the same
+way that we just used the builtin color @samp{magenta}.
+
+ at example
+\definecolor@{MidlifeCrisisRed@}@{rgb@}@{1.0,0.11,0.0@}
+I'm thinking about getting a \textcolor@{MidlifeCrisisRed@}@{sports car@}.
+ at end example
+
+The two @code{\textcolor} and @code{\color} differ in that the first is
+a command form, enclosing the text to be colored as an argument. Often
+this form is more convenient, or at least more explicit. The second
+form is a declaration, as in @code{The moon is made of @{\color@{green@}
+green@} cheese}, so it is in effect until the end of the current group
+or environment. This is sometimes useful when writing macros or as
+below where it colors everything inside the @code{center} environment,
+including the vertical and horizontal lines.
+
+ at example
+\begin@{center@} \color@{blue@}
+ \begin@{tabular@}@{l|r@}
+ UL &UR \\ \hline
+ LL &LR
+ \end@{tabular@}
+\end@{center@}
+ at end example
+
+You can use color in equations. A document might have this definition
+in the preamble
+
+ at example
+\definecolor@{highlightcolor@}@{RGB@}@{225,15,0@}
+ at end example
+
+ at noindent
+and then contain this equation.
+
+ at example
+\begin@{equation@}
+ \int_a^b \textcolor@{highlightcolor@}@{f'(x)@}\,dx=f(b)-f(a)
+\end@{equation@}
+ at end example
+
+Typically the colors used in a document are declared in a class or style
+but sometimes you want a one-off. Those are the second forms in the
+synopses.
+
+ at example
+Colors of \textcolor[rgb]@{0.33,0.14,0.47@}@{Purple@} and
+@{\color[rgb]@{0.72,0.60,0.37@}Gold@} for the team.
+ at end example
+
+The format of @var{color specification} depends on the color model
+(@pxref{Color models}). For instance, while @code{rgb} takes three
+numbers, @code{gray} takes only one.
+
+ at example
+The selection was \textcolor[gray]@{0.5@}@{grayed out@}.
+ at end example
+
+Colors inside colors do not combine. Thus
+
+ at example
+\textcolor@{green@}@{kind of \textcolor@{blue@}@{blue@}@}
+ at end example
+
+ at noindent
+has a final word that is blue, not a combination of blue and green.
+
+ at c xx address coloring a line of a table?
+
+
+ at node Colored boxes
+ at subsection Colored boxes
+
+ at cindex color
+ at cindex colored boxes
+ at cindex box, colored
+
+Synopses:
+
+ at example
+\colorbox@{@var{name}@}@{...@}
+\colorbox[@var{model name}]@{@var{box background color}@}@{...@}
+ at end example
+
+ at noindent
+or
+
+ at example
+\fcolorbox@{@var{frame color}@}@{@var{box background color}@}@{...@}
+\fcolorbox[@var{model name}]@{@var{frame color}@}@{@var{box background color}@}@{...@}
+ at end example
+
+Make a box with the stated background color. The @code{\fcolorbox}
+command puts a frame around the box. For instance this
+
+ at example
+Name:~\colorbox@{cyan@}@{\makebox[5cm][l]@{\strut@}@}
+ at end example
+
+ at noindent
+makes a cyan-colored box that is five centimeters long and gets its
+depth and height from the @code{\strut} (so the depth is
+ at code{-.3\baselineskip} and the height is @code{\baselineskip}). This
+puts white text on a blue background.
+
+ at example
+\colorbox@{blue@}@{\textcolor@{white@}@{Welcome to the machine.@}@}
+ at end example
+
+The @code{\fcolorbox} commands use the same parameters as @code{\fbox}
+(@pxref{\fbox & \framebox}), @code{\fboxrule} and @code{\fboxsep}, to
+set the thickness of the rule and the boundary between the box interior
+and the surrounding rule. @LaTeX{}'s defaults are @code{0.4pt} and
+ at code{3pt}, respectively.
+
+This example changes the thickness of the border to 0.8 points. Note
+that it is surrounded by curly braces so that the change ends at the end
+of the second line.
+
+ at example
+@{\setlength@{\fboxrule@}@{0.8pt@}
+\fcolorbox@{black@}@{red@}@{Under no circumstances turn this knob.@}@}
+ at end example
+
+
+ at node Colored pages
+ at subsection Colored pages
+
+ at cindex color
+ at cindex colored page
+ at cindex page, colored
+ at cindex background, colored
+
+Synopses:
+
+ at example
+\pagecolor@{@var{name}@}
+\pagecolor[@var{color model}]@{@var{color specification}@}
+\nopagecolor
+ at end example
+
+The first two set the background of the page, and all subsequent pages,
+to the color. For an explanation of the specification in the second
+form @pxref{Colored text}. The third returns the background to normal,
+which is a transparent background. (If that is not supported use
+ at code{\pagecolor@{white@}}, although that will make a white background
+rather than the default transparent background.)
+
+ at example
+ ...
+\pagecolor@{cyan@}
+ ...
+\nopagecolor
+ at end example
+
+
@node Special insertions
@chapter Special insertions
@@ -22186,7 +22538,7 @@
@noindent
The @code{jobname} option is there because otherwise both files would be
called @file{main.pdf} and the second would overwrite the
-first. (@pxref{Jobname}.)
+first (@pxref{Jobname}).
In this example we use the command line to select which parts of a
document to include. For a book named @file{mybook.tex} and structured
@@ -22233,19 +22585,20 @@
In general, @LaTeX{} is invoked as @code{@var{latex-engine}
@var{options} @var{argument}}, where @var{latex-engine} is
- at command{pdflatex}, @command{lualatex}, etc.@: (@pxref{@TeX{} engines}).
-If @var{argument} does not start with a backslash, as is the case above
-with @code{thesis}, then @TeX{} considers it to be the name of the file
-to input as the main document. This file is referred to as the @dfn{root
-file} (@pxref{Splitting the input}, and at tie{}@ref{\input}). The name of
-that root file, without the @file{.tex} extension if any, is the
-jobname. If @var{argument} does start with a backslash, or if @TeX{} is
-in interactive mode, then it waits for the first @code{\input} command,
-and the jobname is the argument to @code{\input}.
+ at command{pdflatex}, @command{lualatex}, etc.@: (@pxref{@TeX{}
+engines}). If @var{argument} does not start with a backslash, as is
+the case above with @code{thesis}, then @TeX{} considers it to be the
+name of the file to input as the main document. This file is referred
+to as the @dfn{root file} (@pxref{Splitting the input}, and
+ at ref{\input}). The name of that root file, without the @file{.tex}
+extension if any, is the jobname. If @var{argument} does start with a
+backslash, or if @TeX{} is in interactive mode, then it waits for the
+first @code{\input} command, and the jobname is the argument to
+ at code{\input}.
There are two more possibilities for the jobname. It can be directly
specified with the @code{-jobname} option, as in @code{pdflatex
--jobname=myname} (@pxref{Command line input} for a real example).
+-jobname=myname} (@pxref{Command line input} for a practical example).
@findex texput at r{, jobname default}
@cindex fallback jobname
More information about the latexrefman-commits
mailing list.