当我处理需要特殊布局的文档时,我最初往往会积累很长的序言。在某个时候,如果我需要定期重复使用类似的布局,我会决定我真的应该整理一下并创建一个自定义类或包。如果是一个类,它通常是寄生类,即它会加载另一个类,这样我就不必担心错过重要的东西。
在某些情况下,我现在处于这样一种情况:我有一些自定义命令,它们的操作方式与标准命令没有什么不同。例如,我可能会使用类似这样的命令,而不是使用\section
类article
:
% Note that this is definitely not an MWE!
% My question is specially about code which makes little sense outside
% a very specific context. If the code did make sense on its own, I would
% not need to ask the question.
% BEGIN defn \ns
\NewDocumentCommand\ns{sO{}}{%
\gdef\thiss{#2}%
\setcounter{ssn}{0}%
\IfBooleanTF #1
{%
\addcontentsline{toc}{section}{#2}%
#2}%
{%
\stepcounter{sn}%
\addcontentsline{toc}{section}{\S\thesn\hspace*{1.5em}#2}%
\S\thesn\hspace*{1.5em}#2}%
}
% END defn \ns
% BEGIN defn \nst
\NewDocumentCommand\nst{sd()O{}md<>O{}O{}sd<>}{% \nst*(frame width)[graphics options]{image file}<caption>{section title}{subsection or other subheading}<additional source/copyright/attribution>
\clearpage
\pagestyle{empty}\cleardoublepage
\begin{titlingpage}
\AddThispageHook{\usebox{\mysecsglas}}%\input{../../secs/secs-glas}%
\noindent\sffamily\bfseries\color{bcol1}%
\begin{center}
\vspace*{\fill}
\IfNoValueTF{#2}%
{%
\includegraphics[#3]{#4}}%
{%
\efbox[#2]{\includegraphics[#3]{#4}}}%
\IfNoValueTF{#5}{\relax}{\medskip\\\normalfont #5}%
\bigskip
\vspace*{\fill}\vspace*{\fill}\\
\end{center}
\hspace*{\fill}%
\IfBooleanTF{#1}{%
\nsfont\ns*[#6]}{%
\nsfont\ns[#6]}%
\vskip -.5em
\stepcounter{ssn}%
\hspace*{\fill}{\nssfont #7}
\end{titlingpage}
\clearpage\thispagestyle{empty}
\setcounter{ssn}{0}
\vspace*{\fill}\vspace*{\fill}\begin{center}
Sealing wax\IfBooleanTF{#8}{, cabbages}{} and kings courtesy Lewis Carroll.\smallskip\\
\IfNoValueTF{#9}{\relax}{#9\smallskip\\}
Typeset using pdf\LaTeX, {B{\sc \uppercasesc i\kern-.025em \uppercasesc b}\kern-.08em\LaTeX} and Biber in Latin Modern and URW ChanceryL.
\end{center}
\cleardoublepage}
% END defn \nst
一方面,这些命令在我的文档中用作 的替代品\section
。(可能更接近使用book
或report
并说它被用作\chapter
。但实际上,我使用的是article
因为它就是这样开始的。)它们设置标题,将内容添加到目录中等等。
另一方面,这些类型的命令也与标准命令截然不同,因为它们可以执行大量其他操作,并且专为更具体的用途而设计。
我想知道最佳实践是否涉及重新定义标准命令并使用\chapter
或\section
或其他。或者最佳实践是否涉及保留这些命令。
请注意,我知道这两种方法都可以。另外,这种方法太过量身定制,其他人可能根本不会感兴趣,所以我不会问是否应该将任何版本的这种方法强加给其他人。(这样做显然是愚蠢的。)我更多地考虑的是从维护和更新代码以供将来自己使用的角度考虑什么是最好的。
答案1
由于您似乎很关心\section
,我将举几个例子。
这memoir
课程允许二的可选参数\section
,一个用于目录条目,另一个用于标题。在 KOMA 脚本类中\section
只有一个可选参数,该参数应包含一个对列表key=value
(为了向后兼容,它也允许使用标准类中的短标题版本)。
对于两者来说,标准调用都是\section{...}
。
Lamport 的梦想是设计一个系统,这样只需更改文档类就可以将文档排版为多种格式。可惜,这被证明是不可能的。例如,AMS 类想出于很好的理由,在 之前键入了 abstract \maketitle
。在标准类中,这会导致灾难。其他类需要特定命令来实现其各种目的。
相同的 AMS 类具有非常有趣的功能\only
(虽然没有很好的记录),用于决定章节标题的哪些部分要放入目录中以及哪些部分要放入标题中,从而以不同于的方式解决问题memoir
。
每次使用附加功能时,标准类将不再能够处理该文档。因此,通常不可能将文档从 转移memoir
到book
,因此 语法中的微小变化\section
是问题中最小的一个。
在我看来,类或包的编写者应该关注用户。如果的语法\section
与“标准”语法没有太大区别,请调用该命令\section
,不要犹豫。另一方面,如果你想要更改\section
为 have,即使出于某些好的理由,二强制参数,不要这样做:用户几乎肯定会忘记一个。调用命令\sectionx
或任何你认为足够独特的东西,以便用户知道他们应该做一些与平常不同的事情。
另一个例子。假设你的出版商希望引用用斜体:这是一个重新定义环境quotation
来改变字体的情况是很好。提供不同名称的环境会因为另一个原因而使用户感到困惑:他们将继续使用quotation
,而文字编辑将经历一些噩梦。
请注意,在用户中你包括,特别是当该类供您个人使用时。当您需要在类是您自己的类时使用两个强制参数,而在将文档提交给其他人时使用\section
普通参数时,您会遇到双重人格问题。\section
最后一个例子。在memoir
当你说 时\listoffigures
,列表将自动包含在目录中,你可以使用\listoffigures*
来避免包含。AMS 类做同样的事情,但没有办法避免包含。好的:这是标准类应该一开始就被赋予了,但不幸的是这个想法没有被考虑。问题是memoir
也会\tableofcontents
将自己添加到目录中,并且必须记住输入\tableofcontents*
。在我看来,这是一个非常严重的错误:这就像将库存添加到库存中。在阅读目录时,没有人希望被告知目录从哪一页开始:这就像说明“要按下按钮 A,请开始按下按钮 A”。
永远记住你的课程或课程包的用户:不要强迫他们做奇怪的、令人费解的练习。