% \iffalse meta-comment
%
% Copyright (C) 1994 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 newlfont.sty )
%%% LaTeX 2.09 ( NFSS1 oldlfont.sty )
%%% LaTeX 2.09 ( NFSS1 basefont.tex )
%%% LaTeX 2.09 ( NFSS2 public alpha release )
%%% LaTeX2e    ( as of 1993/12/25 )
%%%
%%% It does not require any extra files except the standard article
%%% class (style) file.
%%%

\documentstyle{article}

\def\filedate{1994/01/31}

%%% 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 complex definitions need to be 
%%% made in the preamble.


\hyphenation{hexa-deci-mal}

\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{\nopagebreak\small\nverbatim}

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

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

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

\newcommand{\NFSS}{\textsf{NFSS}}

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

\@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}{\mbox{\AmS-\LaTeX}}

\newcommand{\filex}[1]{\makebox[20pt][l]{\tt #1}\ignorespaces}

\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 most of the new features of
\LaTeXe---it makes no claims of completeness or of complete accuracy
(but please tell us if you find any errors). 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; 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' will be standard; 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}

These are the commands that can appear before the |\documentclass| line.

\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}
\label{sec:pre}

The changes to these 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 (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
date 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.  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. 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 loaded by the \m{class-name} argument
of the |\documentclass| declaration).  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 |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.

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

The options specified in the |\documentclass| and |\usepackage|
declarations are processed as follows.

\begin{enumerate}
\item They are first divided into two types, {\em
  local\/} and {\em global\/}:
\begin{itemize}
  \item for a class, the options from its |\documentclass| command are
    local and there are no global options;
  \item for a package, the options from its |\usepackage| command are
    local but the options from 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 their order 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.  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'; they may, of
   course, be used later since they become global options for every
   package subsequently loaded. 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 message and will list 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.  Some of these can also
be used in the preamble.

\subsubsection{Definitions}

The means of creating and changing both commands and environments
have been enhanced and extended.

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

The optional argument, \m{default}, 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 of \m{cmd};
  \item when the command \m{cmd} is used without this first (optional)
    argument being specified, the value of |#1| (i.e.~its first
    argument) in the \m{definition} will be whatever was specified as
    \oarg{default} when \m{cmd} was defined.
\end{itemize}
For example, after the following:
\begin{verbatim}
   \newcommand{\seq}[2][n]{#2_{0},\ldots\,#2_{#1}}
\end{verbatim}
using |\seq{a}| (within a formula) will produce $a_{0},\ldots\,a_{n}$,
whereas |\seq[k]{x}| will produce $x_{0},\ldots\,x_{k}$.

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

These next three commands 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, three special lengths can be used.  These are
all dimensions of the box which 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}

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}
|\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 LR-mode 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 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, centred, or
`stretched' alignment respectively.  The default value of
\m{inner-pos} is to be the same as the actual value of \m{pos}.


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


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

\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 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 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
Section~\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; if you do not
like the result, this can be over-ridden by using |\/| or |\nocorr|.

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

\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 `shel\literal{f}ful', produced by
`|shelfful|' and `|shel\literal{f}ful|'. (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').


\section{Warning: stop here?}

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 as follows, and to link this
classification to their appearance (syntactic form). 

\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 
  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 
  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{System dependent commands}

When the \LaTeXe\ format is made, certain tests are run to try to
determine the behaviour of the \TeX\ implementation in use 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 |dircheck.dtx| contains a more detailed explanation of these
requirements, including examples.  This documentation may be typeset by
running \LaTeXe\ on the file |dircheck.drv|.


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

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{High level class \& package interface}

The commands in this section allow class and package writers to clearly
identify their files and to 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, must be in the form YYYY/MM/DD.

Example:
\begin{verbatim}
   \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.

Example:
\begin{verbatim}
   \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.

Example:
\begin{verbatim}
   \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.

Example:
\begin{verbatim}
   \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}
   \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 specified in the class
or package. The |\@options| command from \LaTeX~2.09 has been made
equivalent to this in order to ease the task of updating old main
document styles to \LaTeXe\ class files.


\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 that 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 directly affect package writers will be listed
here.

This section is not yet complete.

\subsection{Obsolete commands}

