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

AsciiDocで日本語の原稿を書く際,マークアップと地の文の間にスペースを入れない方法をまとめておきます.インストールしている処理系はAsciidoctorであることを前提にしています.
目次

AsciiDoc はマークアップを地の文と区別するためにマークアップの前後に空白を入れる必要があります.そうした空白を削除するツールも存在します.ここでは,そうしたツールに頼らずに余分な空白を入れないようにする方法をまとめておきます.この投稿は4年前に書いたHugo で 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の置き換えは文字のフォーマットが終了してから行われるため,フォーマット記号をそのまま印字させることができます.

URLの前後の空白

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

wshito

Read more posts by this author.

Itoshima, Japan http://diary.wshito.com