如何格式化 Framemaker 文档中的源代码？[关闭]

Question

我必须在 Framemaker 中编写一份技术文档来解释各种编程源代码。

所以我的文档由一堆文本组成，后面是一堆源代码（Java、XML），然后是更多文本，等等。

这个问题不是关于我是否应该使用Framemaker——那是我必须使用的软件。。。

我感到困惑的是如何将源代码格式化为我的文档的一部分。有没有人为技术文档做过此操作并遇到过任何说明或提示？到目前为止，我的谷歌搜索还没有产生任何与我需要做的事情相关的内容。

Answer 1

至少，为代码示例创建一个段落样式，使用一个好的等宽字体，并且不要忘记关闭连字符。

当我以前这样做时，我会创建一个表格样式并将代码粘贴在那里，所以我上面有一个很好的标题标题，它突出了一点。唯一的问题是Frame表格单元格不会突破分页符，因此如果您的代码比页面长或者威胁要低于页面底部，则需要在表格中创建多行并且分解行中的代码。

Answer 2

摘自我几年前写的一篇论文，该论文将于下周再次在线发布。

印刷专家主要关注的是可读性，并拥有数百千年甚至数千年的工具，实践和传统，以自然语言设置文本。然而，计算机程序不是用自然语言编写的。它们是用“编程语言”写的：人工语言有自己的语法规则，自己的演讲惯例以及自己的知名度标准。因此，计算机代码是排版的特殊领域，音乐，数学和化学也是如此。这些域有自己的规则，这不是设置自然语言时使用的规则。

计算机编程本身是最近的起源，将其设置为类型的实践并没有超过45年：在过去的20年或更短的时间内，大量计算机代码仅出版。相关的印刷学纪律是不成熟的或实际上不存在的，并且该领域的从业者对印刷的期望也很低，您可以通过检查许多贸易书籍来看到。您没有理由不尝试做得更好。

1. 使用无衬线字体。在我的一本书中，我使用了相同的字体系列，文本使用 FF Scala，代码使用 FF Scala Sans。我认为它看起来很棒，但也有相反的意见：这些可能会迫使您使用等宽字体，尽管我个人认为这是非常过时的。避免使用快递，它不会与任何东西混合。

2. 缩进是符号的一部分。您必须尊重现有的左缩进。源代码已经被标记。将每个选项卡最多减少到一到两个空格，否则您将耗尽水平空间。

3. 尝试失去尽可能多的垂直空间，例如抑制空白行。尝试将整个示例放在一页上。如有必要，让它漂浮以实现这一目标。

4. 换行符是符号的一部分。在未咨询作者的情况下，请勿添加换行符。

5. 引号是符号的一部分。不要将单数更改为双数，反之亦然。

6. 理由：计算机程序总是以左对齐、右对齐的方式编写、查看和设置。

7. 分页。在书中设置计算机代码时，分页符不能仅仅遵循排版自然语言时使用的简单孤儿/寡妇原则。相反，如果可能的话，代码的逻辑“块”必须保持在一起。印刷商通常不可能确定代码中的块边界，尽管空白行通常是页面断路的可接受点。“块注释”应与以下代码块一起保留。如果您不知道这些是什么，请询问作者。

8. 连字符。编程语言不是自然语言，不遵守通常的连字符约定。如果您需要或不需要连字符，请咨询作者。除非按照作者的指示，否则程序文本中的单词不得使用连字符或换行符。

9. 大写和小写。程序代码中的大小写通常对计算机很重要，而且实际上对作者和读者来说也总是很重要。经常使用仅大小写不同的词对，代表不同的事物：例如BufferedOutputStream 和 bufferedOutputStream。程序员，尤其是作者制图员通常以对案例的高度系统性，这可能对印刷学家（或其他程序员！）不一定有意义。

实用建议

• 缩进以 em 为单位。em 是计算机程序排版中许多问题的解决方案。作者的制表符很可能是下一个 8 个空格的倍数（1、9、17、……）；程序代码的印刷制表符应为 1 或 2 em 的倍数。采用 em 作为缩进单位对于作者来说一开始可能“看起来很有趣”，因为缩进可能比在屏幕或打印输出上看到的要窄得多。然而，只要保留制表位的垂直对齐方式，就完全保留了作者的意图。
• 换行符必须按照 MS。
• 分页符：如果程序代码中间可能出现分页符，则必须咨询作者以了解首选分页符点。通常在简短的例子中应该完全避免这种情况；在较长的程序中，作者应在 MS 中指出所有可能的分页符。
• 引号：按照惯例，使用“直”引号，而不是印刷引号。这是历史上通过使用不带印刷引号的字体（例如Courier、Helvetica）排版计算机代码。符号的属性不需要它。我认为在设置计算机程序时没有理由不使用印刷报价，只要单语引号保持单身和双引号保持双重，即只要保留作者的报价而不是“纠正”标准的印刷实践。
• 数字：传统上，程序代码中一直使用衬里数字。如果您对在程序代码中使用旧式数字感到烦恼，或者如果字体是这样构建的，我认为没有理由反对它。您必须选择一种字体，其中 1、I 和 l（小写 L）不同，0（零）和 O 也不同。