These commands, etc.\ are no longer available.

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

\begin{decl}
|\@maxsep|\\
|\@dblmaxsep|
\end{decl}
These two parameters are no longer used so they have been removed.

\subsection{New commands}

\begin{decl}
|\@checkcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
\end{decl}
This 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 numbers less
than 10 (warning: this includes all 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{Incompatibilities and changes}

Section~\ref{sec:pre} describes the more obvious changes which affect
the preamble of the document.

This section describes the major differences which will be found when
processing a document.  It compares \LaTeXe{} with various old
versions of \LaTeX.


\subsection{Compared to the original \LaTeX~2.09}

\subsubsection{Font changes}

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. The
combination |\bf\it| selected a medium weight italic (the |\it|
completely replacing the |\bf|) and similarly |\it\bf| produced an
upright bold font.

The size-changing commands such as |\large| always switched to a roman
font.  \LaTeXe\ introduces the more flexible font changing
declarations, such as |\rmfamily|, and commands, such as |\textrm|.

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.  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 new \NFSS\ text font commands and
declarations.)

\subsubsection{Compatibility mode}

If the document begins with |\documentstyle| rather than
|\documentclass| then a more complete emulation of \LaTeX~2.09 is
used.
\begin{itemize}
\item A |.sty| file will be loaded if a |.cls| file cannot be found.
\item Size changing commands switch to a roman font.
\item All the standard two-letter font commands are allowed in math.
\item The declaration |\sloppy|, which normally has an improved
  definition, reverts to its old definition; this helps maintain the
  line-breaking on existing documents.
\end{itemize}


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

Release 1 of the \NFSS\ introduced the concept of orthogonal font
switching but not the new declaration names such as |\rmfamily|.  With
the |newlfont| option it redefined the existing two-letter forms and
their use was not allowed in math mode. \LaTeX2e\ is distributed with
a package |newlfont| that defines |\rm|, |\bf| etc in a way similar to
\NFSS1.

The following list details some more differences between \NFSS1 and
\LaTeXe.

\begin{itemize}
\item
  These obsolete commands from \NFSS{}1 have been removed: |\family|, 
  |\series|, |\shape|, and |\size|.  Instead use |\fontfamily|,
  |\fontseries|, |\fontshape|, and |\fontsize|.

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

\item
  The commands |\normalshape| and |\mediumseries| have been renamed to
  |\upshape| and |\mdseries|.

\item
  The following internal commands are also now obsolete:\\
  |\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 \LaTeXe{}
  this request is now interpreted as asking for a font at `14pt'
  sharp. Since in the standard FontShape declarations such a font
  is not available, \LaTeXe{} will attempt to use a nearby size and
  therefore will (after a warning) also use the `14.4pt' size, so
  documents will come out unchanged.

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

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

\subsection{Compared to 2.09 with \NFSS2}

While \LaTeXe\ was being developed, a prototype \NFSS2 release was made
available for use with \LaTeX~2.09. The internal structure of 
\LaTeXe\ has not significantly altered from this but 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}.


\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}; any paper size can be modified
  by the option \texttt{landscape}.
  These set the |\paperheight| and |\paperwidth| parameters.  When
  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{File extension conventions}

The \LaTeXe\ system uses many different types of files. The main file
extensions and their meanings are listed here.

\filex{l2e} Plain text files containing basic documentation, etc.

\filex{ins} Docstrip batch files: run iniTeX on these to unpack files.\\
\filex{ltx} Internal \LaTeX\ files, used only during the installation.\\
\filex{cfg} Configuration files: these are the only files that you are\\
\filex{}    \ allowed to edit to customise \LaTeX\ for your site.

\filex{fdd} Documented sources for font definition files.\\
\filex{dtx} Documented sources for other files.\\
\filex{drv} Driver files: run \LaTeX{} on these to produce documentation.

\filex{cls} Class files.\\
\filex{clo} Files implementing class options.\\
\filex{sty} Package files (and \LaTeX~2.09 style files).\\
\filex{fd}  Font definition files.\\
\filex{def} Other \LaTeX{} definition files.

\filex{tex} \LaTeX\ document.\\
\filex{aux} \LaTeX\ document information.\\
\filex{toc} \LaTeX\ document table-of-contents information.

