asciidoctorのエスケープ応用編～ エスケープした文字列を強調するなど～

概要

asciidoctorのエスケープのまとめです。

大抵は、バックスラッシュ(\)を使う方法でうまくいき、他のサイトもその方法を紹介しています。それももう少し複雑なマークアップ(入れ子)をしていくとうまくいかないため、Predefined Attributesを使った方法も含めて、エスケープ方法のまとめ記事を書いてみました。

大雑把に言えば、次の表にあるような書き方もあるよ。ということです。

方法1: バックスラッシュ(\)を使う

見栄えを保てること、リファレンスを見なくても想像つく点で、とっつきやすい方法。include, pass マクロ等の無効にも使える。

例

• X.\*.* -> X.*.*

補足

• エスケープする文字、しない文字が混在してくると訳が分からなくなるので、その場合は、Predefined Attributes をお勧めしたい。
  * を含む文章を強調する場合だとか。

方法2: Predefined Attributes を使う

Predefined Attributes (定義済みの属性) を使う。これが一番副作用のない方法。意味的な部分とマークアップで別の表記となるから、エスケープした文字列を強調するだとかができるようになります。

以下、よく使うものを挙げておく。

• {vbar} ... | に置換される。table書式中で有用。
• {asterisk} ... * に置換される
• {backslash} ... \ に置換される
• {startsb} ... [ に置換される
• {endsb} ... ] に置換される

例

• X.{asterisk}.{asterisk} -> X.*.*

注意

• {amp} は、& (特殊文字)に置き換えられる
  文字として表示したければ & を使う
  参考にある表で、置換後に &#nnnnn となっているのは文字として置換されるが、それ以外は、置換後の文字そのものとなる。

方法3: Passthrough をする

pass:[～] を使う。エスケープする目的での使用はあまりお勧めしない。

例

• pass:[X.*.*] -> X.*.*

補足

• 良くも悪くも そのまま出力 なので、HTMLでいうと特殊文字を含むと出力が壊れるし、スタイルシート周りも周囲と異なる結果となる
• PDF出力時でも、対応する Passthrough された内容が解釈できなければ表示できない
  → マニアックな話をすると、 asciidoctor-pdf　は <strong>Foo</strong> といった 特定のHTMLタグ をPDF上の表現に置き換える仕組みのようです。

その他: テーブルのセル中で | をバンバン使う

separator を使う。ただ、セパレーターに | 以外を使うと、エディターのSyntax highlight が効かなくなるので、数が多くなければ {vbar} を使うやり方を推奨する。

[cols="3" separator="¦"]
|===
¦ Equations ¦ English ¦ Mean

¦ |A × B|
¦ magnitude A cross B
¦ 外積の大きさ
|===

参考

• Predefined Attributes for Character Replacements | Asciidoctor User Manual
  日本語がよいという人は以下を参照
  • Asciidoctor 文法クイックリファレンス(日本語訳) > 17. 属性 > 17.2. 属性の優先順位 (高いものから列挙)
    ※ 訳のアンカーの付け方が微妙で、翻訳が修正されるとリンク切れになるかもしれない。