% \iffalse meta-comment
%
% Copyright (C) 1993 by LaTeX3 project.  All rights reserved.
% For additional copyright information see further down in this file.
% 
% This file is part of the LaTeX2e system (PRELIMINARY TEST RELEASE)
% ------------------------------------------------------------------
% 
%  This system is distributed in the hope that it will be useful,
%  but WITHOUT ANY WARRANTY; without even the implied warranty of
%  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
% 
% 
% IMPORTANT NOTICE:
% 
% For error reports in case of UNCHANGED versions see readme files.
% 
% Please do not request updates from us directly.  Distribution is
% done through Mail-Servers and TeX organizations.
% 
% You are not allowed to change this file.
% 
% You are allowed to distribute this file under the condition that
% it is distributed together with all files mentioned in 00readme.l2e.
% 
% If you receive only some of these files from someone, complain!
% 
% You are NOT ALLOWED to distribute this file alone.  You are NOT
% ALLOWED to take money for the distribution or use of either this
% file or a changed version, except for a nominal charge for copying
% etc.
% \fi
%%%
%%% This file has been tested with
%%% LaTeX 2.09 ( OFSS lfonts.tex)
%%% LaTeX 2.09 ( NFSS1 oldlfont.sty )
%%% LaTeX 2.09 ( NFSS1 basefont.tex )
%%% LaTeX 2.09 ( NFSS2 public alpha release )
%%% LaTeX2e    ( as of 1994/12/16 )
%%%
%%% It does not require any extra files except the standard article
%%% class (style) file.
%%%

\documentstyle{article}



%%% The following definitions are *not* intended to be a
%%% good example of LaTeX coding style.
%%%
%%% In order to ensure easy processing of this LaTeX2e introduction
%%% with previous (and future) versions of LaTeX without assuming
%%% any non-standard styles, Certain definitions need to be made
%%% in the preamble.



\def\filedate{93/12/20}