\filex{ist} Makeindex style files.\\
\filex{idx} Raw index files.\\
\filex{ind} Sorted index files.\\
\filex{gls} Raw glossary files.\\
\filex{glo} Sorted Glossary files.

\filex{log} \TeX\ log file (some systems).\\
\filex{lis} \TeX\ log file (some systems).\\
\filex{ilg} Makeindex log file.

\filex{fmt} \TeX\ format file (binary).\\
\filex{dvi} \TeX\ output file (binary).


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

\subsection{Using text fonts}

There are two ways of changing the text font: commands, which take the
affected text as an argument; declarations, which change the text from
that point onward.

Although the command form is the best one for use in documents, it
does more work so it is not as efficient as the declaration form.
Therefore, when writing package files it is better to use a
declaration unless the automatic insertion of the italic correction
(see below) is needed.

\subsubsection{Font changing commands}

Font changes use the following commands.

THe font family is changed with:
\begin{verbatim}
   \textrm{...} \textsf{...} \texttt{...}
\end{verbatim}
The font series (weight/width) is changed with:
\begin{verbatim}
   \textbf{...} \textmd{...}
\end{verbatim}
The font shape is changed with:
\begin{verbatim}
   \textit{...} \textsl{...} \textsc{...} \textup{...}
\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| at
an appropriate place, depending on whether you wish to suppress the
correction before or after the argument text.

The automatic insertion of the italic correction is regulated by the
contents of |\nocorrlist|.  This is a list of characters; immediately
in front of these, no italic correction is inserted.  Its value could,
for example, be set as follows:
\begin{verbatim}
   \def\nocorrlist{.,;:}
\end{verbatim}

\subsubsection{Font changing declarations}

Each of the above commands has a corresponding declaration.

Font family:
\begin{verbatim}
   {\rmfamily ...} {\sffamily ...} {\ttfamily ...}
\end{verbatim}
Font series (weight/width):
\begin{verbatim}
   {\bfseries ...} {\mdseries ...}
\end{verbatim}
Font shape:
\begin{verbatim}
   {\itshape ...} {\slshape ...} {\scshape ...} {\upshape ...}
\end{verbatim}
Emphasis:
\begin{verbatim}
   {\em ...}
\end{verbatim}


\subsubsection{Font hooks}

\NFSS{} provides a set of built-in hooks that modify the
behaviour of the high-level font changing 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| \\
 |\mddefault| & |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|  \\
 |\updefault|  & |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.


\subsubsection{Accessing symbols in text}

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

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


\subsection{Math fonts}

\subsubsection{Predefined math versions}

The standard format declares two math versions: `normal' and `bold'.

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


\subsubsection{Predefined math alphabets}

The system provides the following.
\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}


\subsubsection{Declaring math sizes}

\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 bit-map math fonts
you may not have for every \m{t-size} a corresponding set of math
sizes.

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


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

Example:
\begin{verbatim}
   \DeclareMathVersion{normal}
\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.

In these examples, |\foo| is defined everywhere but |\baz|,
by default, is defined nowhere.
\begin{verbatim}
   \DeclareMathAlphabet{\foo}{OT1}{cmtt}{m}{n}
   \DeclareMathAlphabet{\baz}{OT1}{}{}{}
\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.

This example defines
|\baz| for the `normal' math version only):
\begin{verbatim}
   \SetMathAlphabet\baz{normal}{OT1}{cmss}{m}{n}
\end{verbatim}

Note that this declaration is not used for all math alpahabets: 
section~\ref{sec:symalph} describes |\DeclareSymbolFontAlphabet|,
which is used to set up math alphabets contained in fonts which have
are declared as symbol fonts.


\subsubsection{Declaring symbol fonts}
\label{sec:symalph}

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

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

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

Internally it allocates a new math group with name
|\sym|\m{sym-font-name}.

For example, the following sets up the first four standard math fonts: 
\begin{verbatim}
   \DeclareSymbolFont{operators}{OT1}{cmr}{m}{n}
   \DeclareSymbolFont{letters}{OML}{cmm}{m}{it}
   \DeclareSymbolFont{symbols}{OMS}{cmsy}{m}{n}
   \DeclareSymbolFont{largesymbols}{OMX}{cmex}{m}{n}
\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 that \m{sym-font-name} is a symbol font, \m{version name} is a
known math version and \m{cdp} is a declared encoding scheme.

For example, the following come from the set up of the `bold'
math version:
\begin{verbatim}
   \SetSymbolFont{operators}{bold}{OT1}{cmr}{bx}{n}
   \SetSymbolFont{letters}{bold}{OML}{cmm}{b}{it}
