summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/usrguide-historic.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/usrguide-historic.tex')
-rw-r--r--macros/latex-dev/base/usrguide-historic.tex1832
1 files changed, 1832 insertions, 0 deletions
diff --git a/macros/latex-dev/base/usrguide-historic.tex b/macros/latex-dev/base/usrguide-historic.tex
new file mode 100644
index 0000000000..ce35aaa77c
--- /dev/null
+++ b/macros/latex-dev/base/usrguide-historic.tex
@@ -0,0 +1,1832 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 1993-2022
+% The LaTeX Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the LaTeX base system.
+% -------------------------------------------
+%
+% It may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2008 or later.
+%
+% This file has the LPPL maintenance status "maintained".
+%
+% The list of all files belonging to the LaTeX base distribution is
+% given in the file `manifest.txt'. See also `legal.txt' for additional
+% information.
+%
+% The list of derived (unpacked) files belonging to the distribution
+% and covered by LPPL is defined by the unpacking scripts (with
+% extension .ins) which are part of the distribution.
+%
+% \fi
+% Filename: usrguide-historic.tex
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+
+\documentclass{ltxguide}[2001/05/28]
+
+\title{\LaTeX\ for authors --- historic version}
+
+\author{\copyright~Copyright 1995--2022, \LaTeX\ Project Team.\\
+ All rights reserved.%
+ \footnote{This file may distributed and/or modified under the
+ conditions of the \LaTeX{} Project Public License, either version 1.3c
+ of this license or (at your option) any later version. See the source
+ \texttt{usrguide.tex} for full details.}%
+}
+
+\date{30 August 2022}
+
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\section{Introduction}
+
+Welcome to \LaTeXe, the new standard version of the \LaTeX{} Document
+Preparation System.
+
+This document describes how to take advantage of the new features of
+\LaTeX, and how to process your old \LaTeX{} documents with
+\LaTeXe. However, this document is only a brief introduction to the
+new facilities and is intended for authors who are already familiar
+with the old version of \LaTeX{}. It is \emph{not} a reference manual
+for \LaTeXe{} nor is it a complete introduction to \LaTeX.
+
+It is somewhat of an historical document now, since \LaTeXe{} came into
+existence in 1994.
+
+\subsection[\LaTeXe---The new \LaTeX~release]
+ {\LaTeXe---The new \LaTeX~release\\ (well, for more than 10 years now)}
+
+The previous version of \LaTeX{} was known as \LaTeX~2.09. Over the
+years many extensions have been developed for \LaTeX. This is, of
+course, a sure sign of its continuing popularity but it has had one
+unfortunate result: incompatible \LaTeX{} formats came into use at
+different sites. This included `standard \LaTeX~2.09', \LaTeX{} built
+with the \emph{New Font Selection Scheme}~(\NFSS), \SLiTeX, \AmSLaTeX,
+and so on. Thus, to process documents from various places, a site
+maintainer was forced to keep multiple versions of the \LaTeX{}
+program. In addition, when looking at a source file it was not always
+clear for which format the document was written.
+
+To put an end to this unsatisfactory situation, \LaTeXe{} has been
+produced; it brings all such extensions back under a single format and
+thus prevents the proliferation of mutually incompatible dialects of
+\LaTeX~2.09. With \LaTeXe{} the `new font selection scheme' is
+standard and, for example, \textsf{amsmath} (formerly the \AmSLaTeX{}
+format) or \textsf{slides} (formerly the \SLiTeX{} format) are simply
+extensions, which may be loaded by documents using the same base format.
+
+The introduction of a new release also made it possible to add a small
+number of often-requested features and to make the task of writing
+packages and classes simpler.
+
+\subsection{\LaTeX3---The long-term future of \LaTeX}
+\label{Sec:ltx3}
+
+\LaTeXe{} is the consolidation step in a comprehensive
+reimplementation of the \LaTeX{} system. The next major release of
+\LaTeX{} will be \LaTeX3, which will include a radical overhaul of the
+document designers' and package writers' interface to \LaTeX.
+
+\LaTeX3 is a long-term research project but, until it is completed,
+the project team are committed to the active maintenance of \LaTeXe{}.
+Thus the experience gained from the production and maintenance of
+\LaTeXe{} will be a major influence on the design of \LaTeX3.
+A brief description of the project can be found in the document
+|ltx3info.tex|.
+
+If you would like to support the project then you are welcome to send
+donations to the \LaTeX\ Project Fund; this has been set up to help
+the research team by financing various expenses associated with this
+voluntary work of maintaining the current \LaTeX{} and developing
+\LaTeX\ further.
+
+The fund is administered by The \TeX{} Users Group and by various
+local user groups. Information about making donations and joining
+these groups is available from:
+\begin{quote}\small\label{addrs}
+ \texttt{http://www.tug.org/lugs.html}
+\end{quote}
+
+The \LaTeX3{} project has its home page
+on the World Wide Web at:
+\begin{verbatim}
+ http://www.latex-project.org/
+\end{verbatim}
+This page describes \LaTeX{} and the \LaTeX3 project, and contains
+pointers to other \LaTeX{} resources, such as the user guides, the
+\TeX{} Frequently Asked Questions, and the \LaTeX{} bugs database.
+
+Older articles covering aspects of the \LaTeX3 project are also
+available for anonymous ftp from the Comprehensive \TeX{} Archive, in
+the directory:
+\begin{verbatim}
+ ctan:info/ltx3pub
+\end{verbatim}
+The file |ltx3pub.bib| in that directory contains an abstract of each
+of the files.
+
+\subsection{Overview}
+
+This document contains an overview of the new structure and features
+of \LaTeX. It is \emph{not} a self-contained document, as it contains
+only the features of \LaTeX{} which have changed since version 2.09.
+You should read this document in conjunction with an introduction to
+\LaTeX{}.
+
+\begin{description}
+
+\item[Section~\ref{Sec:class+packages}]
+ contains an overview of the new structure of
+ \LaTeX{} documents. It describes how classes and packages work and
+ how class and package options can be used. It lists the standard
+ packages and classes which come with \LaTeX.
+
+\item[Section~\ref{Sec:commands}] describes the new commands available
+ to authors in \LaTeXe.
+
+\item[Section~\ref{Sec:209}] shows how to process old \LaTeX{}
+ documents with \LaTeXe.
+
+\item[Section~\ref{Sec:problems}] contains advice on dealing with
+ problems you may encounter in running \LaTeXe.
+ It lists some error messages which are new in \LaTeXe{} and
+ it describes some of the more common problems and how to cure them,
+ or where to find further information.
+
+\end{description}
+
+\subsection{Further information}
+
+For a general introduction to \LaTeX, including the new features of
+\LaTeXe, you should read \emph{\LaTeXbook}
+by Leslie Lamport~\cite{A-W:LLa94}.
+
+A more detailed description of the new features of \LaTeX, including an
+overview of more than 200 packages and nearly 1000 ready to run examples, is
+to be found in \emph{\LaTeXcomp second edition} by Frank Mittelbach and
+Michel Goossens~\cite{A-W:MG2004}.
+
+Packages and programs for producing and manipulating graphics are
+discussed at length in \emph{\LaTeXGcomp} by Michel Goossens,
+Sebastian Rahtz and Frank Mittelbach~\cite{A-W:GRM97}.
+
+Solutions for publishing with \LaTeX{} on the World Wide Web are given
+in \emph{\LaTeXWcomp} by Michel Goossens and Sebastian
+Rahtz~\cite{A-W:GR99}.
+
+For more information about the many new \LaTeX{} packages you should
+read the package documentation, which should be available from the
+same source as your copy of \LaTeX.
+
+There are a number of documentation files which accompany every copy
+of \LaTeX. A copy of \emph{\LaTeX{} News} will come out with each
+six-monthly release of \LaTeX; it will be found in the files
+|ltnews*.tex|. The class- and package-writer's guide \emph{\clsguide}
+describes the new \LaTeX{} features for writers of document classes
+and packages; it is in |clsguide.tex|. The guide \emph{\fntguide}
+describes the \LaTeX{} font selection scheme for class- and
+package-writers; it is in |fntguide.tex|. Support for Cyrillic languages
+in \LaTeX{} is described in \emph{\cyrguide}.
+
+The documented source code (from the files used to produce the kernel
+format via |latex.ltx|) is now available as
+\emph{The \LaTeXe\ Sources}. ]
+This very large document also includes an index of
+\LaTeX{} commands. It can be typeset from the \LaTeX{} file
+|source2e.tex| in the |base| directory, using the source files and
+the class file |ltxdoc.cls| from this directory.
+
+For more information about \TeX{} and \LaTeX{}, please contact your
+local \TeX{} Users Group, or the international \TeX{} Users Group (see
+page \pageref{addrs}).
+
+
+\section{Classes and packages}
+\label{Sec:class+packages}
+
+This section describes the new structure of \LaTeX{} documents and the
+new types of file: \emph{classes} and \emph{packages}.
+
+\subsection{What are classes and packages?}
+
+The main difference between \LaTeX~2.09 and \LaTeXe{} is in the
+commands before |\begin{document}|.
+
+In \LaTeX~2.09, documents had \emph{styles},
+such as \textsf{article} or \textsf{book}, and \emph{options},
+such as \textsf{twoside} or \textsf{epsfig}.
+These were indicated by the |\documentstyle| command:
+\begin{quote}
+ |\documentstyle|\oarg{options}\arg{style}
+\end{quote}
+For example, to specify a two-sided article with encapsulated
+PostScript figures, you said:
+\begin{verbatim}
+ \documentstyle[twoside,epsfig]{article}
+\end{verbatim}
+However, there were two different types of document style option:
+\emph{built-in options} such as |twoside|; and \emph{packages} such as
+|epsfig.sty|. These were very different, since any \LaTeX{} document
+style could use the \textsf{epsfig} package but only document styles
+which declared the \textsf{twoside} option could use that option.
+
+To avoid this confusion, \LaTeXe{} differentiates between built-in
+options and packages. These are given by the new |\documentclass| and
+|\usepackage| commands:
+\begin{quote}
+ |\documentclass|\oarg{options}\arg{class} \\
+ |\usepackage|\oarg{options}\arg{packages}
+\end{quote}
+For example, to specify a two-sided article with encapsulated
+PostScript figures, you now write:
+\begin{verbatim}
+ \documentclass[twoside]{article}
+ \usepackage{epsfig}
+\end{verbatim}
+You can load more than one package with a single |\usepackage|
+command; for example, rather than writing:
+\begin{verbatim}
+ \usepackage{epsfig}
+ \usepackage{multicol}
+\end{verbatim}
+you can specify:
+\begin{verbatim}
+ \usepackage{epsfig,multicol}
+\end{verbatim}
+Note that \LaTeXe{} still understands the \LaTeX~2.09 |\documentstyle|
+command. This command causes \LaTeXe{} to enter \emph{\LaTeX~2.09
+compatibility mode}, which is described in Section~\ref{Sec:209}.
+
+You should not, however, use the |\documentstyle| command for new
+documents because this compatibility mode is very slow and the new
+features of \LaTeXe{} are not available in this mode.
+
+To help differentiate between classes and packages, document classes
+now end with |.cls| rather than |.sty|. Packages still end with
+|.sty|, since most \LaTeX~2.09 packages work well with \LaTeXe.
+
+\subsection{Class and package options}
+
+In \LaTeX~2.09, only document styles could have options such as
+|twoside| or |draft|. In \LaTeXe{}, both classes and packages are
+allowed to have options. For example, to specify a two-sided article
+with graphics using the |dvips| driver, you write:
+
+\begin{verbatim}
+ \documentclass[twoside]{article}
+ \usepackage[dvips]{graphics}
+\end{verbatim}
+It is possible for packages to share common options. For example,
+you could, in addition, load the \textsf{color} package by specifying:
+\begin{verbatim}
+ \documentclass[twoside]{article}
+ \usepackage[dvips]{graphics}
+ \usepackage[dvips]{color}
+\end{verbatim}
+But because |\usepackage| allows more than one package to be listed,
+this can be shortened to:
+\begin{verbatim}
+ \documentclass[twoside]{article}
+ \usepackage[dvips]{graphics,color}
+\end{verbatim}
+In addition, packages will also use each option given to
+the |\documentclass| command (if they know what to do with it), so you
+could also write:
+\begin{verbatim}
+ \documentclass[twoside,dvips]{article}
+ \usepackage{graphics,color}
+\end{verbatim}
+Class and package options are covered in more detail in
+\emph{\LaTeXcomp} and in \emph{\clsguide}.
+
+\subsection{Standard classes}
+
+The following classes are distributed with \LaTeX:
+\begin{description}
+
+\item[article] The |article| class described in \emph{\LaTeXbook}.
+\item[book] The |book| class described in \emph{\LaTeXbook}.
+\item[report] The |report| class described in \emph{\LaTeXbook}.
+\item[letter] The |letter| class described in \emph{\LaTeXbook}.
+\item[slides] The |slides| class described in \emph{\LaTeXbook},
+ formerly \SLiTeX.
+\item[proc] A document class for proceedings, based on |article|.
+ Formerly the |proc| package.
+\item[ltxdoc] The document class for documenting the \LaTeX{}
+ program, based on |article|.
+\item[ltxguide] The document class for \emph{\usrguide} and
+ \emph{\clsguide}, based on |article|. The document you are reading
+ now uses the |ltxguide| class. The layout for this class is likely
+ to change in future releases of \LaTeX.
+\item[ltnews] The document class for the \emph{\LaTeX{} News}
+ information sheet, based on |article|. The layout for this class
+ is likely to change in future releases of \LaTeX.
+\item[minimal]
+\NEWfeature{1995/12/01}
+ This class is the bare minimum (3 lines) that is needed in a
+ \LaTeX\ class file. It just sets the text width and height, and
+ defines |\normalsize|. It is principally intended for debugging
+ and testing \LaTeX\ code in situations where you do not need to
+ load a `full' class such as |article|. If, however, you are
+ designing a completely new class that is aimed for documents with
+ structure radically different from the structure supplied by the
+ article class, then it may make sense to use this as a base and add
+ to it code implementing the required structure, rather than
+ starting from |article| and modifying the code there.
+\end{description}
+
+\subsection{Standard packages}
+\label{Sec:st-pack}
+
+The following packages are distributed with \LaTeX:
+\begin{description}
+\item[alltt]
+\NEWfeature{1994/12/01}
+ This package provides the |alltt| environment, which is like
+ the |verbatim| environment except that |\|, |{|, and |}|
+ have their usual meanings. It is described in |alltt.dtx| and
+ \emph{\LaTeXbook}.
+\item[doc] This is the basic package for typesetting the documentation
+ of \LaTeX{} programs. It is described in |doc.dtx| and in
+ \emph{\LaTeXcomp}.
+\item[exscale] This provides scaled versions of the math extension
+ font. It is described in |exscale.dtx| and \emph{\LaTeXcomp}.
+ \item[fontenc] This is used to specify which font encoding \LaTeX{}
+ should use. It is described in |ltoutenc.dtx|.
+\item[graphpap]
+\NEWfeature{1994/12/01}
+ This package defines the |\graphpaper| command; this
+ can be used in a |picture| environment.
+\item[ifthen] Provides commands of the form `if\dots then do\dots
+ otherwise do\dots'.
+ It is described in |ifthen.dtx| and \emph{\LaTeXcomp}.
+\item[inputenc]
+\NEWfeature{1994/12/01}
+ This is used to specify which input encoding \LaTeX{} should use.
+ It is described in |inputenc.dtx|.
+\item[latexsym] \LaTeXe{} no longer loads the \LaTeX{} symbol font by
+ default. To access it, you should use the |latexsym| package. It
+ is described in |latexsym.dtx| and in \emph{\LaTeXcomp}; see also
+ Section~\ref{Sec:problems}.
+ \item[makeidx] This provides commands for producing indexes. It is
+ described in \emph{\LaTeXbook} and in \emph{\LaTeXcomp}.
+ \item[newlfont] This is used to emulate the font commands of
+ \LaTeX~2.09 with the New Font Selection Scheme. It is described in
+ \emph{\LaTeXcomp}.
+ \item[oldlfont] This is used to emulate the font commands of
+ \LaTeX~2.09. It is described in \emph{\LaTeXcomp}.
+ \item[showidx]
+ This causes the argument of each |\index| command to
+ be printed on the page where it occurs.
+ It is described in \emph{\LaTeXbook}.
+ \item[syntonly] This is used to process a document without
+ typesetting it. It is described in |syntonly.dtx| and in
+ \emph{\LaTeXcomp}.
+ \item[tracefnt] This allows you to control how much information about
+ \LaTeX's font loading is displayed. It is described in
+ \emph{\LaTeXcomp}.
+\end{description}
+
+\subsection{Related software}
+
+\NEWdescription{1998/12/01}
+The following software should be available from the same distributor
+as your copy of \LaTeXe. You should obtain at least the
+\textsf{graphics} and \textsf{tools} collections in order to have all
+the files described in \emph{\LaTeXbook}. The |amsmath| package (part
+of \textsf{amslatex} and formerly known as |amstex|)
+and \textsf{babel} are also mentioned in the list
+of `standard packages' in section C.5.2 of that book.
+\begin{description}
+\item[amslatex] Advanced mathematical typesetting from the American
+ Mathematical Society. This includes the |amsmath| package; it
+ provides many commands for typesetting mathematical formulas of
+ higher complexity. It is produced and supported by the American
+ Mathematical Society and it is described in \emph{\LaTeXcomp}.
+\item[babel] This package and related files support typesetting in
+ many languages. It is described in \emph{\LaTeXcomp}.
+\item[cyrillic]
+\NEWfeature{1998/12/01}
+ Everything you need (except the fonts themselves) for
+ typesetting with Cyrillic fonts.
+\item[graphics] This includes the |graphics| package which
+ provides support for the inclusion and transformation of graphics,
+ including files produced by other software. Also included, is the
+ |color| package which provides support for typesetting in colour.
+ Both these packages are described in \emph{\LaTeXbook}.
+\item[psnfss] Everything you need (except the fonts themselves) for
+ typesetting with a large range of Type~1 (PostScript) fonts.
+\item[tools] Miscellaneous packages written by the \LaTeX3
+ project team.
+\end{description}
+These packages come with documentation and each of them is also
+described in at least one of the books \emph{\LaTeXcomp} and
+\emph{\LaTeXbook}.
+
+\subsubsection{Tools}
+
+This collection of packages includes, at least, the following (some
+files may have slightly different names on certain systems):
+
+\begin{description}
+\item[array]
+ Extended versions of the environments |array|, |tabular|
+ and |tabular*|, with many extra features.
+\item[calc]
+\NEWfeature{1996/12/01}
+ Enables the use of certain algebraic notation when specifying
+ values for lengths and counters.
+\item[dcolumn]
+ Alignment on `decimal points' in tabular entries. Requires the
+ |array| package.
+\item[delarray]
+ Adds `large delimiters' around arrays. Requires |array|.
+\item[hhline]
+ Finer control over horizontal rules in tables. Requires |array|.
+\item[longtable]
+ Multi-page tables. (Does not require |array|, but it uses the
+ extended features if both are loaded.)
+\item[tabularx]
+ Defines a |tabularx| environment that is similar to |tabular*|
+ but it modifies the column widths, rather than the inter-column
+ space, to achieve the desired table width.
+\item[afterpage]
+ Place text after the current page.
+\item[bm]
+ Access bold math symbols.
+\item[enumerate]
+ Extended version of the |enumerate| environment.
+\item[fontsmpl]
+ Package and test file for producing `font samples'.
+\item[ftnright]
+ Place all footnotes in the right-hand column in two-column mode.
+\item[indentfirst]
+ Indent the first paragraph of sections, etc.
+\item[layout]
+ Show the page layout defined by the current document class.
+\item[multicol]
+ Typeset text in columns, with the length of the columns
+ `balanced'.
+\item[rawfonts]
+ Preload fonts using the old internal font names of \LaTeX~2.09.
+ See Section~\ref{Sec:oldinternals}.
+\item[somedefs]
+ Selective handling of package options. (Used by the rawfonts
+ package.)
+\item[showkeys]
+ Prints the `keys' used by |\label|, |\ref|, |\cite| etc.; useful
+ whilst drafting.
+\item[theorem]
+ Flexible declaration of `theorem-like' environments.
+\item[varioref]
+ `Smart' handling of page references.
+\item[verbatim]
+ Flexible extension of the verbatim environment.
+\item[xr]
+ Cross reference other `external' documents.
+\item[xspace]
+ `Smart space' command that helps you to avoid the common mistake
+ of missing spaces after command names.
+\end{description}
+
+
+\section{Commands}
+\label{Sec:commands}
+
+This section describes the new commands available in \LaTeXe.
+They are covered in more detail in \emph{\LaTeXbook} and in
+\emph{\LaTeXcomp}.
+
+\subsection{Preamble commands}
+\label{Sec:pre}
+
+The changes to the preamble commands are intentionally designed to make
+\LaTeXe{} documents look clearly different from old documents. The
+commands should be used only before |\begin{document}|.
+
+\begin{decl}
+|\documentclass| \oarg{option-list} \arg{class-name}
+ \oarg{release-date}
+\end{decl}
+
+This command replaces the
+\LaTeX~2.09 command |\documentstyle|.
+
+There must be exactly one |\documentclass| command in a document; and
+it should normally come before any other command. (There are some
+exceptions, e.g., you can have |filecontents| environments before it
+or |\RequirePackage| but these should be only used in special
+scenarios as discussed elsewhere.)
+
+The \m{option-list} is a list of options, each of which may modify the
+formatting of elements which are defined in the \m{class-name} file,
+as well as those in all following |\usepackage| commands (see
+below).
+
+The optional argument \m{release-date} can be used to specify the
+earliest desired release date of the class file; it should contain a
+date in the format \textsc{yyyy/mm/dd}. If a version of the class
+older than this date is found, a warning is issued.
+
+For example, to specify a two-column article, using a version of
+|article.cls| released after June 1994, you specify:
+\begin{verbatim}
+ \documentclass[twocolumn]{article}[1994/06/01]
+\end{verbatim}
+
+\begin{decl}
+|\documentstyle| \oarg{option-list} \arg{class-name}
+\end{decl}
+
+This command is still supported for compatibility with old files. It
+is essentially the same as |\documentclass| except that it invokes
+\emph{\LaTeX~2.09 compatibility mode}. It also causes any options in
+the \m{option-list} that are not processed by the class file to be
+loaded as packages after the class has been loaded. See
+Section~\ref{Sec:209} for more details on \LaTeX~2.09 compatibility
+mode.
+
+\begin{decl}
+|\usepackage| \oarg{option-list} \arg{package-name} \oarg{release-date}
+\end{decl}
+
+Any number of |\usepackage| commands is allowed. Each package file
+(as denoted by \m{package-name}) defines new elements (or modifies
+those defined in the class file loaded by the \m{class-name} argument
+of the |\documentclass| command). A package file thus extends the
+range of documents which can be processed.
+
+The \m{option-list} argument can contain a list of options, each of
+which can modify the formatting of elements which are defined in this
+\m{package-name} file.
+
+As above, \m{release-date} can contain the earliest desired release
+date of the package file in the format \textsc{yyyy/mm/dd}; if an
+older version of the package is found, a warning is issued.
+
+For example, to load the |graphics| package for the |dvips| driver,
+using a version of |graphics.sty| released after June 1994, you write:
+\begin{verbatim}
+ \usepackage[dvips]{graphics}[1994/06/01]
+\end{verbatim}
+Each package is loaded only once. If the same package is requested
+more than once, nothing happens in the second or following attempt
+unless the package has been requested with options that were not given
+in the original |\usepackage|. If such extra options are specified
+then an error message is produced. See Section~\ref{Sec:problems} how
+to resolve this problem.
+
+As well as processing the options given in the \m{option-list} of the
+|\usepackage| command, each package processes the
+\m{option-list} of the |\documentclass| command as well. This
+means that any option which should be processed by every package (to
+be precise, by every package that specifies an action for it) can be
+specified just once, in the |\documentclass| command, rather than
+being repeated for each package that needs it.
+
+\begin{decl}
+|\listfiles|
+\end{decl}
+
+If this command is placed in the preamble then a list of the files
+read in (as a result of processing the document) will be displayed
+on the terminal (and in the log file) at the end of the run. Where
+possible, a short description will also be produced.
+
+\NEWdescription{1995/12/01}
+\emph{Warning}: this command will list only files which were read
+using \LaTeX{} commands such as |\input|\arg{file} or
+|\include|\arg{file}. If the file was read using the primitive \TeX{}
+syntax |\input |\emph{file} (without |{ }| braces around the file name)
+then it will not be listed; failure to use the \LaTeX{} form with the
+braces can cause more severe problems, possibly leading to overwriting
+important files, so \textbf{always put in the braces}.
+
+
+\begin{decl}
+|\setcounter{errorcontextlines}| \arg{num}
+\end{decl}
+
+\TeX~3 introduced a new primitive |\errorcontextlines| which controls
+the format of error messages. \LaTeXe\ provides an interface to this
+through the standard |\setcounter| command. As most \LaTeX\ users do
+not want to see the internal definitions of \LaTeX\ commands each time
+they make an error, \LaTeXe{} sets this to $-1$ by default.
+
+
+\subsection{Environments to write out support files}
+
+\NEWfeature{2019}
+%
+Until the \LaTeX\ release in 2019 the |filecontents| environment was
+restricted to a place before the |\documentclass| command. These days
+it can be used anywhere, though we still think that in most cases it is
+best to only use it a the top of your document or in the preamble.
+
+\begin{decl}
+|\begin{filecontents}| \oarg{option-list} \arg{file-name} \\
+ \m{file-contents} \\
+|\end{filecontents}|
+\end{decl}
+
+The |filecontents| environment is intended for bundling within a
+single document file the contents of packages, options, or other
+files. When the document file is run through \LaTeXe{} the body of
+this environment is written verbatim (preceded by a comment line) to a
+file whose name is given as the environment's only argument. However,
+if that file already exists then nothing happens except for an
+information message.
+
+These days most UTF-8 text characters can be used in a
+|filecontents| envi\-ronment---they will be written unchanged to the
+output file. However, tabs and form feeds produce a warning,
+explaining that they are turned into spaces or blank lines,
+respectively.
+
+By default the environment does not overwrite an existing file and it
+even refuses to write out the data if there exists a file that is
+anywhere in the path that \TeX\ searches when inputting files. With
+the option |nosearch| you can ask it to look only into the current
+directory and with the option |overwrite| (or |force|) you can request
+it to write the file regardless. It will, however, never write to
+|\jobname.tex| to avoid overwriting itself.
+
+The |filecontents| environment is used for including \LaTeX{} files.
+For other plain text files (such as Encapsulated PostScript files),
+you should use the |filecontents*| environment which does not add a
+comment line.
+
+
+
+
+\subsection{Document structure}
+
+The |book| document class introduces new commands to indicate
+document structure.
+\begin{decl}
+|\frontmatter| \\ |\mainmatter| \\ |\backmatter|
+\end{decl}
+These commands indicate the beginning of the front matter (title page,
+table of contents and prefaces), main matter (main text) and back
+matter (bibliography, indexes and colophon).
+
+\subsection{Definitions}
+
+In \LaTeX, commands can have both mandatory and optional arguments,
+for example in:
+\begin{verbatim}
+ \documentclass[11pt]{article}
+\end{verbatim}
+the |11pt| argument is optional, whereas the |article| class name is
+mandatory.
+
+In \LaTeX~2.09 users could define commands with arguments, but these
+had to be mandatory arguments. With \LaTeXe, users can now define
+commands and environments which also have one optional argument.
+
+\begin{decl}
+|\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
+|\newcommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
+|\renewcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
+|\renewcommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
+\end{decl}
+
+These commands have a new, second, optional argument; this is used for
+defining commands which themselves take one optional argument. This
+new argument is best introduced by means of a simple (and hence not
+very practical) example:
+\begin{verbatim}
+ \newcommand{\example}[2][YYY]{Mandatory arg: #2;
+ Optional arg: #1.}
+\end{verbatim}
+This defines |\example| to be a command with two arguments, referred
+to as |#1| and |#2| in the \arg{definition}---nothing new so far. But
+by adding a second optional argument to this |\newcommand| (the
+|[YYY]|) the first argument (|#1|) of the newly defined command
+|\example| is made optional with its default value being |YYY|.
+
+Thus the usage of |\example| is either:
+\begin{verbatim}
+ \example{BBB}
+\end{verbatim}
+which prints:
+\begin{quote}
+ Mandatory arg: BBB;
+ Optional arg: YYY.
+\end{quote}
+or:
+\begin{verbatim}
+ \example[XXX]{AAA}
+\end{verbatim}
+which prints:
+\begin{quote}
+ Mandatory arg: AAA;
+ Optional arg: XXX.
+\end{quote}
+
+The default value of the optional argument is \texttt{YYY}.
+This value is specified as the \oarg{default} argument of the
+|\newcommand| that created |\example|.
+
+As another more useful example, the definition:
+\begin{verbatim}
+ \newcommand{\seq}[2][n]{\lbrace #2_{0},\ldots,\,#2_{#1} \rbrace}
+\end{verbatim}
+means that the input |$\seq{a}$| produces
+the formula $\lbrace a_{0},\ldots,\,a_{n} \rbrace$,
+whereas the input |$\seq[k]{x}$| produces the formula
+$\lbrace x_{0},\ldots,\,x_{k} \rbrace$.
+
+In summary, the command:
+\begin{quote}
+ |\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
+\end{quote}
+defines \m{cmd} to be a command with \m{num} arguments, the first of
+which is optional and has default value \m{default}.
+
+Note that there can only be one optional argument but, as before,
+there can be up to nine arguments in total.
+
+\begin{decl}
+|\newenvironment|
+ \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\
+|\newenvironment*|
+ \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\
+|\renewenvironment|
+ \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\
+|\renewenvironment*|
+ \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def}
+\end{decl}
+
+\LaTeXe\ also supports the creation of environments that have one
+optional argument. Thus the syntax of these two commands has
+been extended in the same way as that of |\newcommand|.
+
+\begin{decl}
+|\providecommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
+|\providecommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
+\end{decl}
+
+This takes the same arguments as |\newcommand|. If \m{cmd} is already
+defined then the existing definition is kept; but if it is currently
+undefined then the effect of |\providecommand| is to define \m{cmd}
+just as if |\newcommand| had been used.
+
+\NEWfeature{1994/12/01}
+ All the above five `defining commands' now have \texttt{*}-forms that
+ are usually the better form to use when defining commands with
+ arguments, unless any of these arguments is intended to contain
+ whole paragraphs of text. Moreover, if you ever do find yourself
+ needing to use the non-star form then you should ask whether
+ that argument would not better be treated as the contents of a
+ suitably defined environment.
+
+\NEWfeature{1995/12/01}
+ The commands produced by the above five `defining commands' are
+ now robust.
+
+\subsection{Boxes}
+
+These next three commands for making LR-boxes all existed in
+\LaTeX~2.09. They have been enhanced in two ways.
+
+\begin{decl}
+|\makebox| \oarg{width} \oarg{pos} \arg{text} \\
+|\framebox| \oarg{width} \oarg{pos} \arg{text} \\
+|\savebox| \arg{cmd} \oarg{width} \oarg{pos} \arg{text}
+\end{decl}
+
+One small but far-reaching change for \LaTeXe\ is that, within the
+\m{width} argument only, four special lengths can be used. These are
+all dimensions of the box that would be produced by using simply
+|\mbox|\arg{text}:
+\begin{itemize}
+\item [] |\height|\quad its height above the baseline;
+\item [] |\depth|\quad its depth below the baseline;
+\item [] |\totalheight|\quad the sum of |\height| and |\depth|;
+\item [] |\width|\quad its width.
+\end{itemize}
+Thus, to put `hello' in the centre of a box of twice its natural
+width, you would use:
+\begin{verbatim}
+ \makebox[2\width]{hello}
+\end{verbatim}
+Or you could put \textit{f} into a square box, like
+this:
+ \framebox{\makebox[\totalheight]{\itshape f\/}}
+\begin{verbatim}
+ \framebox{\makebox[\totalheight]{\itshape f\/}}
+\end{verbatim}
+Note that it is the total width of the framed box, including the
+frame, which is set to |\totalheight|.
+
+The other change is a new possibility for \m{pos}: |s| has been added
+to |l| and |r|. If \m{pos} is |s| then the text is stretched the full
+length of the box, making use of any `rubber lengths' (including any
+inter-word spaces) in the contents of the box. If no such `rubber
+length' is present, an `underfull box' will probably be produced.
+
+\begin{decl}
+|\parbox| \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width}
+ \arg{text} \\
+|\begin{minipage}|
+ \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width}\\
+\m{text}\\
+|\end{minipage}|
+\end{decl}
+
+As for the box commands above, |\height|, |\width|, etc.~may be used
+in the \oarg{height} argument to denote the natural dimensions of the
+box.
+
+The \m{inner-pos} argument is new in \LaTeXe. It is the vertical
+equivalent to the \m{pos} argument for |\makebox|, etc, determining
+the position of \m{text} within the box. The \m{inner-pos} may be any
+one of |t|, |b|, |c|, or |s|, denoting top, bottom, centered, or
+`stretched' alignment respectively. When the \m{inner-pos} argument
+is not specified, \LaTeX\ gives it same value as \m{pos} (this could be
+the latter's default value).
+
+
+\begin{decl}
+|\begin{lrbox}| \arg{cmd}\\
+\m{text}\\
+|\end{lrbox}|
+\end{decl}
+
+This is an environment which does not directly print anything.
+Its effect is to save the typeset \m{text} in the bin \m{cmd}. Thus
+it is like |\sbox| \arg{cmd} \arg{text}, except that any white space
+before or after the contents \m{text} is ignored.
+
+This is very useful as it enables both the |\verb| command and the
+\texttt{verbatim} environment to be used within \m{text}.
+
+It also makes it possible to define, for example, a `framed box'
+environment. This is done by first using this environment to save
+some text in a bin \m{cmd} and then calling
+|\fbox{\usebox{|\m{cmd}|}}|.
+
+The following example defines an environment, called |fmpage|, that is
+a framed version of |minipage|.
+\begin{verbatim}
+ \newsavebox{\fmbox}
+ \newenvironment{fmpage}[1]
+ {\begin{lrbox}{\fmbox}\begin{minipage}{#1}}
+ {\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}}
+\end{verbatim}
+
+
+\subsection{Measuring things}
+
+The first of these next commands was in \LaTeX~2.09. The two new
+commands are the obvious analogues.
+
+\begin{decl}
+|\settowidth| \arg{length-cmd} \arg{lr text} \\
+|\settoheight| \arg{length-cmd} \arg{lr text} \\
+|\settodepth| \arg{length-cmd} \arg{lr text}
+\end{decl}
+
+\subsection{Line endings}
+
+\NEWdescription{1994/12/01}
+The command |\\|, which is used to indicate a line-end in various
+places, is now a robust command when used within arguments such as
+section titles.
+
+Also, because it is often necessary to distinguish which type of line
+is to be ended, we have introduced the following new command; it
+has the same argument syntax as that of |\\|.
+\begin{decl}[1994/12/01]
+|\tabularnewline| \oarg{vertical-space}
+\end{decl}
+One example of its use is when the text in the last
+column of a |tabular| environment is set with |\raggedright|; then
+|\tabularnewline| can be used to indicate the end of a row of the
+|tabular|, whilst |\\| will indicate the end of a line of text in a
+paragraph within the column. This command can be used in the |array|
+environment as well as |tabular|, and also the extended versions of
+these environments offered by the \textsf{array} and \textsf{longtable}
+packages in the tools collection.
+
+\subsection{Controlling page breaks}
+
+Sometimes it is necessary, for a final version of a document, to
+`help' \LaTeX\ break the pages in the best way. \LaTeX~2.09 had a
+variety of commands for this situation: |\clearpage|, |\pagebreak|
+etc. \LaTeXe\ provides, in addition, commands which can produce
+longer pages as well as shorter ones.
+
+
+\begin{decl}
+|\enlargethispage| \arg{size} \\
+|\enlargethispage*| \arg{size}
+\end{decl}
+
+These commands increase the height of a page (from its normal value of
+|\textheight|) by the specified amount \m{size}, a rigid length. This
+change affects \emph{only} the current page.
+
+This can be used, for example, to allow an extra line to be fitted
+onto the page or, with a negative length, to produce a page
+shorter than normal.
+
+The star form also shrinks any vertical white space on the page as
+much as possible, so as to fit the maximum amount of text on the
+page.
+
+\NEWdescription{1995/12/01}
+These commands do not change the position of the footer text; thus, if
+a page is lengthened too far, the main text may overprint the footer.
+
+\subsection{Floats}
+
+There is a new command, |\suppressfloats|, and a new `float
+specifier'. These will enable people to gain better
+control of \LaTeX's float placement algorithm.
+
+\begin{decl}
+|\suppressfloats| \oarg{placement}
+\end{decl}
+
+This command stops any further floating environments from being placed
+on the current page. With an optional argument, which should be either
+|t| or |b| (not both), this restriction applies only to putting
+further floats at the top or at the bottom. Any floats which would
+normally be placed on this page are placed on the next page instead.
+
+\begin{decl}
+The extra float location specifier: \ \texttt{!}
+\end{decl}
+
+This can be used, along with at least one of \texttt{h}, \texttt{t},
+\texttt{b} and \texttt{p}, in the location optional argument of a
+float.
+
+If a \texttt{!} is present then, just for this particular float,
+whenever it is processed by the float mechanism the following are
+ignored:
+\begin{itemize}
+\item all restrictions on the number of floats which can appear;
+\item all explicit restrictions on the amount of space on a text page
+which may be occupied by floats or must be occupied by text.
+\end{itemize}
+The mechanism will, however, still attempt to ensure that pages are
+not overfull and that floats of the same type are printed in the
+correct order.
+
+Note that its presence has no effect on the production of float pages.
+
+A \texttt{!} specifier overrides the effect of any |\suppressfloats|
+command for this particular float.
+
+\subsection{Font changing: text}
+
+The font selection scheme used in \LaTeXe{} differs a lot from that
+used in \LaTeX~2.09. In this section, we give a brief description of
+the new commands. A more detailed description with examples is given
+in \emph{\LaTeXcomp}, and the interface for class- and package-writers
+is described in \emph{\fntguide}.
+
+\begin{decl}
+|\normalfont|\\
+|\rmfamily|\\
+|\sffamily|\\
+|\ttfamily|\\
+|\mdseries|\\
+|\bfseries|\\
+|\upshape|\\
+|\itshape|\\
+|\slshape|\\
+|\scshape|
+\end{decl}
+
+These are font commands whose use is the same as the commands |\rm|,
+|\bf|, etc. The difference is that each command changes just one
+attribute of the font (the attribute changed is part of the name).
+One result of this is that, for example, |\bfseries\itshape| produces
+both a change of series and a change of shape, to give a bold italic
+font.
+
+\begin{decl}
+|\textnormal|\arg{text}\\
+|\textrm|\arg{text}\\
+|\textsf|\arg{text}\\
+|\texttt|\arg{text}\\
+|\textmd|\arg{text}\\
+|\textbf|\arg{text}\\
+|\textup|\arg{text}\\
+|\textit|\arg{text}\\
+|\textsl|\arg{text}\\
+|\textsc|\arg{text}\\
+|\emph|\arg{text}
+\end{decl}
+
+These are one-argument commands; they take as an argument the
+text which is to be typeset in the particular font. They also
+automatically insert italic corrections where appropriate; if you do
+not like the result, you can add an italic correction with |\/| or
+remove it with |\nocorr|. The |\nocorr| should always be the first or
+last thing within the \arg{text} argument.
+
+\subsection{Font changing: math}
+
+Most of the fonts used within math mode do not need to be explicitly
+invoked; but to use letters from a range of fonts, the following
+class of commands is provided.
+
+\begin{decl}
+|\mathrm| \arg{letters}\\
+|\mathnormal| \arg{letters}\\
+|\mathcal| \arg{letters}\\
+|\mathbf| \arg{letters}\\
+|\mathsf| \arg{letters}\\
+|\mathtt| \arg{letters}\\
+|\mathit| \arg{letters}
+\end{decl}
+
+These are also one-argument commands which take as an argument the
+letters which are to be typeset in the particular font. The argument
+is processed in math mode so spaces within it will be ignored. Only
+letters, digits and accents have their font changed, for example
+|$\mathbf{\tilde A \times 1}$| produces $\mathbf{\tilde A \times 1}$.
+
+\subsection{Ensuring math mode}
+
+\begin{decl}
+|\ensuremath| \arg{math commands}
+\end{decl}
+
+In \LaTeX~2.09, if you wanted a command to work both in math mode and
+in text mode, the suggested method was to define something like:
+\begin{verbatim}
+ \newcommand{\Gp}{\mbox{$G_p$}}
+\end{verbatim}
+Unfortunately, the |\mbox| stops |\Gp| changing size correctly in (for
+instance) subscripts or a fraction.
+
+In \LaTeXe{} you can define it thus:
+\begin{verbatim}
+ \newcommand{\Gp}{\ensuremath{G_p}}
+\end{verbatim}
+Now |\Gp| will work correctly in all contexts.
+
+This is because the |\ensuremath| does nothing, producing simply
+|G_p|, when |\Gp| is used within math mode; but it ensures that math
+mode is entered (and exited) as required when |\Gp| is used in text
+mode.
+
+
+\subsection{Setting text superscripts}
+
+\begin{decl}
+|\textsuperscript| \arg{text}
+\end{decl}
+
+\NEWfeature{1995/06/01} In \LaTeX~2.09 textual superscripts such as
+footnote markers were produced by internally entering math mode and
+typesetting the number as a math superscript. This normally looked
+fine since the digits in math fonts are the same as those in text
+fonts when Computer Modern fonts are used. But when a different
+document font (such as Times) is selected, the results look rather
+strange. For this reason the command |\textsuperscript| has been
+introduced which typesets its argument in the current text font, in a
+superscript position and in the correct size.
+
+\subsection{Text commands: all encodings}
+
+\NEWdescription{1994/12/01}
+ One of the main differences between \LaTeXe{} and \LaTeX~2.09 is
+ that \LaTeXe{} can deal with fonts in arbitrary \emph{encodings}.
+ (A font encoding is the sequence of characters in the font---for
+ example a Cyrillic font would have a different encoding from a Greek
+ font.)
+
+ The two major font encodings that are used for Latin languages such
+ as English or German are |OT1| (Donald Knuth's 7-bit encoding, which
+ has been used during most of \TeX's lifetime) and |T1| (the new
+ 8-bit `Cork' encoding).
+
+ \LaTeX~2.09 only supported the |OT1| encoding, whereas \LaTeXe{} has
+ support for both |OT1| and |T1| built-in. The next section will
+ cover the new commands which are available if you have |T1|-encoded
+ fonts. This section describes new commands which are available in
+ all encodings.
+
+ Most of these commands provide characters which were available in
+ \LaTeX~2.09 already. For example |\textemdash| gives an `em dash',
+ which was available in \LaTeX~2.09 by typing |---|. However, some
+ fonts (for example a Greek font) may not have the |---| ligature,
+ but you will still be able to access an em dash by typing
+ |\textemdash|.
+
+\begin{decl}[1994/12/01]
+ |\r{<text>}|
+\end{decl}
+ This command gives a `ring' accent, for example `\r{o}' can be typed
+ |\r{o}|.
+
+\begin{decl}[1994/12/01]
+ |\SS|
+\end{decl}
+ This command produces a German `SS', that is a capital `\ss'. This
+ letter can hyphenate differently from `SS', so is needed for entering
+ all-caps German.
+
+\begin{decl}[1994/12/01]
+ |\textcircled{<text>}|
+\end{decl}
+ This command is used to build `circled characters' such as
+ |\copyright|. For example |\textcircled{a}| produces
+ \textcircled{a}.
+
+\begin{decl}[1994/12/01]
+ |\textcompwordmark|
+\end{decl}
+ This command is used to separate letters which would normally
+ ligature. For example `f\textcompwordmark i' is produced with
+ |f\textcompwordmark i|. Note that the `f' and `i' have not
+ ligatured to produce `fi'. This is rarely useful in English
+ (`shelf\textcompwordmark ful' is a rare example of where it might be
+ used) but is used in languages such as German.
+
+\begin{decl}[1994/12/01]
+ |\textvisiblespace|
+\end{decl}
+ This command produces a `visible space' character
+ `\textvisiblespace'. This is sometimes used in computer listings,
+ for example `type \textsf{hello\textvisiblespace world}'.
+
+\begin{decl}[1994/12/01]
+ |\textemdash|
+ |\textendash|
+ |\textexclamdown|
+ |\textquestiondown| \\
+ |\textquotedblleft|
+ |\textquotedblright|
+ |\textquoteleft|
+ |\textquoteright|
+\end{decl}
+ These commands produce characters which would otherwise be
+ accessed via ligatures:
+ \begin{center}
+ \begin{tabular}{ccl}
+ \emph{ligature} & \emph{character} & \emph{command} \\
+ |---| & --- & |\textemdash| \\
+ |--| & -- & |\textendash| \\
+ |!`| & !` & |\textexclamdown| \\
+ |?`| & ?` & |\textquestiondown| \\
+ |``| & `` & |\textquotedblleft| \\
+ |''| & '' & |\textquotedblright| \\
+ |`| & ` & |\textquoteleft| \\
+ |'| & ' & |\textquoteright|
+ \end{tabular}
+ \end{center}
+ The reason for making these characters directly accessible is so
+ that they will work in encodings which do not have these characters.
+
+\begin{decl}[1994/12/01]
+ |\textbullet|
+ |\textperiodcentered|
+\end{decl}
+ These commands allow access to characters which were previously only
+ available in math mode:
+ \begin{center}
+ \begin{tabular}{lcl}
+ \emph{math command} & \emph{character} & \emph{text command} \\
+ |\bullet| & $\bullet$ & |\textbullet| \\
+ |\cdot| & $\cdot$ & |\textperiodcentered|
+ \end{tabular}
+ \end{center}
+
+\begin{decl}[1995/12/01]
+ |\textbackslash|
+ |\textbar|
+ |\textless|
+ |\textgreater|
+\end{decl}
+ These commands allow access to ASCII characters which were
+ only available in verbatim or math mode:
+ \begin{center}
+ \begin{tabular}{lcl}
+ \emph{math command} & \emph{character} & \emph{text command} \\
+ |\backslash| & $\backslash$ & |\textbackslash| \\
+ |\mid| & $\mid$ & |\textbar| \\
+ |<<| & $<$ & |\textless| \\
+ |>>| & $>$ & |\textgreater|
+ \end{tabular}
+ \end{center}
+
+\begin{decl}[1995/12/01]
+ |\textasciicircum|
+ |\textasciitilde|
+\end{decl}
+ These commands allow access to ASCII characters which were
+ previously only available in verbatim:
+ \begin{center}
+ \begin{tabular}{cl}
+ \emph{verbatim} & \emph{text command} \\
+ |^| & |\textasciicircum| \\
+ |~| & |\textasciitilde|
+ \end{tabular}
+ \end{center}
+
+\begin{decl}[1995/12/01]
+ |\textregistered|
+ |\texttrademark|
+\end{decl}
+ These commands provide the `registered trademark' (R) and
+ `trademark' (TM) symbols.
+
+\subsection{Text commands: the T1 encoding}
+
+\NEWdescription{1994/12/01}
+ The |OT1| font encoding is fine for typesetting in English, but has
+ problems when typesetting other languages. The |T1| encoding solves
+ some of these problems, by providing extra characters (such as `eth'
+ and `thorn'), and it allows words containing accented letters to be
+ hyphenated (as long as you have a package like |babel| which allows
+ for non-American hyphenation).
+
+ This section describes the commands you can use if you have the |T1|
+ fonts. To use them, you need to get the `ec fonts', or the
+ |T1|-encoded PostScript fonts, as used by \textsf{psnfss}.
+ All these fonts are
+ available by anonymous ftp in the Comprehensive \TeX{} Archive, and
+ are also available on the CD-ROMs \emph{4all \TeX} and
+ \emph{\TeX{} Live} (both available from the \TeX{} Users Group).
+
+ You can then select the |T1| fonts by saying:
+\begin{verbatim}
+ \usepackage[T1]{fontenc}
+\end{verbatim}
+ This will allow you to use the commands in this section.
+
+ \emph{Note:} Since this document must be processable on any site
+ running an up-to-date \LaTeX, it does not contain any characters
+ that are present only in |T1|-encoded fonts. This means that this
+ document cannot show you what these glyphs look like! If you want
+ to see them then run \LaTeX{} on the document |fontsmpl| and
+ respond `|cmr|' when it prompts you for a family name.
+
+\begin{decl}[1994/12/01]
+ |\k{<text>}|
+\end{decl}
+ This command produces an `ogonek' accent.
+
+\begin{decl}[1994/12/01]
+ |\DH|
+ |\DJ|
+ |\NG|
+ |\TH|
+ |\dh|
+ |\dj|
+ |\ng|
+ |\th|
+\end{decl}
+ These commands produce characters `eth', `dbar', `eng', and `thorn'.
+
+\begin{decl}[1994/12/01]
+ |\guillemotleft|
+ |\guillemotright|
+ |\guilsinglleft|
+ |\guilsinglright| \\
+ |\quotedblbase|
+ |\quotesinglbase|
+ |\textquotedbl|
+\end{decl}
+ % A local hack (could be improved):
+ \newcommand{\fauxguillemet}[1]{$\vcenter{\hbox{$\scriptscriptstyle#1$}}$}
+ These commands produce various sorts of quotation mark.
+ Rough representations of them are:
+ \fauxguillemet\ll a\fauxguillemet\gg{}
+ \fauxguillemet<a\fauxguillemet>
+ ,\kern -0.1em,\kern 0.05em a\kern -0.05em``
+ ,\kern 0.05em a\kern -0.05em` and |"|a|"|.
+
+\NEWdescription{2001/06/01}
+ There are therefore some extra short-form ligatures available for
+ use in documents that will only be used with |T1|-encoded fonts.
+
+ The guillemets |\guillemotleft| and |\guillemotright|%
+ \footnote{We apologise once again for maintaining Adobe's
+ enormous solipsism~(sic) of confusing a diving bird with
+ punctuation marks!}
+ can be obtained by typing |<<<<| and |>>>>| and |\quotedblbase|
+ by typing |,,|\,.
+
+ Also, unlike the unexpected results with
+ |OT1|-encoded fonts, |<<| and |>>| will produce \textless{} and
+ \textgreater{}.
+
+ Note also that the single character |"| will no longer produce ''
+ but rather |\textquotedbl|.
+
+\subsection{Logos}
+
+\begin{decl}
+|\LaTeX|\\
+|\LaTeXe|
+\end{decl}
+
+|\LaTeX| (producing `\LaTeX') is still the `main' logo command,
+but if you need to refer to the new features, you can write
+|\LaTeXe| (producing `\LaTeXe').
+
+\subsection{Picture commands}
+
+\begin{decl}
+ |\qbezier[<N>](<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)| \\
+ | \bezier{<N>}(<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)|
+\end{decl}
+The |\qbezier| command can be used in |picture| mode to draw a
+quadratic Bezier curve from position |(<AX>,<AY>)| to |(<CX>,<CY>)| with
+control point |(<BX>,<BY>)|. The optional argument \m{N} gives the
+number of points on the curve.
+
+For example, the diagram:
+\begin{center}
+ \begin{picture}(50,50)
+ \thicklines
+ \qbezier(0,0)(0,50)(50,50)
+ \qbezier[20](0,0)(50,0)(50,50)
+ \thinlines
+ \put(0,0){\line(1,1){50}}
+ \end{picture}
+\end{center}
+is drawn with:
+\begin{verbatim}
+ \begin{picture}(50,50)
+ \thicklines
+ \qbezier(0,0)(0,50)(50,50)
+ \qbezier[20](0,0)(50,0)(50,50)
+ \thinlines
+ \put(0,0){\line(1,1){50}}
+ \end{picture}
+\end{verbatim}
+The |\bezier| command is the same, except that the argument \m{N} is not
+optional. It is provided for compatibility with the \LaTeX~2.09
+|bezier| document style option.
+
+\subsection{Old commands}
+
+\begin{decl}
+|\samepage|
+\end{decl}
+
+The |\samepage| command still exists but is no longer being
+maintained.
+This is because it only ever worked erratically; it does not
+guarantee that there will be no page-breaks within its scope; and
+it can cause footnotes and marginals to be wrongly placed.
+
+We recommend using |\enlargethispage| in conjunction with page-break
+commands such as |\newpage| and |\pagebreak| to help control page
+breaks.
+
+\begin{decl}
+ |\SLiTeX|
+\end{decl}
+Since \SLiTeX{} no longer exists, the logo is no longer defined in the
+\LaTeX{} kernel. A suitable replacement is |\textsc{Sli\TeX}|. The
+\SLiTeX{} logo is defined in \LaTeX~2.09 compatibility mode.
+
+\begin{decl}
+|\mho| |\Join| |\Box| |\Diamond| |\leadsto| \\
+|\sqsubset| |\sqsupset| |\lhd| |\unlhd| |\rhd| |\unrhd|
+\end{decl}
+
+These symbols are contained in the \LaTeX{} symbol font, which was
+automatically loaded by \LaTeX~2.09. However, \TeX{} has room for
+only sixteen math font families; thus many users discovered that they
+ran out. Because of this, \LaTeX{} does not load the \LaTeX{} symbol
+font unless you use the \textsf{latexsym} package.
+
+These symbols are also made available, using different fonts, by the
+\textsf{amsfonts} package, which also defines a large number of other
+symbols. It is supplied by the American Mathematical Society.
+
+The \textsf{latexsym} package is loaded automatically in \LaTeX~2.09
+compatibility mode.
+
+\section{\LaTeX~2.09 documents}
+\label{Sec:209}
+
+\LaTeXe{} can process (almost) any \LaTeX~2.09 document, by entering
+\emph{\LaTeX~2.09 compatibility mode}. Nothing has changed, you run
+\LaTeX{} in the same way you always did, and you will get much the
+same results.
+
+The reason for the `almost' is that some \LaTeX~2.09 packages made use
+of low-level unsupported features of \LaTeX. If you discover such a
+package, you should find out if it has been updated to work with
+\LaTeXe. Most packages will still work with \LaTeXe---the easiest way
+to find out whether a package still works is to try it!
+
+\LaTeX~2.09 compatibility mode is a comprehensive emulation of
+\LaTeX~2.09, but at the cost of time. Documents can run up to 50\%
+slower in compatibility mode than they did under \LaTeX~2.09.
+In addition, many of the new features of \LaTeXe{} are not available in
+\LaTeX~2.09 compatibility mode.
+
+\subsection{Warning}
+
+\NEWdescription{1995/12/01}
+This \emph{\LaTeX~2.09 compatibility mode} is provided solely to allow
+you to process 2.09 documents, i.e.~documents that were written (we
+hope, a long time ago) for a very old system and therefore could be
+processed by using a genuine antique \LaTeX~2.09 system.
+
+This mode is therefore \emph{not} intended to provide access to the
+enhanced features of \LaTeXe{}. Thus it must not be used to process
+new documents which masquerade as 2.09 documents (i.e.~they begin with
+|\documentstyle|) but which could not be processed using that genuine
+antique \LaTeX~2.09 system because they contain some new,
+\LaTeXe{}-only, commands or environments.
+
+To prevent such misuse of the system, and the consequent trouble it
+causes when such misleadingly encoded documents are distributed, the
+\emph{\LaTeX~2.09 compatibility mode} turns off most of these new
+features and commands. Any attempt to use them will give you an error
+message and, moreover, many of them simply will not work, whilst
+others will produce unpredictable results.
+So don't bother sending us any bug reports about such occurrences since
+they are intentional.
+
+
+\subsection{Font selection problems}
+\label{Sec:fsprob}
+
+When using compatibility mode, it is possible that you will find
+problems with font-changing commands in some old documents. These
+problems are of two types:
+
+\begin{itemize}
+\item producing error messages;
+\item not producing the font changes you expected.
+\end{itemize}
+
+In case of error messages it is possible that the document (or an old
+style file used therein) contains references to old internal commands
+which are no longer defined, see Section~\ref{Sec:oldinternals} for
+more information if this is the case.
+
+\NEWdescription{1995/12/01}
+One example of the unexpected is if you use one of the new style of
+math-mode font changing command as follows:
+\begin{verbatim}
+$ \mathbf{xy} A $
+\end{verbatim}
+You may well find that this behaves as if you had put:
+\begin{verbatim}
+$ \bf {xy} A $
+\end{verbatim}
+everything including the $A$ coming out bold.
+
+\LaTeX~2.09 allowed sites to customize their \LaTeX{} installation,
+which resulted in documents producing different results on different
+\LaTeX{} installations. \LaTeXe{} no longer allows so much
+customization but, for compatibility with old documents, the local
+configuration file |latex209.cfg| is loaded every time \LaTeXe{}
+enters \LaTeX~2.09 compatibility mode.
+
+For example, if your site was customized to use the New Font
+Selection Scheme (\NFSS) with the |oldlfont| option, then you can
+make \LaTeXe{} emulate this by creating a |latex209.cfg| file
+containing the commands:
+\begin{verbatim}
+\ExecuteOptions{oldlfont}\RequirePackage{oldlfont}
+\end{verbatim}
+Similarly, to emulate \NFSS{} with the |newlfont| option, you can
+create a |latex209.cfg| file containing:
+\begin{verbatim}
+\ExecuteOptions{newlfont}\RequirePackage{newlfont}
+\end{verbatim}
+
+
+\subsection{Native mode}
+\label{Sec:native}
+
+To run an old document faster, and use the new features of
+\LaTeXe, you should try using \emph{\LaTeXe{} native mode}.
+This is done by replacing the command:
+\begin{quote}
+ |\documentstyle[|\m{options}|,|\m{packages}|]|\arg{class}
+\end{quote}
+with:
+\begin{quote}
+ |\documentclass|\oarg{options}\arg{class} \\
+ |\usepackage{latexsym,|\m{packages}|}|
+\end{quote}
+However, some documents which can be processed in \LaTeX~2.09
+compatibility mode may not work in native mode. Some \LaTeX~2.09
+packages will only work with \LaTeXe{} in 2.09 compatibility mode.
+Some documents will cause errors because of \LaTeXe's improved error
+detection abilities.
+
+But most \LaTeX~2.09 documents can be processed by \LaTeXe{}'s native
+mode with the above change. Again, the easiest way to find out
+whether your documents can be processed in native mode is to try it!
+
+
+\section{Local modifications}
+\label{sec:loc}
+
+\NEWdescription{1995/12/01}
+There are two common types of local modifications that can be done
+very simply. Do not forget that documents produced using such
+modifications will not be usable at other places (such documents are
+called `non-portable').
+
+One type of modification is the use of personal commands for commonly
+used symbols or constructions. These should be put into a package
+file (for example, one called \texttt{mymacros.sty}) and loaded by
+putting |\usepackage{mymacros}| in the document preamble.
+
+Another type is a local document class that is very similar to one of
+the standard classes but contains some straightforward modifications
+such as extra environments, different values for some parameters, etc.
+These should be put into a class file; here we shall describe a simple
+method of constructing such a file using, as an example, a class
+called \textsf{larticle} that is very similar to the \textsf{article}
+class.
+
+\NEWfeature{1995/12/01}
+The class file called \texttt{larticle.cls} should (after the
+preliminary identification commands) start as follows:
+\begin{verbatim}
+ \LoadClassWithOptions{article}
+\end{verbatim}
+This command should be followed by whatever additions and changes you
+wish to make to the results of reading in the file
+\texttt{article.sty}.
+
+The effect of using the above |\LoadClassWithOptions| command is to
+load the standard class file \textsf{article} with whatever options
+are asked for by the document. Thus a document using your
+\textsf{larticle} class can specify any option that could be specified
+when using the standard \textsf{article} class; for example:
+\begin{verbatim}
+ \documentclass[a4paper,twocolumn,dvips]{larticle}
+\end{verbatim}
+
+
+\section{Problems}
+\label{Sec:problems}
+
+This section describes some of the things which may go wrong when
+using \LaTeXe, and what you can do about it.
+
+\subsection{New error messages}
+
+\LaTeXe{} has a number of new error messages.
+Please also note that many error messages now produce further helpful
+information if you press |h| in response to the error prompt.
+
+\begin{decl}
+|Option clash for package |\m{package}|.|
+\end{decl}
+The named package has been loaded twice with different options. If
+you enter |h| you will be told what the options were, for example, if
+your document contained:
+\begin{verbatim}
+ \usepackage[foo]{fred}
+ \usepackage[baz]{fred}
+\end{verbatim}
+then you will get the error message:
+\begin{verbatim}
+ Option clash for package fred.
+\end{verbatim}
+and typing |h| at the |?| prompt will give you:
+\begin{verbatim}
+ The package fred has already been loaded with options:
+ [foo]
+ There has now been an attempt to load it with options:
+ [baz]
+ Adding the line:
+ \usepackage[foo,baz]{fred}
+ to your document may fix this.
+ Try typing <<return>> to proceed.
+\end{verbatim}
+The cure is, as suggested, to load the package with both sets of
+options. Note that since \LaTeX{} packages can call other packages,
+it is possible to get a package option clash without explicitly
+requesting the same package twice.
+
+\begin{decl}
+ |Command |\m{command}| not provided in base NFSS.|
+\end{decl}
+The \m{command} is not provided by default in \LaTeXe. This error is
+generated by using one of the commands:
+\begin{verbatim}
+ \mho \Join \Box \Diamond \leadsto
+ \sqsubset \sqsupset \lhd \unlhd \rhd \unrhd
+\end{verbatim}
+which are now part of the \textsf{latexsym} package.
+The cure is to add:
+\begin{verbatim}
+ \usepackage{latexsym}
+\end{verbatim}
+in the preamble of your document.
+
+\begin{decl}
+ |LaTeX2e command <command> in LaTeX 2.09 document.|
+\end{decl}
+The \m{command} is a \LaTeXe{} command but this is a \LaTeX~2.09
+document. The cure is to replace the command by a \LaTeX~2.09
+command, or to run document in native mode, as described in
+Section~\ref{Sec:native}.
+
+\begin{decl}
+ |NFSS release 1 command \newmathalphabet found.|
+\end{decl}
+The command |\newmathalphabet| was used by the New Font Selection
+Scheme Release 1 but it has now been replaced by
+|\DeclareMathAlphabet|, the use of which is described in
+\emph{\fntguide}.
+
+The best cure is to update the package which contained the
+|\newmathalphabet| command. Find out if there is a new release of
+the package, or (if you wrote the package yourself) consult
+\emph{\fntguide} for the new syntax of font commands.
+
+If there is no updated version of the package then you can cure this
+error by using the \textsf{newlfont} or \textsf{oldlfont} package,
+which tells \LaTeX{} which version of |\newmathalphabet| should be
+emulated.
+
+You should use \textsf{oldlfont} if the document selects math fonts with
+syntax such as this:
+\begin{quote}
+ |{\cal A}|, etc.
+\end{quote}
+Use \textsf{newlfont} if the document's syntax is like this:
+\begin{quote}
+ |\cal{A}|, etc.
+\end{quote}
+
+
+\begin{decl}
+ |Text for \verb command ended by end of line.|
+\end{decl}
+The |\verb| command has been begun but not ended on that line. This
+usually means that you have forgotten to put in the end-character of
+the |\verb| command.
+
+\begin{decl}
+ |Illegal use of \verb command.|
+\end{decl}
+The |\verb| command has been used inside the argument of another
+command. This has never been allowed in \LaTeX{}---often producing
+incorrect output without any warning---and so \LaTeXe{} produces
+an error message.
+
+\subsection{Old internal commands}
+\label{Sec:oldinternals}
+
+A number of \LaTeX~2.09 internal commands have been removed, since
+their functionality is now provided in a different way. See
+\emph{\clsguide} for more details of the new, supported interface for
+class and package writers.
+
+\begin{decl}
+ |\tenrm| |\elvrm| |\twlrm| \dots\\
+ |\tenbf| |\elvbf| |\twlbf| \dots\\
+ |\tensf| |\elvsf| |\twlsf| \dots\\
+ $\vdots$
+\end{decl}
+These commands provided access to the seventy fonts preloaded by
+\LaTeX~2.09. In contrast, \LaTeXe{} normally preloads at most
+fourteen fonts, which saves a lot of font memory; but a consequence is
+that any \LaTeX{} file which used the above commands to directly
+access fonts will no longer work.
+
+Their use will usually produce an error message such as:
+\begin{verbatim}
+ ! Undefined control sequence.
+ l.5 \tenrm
+\end{verbatim}
+The cure for this is to update the document to use the new
+font-changing commands provided by \LaTeXe; these are described in
+\emph{\fntguide}.
+
+If this is not possible then, as a last resort, you can
+use the \textsf{rawfonts} package, which loads the
+seventy \LaTeX~2.09 fonts and provides direct access to them using the
+old commands. This takes both time and memory. If you do not
+wish to load all seventy fonts, you can select some of them by using the
+|only| option to \textsf{rawfonts}. For example, to load only |tenrm|
+and |tenbf| you write:
+\begin{verbatim}
+ \usepackage[only,tenrm,tenbf]{rawfonts}
+\end{verbatim}
+
+The \textsf{rawfonts} package is distributed as part of the \LaTeX{}
+tools software, see Section~\ref{Sec:st-pack}.
+
+\subsection{Old files}
+
+One of the more common mistakes in running \LaTeX{} is to read in old
+versions of packages instead of the new versions. If you get an
+incomprehensible error message from a standard package, make sure you
+are loading the most recent version of the package. You can find out
+which version of the package has been loaded by looking in the log
+file for a line like:
+\begin{verbatim}
+ Package: fred 1994/06/01 v0.01 Fred's package.
+\end{verbatim}
+You can use the \m{release-date} options to |\documentclass| and
+|\usepackage| to make sure that you are getting a suitably recent copy
+of the document class or package. This is useful when sending a
+document to another site, which may have out-of-date software.
+
+\subsection{Where to go for more help}
+
+If you can't find the answer for your problem here, try looking in
+\emph{\LaTeXbook} or \emph{\LaTeXcomp}. If you have a problem with
+installing \LaTeX, look in the installation guide files which come with
+the distribution.
+
+If this doesn't help, contact your local \LaTeX{} guru or local
+\LaTeX{} mailing list.
+
+If you think you've discovered a bug then please report it! First,
+you should find out if the problem is with a third-party package or
+class. If the problem is caused by a package or class other than
+those listed in Section~\ref{Sec:class+packages} then please report
+the problem to the author of the package or class, not to the \LaTeX3
+project team.
+
+If the bug really is with core \LaTeX{} then you should create a
+\emph{short}, \emph{self-contained} document which exhibits the
+problem. You should run a \emph{recent} (less than a year old)
+version of \LaTeX{} on the file and then run \LaTeX{} on
+|latexbug.tex|. This will create an error report which you should
+send, together with the sample document and log file, to the
+\LaTeX{} bugs address which can be found in the file
+|latexbug.tex| or |bugs.txt|.
+
+
+\section{Enjoy!}
+\label{Sec:enjoy}
+
+We certainly hope you will enjoy using the new standard \LaTeX{} but,
+if this is not possible, we hope that you will enjoy success and
+fulfillment as a result of the documents which it will help you to
+create.
+
+If you find that the contribution of \LaTeX{} to your life is such
+that you would like to support the work of the project team, then
+please read Section~\ref{Sec:ltx3} and discover practical ways to do
+this.
+
+\begin{thebibliography}{1}
+
+\bibitem{A-W:GRM97}
+Michel Goossens, Sebastian Rahtz and Frank Mittelbach.
+\newblock {\em The {\LaTeX} Graphics Companion}.
+\newblock Addison-Wesley, Reading, Massachusetts, 1997.
+
+
+\bibitem{A-W:GR99}
+Michel Goossens and Sebastian Rahtz.
+\newblock {\em The {\LaTeX} Web Companion}.
+\newblock Addison-Wesley, Reading, Massachusetts, 1999.
+
+
+\bibitem{A-W:DEK91}
+Donald~E. Knuth.
+\newblock {\em The \TeX book}.
+\newblock Addison-Wesley, Reading, Massachusetts, 1986.
+\newblock Revised to cover \TeX3, 1991.
+
+
+\bibitem{A-W:LLa94}
+Leslie Lamport.
+\newblock {\em {\LaTeX:} A Document Preparation System}.
+\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.
+
+\bibitem{A-W:MG2004}
+Frank Mittelbach and Michel Goossens.
+\newblock {\em The {\LaTeX} Companion second edition}.
+\newblock With Johannes Braams, David Carlisle, and Chris Rowley.
+\newblock Addison-Wesley, Reading, Massachusetts, 2004.
+
+
+\end{thebibliography}
+
+\end{document}