asciidoc - AsciiDoc ドキュメントに複数のファイルを使用する利点は何ですか?

Question

Asciidoc を使用してユーザー ガイドを作成することを検討しており、github で単一のファイルをバージョン管理するだけでした。

ただし、ProGit ( https://github.com/progit/progit2/tree/master/book ) のような確立されたプロジェクトは、単一のドキュメントを生成するものの、Asciidoc を複数のファイルに分割することがわかります。

論理ドキュメントを複数のファイルに分割する利点は何ですか?

Answer 1

複数のドキュメントを使用する最大の利点は、組織的および精神的なものだと思います。セクションごとにドキュメントがあるとします。セクションが独自のドキュメントにある場合は、セクションを見つけて修正または追加するのがはるかに簡単になります。また、大きいドキュメントよりも小さいドキュメントを開く方が、精神的に消費して考えるのが簡単です。ドキュメントを開いてスクロール バーがどんどん小さくなっていくと、変更が必要な場所を見つけるのにどれくらいの時間がかかるか、変更を加える価値があるかどうか、読み込みにどれくらいの時間がかかるかを考え始めます。もちろん、これらはすべて主観的なものであり、その問題を抱えていない人もいるかもしれません。

複数のドキュメントを使用するもう 1 つの正当な理由は、将来、各セクションや章を分割することを決定した場合、複数のドキュメントから始めて、それらを 1 つの大きなドキュメントに含める方が、後で切り刻むよりも簡単です。

組織の問題に加えて、複数の人が 1 つのドキュメントで作業している場合、1 つの大きなドキュメントよりも小さなドキュメントで変更を確認する方が簡単です。

Answer 2

同じ質問は、他のプログラミング システムにも当てはまります。

1 つの大きなファイルの利点:

• 既知の用語の検索がより簡単になります。たとえば/# header、Vimで
• テキストの順序は ID なしで暗示されます。小さいファイルの場合、一部のファイルに TOC が必要か、各ファイル01_に などの番号を付ける必要があります。

小さなファイルの利点:

• セクションの閲覧がより簡単になります。例:lsまたは手作りの TOC を見る。カスタム エディターのアウトライン機能で克服できます。
• 変更されたファイルのみを再コンパイルします。例: a.c -> a.o -> a.exe. リンカの部分だけは毎回発生しなければなりませんが、その方が安価です。
• ファイル読み込み時間の短縮
• セクション内で何かを見つけたい場合は、Ctrl + F を押して入力するだけで、そのファイルから移動することはありません。大きなファイルでは、セクションを離れたかどうかを判断するのにある程度の労力/ツールが必要です。
• 名前がわかれば、特定のセクションに簡単にジャンプできます。たとえば、Vim では:b something、ファイル名をタブでオートコンプリートできます。セクションが大きなファイル内の単なるヘッダーである場合、それはできません。

Answer 3

複数のライターや非常に大きな本で作業していて、コンテンツを GitHub のようなバージョン管理システムに保存している場合に最適です。これにより、ライターは、変更を 1 つの巨大なドキュメントにマージすることなく、コンテンツを所有および編集できます。

複数のドキュメントがコンテンツのタグ付けの代わりになる場合があります。たとえば、最終的なドキュメントのリリース バージョンになるかどうかわからないさまざまなコンテンツがある場合、(章のブック ファイルで) 未完成の章を参照する行をコメント アウトする方が、試してみるよりも簡単です。特定のコンテンツにタグを付け、それをフィルタリングする出力スクリプトを記述します。

ライターが 1 人で、コンテンツを再利用しない場合は、すべてを 1 か所にまとめた方が簡単です。