\end{verbatim}




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

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

This declaration should be used in preference to
|\DeclareMathAlpahbet| and |\SetMathAlphabet| when the math alphabet
is part of a symbol font; this is because it makes better use of
the limited number (only 16) of \TeX's math groups.

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

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


\subsection{Math symbols}

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

The \m{symbol} can be either a single character, eg `|>|', or a macro
name, eg |\sum|.

Defines this macro or character \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.  The \m{position} can be decimal, octal, or
hexadecimal with the usual notation |'| or |"| for octal and hex.
Symbolic values for \m{type} are the corresponding |\mathord|,
|\mathbin|,\ldots{} commands.

Allows a macro \m{symbol} to be redefined only if it was previously
defined to be a math symbol.

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

Example:
\begin{verbatim}
   \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.  The \m{position-i} can be
decimal, octal, or hexadecimal with the usual notation |'| or |"| for
octal and hex.

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

If \TeX{} is not looking for a delimiter, \m{cmd} is treated just as
if it had been defined with |\DeclareMathSymbol| using
\m{sym-font-name-1} \m{position-1}.  In other words, if a command is
defined as a delimiter then this automatically defines it as a math
symbol.

However, if this command is used to define a single character as a
delimiter this has no effect on its normal use.  It can be defined,
via |\DeclareMathSymbol|, to have completely different behaviour when
it is used as a math symbol.

Example:
\begin{verbatim}
   \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 font when used in a math alphabet.

Example:
\begin{verbatim}
   \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.

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


\subsection{Text font declarations}

\subsubsection{Encoding}

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

The \m{math-settings} are similar but for math alphabets (only!). They
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|.

Example:
\begin{verbatim}
   \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 an argument, the current setting of this default
is left unchanged.

This example is used by amsfonts.sty for accent positioning; it changes
only the math settings:
\begin{verbatim}
   \DeclareFontEncodingDefaults{\relax}{\def\accentclass@{7}}
\end{verbatim}

\subsubsection{Family, shape and size}

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

Declares a font family \m{family} to be available in an encoding scheme
\m{cdp}. The \m{loading-options} are executed for every
font shape of that combination once at the time of loading.

Checks that \m{cdp} was previously declared.

This example refers to the Computer Modern Typewriter in Cork encoding:
\begin{verbatim}
   \DeclareFontFamily{T1}{cmtt}{\hyphenchar\font=-1}
\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; here \m{loading-info} contains the
information that combines sizes with external fonts. The syntax is
complex and is described in Section~\ref{sec:loadinfo} below.

The \m{loading-options} are used as above; they allow overwriting,
for this particular shape, of the general loading options made at the
family level.

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

Example:
\begin{verbatim}
   \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}

\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 evaluated only when this declaration is made.
The font is selected without any adjustments to baselineskip and other
surrounding conditions.

This example makes |\picturechar .| select a small dot very quickly:
\begin{verbatim}
   \DeclareFixedFont{\picturechar}{OT1}{cmr}{m}{n}{5}
\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
(i.e.~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|.

Example:
\begin{verbatim}
   \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 cannot 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|.

Example:
\begin{verbatim}
   \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|.


\subsubsection{Size functions}

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

Declares a size-function \m{name} for use in |\DeclareFontShape|
commands.  The interface is still lousy but then there should be no
real need to a define new size functions.

The \m{code} is executed when the size or size-range in
|\DeclareFontShape| matches the requested user size.

The arguments of the size-function 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.

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


The system provides the following functions.

\begin{description}
\item[`' (empty)]
Load the external font (in \m{fontarg}) at user requested size. If
\m{optarg} present, used as scale-factor.

\item[s]
Like the empty function but without terminal warnings, only
loggings.

