第 1 部
私たちは、より簡単に操作できるよう Merlin Project を継続的に改善しています。すでに以前から、開始ダイアログの見直しやインスペクタの整理に取り組んできました。
バージョン 8 では ダイナミックヘルプ が加わりました。? アイコンをクリックするだけで、マウス（iPad では指）で指し示した各オブジェクトについて、説明のヘルプテキストが表示されます。独自の項目には、専用のヘルプテキストを作成 することもできます。
ただ残念ながら、私たちのハンドブックは少し遅れをとっています。とはいえご安心ください。次のような充実した最新のドキュメントが用意されています。
完全なハンドブックは現時点では存在しません。そして、まさにそれを今、変えていきたいと考えています。
このプロジェクト
私は少し前に、ハンドブックを書き直し、まさにそのリファレンスを作成する作業を始めました。もちろんそのためのプロジェクトを立ち上げましたが、残念ながら、他のすべてのプロジェクトと利用可能な時間を分け合わなければなりません。
目標
主要な言語 で Merlin Project の機能の最新ドキュメントを作成するという当然の目標に加え、いくつかの下位目標も設定しました。
- ハンドブックは HTML、PDF、eBook で入手できるようにすること。
- オンデマンド印刷をオプションとして可能にすること。
- ハンドブックは私たちのすべての製品に対応すること。すなわち、
- 私たちのウェブサイト、iTunes Book Store、その他のサイトで無料で提供すること。
ただし、どれだけ計画を立てても、目標日は完全に未定です。というのも、週ごとに作業量が異なるためです。そのため、目標として日付を設定するのは全く現実的ではありません。
ツール
ProjectWizards では、すべてのテキストを Ascii 形式で書き、遅くともその日の終わりには Git にチェックインしています。
現在の流行とはまったく逆に、私たちは Markdown やその派生・拡張では書きません。私たちはずいぶん前から AsciiDoc に、そしてここ数年は、Dan Allen（Twitter 経由）による新しい再実装である Asciidoctor に注力しています。この決定の主な理由は次のとおりです。
- 変数
- 他のファイルへのリンク
- 条件付きのテキストと書式
- 表、図、その他多くのコンテンツ
- さまざまな形式へのテキスト出力
- 目次の自動生成、用語集、索引、参考文献
- その他多数 …
そして言い忘れる前に。もちろん私にとって BBEdit は 今でも エディタ #1 です。
AsciiDoc と Asciidoctor
簡単に言うと、AsciiDoc のソーステキストを Asciidoctor に渡すと、公開できる成果物が得られます。つまり、
- AsciiDoc は言語
- Asciidoctor はプロセッサ
Markdown と同様に、AsciiDoc は控えめで簡潔であり、執筆を簡単に、さらには快適にするための言語として開発されました。しかし AsciiDoc 自体は公開用の形式ではありません。むしろ一種の速記のようなものです。ここで AsciiDoc プロセッサの出番となります。
Asciidoctor のような AsciiDoc プロセッサは、AsciiDoc のソーステキストを読み込み、HTML 5、eBook、PDF などの公開可能な形式に変換します。これはもちろん、Cascading Style Sheets（CSS）といったデザイン上の手段で補完されます。
Working Out Loud（WOL）
Working Out Loud の考え方にならい、私はこの作業について定期的に報告していくつもりです。その際、週に何語、何文書けたかという点はあまり重視しません。私にとっては、AsciiDoc と Asciidoctor に関する手助けや新しい気づきを紹介することのほうがずっと大切です。
このアプローチによって、Dan Allen のたゆまぬ取り組みに敬意を表し、彼を支援したいとも考えています。そして同じくらい、これはプロジェクト管理における AsciiDoc への一票でもあります。
来週の金曜日から、ここで始めます。
続き：AsciiDoc で書く新しいハンドブック 第 2 部
このブログ記事についてご質問やご意見がございましたら、ぜひフォーラムへのご投稿をお待ちしております。
