☰

如何编写可读的命令

tag-icon • tag-icon macros
如何编写可读的命令

考虑定义环境的常见 LaTeX 方式，例如：

\begin{summary}
In olden times when wishing still helped one, there lived a
king whose daughters were all beautiful, but the youngest was 
so beautiful that the sun...
\end{summary}

与此相比，Knuth 的方式和 ConTeXt 倾向于省略括号。

\summary
In olden times when wishing still helped one, there lived a
king whose daughters were all beautiful, but the youngest was 
so beautiful that the sun...
\endsummary

后者在编辑器中更易读，也让作者的工作更轻松。我个人更喜欢后者，尽管有人可能会争论 LaTeX 使用参数和命令的方式的优点，但我建议这些样式命令不属于文本，而应该放在setsummarystyle可前导部分，即尝试让文本只包含结构命令（无样式）。

您有自己的策略来让文本尽可能干净、易读吗？对替代方案和问题区域有什么建议吗？

如果您想实验，请参见 MWE 示例。

\documentclass{book}
\usepackage[paperwidth=4.75in,paperheight=7.25in,
            textwidth=4.2in,textheight=6.5in,
            headsep=0.1in, footskip=0.15in,
            marginratio=1:1]{geometry}
\usepackage{lipsum}
\long\def\summary#1\endsummary{{%
 \baselineskip11pt
 \leftskip3em\rightskip3em
 \noindent
 {\bf Summary}.\quad#1
 \bigskip
\par}}%

\begin{document}
\chapter*{Introduction}

\summary
 In olden times when wishing still helped one, there lived a
king whose daughters were all beautiful, but the youngest was 
so beautiful that the sun itself, which has seen so much, was
astonished whenever it shone in her face. Close by the king's
castle lay a great dark forest, and under an old lime-tree in the
forest was a well, and when the day was very warm, the
king's child went out into the forest and sat down by the side
of the cool fountain, and \ldots
\endsummary

\lipsum[1]
\end{document}

答案1

我更喜欢 LaTeX 标记环境的方式，因为它在环境和命令之间提供了清晰的区分：当出现问题时，我总是可以搜索\begin或\end。ConTeXt 的方式是不是我认为更具可读性。

一般来说，我从不缩进环境的内容：我发现这很分散注意力，而且浪费屏幕上的空间。一个好的语法高亮器足以找到视觉线索。但我总是把\begin和\end命令放在文档的新行上，并在分段命令之前使用至少两个空行。而且我的编辑器突出显示\begin和\end的方式与普通命令不同。这不能用\summary-\endsummary对来完成，除非你教编辑器所有这样的对。

我总是尝试正确缩进宏定义，正如 Didier Verna 所建议的那样，尤其是\if...涉及到宏定义时。当然

\newcommand{\macro}{\@ifstar{\@macros}{\@macro}}

得不到“适当”的治疗

\newcommand{\macro}{%
  \@ifstar
    {\@smacro}
    {\@macro}%
 }

但更复杂的事情会。

顺便说一句，我还发现这\def\summary#1\endsummary{...}不是定义环境的好方法：

\def\summary{%
\baselineskip11pt
\leftskip3em\rightskip3em
\noindent
\textbf{Summary.}\quad}
\def\endsummary{\bigskip\par}

会更好，因为它不必读取所有参数只是为了排版而重新读取它，但我知道这只是一个例子。

如果你喜欢这种方式，那么

