diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/base/usrguide.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/base/usrguide.tex | 1815 |
1 files changed, 0 insertions, 1815 deletions
diff --git a/Master/texmf-dist/source/latex/base/usrguide.tex b/Master/texmf-dist/source/latex/base/usrguide.tex deleted file mode 100644 index 5f7a9404d53..00000000000 --- a/Master/texmf-dist/source/latex/base/usrguide.tex +++ /dev/null @@ -1,1815 +0,0 @@ -% \iffalse meta-comment -% -% Copyright 1993-2014 -% 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--2014, \LaTeX3 Project Team.\\ - All rights reserved.} - -\date{29 September 2014} - - -\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} - tex-archive/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} -|\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} -|\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} |