sty和cls文档编写指南

前言

本文是对LATEX 2ε for class and package writers的翻译和概括。

可以参考以下链接得到原文档
https://www.jianshu.com/p/12b4a4b3afce?from=singlemessage

也可以参考
https://zhuanlan.zhihu.com/p/19705200

文档编写的介绍从第三部分开始，文档的命令从第四部分开始，参数的传递从第五部分开始。

1.sty和cls文档简介

a.可以使用docstrip生成sty和cls文件

b.如果命令可以在其他tex文件中使用，应该写在sty文件中。
如果命令（排版格式）只适合某一文档，应该写在cls文件中。

2.编写sty和cls

a.tex命令包含三种格式

tex作者使用的，即一般tex文件包含的命令，
sty和cls作者使用的，如\RequirePackge，
tex内部命令,如\@temcnta。
您不可以在tex文件中使用后两种命令。

b.鲁棒性

为了增强文档鲁棒性，使用较为严谨的命令。
文件加载命令：

\LoadClass{cls file name}  %加载cls文件
\LoadClassWithOptions
\RequirePackage{sty file name}  %加载所需要的包
\RequirePackageWithOptions
\input{file name}

不建议使用最后一种，会导致多次加载。

命令定义

\newcommand
\renewcommand
\providecommand
\CheckCommand
\def

上面四个差别不大，不建议使用第四种，会导致意外定义新命令

环境定义

\newenvironment
\renewenvironment
 \def\foo{...}    \def\endfoo{...}

上面两个均可，不建议使用第三种

c.便携性

文档名尽量不要超过8字符，不包括3个字符的扩展名，
不能和已有的latex标准包重名，
尽量加上首字母前缀，比如XXX thesis.cls

d.重定义document

使用\AtBeginDocument和\AtEndDocument重定义docunment

3.cls和sty结构

一个完整的cls或者sty文件通常包含以下的结构。

a.文档介绍

\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{包的名称}[时间及其他信息]

\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{类名称}[时间及其他信息]

时间使用YYYY/MM/DD格式

b.引用cls或者sty文件

\RequirePackage[options]{package}[date]
\LoadClass[hoptionsi]{hclass-namei}[hdatei]

当载入的文件中options和当前文档相同，使用以下命令：

\LoadClassWithOptions{article}
\RequirePackageWithOptions{graphics}

c.定义选项

使用如下命令定义选项

\DeclareOption{option}{code}

如果出现了选项，则会执行选项中的代码。
使用如下代码，将error变为warning

\DeclareOption*{%
\PackageWarning{fred}{Unknown option ‘\CurrentOption’}%
}

使用如下命令使定义的选项被文档调用执行

\ProcessOptions\relax

d.最小文档

文档必须包括四个内容：
\normalsize，\textwidth， \textheight，页数的规范
一个最小文档如下例：

\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

信件文档如下例：(文档名为neplet.cls)

\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class]

\DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
\ProcessOptions\relax
\LoadClass[a4paper]{letter}

\renewcommand{\ps@firstpage}{%
\renewcommand{\@oddhead}{letterhead goes here}%
\renewcommand{\@oddfoot}{letterfoot goes here}%
}

4.文档命令

\NeedsTeXFormat {format-name} [release-date]  %文档的定义
\ProvidesClass {class-name} [release-info]%表示当前文档提供了XX类的定义
\ProvidesPackage {package-name} [release-info]%表示当前文档提供了XX包的定义
\ProvidesFile {file-name} [release-info]%表示当前文档提供了XX文件的定义

\RequirePackage [options-list] {package-name} [release-info]
\RequirePackageWithOptions {package-name} [release-info]%引用包
\LoadClass [hoptions-listi] {class-name} [release-info]
\LoadClassWithOptions {class-name} [release-info]%引用类

\DeclareOption {option-name} {code}%选项定义
\DeclareOption* {code}%对于所有选项都为执行

以下命令只在定义option的code中使用

\CurrentOption%引用当前选项
\OptionNotUsed%当前选项加入未使用选项列表

\PassOptionsToPackage {options-list} {package-name}
\PassOptionsToClass {options-list} {class-name}%意味着如果调用这个包，就会执行optionlist中的选项

\AtEndOfClass{code}
\AtEndOfPackage{code}%代码将在执行完整个包之后执行

\AtBeginDocument {code}
\AtEndDocument {code}%代码将在执行\begin{document}或者\end{docpment}时执行

\AtBeginDvi {specials}
\ProcessOptions%
\ProcessOptions*
\\@options%
\ExecuteOptions {hoptions-listi}

以上只在code中使用

\IfFileExists {file-name} {true} {false}%定义文件不存在时如何操作，这个命令本身不会加载文件
\InputIfFileExists {file-name} {true} {false}%如果存在，执行True中代码，然后加载文件，否则执行faulse

\ClassError {class-name} {error-text} {help-text}
\PackageError {package-name} {error-text} {help-text}%如果在引入包中出现错误，将显示text的内容。
%\protect加在命令之前，使得其被打印而不是执行，\MessageBreak打印换行，\space打印空格。

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

\DeclareRobustCommand {cmd} [num] [default] {definition}
\DeclareRobustCommand* {cmd} [num] [default] {definition}%定义更加鲁棒的命令，和renewcommand类似。

\CheckCommand {cmd} [num] [default] {definition}
\CheckCommand* {cmd} [num] [default] {definition}%定义的同时会检查,如果不同则会产生warning

\paperheight
\paperwidth%设定页面大小

\MakeUppercase {text}
\MakeLowercase {text}%大小写转换

\ignorespacesafterend%取消空格

\normalsfcodes%恢复字间距

\if@compatibility

可能需要重新定义如下命令

\rm \sf \tt \bf \it \sl \sc
\normalsize
\@normalsize

需要重新定义如下命令

\tiny \footnotesize \small \large
\Large \LARGE \huge \Huge
\tenrm \elvrm \twlrm . . .
\tenbf \elvbf \twlbf . . .
\tensf \elvsf \twlsf . . .

可能需要替换如下命令

\vpt \vipt \viipt . . .
\prm, \pbf, \ppounds, \pLaTeX . . .

以下命令被移除

\footheight
\@maxsep
\@dblmaxsep

5.参数传递

参数传递使得tex写作是不需要重复添加相同的信息。（比如页眉上方的标题）。遗憾的是原文中并没有介绍相关的内容。以下内容均来自于下方链接。
https://blog.csdn.net/RobertChenGuangzhi/article/details/50461514

在cls文件中，使用以下命令定义参数
\newcommand{\\@ang-name}{默认值}
参数名通常为\@后跟tex文件中使用的名称
在cls文件中，使用以下命令关联cls参数和tex参数

\newcommand{\tex-cmd}[参数数目][默认值]{
  \renewcommand{\\@avg-name1}{#1}
  \renewcommand{\\@avg-name2}{#2}
  \renewcommand{\\@avg-name3}{#3}
...
}

命令名通常为\加上tex文件中引用的名称。
在cls文件中使用\@avg-name1...调用参数

在tex文件中使用如下代码获取参数：
\tex-cmd{参数1的值}{参数2的值}{参数3的值}..

总结

以上是文档的大概内容，我会更新一篇报告的cls文件。