LaTeX2e类和包的设计（四）

注意：在tex的编写中，如果用到带@的命令，必须把它包含在/makeatletter和/makeatother之间。如果是在宏包中使用，则无需此两个命令。

一、class and package的结构：
1) Identification:
  1.1)Package files do this as follows:
 /NeedsTeXFormat{LaTeX2e}
 /ProvidesPackage{<package>}[<date><other information>]
For example:
 /NeedsTeXFormat{LaTeX2e}
 /ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package]
  1.2)Class files do this as follows:
 /NeedsTeXFormat{LaTeX2e}
 /ProvidesClass{<class-name>}[<date><other information>]
For example:
 /NeedsTeXFormat{LaTeX2e}
 /ProvidesClass{article}[1994/06/01 Standard LaTeX class]
<date>的格式应该是：年/月/日
2) Using classes and packages:
  2.1)A LaTeX package or class can load a package as follows:
 /RequirePackage[<options>]{<package>}[<date>]
For example:
 /RequirePackage{ifthen}[1994/06/01]
  2.2)A LaTeX class can load one other class as follows:
 /LoadClass [<options>]{<class-name>}[<date>]
For example:
 /LoadClass [twocolumn]{article}
  2.3)Simply load a class or package file:
 /LoadClassWithOptions{<class-name>}[<date>]
 /RequirePackageWithOptions{<package>}[<date>]
For example:
 /LoadClassWithOptions{article}
 /RequirePackageWithOptions{graphics}[1995/12/01]
3) Declaring options:
 /DeclareOption{<option>}{<code>}
For example:
 /DeclareOption{dvips}{/input{dvips.def}}
For example another:
 /DeclareOption{a4paper}{%
   /setlength{/paperheight}{297mm}%
   /senlength{/paperwidth}{210mm}%
   }
  3.1)pass options on to another package or class,using the command:
 /PassOptionsToPackage
 or /PassOptionsToClass
For example, to pass every unknown option on to the article class:
 /DeclareOption*{%
   /PassOptionsToClass{/CurrentOption}{article}%
   }
To process the options with which the file was called, you should use:
 /ProcessOptions/relax
For example, if the jane package file contains:
 /DeclareOption{foo}{/typeout{Saw foo.}}
 /DeclareOption{baz}{/typeout{Saw baz.}}
 /DeclareOption*{/typeout{What's /CurrentOption?}}
 /ProcessOptions/relax
4) A minimal class file
  There are four things that every class file must contain: these are a definition of /normailsize, values fro /textwidth and /textheight and a specification for page-numbering.
  So a minimal document class file looks like this:
 /NeedsTeXFormat{LaTeX2e}
 /ProvidesClass{minimal}[1995/10/30 Standard LaTeX minimal class]
 /renewcommand{/normalsize}{/fontsize{10pt}{12pt}/selectfont}
 /setlength{/textwidth}{6.5in}
 /setlength{/textheight}{8in}
 /pagenumbering{arabic}
 %needed even though this class will not show page numbers
5) Example: a local letter class
  The class begins by announcing itself as neplet.cls.
 /NeedsTeXFormat{LaTeX2e}
 /ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class]
 %passes any options on to the letter class. a4paper option.
 /DeclareOption*{/PassOptionsToClass{/CurrentOption}{letter}}
 /ProcessOptions/relax
 /LoadClass[a4paper]{letter}
 %redefine the firstpage page style.
 /renewcommand{/ps@firstpage}{%
   /renewcommand{/@oddhead}{<letterhead goes here>}%
   /renewcommand{/@oddfoot}{<letterfoot goes here>}%
   }
6) 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.
 /NeedsTeXFormat{LaTeX2e}
 /ProvidesClass{smplnews}[1995/04/01 The Simple News newsletter class]
 /newcommand{/headlinecolor}{/normalcolor}
 % pass most specified options on to the article class
 /DeclareOption{onecolumn}{/OptionNotUsed}
 /DeclareOption{green}{/renewcommand}{/headlinecolor}{/color{green}}}
 /DeclareOption*{/PassOptionsToClass{/CurrentOption}{article}}
 /ProcessOptions/relax
 %load the class article with the option twocolumn
 /LoadClass[twocolumn]{article}
 %load the color package
 /RequirePackage{color}
 %redefine /maketitle to produce the title
 %in 72pt Helvetica bold oblique
 /renewcommand{/maketitle}{%
   /twocolumn[%
     /fontsize{72}{80}/fontfamily{phv}/fontseries{b}%
     /fontshape{sl}/selectfont/headlinecolor
     /@title
     ]%
   }
 %redefine /section and switches off section numbering.
 /renewcommand{/section}{%
   /@startsection
     {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}%
     {1ex plus .2ex}{/large/sffamily/slshape/headlinecolor}%
   }
 /setcounter{secnumdepth}{0}
 %set the three essential things
 /renewcommand{/normalsize}{/fontsize{9}{10}/selectfont}
 /setlength{/textwidth}{17.5cm}
 /setlength{/textheight}{25cm}
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.

