第 2 部
これは、新しい Merlin Project ハンドブックに関する私のプロジェクトレポートの第 2 部です。毎週金曜日に、プロジェクトについて多かれ少なかれ短い近況をお伝えしていく予定です。
プロジェクト
AsciiDoc に取りかかる前に、まずは私のプロジェクトをざっと見てみましょう。
- Git リポジトリを準備しました。
- 章立ては定義済みで、一部は こちら でも紹介しました。
- 前提条件はおおむね把握しています。
- 最初のアウトラインを作成し、現在は少しずつ精緻化しているところです。
- 画像については、まずは 簡単なスクリーンショット だけを使い、必要に応じて後から作り直します。
- 執筆する曜日を決めました。
特に最後の項目は、私にとって本当に難しい課題でした。なんとかして執筆の時間を確保しなければならないからです。単に 空いている時間すべて を充てるやり方では、おそらく永遠に終わらないでしょう。決まった時間枠が必要であり、まさにそれを自分のために用意しました。今後は水曜日を私のハンドブック執筆日とします。これがどれくらい続くか、様子を見てみましょう。
もちろんカンバンも用意しています。英語表記でごめんなさい。私たちは社内ドキュメントの多くを英語で作成しています。
Asci
iDoc のヒント
ファイルを分割する
私はハンドブックを 1 つのファイルではなく、章ごとに分割して作成しています。さらに、ハンドブックの変数と属性は専用のファイルに切り出しています。こうすることで、ファイルを個別にビルドしたりブラウザで表示したりしながら しかも すべての変数と属性を利用できます。私の場合、このファイルは通常 Attributes という名前で、すぐに見つけられるように先頭に「_」を付け、ファイル一覧で常に最上部に表示されるようにしています。
ifndef::_attributes[]include::_attributes.de.adoc[]endif::[]
- ここでは、変数 _attributes がすでに設定されているかどうかを確認しています。
- 設定されていなければ、ファイルがインクルードされます。
このようにして、各ファイルがこれらの行で始まっても、属性ファイルが何度も読み込まれないようにしています。
私の Rapid turnaround
現在はまだ私一人でハンドブックを書いていますが、それでもすべてのテキストとメディアは Git に入れています。つまり、私の朝の執筆は、ターミナル、あるいは手元にあるものに応じて BBEdit Unix Worksheet で、力強い git pull から始まります。次に BBEdit のプロジェクトファイル（もちろんリポジトリに含まれています）を開くと、含まれているすべてのファイルが左側の一覧に表示されます。
画面はおおよそ半分に分割しています。左側で執筆し、右側には Chrome を開いています。ブラウザのウィンドウには、編集中のファイルのプロキシアイコンをドラッグするだけです。拡張機能 Asciidoctor.js のおかげで、BBEdit で保存するたびにブラウザが更新されます。
今日はここまで。続きは来週です。
続き: AsciiDoc で書く新しいハンドブック 第 3 部
このブログ記事についてご質問やご意見がございましたら、ぜひフォーラムへのご投稿をお待ちしております。
