Re:VIEWにあったら良いなと思うこと
Android Studio本はRe:VIEWを使って書いてました。Re:VIEWへのフィードバックと思い、使ってて思った不満点とか改善要望をまとめてみました。このエントリ自体はRe:VIEWに対するネガティブな内容になってますが、今のRe:VIEWでも十分便利です。逆の見方をすれば、これ以外の不満は無いです(実際、超絶便利だったし、PDF生成しやすいこと考えるとSphinxより良かった)。
アイコンが無いのが分かりづらい
本の性質上、@
を多用してたんだけど、このタグで指定したアイコンリソースのパスが間違っているのが気づきづらくて最初難儀しました。PDF作成すると、アイコン指定が間違っているページまでしかPDFが生成されないので、それで判別してたけど、@
も{//image[...]{...}
みたく、指定したパスにファイルが無いことを警告してくれると良いなと思いました。
ちなみに、PDF生成のログは読みづらいので、HTML生成をRe:VIEWのlint代わりに使ってました。HTML生成のほうがログメッセージがシンプルで、Re:VIEWのマークアップのミスを見つけやすかったです。
見出し参照のスタイルを指定できるとうれしい
@
の見出し参照のほかに、そこのページ数も参照したかったので@
というマークアップを使ってました。なので、見出し参照するときは、次のように2つセットでマークアップしてました。
詳しい理由は@<hd>{plugins|プラグインの紹介|言語系プラグインを使うときの注意事項}(@<pageref>{plugins|プラグインの紹介|言語系プラグインを使うときの注意事項})を参照してください。
レンダリングすると、こうなるイメージ。
詳しい理由は『言語系プラグインを使うときの注意事項』(p.200)を参照してください
正直大変だったので、@
のスタイルを「見出しのみ」「見出し+ページ数」とか複数のスタイルから選べるとよかったなと(そもそも、@
は本書用特別あつらえのタグだと思う)。
ps.
あと@
で他章のコラムを参照できるようにしてつかあさい。
用語リストの説明文を継続できるといいな
「用語リストの使い方が悪い」と言われれば、そのとおりなのですが、いわゆるこんなやつ。
: 用語1 説明文1行目 説明文2行目
これを次のようにマークアップしてます。
: 用語1 説明文1行目@<br>{} 説明文2行目
これをこんな風にできたらよいなと思った次第です。
: 用語1 説明文1行目 説明文2行目
用語リストについて言い始めると、説明文の中で//image
や//list
なんかも使いたいんですけど、言うは易し行うは難しだよなーと。
リスト内に引用用のマークをつけられるといいな
こっちは単なるオマケです。前にasciidoctorの説明読んでて、うらやましいと思っただけ。//list
内で@
が使えたので、今回は全然困りませんでした。
- AsciiDoc Syntax Quick Reference | Asciidoctor(ここのCode block with callouts)