为AsciiDoc文档使用多个文件有什么好处？

Question

我们正在考虑使用Asciidoc来创建用户指南，我们只想在github上版本化一个文件。

然而，我们看到，ProGit（https://github.com/progit/progit2/tree/master/book）等已建立的项目虽然也生成了单个文档，但却将Asciidoc拆分为多个文件。

将逻辑文档拆分为多个文件有什么好处？

Answer 1

我认为使用多个文档的最大好处是组织和心理。假设您有每个部分的文档，如果它在自己的文档中，则更容易查找和修复或添加到部分。当您打开较小的文档而不是较大的文档时，它也更容易精神消耗和思考。如果您打开文档并且滚动条开始越来越小，您就会开始思考找到您需要多长时间才能更改，如果值得进行更改以及需要多长时间加载。当然这些都是主观的，也许有些人没有这个问题。

多个文档的另一个好理由是，如果在将来某个时候您决定拆分每个部分/章节，则更容易从多个文档开始并将它们包含在一个大文档中，而不是尝试将其删除。

除了组织问题，如果您有多个人在处理文档，那么在较小的文档中查看更改比在一个大文档中更容易。

Answer 2

当您使用多个作者或非常大的书并将内容存储在GitHub等版本控制系统中时，这非常棒。然后编写者可以拥有和编辑内容，而无需将他们的更改合并到一个巨大的文档中。

多个文档有时可以取代内容标记。例如，如果有各种内容可能会或可能不会使其成为最终文档的发布版本，则更容易注释掉引用未完成章节的行（在章节的书籍文件中）而不是尝试和标记特定的conent并写一个输出脚本来过滤它。

如果您是一名作家并且不会重复使用该内容，您可能会发现将所有内容放在一个地方更容易。

Answer 3

同样的问题适用于任何其他编程系统。

一个大文件的优点：

• 搜索已知术语更容易。例如。 Vim中的/# header
• 隐含文字的顺序没有ID。对于较小的文件，您需要在某个文件中使用TOC，或者将每个文件编号为01_等。

小文件的优点：

• 浏览部分更容易。例如：ls或查看手工制作的TOC。可以使用自定义编辑器大纲功能克服。
• 仅重新编译已更改的文件。例如：a.c -> a.o -> a.exe。每次只能发生链接器部分，但这样会更便宜。
• 较小的文件加载时间
• 如果您想在某个部分中找到某些内容，只需按Ctrl + F键入，它就不会让您退出该文件。在一个大文件中，它可能会，并且如果您离开该部分需要一些努力/工具。
• 一旦你知道它的名字就更容易跳到给定的部分。例如，在Vim中，您可以:b something和标签自动填充文件名。如果该部分只是一个大文件中的标题，则无法执行此操作。