我必须在 Framemaker 中编写一份技术文档，解释各种编程源代码。
所以我的文档由一堆文本组成，然后是一堆源代码（Java、XML），然后是更多的文本，等等。
这个问题与我是否应该使用 Framemaker 无关——这是我必须使用的软件。. .
我感到困惑的是如何将源代码格式化为我的文档的一部分。有没有人为技术文档这样做并遇到任何说明或提示？到目前为止，我的谷歌搜索还没有产生任何与我需要做的事情相关的内容。
问问题
872 次
2 回答
2
至少，为代码示例创建一个段落样式，使用良好的等宽字体，并且不要忘记关闭连字符。
当我以前这样做时，我会创建一个表格样式并将代码粘贴到那里，所以我在它上面有一个漂亮的标题，它有点突出。唯一的问题是 Frame 表格单元格不会跨越分页符，因此如果您的代码比页面长或威胁要低于页面底部，您需要在表格中创建多行并跨行分解代码。
于 2009-07-31T00:33:00.367 回答
0
来自我几年前写的一篇论文，下周将再次在线提供。
排版师主要关注易读性，并且在用自然语言设置文本时，他们拥有可以追溯到数百甚至数千年的工具、实践和传统。但是，计算机程序不是用自然语言编写的。它们是用“编程语言”编写的：人工语言，它们有自己的语法规则、自己的表示约定和自己的易读性标准。因此，计算机代码是排版的一个特殊领域，就像音乐、数学和化学一样。这些域有自己的规则，不是设置自然语言时使用的规则。
计算机编程本身是最近才出现的，将其设置为字体的做法可以追溯到大约 45 年前：大量的计算机代码仅在过去 20 年或更短的时间内才发布。相关的印刷学科不成熟或实际上不存在，而且该领域的从业者对印刷的期望也很低，正如您通过检查许多行业书籍所看到的那样。你没有理由不努力做得更好。
使用无衬线字体。在我的一本书中，我使用了相同的字体系列，FF Scala 用于文本，FF Scala Sans 用于代码。我认为它看起来不错，但也有相反的意见：这些可能会迫使您使用等宽字体，尽管我个人认为这已经过时了。避免使用 Courier，它不会与任何东西混合。
缩进是符号的一部分。您必须尊重现有的左缩进。源代码将已被标记。每个选项卡最多减少一到两个空格，否则您将用完水平空间。
尽量减少垂直空间，例如取消空白行。尝试将整个样本放在一页上。如有必要，让它漂浮以实现这一目标。
换行符是符号的一部分。不要在没有咨询作者的情况下添加换行符。
引号是符号的一部分。不要将单更改为双，反之亦然。
对齐：计算机程序总是被编写、查看和设置为左对齐、右对齐。
分页符。在书中设置计算机代码时，分页符不能仅仅遵循排版自然语言时使用的简单孤儿/寡妇原则。相反，如果可能，代码的逻辑“块”必须保持在一起。排版人员通常不可能确定代码中的块边界，尽管空行通常是分页符的可接受点。“块注释”应与以下代码块一起保存。如果您不知道这些是什么，请询问作者。
断字。编程语言不是自然语言，不遵守通常的断字约定。如果您需要连字符，请咨询作者，或者不要。除非按照作者的说明，否则程序文本中的单词不得连字符或换行。
大写和小写。程序代码中的案例通常对计算机很重要，实际上对作者和他们的读者来说也很重要。经常使用仅大小写不同的词对，表示不同的事物：例如 BufferedOutputStream 和 bufferedOutputStream。程序员，尤其是作者程序员，通常对大小写高度系统化，其方式对排版师（或其他程序员！）可能不一定有意义。
实用建议
- 以 em 单位缩进。排版计算机程序中的许多问题的解决方案是 em。作者的制表符很可能是 8 个空格的下一个倍数（1、9、17、...）；程序代码的印刷制表符应该是 1 或 2 em 的倍数。采用 em 作为缩进单位，起初对作者来说可能“看起来很有趣”，因为缩进可能比在屏幕或打印输出上看到的要窄得多。但是，只要保留制表位的垂直对齐方式，就完全保留了作者的意图。
- 换行符必须按照 MS。
- 分页符：如果在程序代码中间可能出现分页符，必须向作者咨询首选分页符点。通常在简短的示例中完全避免这种情况；在较长的程序中，作者应指出 MS 中所有可能的分页符。
- 引号：通常使用“直”引号，而不是印刷引号。这在历史上是通过在排版计算机代码中使用没有印刷引号的字体（例如 Courier、Helvetica）来确定的。符号的属性不需要它。我认为在设置计算机程序时没有理由反对使用印刷引号，只要单引号保持单引号和双引号保持双引号，即只要保留作者的引号而不是“更正”到标准排版实践。
- 数字：通常，在程序代码中总是使用衬里数字。如果您对在程序代码中使用旧式数字感到困扰，或者如果字体是这样构建的，我看不出有什么理由反对它。您必须选择 1、I 和 l（小写 L）以及 0（零）和 O 不同的字体。
于 2014-08-15T00:37:02.940 回答