diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/base/clsguide.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/base/clsguide.tex | 321 |
1 files changed, 160 insertions, 161 deletions
diff --git a/Master/texmf-dist/doc/latex/base/clsguide.tex b/Master/texmf-dist/doc/latex/base/clsguide.tex index 2b3c4b3b001..d778bf9ff4c 100644 --- a/Master/texmf-dist/doc/latex/base/clsguide.tex +++ b/Master/texmf-dist/doc/latex/base/clsguide.tex @@ -1,30 +1,30 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2019 +% Copyright (C) 1993-2020 % The LaTeX3 Project and any individual authors listed elsewhere -% in this file. -% +% in this file. +% % This file is part of the LaTeX base system. % ------------------------------------------- -% +% % It may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3c % of this license or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt -% and version 1.3c or later is part of all distributions of LaTeX +% and version 1.3c or later is part of all distributions of LaTeX % version 2008 or later. -% +% % This file has the LPPL maintenance status "maintained". -% +% % The list of all files belonging to the LaTeX base distribution is % given in the file `manifest.txt'. See also `legal.txt' for additional % information. -% -% The list of derived (unpacked) files belonging to the distribution -% and covered by LPPL is defined by the unpacking scripts (with +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with % extension .ins) which are part of the distribution. -% +% % \fi % Filename: clsguide.tex @@ -37,46 +37,46 @@ \author{Copyright \copyright~1995--2006 The \LaTeX3 Project\\ All rights reserved} -\date{15 February 2006} +\date{15 February 2006} \begin{document} - + \maketitle - + \tableofcontents - + \section{Introduction} This document is an introduction to writing classes and packages for \LaTeX{}, with special attention given to upgrading existing \LaTeX~2.09 packages to \LaTeXe{}. The latter subject is also covered in an article by Johannes Braams published in TUGboat~15.3. - + \subsection{Writing classes and packages for \LaTeXe} - + \LaTeX{} is a document preparation system that enables the document writer to concentrate on the contents of their text, without bothering too much about the formatting of it. For example, chapters are indicated by |\chapter{<title>}| rather than by selecting 18pt bold. - + The file that contains the information about how to turn logical structure (like `|\chapter|') into formatting (like `18pt bold ragged right') is a \emph{document class}. In addition, some features (such as colour or included graphics) are independent of the document class and these are contained in \emph{packages}. - + One of the largest differences between \LaTeX~2.09 and \LaTeXe{} is in the commands used to write packages and classes. In \LaTeX~2.09, there was very little support for writing |.sty| files, and so writers had to resort to using low-level commands. - + \LaTeXe{} provides high-level commands for structuring packages. It is also much easier to build classes and packages on top of each other, for example writing a local technical report class |cetechr| (for the Chemical Engineering department) based on |article|. - + \subsection{Overview} - + This document contains an overview of how to write classes and packages for \LaTeX{}. It does \emph{not} introduce all of the commands necessary to write packages: these can be found in either @@ -84,33 +84,33 @@ commands necessary to write packages: these can be found in either commands for structuring classes and packages. \begin{description} - + \item[Section~\ref{Sec:general}] contains some general advice about writing classes and packages. It describes the difference between classes and packages, the command naming conventions, the use of |doc| and |docstrip|, how \TeX's primitive file and box commands interact with \LaTeX{}. It also contains some hints about general \LaTeX{} style. - + \item[Section~\ref{Sec:structure}] describes the structure of classes and packages. This includes building classes and packages on top of other classes and packages, declaring options and declaring commands. It also contains example classes. - + \item[Section~\ref{Sec:commands}] lists the new class and package commands. - + \item[Section~\ref{Sec:upgrade}] gives detailed advice on how to upgrade existing \LaTeX~2.09 classes and packages to \LaTeXe{}. - + \end{description} - + \subsection{Further information} - + For a general introduction to \LaTeX{}, including the new features of \LaTeXe{}, you should read \emph{\LaTeXbook} by Leslie Lamport~\cite{A-W:LLa94}. - + A more detailed description of the new features of \LaTeX, including an overview of more than 200 packages and nearly 1000 ready to run examples, is to be found in \emph{\LaTeXcomp\ second edition} by Frank Mittelbach and @@ -118,7 +118,7 @@ Michel Goossens~\cite{A-W:MG2004}. The \LaTeX{} system is based on \TeX{}, which is described in \emph{The \TeX book} by Donald E.~Knuth~\cite{A-W:DEK91}. - + There are a number of documentation files which accompany every copy of \LaTeX{}. A copy of \emph{\LaTeX{} News} will come out with each six-monthly release of \LaTeX{}, and is found in the files @@ -127,7 +127,7 @@ six-monthly release of \LaTeX{}, and is found in the files \emph{\fntguide} describes the \LaTeX{} font selection scheme for class- and package-writers; it is in |fntguide.tex|. Configuring \LaTeX{} is covered by the guide \emph{\cfgguide} in -\texttt{cfgguide.tex} whilst the philosophy behind our policy on +\texttt{cfgguide.tex} whilst the philosophy behind our policy on modifying \LaTeX{} is described in \emph{\modguide} in \texttt{modguide.tex}. @@ -175,7 +175,7 @@ cannot be changed. We would, of course, welcome the production of better classes, or of packages that can be used to enhance these classes. So your first thought when you consider such a deficiency will, we hope, be ``what -can I do to improve this?'' +can I do to improve this?'' Similar considerations apply to those parts of the kernel that are implementing design decisions, many of which should be left to the @@ -187,7 +187,7 @@ enhancements will have to wait for \LaTeX3. \section{Writing classes and packages} \label{Sec:writing} - + This section covers some general points concerned with writing \LaTeX{} classes and packages. @@ -206,33 +206,33 @@ supported by individuals: they should support only the new standard \subsection{Using `docstrip' and `doc'} - + If you are going to write a large class or package for \LaTeX{} then you should consider using the |doc| software which comes with -\LaTeX{}. +\LaTeX{}. \LaTeX{} classes and packages written using this can be processed in two ways: they can be run through \LaTeX{}, to produce documentation; and they can be processed with |docstrip|, to produce the |.cls| or |.sty| file. - + The |doc| software can automatically generate indexes of definitions, indexes of command use, and change-log lists. It is very useful for maintaining and documenting large \TeX{} sources. - + The documented sources of the \LaTeX{} kernel itself, and of the standard classes, etc, are |doc| documents; they are in the |.dtx| files in the distribution. You can, in fact, typeset the source code of the kernel as one long document, complete with index, by running \LaTeX{} on |source2e.tex|. Typesetting these documents uses the class file |ltxdoc.cls|. - + For more information on |doc| and |docstrip|, consult the files |docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its use, look at the |.dtx| files. \subsection{Is it a class or a package?} \label{Sec:classorpkg} - + The first thing to do when you want to put some new \LaTeX{} commands in a file is to decide whether it should be a \emph{document class} or a \emph{package}. The rule of thumb is: @@ -250,59 +250,59 @@ Thus, a company might have a local |ownlet| class for printing letters with their own headed note-paper. Such a class would build on top of the existing |letter| class but it cannot be used with any other document class, so we have |ownlet.cls| rather than |ownlet.sty|. - + The |graphics| package, in contrast, provides commands for including images into a \LaTeX{} document. Since these commands can be used with any document class, we have |graphics.sty| rather than |graphics.cls|. - + \subsection{Command names} - + \LaTeX{} has three types of command. - + There are the author commands, such as |\section|, |\emph| and |\times|: most of these have short names, all in lower case. - + There are also the class and package writer commands: most of these have long mixed-case names such as the following. \begin{verbatim} \InputIfFileExists \RequirePackage \PassOptionsToClass \end{verbatim} - + Finally, there are the internal commands used in the \LaTeX{} implementation, such as |\@tempcnta|, |\@ifnextchar| and |\@eha|: most of these commands contain |@| in their name, which means they cannot be used in documents, only in class and package files. - + Unfortunately, for historical reasons the distinction between these commands is often blurred. For example, |\hbox| is an internal command which should only be used in the \LaTeX{} kernel, whereas |\m@ne| is the constant $-1$ and could have been |\MinusOne|. - + However, this rule of thumb is still useful: if a command has |@| in its name then it is not part of the supported \LaTeX{} language---and its behaviour may change in future releases! If a command is mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on future releases of \LaTeXe{} supporting the command. - + \subsection{Box commands and colour} \label{Sec:colour} - + Even if you do not intend to use colour in your own documents, by taking note of the points in this section you can ensure that your class or package is compatible with the |color| package. This may benefit people using your class or package who have access to colour printers. - + The simplest way to ensure `colour safety' is to always use \LaTeX{} box commands rather than \TeX{} primitives, that is use |\sbox| rather than |\setbox|, |\mbox| rather than |\hbox| and |\parbox| or the |minipage| environment rather than |\vbox|. The \LaTeX{} box commands have new options which mean that they are now as powerful as the \TeX{} primitives. - -As an example of what can go wrong, consider that in + +As an example of what can go wrong, consider that in |{\ttfamily <text>}| the font is restored just \emph{before} the |}|, whereas in the similar looking construction @@ -318,11 +318,11 @@ stored in the box. Exactly what bad effects this can have depends on how colour is implemented: it can range from getting the wrong colours in the rest of the document, to causing errors in the dvi-driver used to print the document. - -Also of interest is the command |\normalcolor|. This is + +Also of interest is the command |\normalcolor|. This is normally just |\relax| (i.e., does nothing) -but you can use it rather like |\normalfont| to -set regions of the page such as captions or section headings to the +but you can use it rather like |\normalfont| to +set regions of the page such as captions or section headings to the `main document colour'. @@ -349,13 +349,13 @@ outside math mode: for example, neither |\textfont 1| nor The new system provides many commands designed to help you produce well-structured class and package files that are both robust and portable. This section outlines some ways to make intelligent use of -these. +these. \subsubsection{Loading other files} \label{Sec:loading} \NEWdescription{1995/12/01} -\LaTeX{} provides these commands: +\LaTeX{} provides these commands: \begin{verbatim} \LoadClass \LoadClassWithOptions \RequirePackage \RequirePackageWithOptions @@ -363,20 +363,20 @@ these. for using classes or packages inside other classes or packages. We recommend strongly that you use them, rather than the primitive |\input| command, for a number of reasons. - + Files loaded with |\input <filename>| will not be listed in the |\listfiles| list. - + If a package is always loaded with |\RequirePackage...| or |\usepackage| then, even if its loading is requested several times, it will be loaded only once. By contrast, if it is loaded with |\input| then it can be loaded more than once; such an extra loading may waste time and memory and it may produce strange results. - + If a package provides option-processing then, again, strange results are possible if the package is |\input| rather than loaded by means of |\usepackage| or |\RequirePackage...|. - + If the package |foo.sty| loads the package |baz.sty| by use of |\input baz.sty| then the user will get a warning: \begin{verbatim} @@ -385,7 +385,7 @@ If the package |foo.sty| loads the package |baz.sty| by use of \end{verbatim} Thus, for several reasons, using |\input| to load packages is not a good idea. - + Unfortunately, if you are upgrading the file |myclass.sty| to a class file then you have to make sure that any old files which contain |\input myclass.sty| still work. @@ -404,7 +404,7 @@ For example, |article.sty| contains just the following lines: \end{verbatim} You may wish to do the same or, if you think that it is safe to do so, you may decide to just remove |myclass.sty|. - + \subsubsection{Make it robust} We consider it good practice, when writing packages and classes, to use @@ -415,20 +415,20 @@ Thus, instead of using |\def...| we recommend using one of also useful. Doing this makes it less likely that you will inadvertently redefine a command, giving unexpected results. - + When you define an environment, use |\newenvironment| or |\renewenvironment| instead |\def\foo{...}| and |\def\endfoo{...}|. - + If you need to set or change the value of a \m{dimen} or \m{skip} register, use |\setlength|. - + To manipulate boxes, use \LaTeX{} commands such as |\sbox|, |\mbox| and |\parbox| rather than |\setbox|, |\hbox| and |\vbox|. - + Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the equivalent class commands) rather than |\@latexerr|, |\@warning| or |\wlog|. - + It is still possible to declare options by defining |\ds@<option>| and calling |\@options|; but we recommend the |\DeclareOption| and |\ProcessOptions| commands instead. These are more powerful and use @@ -460,7 +460,7 @@ It is also useful if local classes or packages have a common prefix, for example the University of Nowhere classes might begin with |unw|. This helps to avoid every University having its own thesis class, all called |thesis.cls|. - + If you rely on some features of the \LaTeX{} kernel, or on a package, please specify the release-date you need. For example, the package error commands were introduced in the June 1994 release so, if you use @@ -486,7 +486,7 @@ particular, no typesetting can be done. \section{The structure of a class or package} \label{Sec:structure} - + \LaTeXe{} classes and packages have more structure than \LaTeX~2.09 style files did. The outline of a class or package file is: \begin{description} @@ -500,9 +500,9 @@ style files did. The outline of a class or package file is: \item[More declarations] This is where the file does most of its work: declaring new variables, commands and fonts; and loading other files. \end{description} - + \subsection{Identification} - + The first thing a class or package file does is identify itself. Package files do this as follows: \begin{verbatim} @@ -527,7 +527,7 @@ For example: \NEWdescription{1998/06/19} The \m{date} should be given in the form `\textsc{yyyy/mm/dd}' and must be present if the optional argument is used (this is also true -for the |\NeedsTeXFormat| command). +for the |\NeedsTeXFormat| command). Any derivation from this syntax will result in low-level \TeX{} errors---the commands expect a valid syntax to speed up the daily usage of the package or class and make no provision for the case that @@ -538,10 +538,10 @@ This date is checked whenever a user specifies a date in their \begin{verbatim} \documentclass{article}[1995/12/23] \end{verbatim} -then users at a different location +then users at a different location would get a warning that their copy of |article| was out of date. - + The description of a class is displayed when the class is used. The description of a package is put into the log file. These descriptions are also displayed by the |\listfiles| command. The phrase @@ -549,14 +549,14 @@ are also displayed by the |\listfiles| command. The phrase banner of any file other than those in the standard \LaTeX{} distribution. - + \subsection{Using classes and packages} - + The first major difference between \LaTeX~2.09 style files and \LaTeXe{} packages and classes is that \LaTeXe{} supports \emph{modularity}, in the sense of building files from small building-blocks rather than using large single files. - + A \LaTeX{} package or class can load a package as follows: \begin{verbatim} \RequirePackage[<options>]{<package>}[<date>] @@ -570,7 +570,7 @@ It allows packages or classes to use features provided by other packages. For example, by loading the |ifthen| package, a package writer can use the `if\dots then\dots else\dots' commands provided by that package. - + A \LaTeX{} class can load one other class as follows: \begin{verbatim} \LoadClass[<options>]{<class-name>}[<date>] @@ -600,7 +600,7 @@ For example: \end{verbatim} \subsection{Declaring options} - + \NEWdescription{1998/12/01} The other major difference between \LaTeX~2.09 styles and \LaTeXe{} packages and classes is in option handling. Packages and classes can @@ -666,7 +666,7 @@ class, you can use: \end{verbatim} If you do this then you should make sure you load the class at some later point, otherwise the options will never be processed! - + So far, we have explained only how to declare options, not how to execute them. To process the options with which the file was called, you should use: @@ -676,7 +676,7 @@ you should use: This executes the \m{code} for each option that was both specified and declared (see Section~\ref{Sec:commands.options} for details of how this is done). - + For example, if the |jane| package file contains: \begin{verbatim} \DeclareOption{foo}{\typeout{Saw foo.}} @@ -686,16 +686,16 @@ For example, if the |jane| package file contains: \end{verbatim} and an author writes |\usepackage[foo,bar]{jane}|, then they will see the messages \texttt{Saw foo.} and \texttt{What's bar?} - + \subsection{A minimal class file} - + Most of the work of a class or package is in defining new commands, or changing the appearance of documents. This is done in the body of the package, using commands such as |\newcommand| or |\setlength|. \LaTeXe{} provides several new commands to help class and package writers; these are described in detail in Section~\ref{Sec:commands}. - + There are four things that every class file \emph{must} contain: these are a definition of |\normalsize|, values for |\textwidth| and |\textheight| and a specification for page-numbering. So a minimal @@ -713,13 +713,13 @@ distribution, as \texttt{minimal.cls}.} looks like this: However, this class file will not support footnotes, marginals, floats, etc., nor will it provide any of the 2-letter font commands such as |\rm|; thus most classes will contain more than this minimum! - + \subsection{Example: a local letter class} - + A company may have its own letter class, for setting letters in the company style. This section shows a simple implementation of such a class, although a real class would need more structure. - + The class begins by announcing itself as |neplet.cls|. \begin{verbatim} \NeedsTeXFormat{LaTeX2e} @@ -742,9 +742,9 @@ the first page of letters. } \end{verbatim} And that's it! - + \subsection{Example: a newsletter class} - + A simple newsletter can be typeset with \LaTeX{}, using a variant of the |article| class. The class begins by announcing itself as |smplnews.cls|. @@ -793,7 +793,7 @@ It redefines |\section| and switches off section numbering. {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}% {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}% } - + \setcounter{secnumdepth}{0} \end{verbatim} It also sets the three essential things. @@ -806,20 +806,20 @@ In practice, a class would need more than this: it would provide commands for issue numbers, authors of articles, page styles and so on; but this skeleton gives a start. The |ltnews| class file is not much more complex than this one. - + \section{Commands for class and package writers} \label{Sec:commands} - + This section describes briefly each of the new commands for class and package writers. To find out about other aspects of the new system, you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and \emph{\usrguide}. - + \subsection{Identification} - + The first group of commands discussed here are those used to identify your class or package file. - + \begin{decl} |\NeedsTeXFormat| \arg{format-name} \oarg{release-date} \end{decl} @@ -830,12 +830,12 @@ format that is needed. When the release date of the format is older than the one specified a warning will be generated. The standard \m{format-name} is \texttt{LaTeX2e}. The date, if present, must be in the form \textsc{yyyy/mm/dd}. - + Example: \begin{verbatim} \NeedsTeXFormat{LaTeX2e}[1994/06/01] \end{verbatim} - + \begin{decl} |\ProvidesClass| \arg{class-name} \oarg{release-info} \\ |\ProvidesPackage| \arg{package-name} \oarg{release-info} @@ -857,25 +857,25 @@ release is not too old. The whole of this \m{release-info} information is displayed by |\listfiles| and should therefore not be too long. - + Example: \begin{verbatim} \ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class] \ProvidesPackage{ifthen}[1994/06/01 v1.0 Standard LaTeX package] \end{verbatim} - + \begin{decl} |\ProvidesFile| \arg{file-name} \oarg{release-info} \end{decl} This is similar to the two previous commands except that here the full filename, including the extension, must be given. It is used for declaring any files other than main class and package files. - + Example: \begin{verbatim} \ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file] \end{verbatim} - + Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used in the identification banner of any file other than those in the standard \LaTeX{} distribution. @@ -896,13 +896,13 @@ Packages and classes should use these commands to load other packages. The use of |\RequirePackage| is the same as the author command |\usepackage|. - + Examples: \begin{verbatim} \RequirePackage{ifthen}[1994/06/01] \RequirePackageWithOptions{graphics}[1995/12/01] \end{verbatim} - + \begin{decl} |\LoadClass| \oarg{options-list} \arg{class-name} \oarg{release-info}\\ @@ -913,7 +913,7 @@ Examples: These commands are for use \emph{only} in class files, they cannot be used in packages files; they can be used at most once within a class file. - + The use of |\LoadClass| is the same as the use of |\documentclass| to load a class file. @@ -945,7 +945,7 @@ There are some commands designed especially for use within the |\DeclareOption| \arg{option-name} \arg{code} \end{decl} This makes \m{option-name} a `declared option' of the class or package -in which it is put. +in which it is put. The \m{code} argument contains the code to be executed if that option is specified for the class or package; it can contain any valid @@ -955,7 +955,7 @@ Example: \begin{verbatim} \DeclareOption{twoside}{\@twosidetrue} \end{verbatim} - + \begin{decl} |\DeclareOption*| \arg{code} \end{decl} @@ -984,7 +984,7 @@ used within these arguments can be found in the next few subsections. |\CurrentOption| \end{decl} This expands to the name of the current option. - + \begin{decl} |\OptionNotUsed| \end{decl} @@ -997,7 +997,7 @@ be added to the list of `unused options'. necessary to double them). \subsection{Moving options around} -\label{Sec:opmove} +\label{Sec:opmove} These two commands are also very useful within the \m{code} argument of |\DeclareOption| or |\DeclareOption*|: @@ -1010,7 +1010,7 @@ The command |\PassOptionsToPackage| passes the option names in This means that it adds the \m{option-list} to the list of options used by any future |\RequirePackage| or |\usepackage| command for package \m{package-name}. - + Example: \begin{verbatim} \PassOptionsToPackage{foo,bar}{fred} @@ -1023,7 +1023,7 @@ is the same as: Similarly, |\PassOptionsToClass| may be used in a class file to pass options to another class to be loaded with |\LoadClass|. - + \NEWdescription{1995/12/01} The effects and use of these two commands should be contrasted with those of the following two (documented above, in \ref{Sec:loadf}): @@ -1077,7 +1077,7 @@ declared. \subsection{Delaying code} \label{Sec:delays} -These first two commands are also intended primarily for use within +These first two commands are also intended primarily for use within the \m{code} argument of |\DeclareOption| or |\DeclareOption*|. \begin{decl} @@ -1087,18 +1087,18 @@ the \m{code} argument of |\DeclareOption| or |\DeclareOption*|. These commands declare \m{code} that is saved away internally and then executed after processing the whole of the current class or package file. - + Repeated use of these commands is permitted: the code in the arguments is stored (and later executed) in the order of their declarations. - + \begin{decl} |\AtBeginDocument| \arg{code}\\ |\AtEndDocument| \arg{code} \end{decl} These commands declare \m{code} to be saved internally and executed while \LaTeX{} is executing |\begin{document}| or |\end{document}|. - + The \m{code} specified in the argument to |\AtBeginDocument| is executed near the end of the |\begin{document}| code, \emph{after} the font selection tables have been set up. It is therefore a useful @@ -1116,11 +1116,11 @@ executed at the beginning of the |\end{document}| code, floating environments are processed. If some of the \m{code} is to be executed after these two processes, you should include a |\clearpage| at the appropriate point in \m{code}. - + Repeated use of these commands is permitted: the code in the arguments is stored (and later executed) in the order of their declarations. - + \begin{decl}[1994/12/01] |\AtBeginDvi| \arg{specials} \end{decl} @@ -1130,21 +1130,21 @@ document. This should not be used for anything that will add any typeset material to the |.dvi| file. - + Repeated use of this command is permitted. - + \subsection{Option processing} \label{Sec:commands.options} - + \begin{decl} |\ProcessOptions| \end{decl} This command executes the \m{code} for each selected option. - + We shall first describe how |\ProcessOptions| works in a package file, and then how this differs in a class file. - + To understand in detail what |\ProcessOptions| does in a package file, you have to know the difference between \emph{local} and \emph{global} options. @@ -1226,7 +1226,7 @@ Note the following: were specified), whilst the |twocolumn| option does not: this is because |twocolumn| is a global option. \end{itemize} - + In a class file, |\ProcessOptions| works in the same way, except that: \emph{all} options are local; and the default value for |\DeclareOption*| is |\OptionNotUsed| rather than an error. @@ -1244,7 +1244,7 @@ error messages being issued. This is like |\ProcessOptions| but it executes the options in the order specified in the calling commands, rather than in the order of declaration in the class or package. For a package this means that the -global options are processed first. +global options are processed first. The |\@options| command from \LaTeX~2.09 has been made equivalent to this in order to ease the task of updating old document styles to @@ -1254,8 +1254,8 @@ this in order to ease the task of updating old document styles to |\ExecuteOptions| \arg{options-list} \end{decl} -For each option in the \m{options-list}, in order, -this command simply executes the command +For each option in the \m{options-list}, in order, +this command simply executes the command |\ds@<option>| (if this command is not defined, then that option is silently ignored). @@ -1269,19 +1269,19 @@ in two columns. Then it could specify: \subsection{Safe file commands} - + These commands deal with file input; they ensure that the non-existence of a requested file can be handled in a user-friendly way. - + \begin{decl} |\IfFileExists| \arg{file-name} \arg{true} \arg{false} \end{decl} If the file exists then the code specified in \m{true} is executed. - + If the file does not exist then the code specified in \m{false} is executed. - + This command does \emph{not} input the file. \begin{decl} @@ -1292,15 +1292,15 @@ before the input, the code specified in \m{true} is executed. If the file does not exist then the code specified in \m{false} is executed. - + It is implemented using |\IfFileExists|. \subsection{Reporting errors, etc} - + These commands should be used by third party classes and packages to report errors, or to provide information to authors. - + \begin{decl} |\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\ |\PackageError| \arg{package-name} \arg{error-text} \arg{help-text} @@ -1308,7 +1308,7 @@ report errors, or to provide information to authors. These produce an error message. The \m{error-text} is displayed and the |?| error prompt is shown. If the user types |h|, they will be shown the \m{help-text}. - + Within the \m{error-text} and \m{help-text}: |\protect| can be used to stop a command from expanding; |\MessageBreak| causes a line-break; and |\space| prints a space. @@ -1340,7 +1340,7 @@ If the user types |h|, this will be shown: Oh dear! Something's gone wrong. Try typing <<return>> to proceed, ignoring \foo. \end{verbatim} - + \begin{decl} |\ClassWarning| \arg{class-name} \arg{warning-text}\\ |\PackageWarning| \arg{package-name} \arg{warning-text}\\ @@ -1365,11 +1365,11 @@ stop a command from expanding; |\MessageBreak| causes a line-break; and |\space| prints a space. Also, these should not end with a full stop as one is automatically added. - + \subsection{Defining commands} \label{Sec:commands.define} - + \LaTeXe{} provides some extra methods of (re)defining commands that are intended for use in class and package files. @@ -1390,7 +1390,7 @@ a robust command, even if some code within the \m{definition} is fragile. You can use this command to define new robust commands, or to redefine existing commands and make them robust. A log is put into the transcript file if a command is redefined. - + For example, if |\seq| is defined as follows: \begin{verbatim} \DeclareRobustCommand{\seq}[2][n]{% @@ -1422,7 +1422,7 @@ This takes the same arguments as |\newcommand| but, rather than define \m{cmd}, it just checks that the current definition of \m{cmd} is exactly as given by \m{definition}. An error is raised if these definitions differ. - + This command is useful for checking the state of the system before your package starts altering the definitions of commands. It allows you to check, in particular, that no other package has redefined the @@ -1442,7 +1442,7 @@ We hope that these changes will not affect many packages. \label{Sec:commands.misc} \subsection{Layout parameters} - + \begin{decl} |\paperheight|\\ |\paperwidth| @@ -1477,7 +1477,7 @@ For example: \begin{tabular}{rl} |\uppercase{aBcD\ae\AA\ss\OE}| & \uppercase{aBcD\ae\AA\ss\OE}\\ |\lowercase{aBcD\ae\AA\ss\OE}| & \lowercase{aBcD\ae\AA\ss\OE}\\ - |\MakeUppercase{aBcD\ae\AA\ss\OE}| & + |\MakeUppercase{aBcD\ae\AA\ss\OE}| & \MakeUppercase{aBcD\ae\AA\ss\OE}\\ |\MakeLowercase{aBcD\ae\AA\ss\OE}| & \MakeLowercase{aBcD\ae\AA\ss\OE} \end{tabular} @@ -1581,11 +1581,11 @@ default setting will be over-ridden. \section{Upgrading \LaTeX~2.09 classes and packages} \label{Sec:upgrade} - + This section describes the changes you may need to make when you upgrade an existing \LaTeX{} style to a package or class but we shall start in optimistic mode. - + Many existing style files will run with \LaTeXe{} without any modification to the file itself. When everything is running OK, please put a note in the newly created package or class file to record @@ -1617,7 +1617,7 @@ reasons. \begin{itemize} \item \LaTeX{} now has a robust, well-defined designer's interface for selecting fonts, which is very different from the \LaTeX~2.09 - internals. + internals. \item Your style file may have used some \LaTeX~2.09 internal commands which have changed, or which have been removed. \end{itemize} @@ -1651,13 +1651,13 @@ condition, as follows: \subsection{Font commands} - + Some font and size commands are now defined by the document class rather than by the \LaTeX{} kernel. If you are upgrading a \LaTeX~2.09 document style to a class that does not load one of the standard classes, then you will probably need to add definitions for these commands. - + \begin{decl} |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc| \end{decl} @@ -1676,7 +1676,7 @@ One possible definition is: This would make the font commands orthogonal; for example |{\bf\it text}| would produce bold italic, thus: \textbf{\textit{text}}. It will also make them produce an error if used in math mode. - + Another possible definition is: \begin{verbatim} \DeclareOldFontCommand{\rm}{\rmfamily}{\mathrm} @@ -1696,7 +1696,7 @@ follow the standard classes and define: \DeclareOldFontCommand{\sc}{\normalfont\scshape}{\mathsc} \end{verbatim} This means, for example, that |{\bf\it text}| will produce medium -weight (rather than bold) italic, thus: \textit{text}. +weight (rather than bold) italic, thus: \textit{text}. \begin{decl} |\normalsize| \\ @@ -1728,11 +1728,11 @@ This means you should use |\renewcommand| for |\normalsize| and \subsection{Obsolete commands} - + Some packages will not work with \LaTeXe{}, normally because they relied on an internal \LaTeX{} command which was never supported and has now changed, or been removed. - + In many cases there will now be a robust, high-level means of achieving what previously required low-level commands. Please consult Section~\ref{Sec:commands} to see if you can now use the \LaTeXe{} @@ -1750,7 +1750,7 @@ check any that you have used or changed. We shall, however, list some of the more important commands which are no longer supported. - + \begin{decl} |\tenrm| |\elvrm| |\twlrm| \dots\\ |\tenbf| |\elvbf| |\twlbf| \dots\\ @@ -1769,7 +1769,7 @@ For example, the command |\twlsf| should be replaced by: Another possibility is to use the |rawfonts| package, described in \emph{\usrguide}. -Also, remember that many of the fonts preloaded by \LaTeX~2.09 +Also, remember that many of the fonts preloaded by \LaTeX~2.09 are no longer preloaded. \begin{decl} @@ -1799,7 +1799,7 @@ These commands have now been reimplemented using If your package redefined one of the |\p|-commands then you must remove the redefinition and use |\DeclareRobustCommand| to redefine the non-|\p| command. - + \begin{decl} |\footheight|\\ |\@maxsep|\\ @@ -1808,20 +1808,20 @@ non-|\p| command. These parameters are not used by \LaTeXe{} so they have been removed, except in \LaTeX~2.09 compatibility mode. Classes should no longer set them. - + \begin{thebibliography}{1} - + \bibitem{A-W:DEK91} Donald~E. Knuth. \newblock {\em The \TeX book}. \newblock Addison-Wesley, Reading, Massachusetts, 1986. \newblock Revised to cover \TeX3, 1991. - + \bibitem{A-W:LLa94} Leslie Lamport. \newblock {\em {\LaTeX:} A Document Preparation System}. \newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. - + \bibitem{A-W:MG2004} Frank Mittelbach and Michel Goossens. \newblock {\em The {\LaTeX} Companion second edition}. @@ -1856,7 +1856,7 @@ Section references below are to \emph{\clsguide}. If your file sets up new fonts, font-changing commands or symbols, you should also read \emph{\fntguide}. - + \item It did not work? There are three possibilities here: \begin{itemize} \item error messages are produced whilst reading your file; @@ -1871,4 +1871,3 @@ Section references below are to \emph{\clsguide}. \end{enumerate} \end{document} - |