二、Commands for class and package writers
1) Identification
/NeedsTeXFormat{<format-name>}[<release-date>]
/ProvidesClass{<class-name>}[<release-info>]
/ProvidesPackage{<package-name>}[<release-info>]

<release-info> information is displayed by /listfiles and should therefore not be too long.
example:
/ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class]
/ProvidesPackage{ifthen}[194/06/01 v1.0 Standard LaTeX package]

/ProvidesFile{<file-name>}[<release-info>]
It is used for declaring any files other than main class and package files.
Example:
/ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file]
2) Loading files
/RequirePackage[<options-list>]{<package-name>}[<release-info>]
/RequirePackageWithOptions{<package-name>}[release-info>]
This group of commands can be used to create your own document class or package by building on existing classes or packages.
Example:
/RequirePackage{ifthen}[1994/06/01]
/RequirePackageWithOptions{graphics}[1995/12/01]

/LoadClass[<options-list>]{<class-name>}[<release-info>]
/LoadClassWithOptions{<class-name>}[<release-info>]

Examples:
/LoadClass{article}[1994/06/01]
/LoadClassWithOptions{article}[1995/12/01]
3) Option declaration
/DeclareOption{<option-name>}{<code>}
This makes <option-name> a 'delcared option' of the class or package in which it is put.
The <code> argument contains the code to be executed if that option is specified for the class or package; it can contain any valid LaTeX2e construct.
Example:
/DeclareOption{twoside}{/@twosidetrue}

/DeclareOption*{<code>}
This declares the <code> to be executed for every option which is specified for, but otherwise not explicitly declared by, the class or package; this code is called the 'default option code' and it can contain any valid LaTeX2e construct.
4) Commands within option code
/CurrentOption
This expands to the name of the current option.
/OptionNotUsed
This causes the current option to be added to the list of 'unused options'.
5) Moving options around
/PassOptionsToPackage{<options-list>}{<package-name>}
/PassOptionsToClass{<options-list>}{<class-name>}
The command /PassOptionsToPackage passes the option names in <options-list> to package <package-name>. This means it adds the <option-list> to the list of options used by any future /RequirePackage or /usepackage command for package <package-name>.
Example:
/PassOptionsToPackage{foo,bar}{fred}
/RequirePackage[baz]{fred}
is the same as:
/RequirePackage[foo,bar,baz]{fred}
For example:
/LoadClassWithOptions{article}
This should be compared with the slightly different construction.
/DeclareOption*{/PassOptionsToClass{/CurrentOption}{article}}
/ProcessOptions/relax
/LoadClass{article}
If, however, the class declares options of its own then the two constructions are different.
/DeclareOption{landscape}{/@landscapetrue}
/ProcessOptions/relax
/LoadClassWithOptions{article}
with:
/DeclareOption{landscape}{/@landscapetrue}
/DeclareOption*{/PassOptionsToClass{/CurrentOption}{article}}
/ProcessOptions/relax
/LoadClass{article}

6) Delaying code
/AtEndOfClass{<code>}
/AtEndOfPackage{<code>}
These commands declare <code> that is saved away internally and then executed after processing the whole of teh current class or package file.
/AtBeginDocument{<code>}
/AtEndDocument{<code>}
You should include a /clearpage at the appropriate point in <code>.
Permit to repeat use of these commands.
/AtBeginDvi{<specials>}

7) Option processing
/ProcessOptions
This command executes the <code> for each selected option.
Local options:
/PassOptionsToPackage{<options>}
/usepackage[<options>]
/RequirePackage[<options>]
Global options:
are any other options that are specified by the author in the <options> argument of /documentclass[<options>]
For example, suppose that a document begins:
/documentclass[german,twocolumn]{article}
/usepackage{gerhardt}
whilst package gerhardt calls package fred with:
/PassOptionsToPackage{german,dvips,a4paper}{fred}
/RequirePackage[errorshow]{fred}
then:
fred's local options are german, dvips, a4paper and errowshow;
fred's global options is twocolumn.
example:
/DeclareOption{dvips}{/typeout{DVIPS}}
/DeclareOption{german}{/typeout{GERMAN}}
/DeclareOption{french}{/typeout{FRENCH}}
/DeclareOption*{/PackageWarning{fred}{Unknown '/CurrentOption'}}
/ProcessOptions/relax

