- ご存知のように、プログラマーは通常、ドキュメントを書くことをあまり好みません。したがって、書くのが簡単で快適であればあるほど、それを書く可能性が高くなります。
- 私たちは自宅で仕事をしているので、マシン上でローカルにドキュメントを書くことができるはずです。
- これを快適に行うには、Wiki用のWebサイトや特定のエディター/ IDE用に調整されたシステム上のフォームがないため、 お気に入りのテキストエディターを使用する機能が必要です。
- 誰もがインターネットへのアクセスが異なります。文書が書かれていないという状況を排除するために、気分が平凡な法則に従って書かれているように見えたときにインターネットが落ちたため、インターネットは文書を書く必要はありません 。
- ドキュメントは、プロジェクトで働くすべての人が利用できるようにする必要があります。 これには、ウェブサイトを通じてそれを読む能力と通常のローカルファイルと同様にそれを扱う能力の両方が含まれます 。
- ドキュメントが読みやすいように、スレッドマークアップ言語とハイパーリンクをサポートしていることが望ましいです。
- ブラウザ（wikiなど）からドキュメントを編集できることが望ましいですが、それほど重要ではありません（開発者はファイルを操作するため、この機能は主にドキュメントを直接編集する可能性が低いクライアントに役立ちます）。
その結果、既存のソリューションを研究した後、私はAsciiDocシステムにとどまりました。 これは、通常のテキストファイル（非常にシンプルで直感的なマークアップを使用）をほぼすべて（html、docbook、manなど）に変換するユーティリティです。 AsciiDocを選択する理由は次のとおりです。
- 非常にシンプルで直感的なマークアップ言語。 実際、AsciiDocマークアップを使用してテキストファイルを見ると、これが単なる通常のテキストファイルではなく、「マークアップファイル」であるとすぐに推測することはできません。 実際、私がAsciiDocを発見する前に、長年にわたってほとんど同じスタイルでプレーンテキストファイルを作成しましたが、後で他の形式に変換することは考えていませんでした！ 明示的な「マークアップ」 がないため 、通常のテキストエディターでのテキストの読み取りと編集が非常に簡単になります 。
- 実際、技術文書の「正しい」形式はDocBookです。 しかし、ペンで、特別なユーティリティの助けを借りて、この形式でドキュメントを書くには... brrr！ また、AsciiDocはDocBook形式に変換することもできます。 したがって、ドキュメントの大部分を単純で便利なAsciiDocテキスト形式で記述し、 それをDocBookに変換してから 、AsciiDocにない特定のDocBook機能を使用して「コーム」することができます。 DocBook形式で引き渡す必要があります。
- AsciiDoc自体は、docbook以外にmanおよびhtml形式に変換できます。また、他に何か必要な場合は、docbookから他の形式に変換できます。
- 生成されたhtmlの外観はcssを介して構成されます（ただし、とりあえず、デフォルトの設定で十分です）。
- AsciiDocは非常に小さく、機敏で、同時に信じられないほど拡張可能なユーティリティです（ただし、拡張する必要はまだありません）。
次に、CGIshkaにすばやく移動し、呼び出されたときに、プロジェクト内の要求されたURLに対応するドキュメントを含む.txtファイルを見つけ、asciidocを使用してhtmlに変換し（元の.txtファイルが変更されるまでhtmlページをキャッシュします）、結果を返しましたhtml
その結果、システムは次のように機能するようになりました。
- 通常の.txtファイルは、ローカルのお気に入りのテキストエディターで、ドキュメントと共にディレクトリに書き込まれます。
- 開発者間で、これらのファイルはプロジェクトソースコード（パッチまたはsvn）と同じ方法で共有されます
- テキストファイルを編集した直後に、対応するURLに移動し、html形式で表示できます（htmlはその場で再生成され、次の変更.txtまでキャッシュされます）。
- まだこれを行っていませんが、実際にはasciidoc形式はwikiで使用されているマークアップと根本的に異なるものではないため、Web経由で文書を編集する可能性を提供するのに問題はないはずです。
参照：
- AsciiDoc Webサイトでは、その機能の詳細な説明に加えて、サイト自体のソースページを.txt形式で見ることができます（はい、AsciiDoc Webサイトはasciidocで書かれています:)）。
- チートシートを作りました。 プレートは非常に重要です。なぜなら AsciiDocには多数の可能性がありますが、非常に小さな数で十分です。この短いリストを手元に用意したいと思います。
- asciidocのインストールおよび設定方法、Vimの構文強調表示、およびHTMLをその場で生成するためのCGIについて説明します。