\makeatletter
\@ifundefined{texttt}{%
  \newcommand\texttt[1]{{\tt#1}}
  \newcommand\textsf[1]{{\sf#1}}
  \newcommand\emph[1]{{\em#1\/}}}% This is \emph{not} the LaTeX2e
                                 %  definition!
\makeatother

\ifx\oldstylenums\undefined
  \newcommand\oldstylenums[1]{$\fam1\relax#1$} % for this document
                                               % only
\fi

\ifx\itshape\undefined
  \let\itshape\it
\fi

\newenvironment{decl}%
    {\par\small\addvspace{4.5ex plus 1ex}%
     \vskip -\parskip
     \noindent\hspace{-\leftmargini}%
     \begin{tabular}{|l|}\hline\ignorespaces}%
    {\\\hline\end{tabular}\par\nopagebreak\addvspace{2.3ex}%
     \vskip -\parskip}

\newcommand{\declline}[1]{\\\multicolumn1{|r|}{\small#1}}

\let\nverbatim\verbatim
\def\verbatim{\small\nverbatim}

\catcode`\|=\active
\def|{\verb|}

\newcommand{\m}[1]{\mbox{$\langle$\emph{#1}$\rangle$}}

\renewcommand{\arg}[1]{{\tt\string{}\m{#1}{\tt\string}}}
\newcommand{\oarg}[1]{{\tt[}\m{#1}{\tt]}}

\newcommand{\NFSS}{\textsf{NFSS}}
\def\AllTeX{(\La)\TeX}

\makeatletter

\ifx\DeclareFontShape\undefined
  \def\La{\TestCount=\the\fam \leavevmode L\raise.42ex
        \hbox{$\fam\TestCount\scriptstyle\kern-.3em A$}}
  \newcount\TestCount
\else
  \def\La{L\kern-.36em
           {\setbox0\hbox{T}%
            \vbox to\ht0{\hbox{%
                               \csname S@\f@size\endcsname
                               \fontsize\sf@size\z@\selectfont
                               A}%
                         \vss}%
           }}
\fi

\@ifundefined{SliTeX}{%
\def\SliTeX{{\rm S\kern-.06em{\sc l%
    \kern-.035emi}\kern-.06emT\kern
   -.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{}


\@ifundefined{f@series}{}{}
\def\LaTeXe{\protect\pLaTeXe}
\def\pLaTeXe{\mbox{%
  \if b\expandafter\@car\f@series\@nil\boldmath\fi
  \LaTeX\kern.15em$2_{\textstyle\varepsilon}$}}

\def\literal#1{{#1\kern\z@}}

\makeatother

\def\AmS{{\protect\the\textfont2 A}\kern-.1667em\lower
         .5ex\hbox{\protect\the\textfont2 M}\kern
         -.125em{\protect\the\textfont2 S}}

\newcommand{\AmSLaTeX}{\AmS-\LaTeX}
\newcommand{\ps}{PostScript}
\newcommand{\MF}{Metafont}


\setlength{\parindent}{0pt}
\setlength{\parskip}{3pt plus 1pt}

\setcounter{tocdepth}{2}

\tolerance500

\begin{document}

\title{\LaTeXe}
\author{\LaTeX3 Project Team}
\date{\filedate}

\maketitle

\begin{abstract}
This file contains a short description of the new features of
\LaTeXe. It assumes a reasonably high level of familiarity with
some parts of the \LaTeX~2.09 system.

Only the changes to the core system are documented here. Changes to
standard packages (such as \texttt{ifthen.sty}) and new packages that
may be distributed with \LaTeXe\ are \emph{not} described.

Full documentation of \LaTeXe{} can be found in the book
``The \LaTeX{} Companion'', by Michel Goossens, Frank Mittelbach and
Alexander Samarin, Addison-Wesley, Reading, Massachusetts, 1993,
ISBN 0-201-54199-8.
\end{abstract}


\tableofcontents


\section{\LaTeXe---The new \LaTeX{} release}

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. Thus, to process documents from various places, a
site maintainer was forced to keep \LaTeX{} (with and without \NFSS),
\SliTeX, \AmSLaTeX, and so on.  In addition, when looking at a source
file it was not always clear what format the document was written for.


To put an end to this unsatisfactory situation, this new \LaTeX{} release
was produced at the end of 1993 that 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 will be standard and style files like \textsf{amstex}
(formerly \AmSLaTeX{} format) or \textsf{slides} (formerly \SliTeX{}
format) will become extension packages, all working with the same base
format.  The introduction of a new release also made it possible
to add a small number of often-requested features.

The next section of this document describes very briefly the major new
features of \LaTeXe{} which are for use in documents.

The following sections describe (again, only in summary form) some of
the changes and enhancements which are of concern only to writers of
classes and packages (these are the files which replace the `style
files').

\section{User document commands}

\subsection{Initial commands}


\begin{decl}
|\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
\end{decl}

This command is usually used in package and class
files, but it could be used as the first line of your document to
declare that the document should run with \LaTeXe. This will ensure
that someone who tries to use \LaTeX~2.09, or plain~\TeX\ would get a
reasonably clear error message straight away.

\begin{decl}
|\begin{filecontents}| \arg{file-name} \\
  \m{file-contents} \\
|\end{filecontents}|
\end{decl}

The |filecontents| environment is intended for packaging, 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 to a file whose name is given as the
environment's only argument. However, if that file already exists
(maybe only in the current directory if the OS supports a notion of a
`current directory' or `default directory') then nothing happens
(except for an information message) and the body of the environment is
by-passed.

The environment is allowed only before |\documentclass|: this helps to
ensure that all packages or options necessary for this particular run
are present when needed.

\subsection{Preamble commands}

\begin{decl}
|\documentclass| \oarg{option-list} \arg{class-name} \oarg{release-date}
\end{decl}

This command (also here called a `declaration') replaces the
\LaTeX2.09 command |\documentstyle|.

There must be exactly one |\documentclass| declaration in a document,
and it must come first (except for the `initial' commands described
above).

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| declarations (see below).

The optional argument \m{release-date} can be used to specify the
desired release date of the class file; it should contain a date in
the format |YYYY/MM/DD|.  If a version of the class older than this is
found, a warning is issued.


\begin{decl}
|\documentstyle| \oarg{option-list} \arg{class-name} \oarg{release-date}
\end{decl}

This command is still supported for compatibility with old files.
It is essentially the same as |\documentclass|, but it loads a
`compatibility mode' which redefines certain commands to act as they did
in \LaTeX~2.09. Also, any options in the \m{option-list} that are not
declared by the class are loaded as packages after the class has been
loaded. This matches the 2.09 behaviour.

\begin{decl}
|\usepackage| \oarg{option-list} \arg{package-name} \oarg{release-date}
\end{decl}

Any number of |\usepackage| declarations is allowed. Each package
file (as denoted by \m{package-name}) defines new elements (or
modifies those defined in the class file \m{class-name} argument of the
|\documentclass| declaration), and 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 |YYYY/MM/DD|; if an older version
of the package is found, a warning is issued.

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 declaration which caused it to be loaded. If such extra options
are specified then an error message is produced.

As well as processing the options given in the \m{option-list} of the
corresponding |\usepackage| declaration, each package processes the
\m{option-list} of the |\documentclass| declaration as well. This
means that any option which should be processed by every package (to
be precise, by every package that can do so) can be specified just
once, in the |\documentclass| declaration, rather than being repeated for
each package that needs it.

Further details of this option processing are in Subsection
\ref{sec:op} below.

Note: class files have the extension |.cls|; packages have the
extension |.sty|.

\begin{decl}
|\listfiles|
\end{decl}

If this declaration is placed in the preamble then a list of the files read
in (as a result of processing the document) should be displayed on the
terminal (and in the log file) at the end of the run. For some of these
listed files, extra information about them will also be produced.  (We
said `should' above since this will all happen as documented only if
class and package writers always read in files using the mechanisms
provided by the system, and we cannot guarantee that this will always be
done.)


\begin{decl}
|\setcounter{errorcontextlines}| \arg{num}
\end{decl}

\TeX3 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, \LaTeX2e sets this to $-1$ by default.

\subsubsection{Option processing}\label{sec:op}

The options for |\documentclass| and |\usepackage|
are processed in the following way.

\begin{enumerate}
\item They are first divided into two types: {\em
  local\/} and {\em global}:
\begin{itemize}
  \item for a class, the options in the |\documentclass| command are
    local and there are no global options;
  \item for a package, the options in the |\usepackage| command are
    local but the options in the |\documentclass| command are global.
\end{itemize}

\item The local and global options that have been declared within this
   class or package are processed first.

   These are usually processed in the order of their declarations in
   the class or package (thus the order they appear in the \m{option-list}
   is irrelevant).

   However, it is possible for a class or package to process the
   options in the order that they appear in each \m{option-list}:
   first the global options; then the local ones.

 \item Any local options that are not declared by this class or
   package are then processed identically.
   For document classes, this usually means that they are ignored,
   except for this fact being recorded by adding the option to a list of
   `unused options'. For packages, this usually means that an error
   message is produced, giving the choice of retyping the option name
   in case it is incorrect.
\end{enumerate}

Finally, when |\begin{document}| is reached, if there are any global
 options which have not been used by either the class or any package,
 the system will produce a warning which lists them.

\subsection{Commands for the main document body}

The following commands have been added in \LaTeXe, or have extended
functionality over their \LaTeX~2.09 versions.

\subsubsection{Definitions}

\begin{decl}
|\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
|\renewcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
\end{decl}

The optional \m{default} argument is new in \LaTeXe; it allows you to
define a command with one optional argument. If this argument to
|\newcommand| is present then:
\begin{itemize}
  \item the first argument of the command \m{cmd} being defined will
  be an optional argument;
  \item when the command \m{cmd} is used without this first
  optional argument, the value of |#1| (the first argument) will be
  whatever was specified as \oarg{default} when \m{cmd} was defined.
\end{itemize}


\begin{decl}
|\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}
\end{decl}
As for |\newcommand|, \LaTeXe\ also supports defining an environments with
one optional argument.

\begin{decl}
|\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.

\subsubsection{Boxes}


\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}

These commands all existed in \LaTeX~2.09.  One small but far-reaching
change for \LaTeXe\ is that, within the \m{width} argument only, three
special lengths can be used.  These are all dimensions of the box
which would be produced by |\mbox|\arg{text}:
\begin{itemize}
\item []   |\height|\quad its height above the baseline;
\item []   |\depth|\quad its height above 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,
use:
\begin{verbatim}
\makebox[2\width]{hello}
\end{verbatim}

The other change is a new possibility for \m{pos}. 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 box
contents. If no such `rubber length' is present, and `underfull box'
will be produced.


\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 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 a |fmpage| environment, that is a framed
version of |minipage|.
\begin{verbatim}
\newsavebox{\mybox}
\newenvironment{fmpage}[1]{\begin{lrbox}{\mybox}\begin{minipage}{#1}}
                          {\end{minipage}\end{lrbox}%
                           \fbox{\usebox{\mybox}}}
\end{verbatim}

\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 horizontal boxes 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 of the \m{pos} argument for |\makebox|. The \m{inner-pos}
may be any one of |t|, |b|, |c|, or |s|. Denoting top, bottom,
centred, or `stretched' alignment respectively. The default value of
\m{inner-pos} is to be the same as that of \m{pos}.

\subsubsection{Measuring things}

\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}
The first of these commands was in \LaTeX~2.09. The two new
commands are the obvious analogues.

\subsubsection{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|, |\samepage| 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 the 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 to allow an extra line to be fitted onto the page or,
with a negative length, to produce a page one line 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 to the
page.

\subsubsection{Floats}

There is a new command, |\suppressfloats|, and a new `float
specifier'.  We hope that 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.

\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.

\subsubsection{Font changing: text}
The font change commands are described in detail in
Appendix~\ref{sec:nfss2}.

Here is a brief description of the two major new classes of commands which
affect the font to be used to typeset text .

\begin{decl}
|\rmfamily|\\
|\bfseries|\\
\vdots
\end{decl}

These are font declarations whose use is the same as the declarations
|\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}\\
|\textbf| \arg{text}\\
|\emph| \arg{text}\\
\vdots
\end{decl}

These are command forms; this means that they take as an argument the
text which is to be typeset in the particular font. They also
automatically insert italic corrections where required.

\subsubsection{Font changing: maths}

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}\\
\vdots
\end{decl}

These are also command forms so they 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.  Also, in
general, the treatment of punctuation, digits, etc is not affected.

\subsubsection{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 if |\G_p| is used
within math mode, but it ensures that math mode is entered (and exited)
as required when |\Gp| is used in text mode.

\subsubsection{Hiding special tokens.}

\begin{decl}
|\literal| \arg{text}
\end{decl}
|\literal| is used to `hide' characters.

This is necessary in certain contexts: for instance, to use a |]|
inside an optional argument you need to type: |\item[\literal{]}]|.
It can also be used to `break a ligature': compare the detailed
appearance of `shelfful' and `shelf\literal{f}ul', produced by
`|shelfful|' and `|shelf\literal{f}ul|'. (The \TeX{}Book suggests
|shelf{}ful| for the latter effect but unfortunately that can fail as
\TeX\ will `re-constitute the ligature' ff if it tries to hyphenate
|shelf{}ful|.)


\subsubsection{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 say
|\LaTeXe| (producing `\LaTeXe').

\subsubsection{Warning}

The rest of this document is aimed exclusively at those who need a
quick reference guide to the inner workings of \LaTeXe.  If this is
not for you, then stop here!

\section{Command naming conventions in \LaTeXe}

\LaTeXe{} attempts to classify commands,and their appearance, into
categories as follows.

\begin{description}
\item[Document commands] Commands that occur in the main document
  file.  These should have lower case names. (For example, |\alpha|,
  |\mbox|.)
\item[Class \& Package Interface commands] The
  high level interfaces for packages and their options. These commands
  have mixed case names. (For example |\ProvidesClass|.)
\item[\LaTeX\ programmer commands] These commands help package
  writers to build up the structures they require. They are lower
  case, usually with a single |@| as the first character. (For example
 |\@ifundefined|, |\@tfor|.)
\item[Saved definitions] These commands save original primitive
  definitions. They start with |@@|. (For example |\@@end|.)
  \LaTeX\ programmers are unlikely to need to use these commands, but
  they should avoid naming their own commands with names starting
  |\@@|\ldots
\item[Internal commands for a particular package] These commands are
  also have names containing |@|, but they often have more than one, or
  it is not the first letter in the command name. When writing a
  package, it is good practice to give all the internal commands a
  consistent naming scheme as this reduces the chances of a clash with
  other packages. (For example, longtable internal commands include
  |\LT@output|, |\LT@start|.)
\end{description}

Note that the above conventions can be broken (|\Box| is a user level
command that is mixed case, |\outer| has a user-level lowercase name
but should never be used at all!). Also, it is not always clear to which
category a command belongs; nevertheless, it is helpful to bear these
conventions in mind when writing new packages.

The system itself does not try to enforce these conventions except
that commands named with an |@| may not usually be used in the main
document.


\section{High level class \& package interface}

The commands in this section allow class and package writers to clearly
identify their files, and define the options that they support. In
\LaTeX~2.09, a main style could only define options using `low level'
definitions. Packages (which were implemented as options to the main
style) could not have options in previous releases.

\subsection{Identification}

\begin{decl}
|\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
\end{decl}

Ensures that the current file is processed under a \TeX{} format with
name \m{format-name}. With \m{release-date} one can specify the
earliest release date of the format that should still work.  Any
release older than this date will be flagged with a warning.

The standard \m{format-name} is \texttt{LaTeX2e}.
The date if present has to be of the form YYYY/MM/DD.

\begin{verbatim}
Example:  \NeedsTeXFormat{LaTeX2e}[1994/01/01]
\end{verbatim}


\begin{decl}
|\ProvidesClass| \arg{class-name} \oarg{release-info} \\
|\ProvidesPackage| \arg{package-name} \oarg{release-info}
\end{decl}

This declares that the current file contains the definitions for the
document class or package \m{class-name}. The optional \m{release-info}
contains the release date in the form YYYY/MM/DD, optionally followed by
a short description (any sequence of non-special characters). The date
information can be used by |\LoadClass| or |\documentclass| (for
classes) or |\RequirePackage| or |\usepackage| (for packages) to test if
the release is not obsolete.  The full information is displayed by
|\listfiles| and should therefore not be too long.

\begin{verbatim}
Example:   \ProvidesClass{article}[1994/01/01 Standard LaTeX2e class]
           \ProvidesPackage{ifthen}[1994/01/01 Standard LaTeX2e package]
\end{verbatim}


\begin{decl}
|\ProvidesFile| \arg{file-name} \oarg{release-info}
\end{decl}

As for the two previous commands, but here the full filename, including
extension must be given. Used for declaring any files other than main
class and package files.

\begin{decl}
|\RequirePackage|
   \oarg{options-list} \arg{package-name} \oarg{release-info}
\end{decl}

With this command, packages can load other packages. The behaviour is
similar to that of |\usepackage|: if the package \m{package-name}
has already been loaded, then nothing happens unless the requested
options are not a subset of the options with which it was loaded; if
they are not then an error is signalled.

\begin{verbatim}
Example:   \RequirePackage{ifthen}[1994/01/01 Standard LaTeX2e package]
\end{verbatim}


\begin{decl}
|\LoadClass| \oarg{options-list} \arg{package-name} \oarg{release-info}
\end{decl}

This command is similar to |\RequirePackage|, but it is for use by
classes only, i.e.~it must not be used in packages files.


\begin{decl}
|\PassOptionsToPackage| \arg{options-list} \arg{package-name} \\
|\PassOptionsToClass| \arg{options-list} \arg{package-name}
\end{decl}

With this command, packages can pass options to another package. This
adds the \m{option-list} to the list of options of any future
|\RequirePackage| or |\usepackage| command for package
\m{package-name}. For example,
\begin{verbatim}
   \PassOptionsToPackage{foo,bar}{fred}
   \RequirePackage[baz]{fred}
\end{verbatim}
is the same as:
\begin{verbatim}
   \RequirePackage[foo,bar,baz]{fred}
\end{verbatim}
Similarly, |\PassOptionsToClass| may be used to pass options to
a class.


\begin{decl}
|\@ifclassloaded|  \arg{class-name} \arg{true} \arg{false} \\
|\@ifpackageloaded| \arg{package-name} \arg{true} \arg{false}
\end{decl}

These two commands can be used to execute different pieces of code,
depending on whether a class or package has already been loaded.


\begin{decl}
|\@ifclasslater|
   \arg{class-name} \arg{release-date} \arg{true} \arg{false} \\
|\@ifpackagelater|
     \arg{package-name} \arg{release-date} \arg{true} \arg{false}
\end{decl}

With these two commands, different pieces of code can be executed,
depending on whether a class or package has already been loaded that
is version more recent than \m{release-date}.


\begin{decl}
|\@ifclasswith|
    \arg{class-name} \arg{option-list} \arg{true} \arg{false} \\
|\@ifpackagewith|
    \arg{package-name} \arg{option-list} \arg{true} \arg{false}
\end{decl}

With these two commands, different pieces of code can be executed,
depending on whether a class or package has already been loaded at
least the options given in \m{option-list}.



\subsection{Option handling}

\begin{decl}
|\DeclareOption| \arg{option-name} \arg{code}
\end{decl}

Declares \m{option-name} to be an option for the current class or
package and \m{code} the code to be executed if that option is
specified.

The \m{code} can contain any valid \LaTeXe{} construct, plus some
special commands for use within this argument which are described
below.

\begin{verbatim}
Example:   \DeclareOption{twoside}{\@twosidetrue}
\end{verbatim}


\begin{decl}
|\DeclareOption*| \arg{code}\\
|\OptionNotUsed|
\end{decl}

Declares \m{code} to be executed for every option which is otherwise
not explicitly declared.  By default, undeclared options to a class
will be silently passed to all packages (just like the declared
options for the class); undeclared options to a package will produce
an error.

The \m{code} can contain any valid \LaTeXe{} construct, plus some
special commands for use within this argument which are described
below.

The example below handles an undeclared option by loading a |clo| file
if it exists. Otherwise it declares the option as unused.
\begin{verbatim}
Example:   \DeclareOption*
             {\InputIfFileExists{\CurrentOption.clo}{}{\OptionNotUsed}}
\end{verbatim}


\begin{decl}
|\CurrentOption|
\end{decl}

Refers to the name of the current option within the \m{code} of
|\DeclareOption| or |\DeclareOption*|.


\begin{decl}
|\ProcessOptions|
\end{decl}

Executes the code for all options specified in the order they are
defined in the file. Afterwards reclaims the memory used by \m{code}
(as given in a |\DeclareOptions| declaration) for \emph{all} options
defined in the file.


\begin{decl}
|\ProcessOptions*| \\
|\@options|
\end{decl}

Like |\ProcessOptions| but executes options in the order specified in
the calling command rather than in the order as specified in the
class or package. |\@options| is an equivalent command which is the name
used in \LaTeX~2.09. This should allow old main document styles to be
used as classes just by renaming the file from |.sty| to |.cls|.


\begin{decl}
|\AtEndOfClass| \arg{code}\\
|\AtEndOfPackage| \arg{code}
\end{decl}

These commands cause \m{code} to be saved away in an internal hook, and
then executed at the end of the current class (package). Repeated use of
the commands work, and the arguments are executed in the order they are
declared.

\begin{decl}
|\AtBeginDocument| \arg{code}\\
|\AtEndDocument| \arg{code}
\end{decl}

These commands cause \m{code} to be saved internally and executed while
\LaTeX\ is executing |\begin{document}| (|\end{document}|).


\subsection{Safe Input Macros}

\begin{decl}
|\InputIfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}

Inputs \m{file-name} if it exists. Immediately before the input,
\m{true} is executed. Otherwise \m{false} is executed.

\begin{decl}
|\IfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}

As above, but does not input the file.

One thing you might like to put in the \m{false} clause is

\begin{decl}
  |\@missingfileerror| \arg{file-basename} \arg{extension}
\end{decl}
This starts an interactive request for a filename, supplying default
extensions. Just hitting the \fbox{Return} key causes the whole input
to be skipped.

\begin{decl}
|\input| \arg{file-name}
\end{decl}

This command has been redefined from the \LaTeX2.09 definition, in terms
of |\InputIfFileExists| and |\@missingfileerror|.

\section{\LaTeX\ programmer commands}

There have been many internal changes made while preparing \LaTeXe\
Only those changes that may directly affect package writers are listed
here.

\subsection{Modified commands}

\begin{decl}
|\@ifundefined| \arg{cmd} \arg{true} \arg{false}
\end{decl}
This command has been redefined to remove a `trailing |\fi|'.  We hope
that this will not affect any existing uses of the command.  It allows
a larger range of commands to go into the \m{true} and \m{false}
arguments.



\begin{decl}
|\footheight|
\end{decl}
This parameter was declared in \LaTeX2.09, and some styles set it to a
value, but the value was never used. It has been removed.

\subsection{New commands}

\begin{decl}
|\@checkcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
\end{decl}
|\@checkcommand| takes the same arguments as |\newcommand|, but rather
than define \m{cmd} it checks that the current definition of \m{cmd}
is \m{definition}. An error is raised if the definition is different.

This command may be useful for checking the state of the system before
your package starts altering command definitions. It allows you to
check that no other package has redefined the same command.

\begin{decl}
|\two@digits| \arg{num}
\end{decl}
This is like the primitive command |\number| except that single-digit
numbers (including negative numbers!) get a leading `0'. This
is useful for producing dates of the form 1994/01/01.

\begin{decl}
|\@percentchar|
\end{decl}
This produces a non-special \% token. It may be used in |\typeout| and
similar commands to produce a percent-sign.

\begin{decl}
|\if@compatibility|
\end{decl}
This flag is true if the document is being run in \LaTeX~2.09
compatibility mode.

\begin{decl}
|\@firstofone| \arg{arg}\\
|\@firstoftwo| \arg{arg1} \arg{arg2}\\
|\@secondoftwo| \arg{arg1} \arg{arg2}
\end{decl}
|\@firstofone| just returns its argument. (It has its uses\ldots)
|\@firstoftwo| returns its first argument, discarding the second.
|\@secondoftwo| returns its second argument, discarding the first.


\begin{decl}
|\paperheight|\\
|\paperwidth|
\end{decl}
These two parameters are usually set by the class to be the size of
the paper being used. This should be actual paper size, unlike
|\textwidth| and |\textheight| which are the size of the main text
body within the margins.

\section{System dependent commands}
When the \LaTeXe\ format is made, certain tests are run to try to
determine the behaviour of the \TeX\ implementation and the syntax of
external file names. These tests may be overruled by the site
maintainer but in any case the following commands should be set up to
match the local system.

The file |texsys.cfg| contains a more detailed explanation of these
requirements, including examples.

\begin{decl}
|\@currdir|\m{filename}\m{space}
\end{decl}
|\@currdir|\m{filename}\m{space} should expand to the syntax on the
local operating system for the file \m{filename} in the current
directory. The expansion should end with a \m{space}. 


\begin{decl}
|\input@path|
\end{decl}
On most \TeX\ systems |\input@path| should be undefined.  It is needed
on systems where the \TeX{} program does not look in the same place
for files when using both |\input| and |\openin|.  On these systems,
\LaTeX\ needs |\input@path| to be defined to be a list of directories
(with the same syntax as |\@currdir|).  Each directory should be in a
|{}| group. The list should start with |{}|.

Examples:\\
| { {} {/usr/lib/tex/inputs/} {/usr/local/lib/tex/inputs/} }|\\
| { {} {c:/tex/inputs/} }|\\
| { {} {tex$inputs:} }|

\begin{decl}
|\@filename@parse| \arg{filename}
\end{decl}
|\filename@parse|\arg{filename} defines the following three macros:\\
|\filename@area| the `area' or `directory' part of \m{filename}\\
|\filename@base| the `base' part of \m{filename}\\
|\filename@ext| the `extension' part of \m{filename}\\
If \m{filename} did not have an extension, |\filename@ext| will be
|\let| to |\relax|.


\section{Incompatibilities and changes}


\subsection{Compared to \LaTeX~2.09}

In \LaTeX~2.09 the only font changing commands (apart from the size
commands) were the `two letter' forms |\rm|, |\bf| etc. These each
referred to a \emph{fixed} font (at the given size) so for instance the
standard commands could not select a bold italic font. |\bf\it| selected
a medium weight italic (the |\it| completely replacing the |\bf|, and
similarly |\it\bf| produced upright bold font. The size commands such as
|\large| always switched to a roman font. \LaTeXe\ introduces the far
more flexible font changing declarations|\rmfamily| \ldots, and commands
|\textrm|\ldots. The old `two-letter' font commands \emph{are not
defined}! by the core \LaTeXe\ system.

The standard classes define |\rm|, |\bf| etc., to select a fixed text
font. (To make it easy to convert old files.) The size commands however
just change the size, they do not select a roman font. Furthermore the
commands |\rm|, |\bf|, |\it| are allowed in math mode (unlike the usual
\NFSS\ text font commands.)

If the document begins with |\documentstyle| rather than
|\documentclass| a more complete emulation is enabled.
\begin{itemize}
\item Size changing commands switch to upright roman font.
\item All the standard `two-letter' font commands are allowed in math.
\item |\sloppy| which normally has an improved definition reverts to its
  old definition, to help maintain the line-breaking on existing
  documents.
\item When looking for a main document class \LaTeXe\ looks for files
  with the extension |.cls| not |.sty|. However the new code has been
  designed so that old files should still work if the are renamed to
  |.cls|. In compatibility mode |\documentstyle| will load a |.sty| file
  if a |.cls| file can not be found.
\end{itemize}


\subsection{Compared to \NFSS{} release 1}

Release 1 of the \NFSS\ introduced the concept of orthogonal font
switching, but rather than use new command names |\rmfamily|,
|\bfseries|, it (if built with the |newlfont| option) redefined the
existing `two-letter' forms. The use of all two-letter font commands was
not allowed in math mode. \LaTeX2e\ is distributed with a package
|newlfont| that defines |\rm|, |\bf| etc in a way compatible with
\NFSS1.

The following list details some more internal differences between \NFSS1
and \NFSS2
\begin{itemize}
\item

  The obsolete commands of \NFSS{}1, i.e., |\family|, |\series|,
  |\shape|, and |\size| have now been removed.  Instead use
  |\fontfamily|, |\fontseries|, |\fontshape|, and |\fontsize|.

\item

  The math alphabets |\mit| and |\cal| have been renamed to
  |\mathnormal| and |\mathcal|.

\item

  The following internal commands are obsolete in \NFSS{}2:

  |\extra@defs|, |\new@fontshape|, |\subst@fontshape|,
  |\newmathalphabet|, |\addtoversion|.


\item
  In \NFSS{}1 an explicit request for |\fontsize{14}{16pt}| was
  actually trying to load a font at 14.4pt, in other words `14' was
  used as a label and not as a real size specification. In release~2
  this request is now interpreted as asking for a font at `14pt'
  sharp. Since in the standard FontShape declarations such a font
  isn't available, \NFSS{} will attempt to use a nearby size and
  therefore will (after a warning) also use the `14.4pt' size, so
  documents will come out right.

  Also the \NFSS2 version of |\fontsize| allows other units to be used
  in its arguments (defaulting to |pt|) so |\fontsize{12dd}{15dd}| is an
  acceptable \NFSS2 declaration (assuming you have fonts for that size).

\item
  The internal switch |\ifdefine@mathfonts| to suppress math font
  changes was removed. Use |\ifmath@fonts| instead but don't rely on
  it for future interfaces either!
\end{itemize}

\subsection{Compared to the \LaTeX~2.09 version of \NFSS2}

While \LaTeXe\ was being developed a prototype \NFSS2 release was made
available for use with \LaTeX~2.09. The internal structure of the
\LaTeXe\ release of \NFSS2 has not significantly altered, however the
prototype, like \NFSS1, redefined the `two-letter' font changing
commands rather than introducing the new |\rmfamily| forms. Use the
package \textsf{newlfont} if you would prefer this behaviour in \LaTeXe.

The other major difference is that all the styles (packages) distributed
with the prototype had a consistent naming scheme \textsf{nf}\ldots. For
example \textsf{nftimes.sty} \textsf{nfoldlfnt.sty}.
After some discussion, it was decided to drop this idea and revert to
the old names \textsf{times.sty} \textsf{oldlfont.sty}.

\appendix


\section{Option naming conventions}

No option names are built into the \LaTeX\ core system, but we hope
that package and class writers will follow these conventions for
names of options that have general applicability. Of course, packages
may also have options with names particular to the package.

\begin{description}
\item[language options] If your package produces `fixed strings' that
produce text in the output then please consider supporting language
options as defined by the babel package.

\item[paper size options]
  The standard classes support the options \texttt{letterpaper},
  \texttt{legalpaper}, \texttt{executivepaper}, \texttt{a4paper},
  \texttt{a5paper}, \texttt{b5paper}, \texttt{landscape}.
  These set the |\paperheight| and |\paperwidth| parameters. If writing
  a class that supports different paper sizes you should make similar
  options, with names ending in |paper| for those sizes that you
  support.

\item[driver options]
 Many graphics related packages need to know what dvi-driver is being
 used (so that the correct syntax may be used in the |\special|
 command). It is hoped that conventional option-names will be agreed
 denoting the major drivers. Currently the suggested list includes:
 \texttt{emtex}, \texttt{dvips}, \texttt{oztex} etc.

\item[debugging options]
  errorshow warningshow infoshow debugshow pausing
\end{description}

\section{Filename conventions}

\LaTeX\ uses many different types of files. The main file extensions
and their meanings are listed below.


|tex| \LaTeX\ documents.\\
|ltx| Internal \LaTeX\ files, used during the installation.\\
|cls| class files.\\
|sty| package files (and \LaTeX~2.09 style files).\\
|clo| Files implementing class options.\\
|dtx| docstrip/doc source files.\\
|ins| docstrip batch files.\\
|drv| doc driver files, for processing with \LaTeX.\\
|fd | Font definition files.\\
|fdd| Documented sources for font definition files.\\
|cfg| configuration files. These are the only files that you are
      allowed to edit to customise \LaTeX\ at your site.\\
|log| \TeX\ log file (may be |lis| on some systems)\\
|ist| Makeindex style files.\\
|idx| Raw index files.\\
|ind| Sorted index files.\\
|gls| Raw glossary files.\\
|glo| Sorted Glossary files.\\
|fmt| \TeX\ format file.\\
|dvi| \TeX\  output file.

\section{\NFSS2 interface commands}\label{sec:nfss2}


\subsection{Switching text fonts}

Font family changes are done with:
\begin{verbatim}
  \textrm{...} \textsf{...} \texttt{...}
\end{verbatim}
Font series (weight/width) are changed with:
\begin{verbatim}
  \textbf{...} \textmd{...}
\end{verbatim}
The font shape is changed with:
\begin{verbatim}
  \textit{..} \textsl{..} \textsc{..}
\end{verbatim}
Finally emphasis can be expressed with
\begin{verbatim}
  \emph{..}
\end{verbatim}

All such commands take care of any necessary italic correction (|\/|).
In case you want to suppress this extra space you can use
|\nocorr| as the first or last entry in the argument, depending on
whether you wish to suppress the correction before or after the argument
text.

\subsection{Accessing symbols}

Use |\symbol{|\m{number}|}| to select a symbol in position
\m{number} of the current font. The characters |'| or |"| at the
beginning of \m{number} denote octal or hexadecimal base,
respectively.

Use |\oldstylenums{|\m{number}|}| to produce non-aligned digits
like \oldstylenums{1982}. Works in text and math and honours spaces in
the argument if used in text. Don't try to put other characters in the
argument, the result would be unpredictable and may change in later
releases.

\subsection{Predefined math alphabets}

\begin{verbatim}
\mathnormal \mathcal \mathrm \mathbf \mathsf \mathit \mathtt
\end{verbatim}

If you use the above commands often, consider defining an abbreviation
in the preamble of your document, e.g.
\begin{verbatim}
\newcommand{\mrm}{\mathrm}
\end{verbatim}

\subsection{Predefined math versions}

The standard format has the math versions ``normal'' and ``bold''
predeclared.

(You can switch between them using |\boldmath| and |\unboldmath| or
directly using |\mathversion{...}|.)


\subsection{Math declarations}


\subsubsection{Declaring math versions}

\begin{decl}
|\DeclareMathVersion|  \m{version-name}
\end{decl}

Defines \m{version-name} to be a math version. Initializes this
version with the default for all symbol fonts declared so far (see
|\DeclareSymbolFont|). Internally stores the stuff in
|\mv@|\m{version-name}.

If used on an already existing version, a warning is issued and all
previous |\SetSymbolFont| declarations for this version are overwritten
by the symbol font defaults, i.e.\ one ends up with a virgin math
version.

\begin{verbatim}
Example:  \DeclareMathVersion{normal}
\end{verbatim}


\subsubsection{Declaring symbol fonts}

\begin{decl}
|\DeclareSymbolFont| \m{sym-font-name} \m{cdp} \m{family} \m{series}
\m{shape}
\end{decl}

Defines \m{sym-font-name} to be a symbolic name for a new symbol font.
\m{cdp} \m{family} \m{series} \m{shape} are the default values for this
symbol font in all math versions if not redefined later with a
|\SetSymbolFont| command. Internally allocates a new math group with
name |\sym|\m{sym-font-name}.

Checks if \m{cdp} is a declared encoding scheme.

\begin{verbatim}
Example:   \DeclareSymbolFont{operators}{OT1}{cmr}{m}{n}
           \DeclareSymbolFont{letters}{OML}{cmm}{m}{it}
           \DeclareSymbolFont{symbols}{OMS}{cmsy}{m}{n}
           \DeclareSymbolFont{largesymbols}{OMX}{cmex}{m}{n}

           (the first four standard math fonts)
\end{verbatim}



\begin{decl}
|\SetSymbolFont| \m{sym-font-name} \m{version name} \m{cdp} \m{family}
\m{series} \m{shape}
\end{decl}

Changes the setting for the symbol font \m{sym font name} in math
version \m{version name} to \m{cdp} \m{family} \m{series} \m{shape}.

Checks if \m{sym-font-name} is a symbol font, \m{version name} is a
known math version and \m{cdp} is a declared encoding scheme.

\begin{verbatim}
Example:    \SetSymbolFont{operators}{bold}{OT1}{cmr}{bx}{n}
            \SetSymbolFont{letters}{bold}{OML}{cmm}{b}{it}

            (updating a bold math version)
\end{verbatim}




\begin{decl}
|\DeclareSymbolFontAlphabet| \m{id} \m{sym-font-name}
\end{decl}

Allows to make use of the math alphabet contained in the symbol font
that was declared earlier as \m{sym font name}.

Checks that \m{id} can be defined and that \m{sym-font-name} is a symbol
font.

\begin{verbatim}
Example:    \DeclareSymbolFontAlphabet{\mathrm}{operators}
            \DeclareSymbolFontAlphabet{\mathcal}{symbols}
\end{verbatim}


\subsubsection{Declaring math alphabets}

\begin{decl}
|\DeclareMathAlphabet| \m{id} \m{cdp} \m{family} \m{series} \m{shape}
\end{decl}

Defines \m{id} to be a new math alphabet with the default \m{cdp}
\m{family} \m{series} \m{shape} in all versions (the old
|\newmathalphabet*| plus encoding scheme).  If \m{shape} is empty then
the \m{id} is declared to be invalid in all versions unless
overwritten later by a |\SetMathAlphabet| command.

Checks that \m{id} can be used and that \m{cdp} is a valid encoding
scheme.

\begin{verbatim}
Example:     \DeclareMathAlphabet{\foo}{OT1}{cmtt}{m}{n}
             \DeclareMathAlphabet{\baz}{OT1}{}{}{}
             (\foo is defined everywhere
              \baz by default nowhere)
\end{verbatim}



\begin{decl}
|\SetMathAlphabet| \m{id} \m{version-name} \m{cdp} \m{family}
\m{series} \m{shape}
\end{decl}

Changes the setting of the math alphabet \m{id} in math version
\m{version-name} to \m{cdp}\m{family}\m{series}\m{shape}.

Checks that \m{id} is a math alphabet, \m{version-name} is a math
version and \m{cdp} is a known encoding scheme.

\begin{verbatim}
Example:     \SetMathAlphabet\baz{normal}{OT1}{cmss}{m}{n}
             (now \baz is defined for `normal' only)
\end{verbatim}



\subsubsection{Declaring math symbols}

\begin{decl}
|\DeclareMathSymbol| \m{symbol} \m{type} \m{sym font name} \m{position}
\end{decl}

Defines cmd \m{symbol} to be a math symbol of type \m{type} (values
0-7 or symbolic see below) in font position \m{position} of symbol
font \m{sym font name} which must have been declared previously.
\m{position} can be decimal, octal, or hexadecimal with the usual
notation |'| or |"| for octal and hex. \m{symbol} can be either a single
character, eg `|>|', or a macro name, eg |\sum|.  Allows overwriting of
\m{symbol} if \m{symbol} is either a single character or was
previously defined to be a math symbol.  Symbolic values for \m{type}
are the corresponding |\mathord|, |\mathbin|,\ldots{} commands.

Checks that \m{symbol} can be used and \m{sym font name} is a declared
symbol font.

\begin{verbatim}
Example:     \DeclareMathSymbol{\alpha}{0}{letters}{"0B}
             \DeclareMathSymbol{\lessdot}{\mathbin}{AMSb}{"0c}
             \DeclareMathSymbol{\foo}{\mathalpha}{AMSb}{"0c}
\end{verbatim}



\begin{decl}
|\DeclareMathDelimiter| \m{cmd}   \m{type}
           \m{sym font name-1} \m{position-1}
\declline{ \m{sym font name-2} \m{position-2} }
\end{decl}

or

\begin{decl}
|\DeclareMathDelimiter| \m{char}
           \m{sym font name-1} \m{position-1}
\declline{ \m{sym font name-2} \m{position-2} }

\end{decl}

Defines \m{cmd} or \m{char} to be a math delimiter where the small
variant is in font position \m{position-1} of symbol font \m{sym font
name-1} and the large variant in font position \m{position-2} of
symbol font \m{sym font name-2}.  Both symbol fonts must have been
declared previously.
\m{position-i} can be decimal, octal, or hexadecimal with the usual
notation |'| or |"| for octal and hex.

If \TeX{} is not looking for a delimiter \m{cmd} is treated just as if
it had been defined with |\DeclareMathSymbol| (the first symbol name
gets used). In other words, if a command is defined as a delimiter
then this automatically defines it as a math symbol. However, if a
single character is defined as a delimiter one can define it to behave
completely different if used as a math symbol.

Checks that \m{cmd} can be used and \m{sym font name-i} are declared
symbol fonts.

\begin{verbatim}
Example:     \DeclareMathDelimiter{\langle}{\mathopen}{symbols}{"68}
                                                 {largesymbols}{"0A}
\end{verbatim}



\begin{decl}
|\DeclareMathAccent| \m{cmd} \m{type} \m{sym font name} \m{position}
\end{decl}

Defines \m{cmd} to act as a math accent. The accent character comes from
\m{sym-font-name} in position \m{position}. The \m{type} can be either
|\mathord| or |\mathalpha|, in the latter case the accent character
changes fonts if used in a math alphabet.

\begin{verbatim}
Example:      \DeclareMathAccent{\acute}{\mathalpha}{operators}{"13}
              \DeclareMathAccent{\vec}{\mathord}{letters}{"7E}
\end{verbatim}




\begin{decl}
|\DeclareMathRadical| \m{cmd}
           \m{sym font name-1} \m{position-1}
\declline{ \m{sym font name-2} \m{position-2} }
\end{decl}

Defines \m{cmd} to be a radical where the small variant is in font
position \m{position-1} of symbol font \m{sym font name-1} and the large
variant in font position \m{position-2} of symbol font \m{sym font
name-2}.  Both symbol fonts must have been declared previously.
\m{position-i} can be decimal, octal, or hexadecimal with the usual
notation |'| or |"| for octal and hex.

\begin{verbatim}
Example:      \DeclareMathRadical\sqrt{symbols}{"70}{largesymbols}{"70}
              (probably the only use for it :-)
\end{verbatim}




\subsection{Declaring sizes for math}


\begin{decl}
|\DeclareMathSizes| \m{t-size} \m{mt-size} \m{s-size} \m{ss-size}
\end{decl}

Declares that \m{mt-size} is the math text size, \m{s-size} is the
script size and \m{ss-size} the scriptscript size to be used in math,
when \m{t-size} is the current text size. For text sizes for which no
such declaration is given the script and scriptscript size will be
calculated and then fonts are loaded for the calculated sizes or the
best approximation (this may result in some warning message by
\NFSS{}).

Normally \m{t-size} and \m{mt-size} will be identical, however, if,
for example, PostScript text fonts are mixed with bitmap math fonts
you may not have for every \m{t-size} a corresponding set of math
sizes.

\begin{verbatim}
Example: \DeclareMathSizes{13.82}{12.4}{10}{7}
\end{verbatim}



\subsection{Font loading}



\subsubsection{Declaring fixed fonts in one size}

\begin{decl}
|\DeclareFixedFont| \m{cmd} \m{cdp} \m{family} \m{series} \m{shape}
                    \m{size}
\end{decl}

Declares command \m{cmd} to be a font switch which selects the font
that is specified by the attributes \m{cdp}, \m{family}, \m{series},
\m{shape}, and  \m{size} without any overhead by \NFSS\ table
processing. The \NFSS\ tables are only evaluated when the \m{cmd} is
defined. The font is selected without any adjustments to baselineskip
and other surrounding conditions.

\begin{verbatim}
Example:   \DeclareFixedFont{\picturechar}{OT1}{cmr}{m}{n}{5}
           {\picturechar .}% select a small dot very fast
\end{verbatim}


\subsubsection{Declaring encodings}


\begin{decl}
|\DeclareFontEncoding| \m{cdp} \m{text-settings} \m{math-settings}
\end{decl}

Declares a new encoding scheme \m{cdp}. The \m{text-settings} are
declarations which are executed every time |\selectfont| switches to
encoding scheme \m{cdp}. (More exactly, they are already executed when
|\fontencoding| is encountered and the new encoding differs from the
previous encoding.)  This can be used for changing definitions of
accents or other beasts that depend on font positions.
\m{math-settings} is similar but for math alphabets (only!). It will
be executed whenever a math alphabet with this encoding is called.
Spaces within the arguments are ignored to avoid surplus spaces in the
document in funny places. If a real space is necessary use |\space|.

\begin{verbatim}
Example:   \DeclareFontEncoding{OT2}{}{\noaccents@}
\end{verbatim}



\begin{decl}
|\DeclareFontEncodingDefaults| \m{text-settings} \m{math-settings}
\end{decl}

Declares \m{text-settings} and \m{math-settings} for all encoding
schemes.  These are executed before the encoding scheme dependent ones
are executed so that one can use the defaults for the major cases and
overwrite them if necessary using |\DeclareFontEncoding|.

If |\relax| is used as argument, the current setting of this default
is left unchanged.

\begin{verbatim}
Example:    \DeclareFontEncodingDefaults{\relax}{\def\accentclass@{7}}
            (used by amsfonts.sty for accent positioning,
             changes only math settings.)
\end{verbatim}


\subsubsection{Font substitution}

\begin{decl}
|\DeclareErrorFont| \m{cdp} \m{family} \m{series} \m{shape} \m{size}
\end{decl}

Declares \m{cdp}\m{family}\m{series}\m{shape} to be the font shape
used in cases where the standard substitution mechanism fails (= would
loop).

Also initializes |\f@encoding| \ldots{} |\f@baselineskip| with the
corresponding values in case a |\selectfont| command is used during the
early part of the style file.

Enforces at |\begin{document}| that \m{cdp}\m{family}\m{series}\m{shape}
is defined via |\DeclareFontShape|.

\begin{verbatim}
Example:    \DeclareErrorFont{OT1}{cmr}{m}{n}{10}
\end{verbatim}


\begin{decl}
|\DeclareFontSubstitution|  \m{cdp} \m{family} \m{series} \m{shape}
\end{decl}

Declares the default values for font substitution which will be used
when a font has to be loaded but can't be found with the current
attributes. These are local to the encoding scheme because the
encoding scheme is never substituted!  They are tried in the order
\m{shape} then  \m{series} and finally \m{family}.

If no defaults are set up for an encoding the values given by
|\DeclareErrorFont| are used.

Enforces at |\begin{document}| that \m{cdp}\m{family}\m{series}\m{shape}
is defined via |\DeclareFontShape|.

\begin{verbatim}
Example:   \DeclareFontSubstitution{T1}{cmr}{m}{n}
\end{verbatim}


\begin{decl}
|\fontsubfuzz| |=| \m{dimen}
\end{decl}

Parameter that is used to decide whether or not to produce a terminal
warning if a font size substitution takes place. If the difference
between the requested and the chosen size is less than |\fontsubfuzz|
the warning is only written to the transcript file. The default value
is |0.4pt|.


\begin{decl}
|\fontsubmax|
\end{decl}

Parameter that holds the maximum deviation detected so far during
font size substitution. It is currently not used by \NFSS{}.


\subsubsection{Declaring font families}

\begin{decl}
|\DeclareFontFamily| \m{cdp} \m{family} \m{loading-option}
\end{decl}

Declares a font family \m{family} to be available in an encoding scheme
\m{cdp}. \m{loading-option} are declarations that are executed for every
font shape of that combination during load time (i.e.\ once).

Checks if \m{cdp} was previously declared.

\begin{verbatim}
Example:   \DeclareFontFamily{T1}{cmtt}{\hyphenchar\font=-1}
           (Computer modern typewriter in Cork encoding)
\end{verbatim}



\begin{decl}
|\DeclareFontShape| \m{cdp} \m{family} \m{series} \m{shape}
                  \m{loading-info} \m{loading-option}
\end{decl}

Declares a font shape combination where \m{loading-info} contains the
information that combines sizes with external fonts. The syntax is
complex and I will not dwell on it here, see below.  \m{loading-option}
are as above and allow overwriting the general loading options on
family level for this individual shape.

Checks if \m{cdp}+\m{family} was previously declared via
|\DeclareFontFamily|.

\begin{verbatim}
Example: \DeclareFontShape{OT1}{cmr}{m}{sl}{%
             <5-8> sub * cmr/m/n
             <8> cmsl8
             <9> cmsl9
             <10> <10.95> cmsl10
             <12> <14.4> <17.28> <20.74> <24.88> cmsl12
           }{}
\end{verbatim}


\subsubsection{Preloading fonts}


\begin{decl}
|\DeclarePreloadSizes| \m{cdp} \m{family} \m{series} \m{shape}
\m{size-list}
\end{decl}

Defines the font shapes that should be included into the format.

\begin{verbatim}
Example:     \DeclarePreloadSizes{OT1}{cmr}{m}{sl}{10,10.95,12}
\end{verbatim}



\begin{decl}
|\DeclareSizeFunction| \m{name} \m{code}
\end{decl}

Declares a size-function \m{name} for use in a |\DeclareFontShape|
command.  The interface is still lousy but then there should be no
real need to a define new size functions.  \m{code} is the code that
should be performed when the size or size-range in |\DeclareFontShape|
matches the requested user size. The size-functions arguments are
automatically parsed and placed into |\mandatory@arg| and
|\optional@arg| for inspection. Also available, of course, is
|\f@size| which is the user requested size. To signal success \m{code}
has to define the command |\external@font| to contain the external
name and any scaling options of the font to be loaded.

\begin{verbatim}
Example: \DeclareSizeFunction{}
           {\edef\external@font{\mandatory@arg\space at\f@size}
         (the `empty' size function simplified)
\end{verbatim}


\subsection{Naming conventions}

\subsubsection{Math alphabets}

Math alphabets all start with |\math...|, e.g., |\mathbf|, |\mathcal|,
etc. Define your private shorthands in the preamble if desired.

\subsubsection{Text font changes}

Text fonts with arguments start with |\text...|, e.g., |\textbf|,
|\textrm|, |\emph|, etc.


\subsubsection{Encoding schemes}

Names for encoding schemes are strings of up to three letters all
upper case. Currently the names officially supported by the \NFSS{}2
release are:
\begin{center}
\begin{tabular}{lll}
 \itshape Encoding & \itshape Description & \itshape declared by \\[2pt]
        T1 &    \TeX{} text Cork encoding
                                         &   \NFSS{}     \\
        OT1 &   \TeX{} text as defined by Don (more or less)
                                         &  \NFSS{}     \\
        OT2 &   \TeX{} text cyrill UW fonts
                                         &   --- \\
        OT3 &    IPA University of Washington (AMS encoding)
                                         &  ---      \\
        OML &   \TeX{} math letters (italic) as defined by Don
                                         &  \NFSS{}     \\
        OMS &   \TeX{} math symbol as defined by Don
                                         &  \NFSS{}     \\
        OMX &   \TeX{} math extended symbol as defined by Don
                                         &  \NFSS{}     \\
        U &     Unknown encoding
                                         &  \NFSS{}     \\
\end{tabular}
\end{center}
This table will be extended in the future if the \TeX{} community,
e.g.\ the national user groups, agree on additional encodings.

The following starting letters are reserved for future use by the
\NFSS{} maintainers and should not used to declare new encodings:
|T| (standard 256 Text encodings), |M| (standard
256 Math encodings), |S| (standard 256 Symbol encodings), |OT|
(standard 128 Text encodings), |OM| (standard 128 Math encodings).

Encoding schemes which are local to a site should start with |L|.
Please don't use other starting letters for non-portable encodings.
Instead, please inform us if a new standard encoding should be added
to a later release.


\subsubsection{Font families}

Font family names should contain up to five lower case letters.

\subsubsection{Font series}
Font series names should contain up to four lower case letters.


\subsubsection{Font shapes}
Font shapes should contain up to two letters lower case.


\subsubsection{Symbol fonts}

Names for symbol fonts are built from lower and upper case letters
with no restriction.

\NFSS{} defines the following names for symbol fonts:
\begin{center}
\begin{tabular}{lll}
\texttt{operators}    &fam 0 &font for operator names (sin, lim, etc.)\\
\texttt{letters}      & fam 1 & where the normal letters come from \\
\texttt{symbols}      & fam 2 & normal size symbols  \\
\texttt{largesymbols} & fam 3 & large size symbols
\end{tabular}
\end{center}


\subsubsection{\protect\m{loading info} for
            \texttt{\char'134 DeclareFontShape}}


This consist of one or more \m{fontshape-decl}s having the following
form:

\begin{quote}
 \m{fontshape-decl} |::=|   \m{size-info} \m{font-info}

 \m{size-info}   |::=| ``|<|''  \m{number-or-range} ``|>|''

 \m{font-info}  |::=| $[$ \m{size-function} ``|*|'' $]$
                ``|[|'' \m{optarg} ``|]|'' \m{fontarg}
                                  \texttt{\char`\|} \m{fontarg}
\end{quote}


The \m{number-or-range} denotes the size or size-range
for which this entry applies. If it contains a hyphen char it is a
range: lower bound on the left (if missing zero implied), upper bound
to the right of hyphen (if missing |\infty| implied). For ranges, the
upper bound is \emph{not} included in the range, lower bound is.

\begin{verbatim}
Examples:    <10>  simple size: 10pt
             <-8>  range: all sizes less than 8pt
             <14.4->  range: all sizes greater or equal 14.4pt
\end{verbatim}

If more than one \m{number-or-range} entry follows without any
intervening \m{font-info} they all share the next \m{font-info}.

The \m{size-function} if present handles the use of \m{font-info}. If
not present, the `empty' \m{size-function} is assumed.

All \m{size-info}s are inspected in the order in which they appear in
the font shape declaration. If a \m{size-info} matches the requested
size its \m{size-function} is executed. If |\external@font| is non-empty
afterwards this process stops, otherwise the next \m{size-info} is
inspected. (See also |\DeclareSizeFunction|.)

If this process doesn't lead to a non-empty |\external@font|, \NFSS{}
tries the nearest simple size.

Implemented functions:
\begin{description}
\item[`' (empty)]

load external font (in \m{fontarg}) at user requested size. If
\m{optarg} present, used as scale-factor.

\item[s]
like the empty one but no terminal warnings, only loggings.

\item[gen]

generates external font from mandatory arg followed by the user
requested size, eg |<8> <9> <10> gen * cmtt|

\item[sgen]

like the `gen' one but no terminal warnings, only loggings.

\item[sub]

tries to load font from a different fontshape declaration given by
\m{fontarg} in form \m{family}|/|\m{series}|/|\m{shape}.

\item[ssub]

silent variant of sub, only loggings.

\item[subf]

like the empty one, but issues a warning, that it has to substitute
the external font \m{fontarg} because the desired font shape wasn't
available in the requested size.

\item[ssubf]

silent variant of subf, only loggings.

\item[fixed]

load font as is (disregarding user size) from \m{fontarg}. If present
\m{optarg} denotes the ``at \dots pt'' size to be used.

\item[sfixed]

silent variant of fixed, only loggings.

\end{description}


\subsubsection{Font hooks}

\NFSS{} provides a set of built-in hooks that modify the
behaviour of the high-level font change commands.  These hooks are
shown in table~\ref{tab:fontdefaults}.
\begin{table}
\noindent\hspace{-40pt}
\begin{small}
\begin{tabular}{l l l}
\multicolumn{1}{l}{\itshape Hook} &
\multicolumn{1}{l}{\itshape Default value} &
\multicolumn{1}{l}{\itshape Description} \\[2pt]
 |\encodingdefault| & |OT1|  &  Encoding scheme for `main font' \\
 |\familydefault|   & |\rmdefault|  &  Font family selected for
                                       `main font' \\
 |\seriesdefault|   & |m|    &  Series selected for `main font' \\
 |\shapedefault|    & |n|    &  Shape selected for `main font' \\
 |\rmdefault| & |cmr|  &
                 Font family selected by |\rmfamily| and  |\textrm| \\
 |\sfdefault| & |cmss| &
                 Font family selected by |\sffamily| and |\textsf| \\
 |\ttdefault| & |cmtt| &
                 Font family selected by |\ttfamily|  and |\texttt| \\
 |\bfdefault|           & |bx|  & Series selected by |\bfseries|  and
                                                     |\textbf| \\
 |\mediumseriesdefault| & |m|   & Series selected by
                                   |\mdseries|  and |\textmd| \\
 |\itdefault|           & |it|  & Shape selected by |\itshape|  and
                                                    |\textit| \\
 |\sldefault|           & |sl|  & Shape selected by |\slshape|  and
                                                    |\textsl| \\
 |\scdefault|           & |sc|  & Shape selected by |\scshape| and
                                                    |\textsc|  \\
 |\normalshapedefault|  & |n|   & Shape selected by |\upshape| and
                                                    |\textup|
\end{tabular}
\end{small}
\caption{Font attribute hooks}
\label{tab:fontdefaults}
\end{table}


The initial setting of |\familydefault| means that changing only
|\rmdefault| will also change |\familydefault| to its value. However, if
|\familydefault| is changed |\rmdefault| is not affected.



\subsection{Low level interfaces}

\begin{decl}
|\fontencoding| \m{encoding}
\end{decl}

\begin{decl}
|\fontfamily|  \m{family}
\end{decl}

\begin{decl}
|\fontseries| \m{series}
\end{decl}

\begin{decl}
|\fontshape| \m{shape}
\end{decl}

\begin{decl}
|\fontsize| \m{size} \m{baselineskip}
\end{decl}

\begin{decl}
|\selectfont|
\end{decl}

\begin{decl}
|\usefont| \m{encoding} \m{family} \m{series} \m{shape}
\end{decl}




\subsection{Internal interfaces}

Font attributes are held internally in local macros:

\begin{verbatim}
\f@encoding     current encoding value
\f@family       current family value
\f@series       current series value
\f@size         current size value    (in pt without explicit dimension!)
\f@baselineskip current baselineskip value

\tf@size        current text size for math
                 (normally the same as \f@size)
\sf@size        current script size for math
\ssf@size       current scriptscript size for math

Example of use: \fontsize{17.28}{\f@baselineskip} will set size to 17
                without changing baselineskip.
\end{verbatim}



\subsubsection{Utilities}

\begin{decl}
|\hexnumber@| \m{num}
\end{decl}

Converts \m{num} into a single hex digit if in range $0 \leq
\mbox{\m{num}} < 16$.  Completely expandable and thus can be used to
construct longer hex numbers in an emergency.

\begin{verbatim}
Example: \xdef\yen{\noexpand\mathhexbox\hexnumber@\symAMSa 55 }
\end{verbatim}



\begin{decl}
|\f@warn@break|
\end{decl}

This command is used within warning messages generated by \NFSS{} and
is defined to produce a new line beginning with the string ``|NFSS|''
(plus a suitable number of spaces) which means that it is fairly easy
to extract all \NFSS{} related messages from the transcript file. If
this is not desired one can redefine it to be less conspicuous, e.g.,

\begin{verbatim}
Example: \def\f@warn@break{^^J\@spaces\@spaces\@spaces}
\end{verbatim}


\end{document}