From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex-dev/doc/usrguide.tex | 1817 +++++++++++++++++++++++++++++++++++++ 1 file changed, 1817 insertions(+) create mode 100644 macros/latex-dev/doc/usrguide.tex (limited to 'macros/latex-dev/doc/usrguide.tex') diff --git a/macros/latex-dev/doc/usrguide.tex b/macros/latex-dev/doc/usrguide.tex new file mode 100644 index 0000000000..df02c20293 --- /dev/null +++ b/macros/latex-dev/doc/usrguide.tex @@ -0,0 +1,1817 @@ +% \iffalse meta-comment +% +% Copyright 1993-2019 +% The LaTeX3 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 2005/12/01 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.tex + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[2001/05/28] + +\title{\LaTeXe~for authors} + +\author{\copyright~Copyright 1995--2019, \LaTeX3 Project Team.\\ + All rights reserved.} + +\date{27 January 2019} + + +\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 \LaTeX3 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 +\LaTeX3. + +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{Initial commands} + +Initial commands can appear only before the |\documentclass| +line. + +\begin{decl} +|\begin{filecontents}| \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. + +Only normal ASCII text characters (7-bit visible text) should be +included in a |filecontents| environment. Anything else, such as tab +characters, form-feeds or 8-bit characters, should not be included in a +|filecontents| environment. + +Tabs and form feeds produce a warning, explaining that they are turned +into spaces or blank lines, respectively. +What happens to 8-bit characters depends on the \TeX{} installation and +is in general unpredictable. + +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. + +These environments are allowed only before |\documentclass|. This +ensures that any packages that have been bundled in the document are +present when needed. + +\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 must come after the |filecontents| environments, if any, but before +any other commands. + +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{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{}| +\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{}| +\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{}| +\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 + ,\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[](,)(,)(,)| \\ + | \bezier{}(,)(,)(,)| +\end{decl} +The |\qbezier| command can be used in |picture| mode to draw a +quadratic Bezier curve from position |(,)| to |(,)| with +control point |(,)|. 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 <> 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 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} -- cgit v1.2.3