写文档有什么建议?

我得从比较专业的角度指出 LaTeX 的一个重大问题:

如果 LaTeX 更新版本(到 3e)了,旧的文档编译不过了怎么办?

因为 LaTeX 从 2 更新到 2e 就发生了这种事,Common Lisp The Language 的公开 PDF 有一处排版问题,我一直想修复。

但虽然 CLtL 的 LaTeX 代码是公开的,因为用的是旧的 LaTeX 2,早就没法编译了。

重构?总共 6 万行的文件,里面还尽是这样的自定义宏。

\begin{lisp}
;;; Create a one-dimensional array of five elements. \\*
(make-array 5) \\
 \\
;;; Create a two-dimensional array, 3 by 4, with four-bit elements. \\*
(make-array '(3 4) \cd{:element-type} '(mod 16)) \\
 \\
;;; Create an array of single-floats.\\*
(make-array 5 \cd{:element-type} 'single-float)) \\
\\
;;; Making a shared array. \\*
(setq a (make-array '(4 3))) \\
(setq b (make-array 8 :displaced-to a \\*
~~~~~~~~~~~~~~~~~~~~~~:displaced-index-offset 2)) \\
;;; Now it is the case that: \\*
~~~~~~~~(aref b 0) \EQ\ (aref a 0 2) \\*
~~~~~~~~(aref b 1) \EQ\ (aref a 1 0) \\*
~~~~~~~~(aref b 2) \EQ\ (aref a 1 1) \\*
~~~~~~~~(aref b 3) \EQ\ (aref a 1 2) \\*
~~~~~~~~(aref b 4) \EQ\ (aref a 2 0) \\*
~~~~~~~~(aref b 5) \EQ\ (aref a 2 1) \\*
~~~~~~~~(aref b 6) \EQ\ (aref a 2 2) \\*
~~~~~~~~(aref b 7) \EQ\ (aref a 3 0)
\end{lisp}

用 plainTeX 有这问题吗?不好意思,DEK 早早就冻结了 TeX,为的就是換了不同的电脑,不同的操作系统,还能编译出一样的结果。

把要长久留存的文档用一个没有固定标准的格式,绝对不是什么明智的选择。

如果当年用 DocBook 写的,想要換到最新版本就是跑一下 XSLT 的事。