\newcommand{\newTeXenvironment}[1]{%
  \expandafter\def\csname #1\endcsname{\begin{#1+}}%
  \expandafter\def\csname stop#1\endcsname{\end{#1+}}%
  \newenvironment{#1+}}

\newTeXenvironment{summary}
  {\baselineskip16pt
    \leftskip3em\rightskip3em
    \noindent
    \textbf{Summary.}\quad}
   {\bigskip\par}

可以让你说

\summary
<text of the summary>
\stopsummary

纯粹的 ConTeXt 风格。嗯，有点。

答案2

\summary...\endsummary我不同意比更可读或更“干净”的说法\begin{summary}...\end{summary}。问题是它没有明确指出意图of \summary：它可能表示“开始摘要”，就像它那样，也可能表示“发出之前保存的摘要”，就像\tableofcontents。即使它表示“开始摘要”，也可能表示摘要一直持续到下一个换行符，就像 Knuth 的\proclaim，它读到\par(不是显然是基于命令字的终止实体！）。基本上，普通宏可以创建功能在没有沟通的情况下外貌对用户来说。

一个更微妙的优势\begin...\end是它们执行机制. 有了\summary...\endsummary，人们就可以随意改变定义，比如说，\summary现在做只读到行尾，\endsummary意思是\relax。由于它看起来不像环境，因此没有什么可以阻止作者违反合同使其表现得像环境。但是\begin...\end，环境行为是由 LaTeX 本身强加的：即使你对它\summary本身做了一些荒谬的事情（由 内部调用\begin{summary}），你仍然会得到分组，这可以防止你的奇思妙想破坏文档的其余部分。宏（我认为）已设置，因此 LaTeX 会检查环境的结束，而这并不是你手动\@currenv定义对时可以保证的事情。\summary...\endsummary

最后一个好处，虽然在实践中并没有真正实现，那就是理论上，拥有命名环境而不是宏对意味着您可以选择提供统一造型到您的环境中。如果\begin和\end有钩子，您可以使用它们将通用代码插入到每一个环境。例如，您可以使每个环境的内容缩进，或对其单词进行计数，等等。尝试使用\summary!

为了更全面地回答你提出的粗体问题，我确实有一个策略来保持我在 TeX 中的“代码”干净：不要用 TeX 编程！它现在作为一种编程语言已经过时了：大多数控制流逻辑可以通过 TeX 来实现，pgfkeys而不是通过破坏 TeX 疯狂的扩展语义。（见我最喜欢的答案。） 这意味着：

  • 由于密钥树的存在，密钥pgfkeys不会发生名称冲突：您为密钥创建目录，其他人不会使用相同的命名空间。斜线比 @ 更易读，不需要 catcode 破解，但仍然很安全。

  • 当定义带有选项的宏时，使用pgfkeys键值语义，而不是让宏采用四个参数，其中第二个和第四个参数是可选的，含义相似，但不能互换（咳嗽 \newtheorem）。

  • 在处理你的选择时，pgfkeys使用全部决策。它不只是设置布尔值；它还执行任意命令，根据各种默认处理程序跳转到任何其他键，扩展（没有 TeX 的复杂性）到任何辅助键列表，以及它的键他们自己可以表现为带有一个或两个参数的 TeX 宏，这意味着唯一需要“退出”处理的时间是将控制权返回给输入文件本身时。

  • 确实，不使用 就无法进行模式匹配\def。但是，在宏中使用模式匹配是邪恶的，而 LaTeX 不允许这样做的原因\newcommand（在我看来）是你不需要这样做。模式匹配意味着你必须将文档编写成某种样子，即使它看起来不像你在给出命令。它的一种可能用途是编写解析器，如果你喜欢创建一种描述性语言，比如 TikZ 的一些命令（\path (0,1) node (name) to (3,3) circle;例如）。据我所知，TikZ 不会这样做，但你可以用来pgfkeys处理所有关键字，并拥有一个简单的“抓取器”宏集合，即\def\getpoint(#1,#2){...}，，\def\getword#1 {...}当然\ignorespaces是一个有用的原语。这减少了定义语法时必须重新发明轮子的情况：只需让每个关键字具有某种行为作为pgfkeys强制其在您的语言中的行为的键。

不知怎的，我觉得这不是你要问的。不过，我认为它肯定回答了“如何编写可读的命令”。使用pgfkeys。

答案3

Didier Verna 在演讲中提到了良好做法迈向 LaTeX 编码标准在 2011 年 TUG 上：

  • 使用缩进以提高可读性：缩进环境内容，并将结束命令缩进到与开始命令相同的级别（即使在极少数情况下，相应的结束命令出现在第二个宏中）

  • 使用@惯例，但要明智：它可以在内部命令名称中使用，但不应过度使用。例如，始终以 开始内部样式宏\@是可以的，但\intr@ducti@n这样做不好

  • 选择不会引起名称冲突的名称：

    • 您可以一致地使用前缀，例如样式文件名
    • 如果 LaTeX 添加前缀，例如\c@<counter>，请考虑使用后缀
    • 避免使用可能已被类或包使用的通用名称，因此自然名称有时并不是最好的选择，即使可读。

使用 LaTeX 时，我会使用\newcommand或\newenvironment代替 来\def注意到何时发生冲突 - 或者在定义命令名称之前检查命令名称是否存在。

答案4

如果要我挑出一件最近提高了我的 latex 文档可读性的事情，那就是使用 unicode。请考虑以下句子（抱歉，德语）

Der Strom $I$ und der magnetische Fluss $Φ$ können über die Induktivität $L=Φ/I$ verknüpft werden.

即使在乳胶源中它也是清晰的。

这件事始于我对自动生成的 .bib 文件的“后处理”感到不满。我曾发表过以下文章（Rutherford，1911），其中

The Scattering of α and β Particles by Matter and the Structure of the Atom

在标题字段中。现在，我可以直接使用生成的文件，而不需要修改过滤器。

所有这些小事都归结为一个整体。

相关内容