3

我们正在考虑使用 Asciidoc 来创建用户指南，我们打算只在 github 上对单个文件进行版本控制。

然而，我们看到，像 ProGit ( https://github.com/progit/progit2/tree/master/book ) 这样的已建立项目，虽然也生成了一个文档，但将 Asciidoc 拆分为多个文件。

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

4

3 回答 3

3

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

多个文档的另一个很好的理由是，如果将来您决定拆分每个部分/章节，那么从多个文档开始并将它们包含在一个大文档中比之后尝试将其拆分更容易。

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

于 2015-01-15T17:05:20.930 回答
1

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

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

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

于 2015-03-11T11:01:56.473 回答
1

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

一个大文件的优点：

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

小文件的优点：

  • 浏览部分更容易。例如：ls或查看手工制作的 TOC。可以通过自定义编辑器大纲功能克服。
  • 仅重新编译更改的文件。例如：a.c -> a.o -> a.exe。只有链接器部分每次都必须发生，但这更便宜。
  • 更小的文件加载时间
  • 如果您想在某个部分中查找某些内容，只需按 Ctrl + F 并键入，它不会带您离开该文件。在一个大文件中，它可能会，并且需要一些努力/工具来说明您是否离开了该部分。
  • 一旦知道它的名称，就更容易跳转到给定的部分。例如，在 Vim 中，您可以:b something使用制表符自动完成文件名。如果该部分只是大文件中的标题，则不能这样做。
于 2015-04-25T09:19:03.653 回答