\item[gen]
Generates the external font from the mandatory arg followed by
the user requested size, e.g. |<8> <9> <10> gen * cmtt|

\item[sgen]
Like the `gen' function but without terminal warnings, only loggings.

\item[sub]
Tries to load a font from a different fontshape declaration given by
\m{fontarg} in the form \m{family}|/|\m{series}|/|\m{shape}.

\item[ssub]
Silent variant of `sub', only loggings.

\item[subf]
Like the empty function but issues a warning that it has to substitute
the external font \m{fontarg} because the desired font shape was not
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 \ldots pt'' size to be used.

\item[sfixed]
Silent variant of `fixed', only loggings.

\end{description}


\subsubsection{Preloading}

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

Specifies the font (.tfm) files that should be loaded by the format.

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


\subsection{Naming conventions}

\subsubsection{Math alphabets}

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

\subsubsection{Text font changes}

The text font changing commands with arguments all 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 cyrillic 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-long text encodings), |M| (standard 256-long math
encodings), |S| (standard 256-long symbol encodings), |OT| (standard
128-long text encodings), |OM| (standard 128-long math encodings).

Encoding schemes which are local to a site should start with |L|.
Please do not 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}


\section{Font file loading information}
\label{sec:loadinfo}

The information which tells \LaTeX{} exactly which font ({\tt .tfm})
files to load is contained in the \m{loading-info} part of a
|\DeclareFontShape| declaration. This part consists of one or more
\m{fontshape-decl}s, each of which has the following form:

\begin{tabular}{c@{$:{:}=$ }l}
 \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} \\
\multicolumn{1}{c}{}& \quad $\mid$ \m{fontarg}
\end{tabular}

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 and the lower bound is.

Examples:

\begin{tabular}{lll}
   |<10>|     &  simple size& 10pt only\\
   |<-8>|     &  range& all sizes less than 8pt\\
   |<8-14.4>| &  range& all sizes greater than or equal to 8pt\\
              &       & \ but less than 14.4pt\\
   |<14.4->|  &  range& all sizes greater than or equal 14.4pt
\end{tabular}

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 the \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 does not lead to a non-empty |\external@font|, \NFSS{}
tries the nearest simple size.


\subsection{Utilities}

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

For \m{num} in the range $0 \leq \mbox{\m{num}} < 16$, converts
\m{num} into a single hex digit.  It is completely expandable and thus
can be used to construct longer hex numbers in an emergency.

Example:
\begin{verbatim}
   \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 
``|Font|'' (plus a suitable number of spaces). This means that
it is fairly easy to extract all \NFSS{} related messages from the
transcript file. If this is not desired, redefine it to be less
conspicuous; for example:
\begin{verbatim}
   \def\f@warn@break{^^J\@spaces\@spaces\@spaces}
\end{verbatim}

\subsection{Low-level interfaces}

The low-level commands used to select a text font are as follows.

\begin{decl}
|\fontencoding| \m{encoding} \\
|\fontfamily|  \m{family}\\
|\fontseries| \m{series}\\
|\fontshape| \m{shape}\\
|\fontsize| \m{size} \m{baselineskip}
\end{decl}

Each of these commands sets the value of just one of the font
attributes; |\fontsize| also sets the value of |\baselineskip|. The
actual font in use is not altered by these commands, but the current
attributes are used to determine which font to use after the the next
|\selectfont| command.

\begin{decl}
|\selectfont|
\end{decl}
Selects a text font, based on the current values of the font attributes.

\begin{decl}
|\usefont| \m{encoding} \m{family} \m{series} \m{shape}
\end{decl}
A short hand for the equivalent |\font|\ldots{} commands followed by a
call to |\selectfont|.

The current values of the font attributes are held internally in these
locally set macros:

\begin{tabular}{l l} 
|\f@encoding| &     current encoding value \\
|\f@family| &       current family value \\
|\f@series| &       current series value \\
|\f@size| &         current size value   \\
           &        \ (in pt, without an explicit dimension) \\
|\f@baselineskip| & current baselineskip value \\[6pt]
|\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
\end{tabular}

As an example of their use, this will set the size to 12 without
changing the baselineskip:
\begin{verbatim}
   \fontsize{12}{\f@baselineskip} 
\end{verbatim}

\end{document}