/ProcessOptions*
/@options
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 golbal options are processed first.
The /@options command from LaTeX2.09 has been made equivalent to this in order to ease the task of updating old document styles to LaTeX2e class files.

/ExecuteOptions{<options-list>}
execute the command /ds@<option>, It can be used to provide a 'default option list' just before /ProcessOptions.
example:
/ExecuteOptions{11pt,twoside,twocolumn}

8) 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.
/IfFileExists{<file-name>}{<true>}{<false>}

/InputIfFileExists{<file-name>}{<true>}{<false>}

9) Reporting errors, etc.
/ClassError{<class-name>}{<error-text>}{<help-text>}
/PackageError{<package-name>}{<error-text>}{<help-text>}
For example:
/newcommand{/foo}{F00}
/PackageError{ethel}{%
  Your hovercraft is full of eels, /MessageBreak
  and /protect/foo/space is /foo
}{%
  Oh dear! Something's gone wrong. /MessageBreak
  /space /space Try typing /space <return>
  /space to proceed, ignoring /protect/foo.
}

/ClassWarning{<class-name>}{<warning-text>}
/PackageWarning{<package-name>}{<warning-text>}
/ClassWarningNoLine{<class-name>}{<warning-text>}
/PackageWarningNoLine{<package-name>}{<warning-text>}
/classInfo{<class-name>}{<info-text>}
/PackageInfo{<package-name>}{<info-text>}
Within the <warning-text> and <info-text>: /protect can be used to 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 on eis automatically added.

10) Defining commands
/DeclareRobustCommand{<cmd>}[<num>][<default>]{<definition>}
/DeclareRobustCommand*{<cmd>}[<num>][<default>]{<definition>}
This command takes the same arguments as /newcommand but it declares a robust command, even if some code within the <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:
/DeclareRobustCommand{/seq}[2][n]{%
 /ifmmode
   #1_{1}/ldots#1_{#2}%
 /else
   /PackageWarning{fred}{You can't use /protect/seq/space in text}%
 /fi
}
for example:
/section{Stuff about sequences $/seq{x}$}

/CheckCommand{<cmd>}[<num>][<default>]{<definition>}
/CheckCommand*{<cmd>}[<num>][<default>]{<definition>}

11) Moving arguments
The setting of protect whilst processing moving arguments has been reimplemented, as has the method of writing information from the .aux file to other files such as the .toc file. Details can be found in the file ltdefns.dtx.

三、Miscellaneous commands
1) Layout parameters
/paperheight
/paperwidth
2) Case changing
/MakeUppercase{<text>}
/MakeLowercase{<text>}
3) The 'openany' option in the 'book' class
The openany option allows chapter and similar openings to occur on left hand pages. Previously this option affected only /chapter and /backmatter. It now also affects /part, /frontmatter and /mainmatter.
4) Better user-defined math display environments
/ignorespacesafterend
Suppose that you want to define an environment for displaying text that is numbered as an equation. A straightforward way to do this is as follows:
/newenvironment{texteqn}
 {/begin{equation}
   /begin{minipage}{0.9/linewidth}}
 {/end{minipage}
   /end{equation}}
For example:
/newenvironment{texteqn}
 {/begin{equation}
  /begin{minipage}{0.9/linewidth}}
 {/end{minipage}
  /end{equation}
  /ignorespacesafterend}

5) Normalising spacing
/normailsfcodes
This command should be used to restore the normal settings of the parameters that affect spacing between words, sentences, etc.

四、Upgrading LaTeX2.09 classes and packages
1) Try it first
test your style in 'compatibility mode'.
2) Troubleshooting
3) Accommodating compatibility mode
accommodate old edition
/if@compatibility
 <code emulating LaTeX2.09 behavior>
/else
 <code suitable for LaTeX2e>
/fi

4) Font commands
Some font and size commands are now defined by the document class.
/newcommand{/rm}{/rmfamily}
/newcommand{/sc}{/scshape}
Another possible definition is:
/DeclareOldFontCommand{/rm}{/rmfamily}{/mathrm}
/DeclareOldFontCommand{/sc}{/scshape}{/mathsc}

/normalsize
/@normalsize

5)Obsolete commands
Some packages will not work with LaTeX2e, normally because they relied on an internal LaTeX command which was never supported and has now changed, or been removed.