AsciiDoc で日本語原稿を書く際の留意点

AsciiDoc は， DocBook に比べマークアップの手間が省ける分，地のテキストとコマンドを分離するマークアップ記号がありません．そのため，通常はコマンドの前後に空白を置かなければならないという制約があります．日本語で一番困るのはテキストのフォーマティング・マークアップでしょう．フォーマティングのマークアップにはconstrainedとunconstrained marksの2種類があり，後者のunconstrained formatting marksを使うとマークアップの前後にスペースが必要ありません．unconstrained marksはマークアップを2つ連続して記述します．

インラインコードは等幅（monospace）のマークアップであるバックティックを使用します．もし，バックティックで囲んだ中に AsciiDoc のマークアップがあった場合，それらは Asciidoctor によってフォーマティングされてしまいます．例えば，ここを``等幅``にするを実現するにはインラインコード中のバックティックをマークアップとしてではなくコードとしてそのまま表示させる必要があります．

このようにインライン・コード中の AsciiDoc 固有の記号もそのまま印字させたい場合には``+と+``で囲みます．例えばここを**太字**にするを記述するには``+ここを**太字**にする+``と書いています．

ちなみに前後にスペースを入れても良いのであればconstrained marksを使うので両サイドのバックティックは1つで構いません．

等幅の内部のマークアップをエスケープするために``+と+``で囲んだわけですが，もしエスケープしたいマークアップがプラス記号やバックティックの場合にはこの方法は使えません．Asciidoctor は囲んだ部分が終わったと勘違いしてしまいます．

この場合にはパススルー・マクロ（inline passthrough macro）を使います．これはpass:[ ]の内部に記述されたものはそのままフォーマットされずに出力するというマクロです．これを使うと例えば，ここを``等幅``にするは``pass:[ここを``等幅``にする]``と記述しています．

パススルー・マクロでもうまくエスケープできない場合はトリプル・プラス・マクロ（triple plus macro）を使うと良いでしょう．例えば，``pass:[ここを``等幅``にする]``を記述するにはpass:[ ]を入れ子にしても後半のバックティック2つがうまくエスケープされないので``+++``pass:[ここを``等幅``にする]``+++``と記述しています．

さて，今の最後のmonospaceの記述はどうやって書いたかと言いますと，これはもはやパススルー・マクロやトリプル・プラス・マクロを入れ子にしてもできません．最終兵器はそのまま印字させたい内容をattributeとして登録し，それをバックティックの中に入れます．attributeの置き換えは文字のフォーマットが終了してから行われるため，フォーマット記号をそのまま印字させることができます．

リンクを挿入する際，httpやhttpsといったURLスキームで始まるURLは Asciidoctor によって自動でリンクとして認識されます． 例えば Asciidoctor というリンクを構築するにはhttps://asciidoctor.org[Asciidoctor]と書きます．しかし，Asciidoctor にURLスキームを自動認識させるにはURLスキームの前にスペースを挿入する必要があります．この余白を回避するにはリンクマクロを使います．単にURLの前にlink:を付けるだけです．つまりlink:https://asciidoctor.org[Asciidoctor]と書くと前後にスペースを入れないでAsciidoctorのような見栄えになります．