WikiForme 0.5 開発裏話 4 - Blog by Sadayuki Furuhashi

前回に続いて第４回。やっと今回が最終回です。
WikiForme 0.6な話も入ってますが、気にせずどんどん。

XMLの自動整形

WikiFormeにはちょっとだけ気の利いたXML（含HTML）の自動整形機能が付いている。
普通にXMLを書き出すと、全部１行で書き出されてしまって非常に読みにくい。WikiFormeでHTMLやSmartDocを書きだしたあと、手で多少修正を加たいかもしれないので、できるだけ読みやすい形式で出力したい。

そこで、全部１行になっているXMLに改行とインデントを加えて、きれいに自動整形する機能を実装してある。コマンドライン版であれば、「-i」オプションを付けるとXMLが自動整形される。

気の利いているのは、インライン要素っぽい要素はインデントを付けない点。たとえば↓このような１行HTMLを自動整形すると、

<html><body><h2>タイトルの中に<strong>太字</strong>のテキスト</h2></body></html>

↓このようになる。

<html>
  <body>
    <h2>タイトルの中に<strong>太字</strong>のテキスト</h2>
  </body>
</html>

<strong>要素の前後は改行されていないところがポイント。これは「改行しない要素はstrongとemとdelと…」と決め打ちで指定しているのではなくて、「テキストの間に入っている要素の前後は改行しない」というルールなので、得体の知れないXMLでもうまく動く。

さらに「<html>要素の中はインデントしない」というような指定もできる。そうすると↓このようになる。

<html>
<body>
  <h2>タイトルの中に<strong>太字</strong>のテキスト</h2>
</body>
</html>

ちょっと気が利いている。

wfdoc

これはWikiForme 0.6に搭載予定の機能で、記法プラグインのソースコード中にコメントを書いておくと、ドキュメントを自動生成してくれる。rdocやJavadocのような機能だが、wfdocはWikiForme用に特化している。

コメントは、たとえば↓このように書く。

##
#* block chapter
##
#? 章
#
#** 対応フォーマット
#|  HTML            OK
#|  SmartDoc        OK
#|  DocBook         OK
#|  InDesign XML    OK
#|  はてな記法      OK
#
#** 書式
#$ *タイトル
#
#$ *#タイトル
#
#~ 先頭に#を付けると、[block:chapter_format]で設定したフォーマットの後ろに`タイトル`をつなげたテキストが、実際のタイトルになる。
#~ #を付けないと、`タイトル`がそのままタイトルになる。
#~ [block:anchor]を使って参照名を設定できる。
#~ `タイトル`はインライン要素が展開される。
#
f = Format.block :chapter
f.default_syntax '*'
f.parent :body
f.contain :@contents, :section, :@blank
f.module_eval {
  def preprocess
# …以下いろいろ…

見ての通り、コメントをWiki記法で書く。最初に書く「#* block chapter」の行と、実際のコードの中の「f = Format.block :chapter」の関連を読み取って、１ページ = １要素にしてHTML*1に出力してくれる。「[block:chapter_format]」どは自動でリンクになる。

このwfdocの実装にもWikiFormeを利用している。となれば、このwfdocも構造化される。ツリーにすると↓このようになる。

#* block chapter
- #? 章
- #** 対応フォーマット
  - …いろいろ…
- #** 書式
  - …いろいろ…
- #code （親要素補完で自動生成）
  - f = Format.block :chapter
  - f.default_syntax '*'
  - …

ポイントは、１要素分のコメントが全部「#* block chapter」の下に入るところにある。どこからどこまでがコメント（ドキュメント）で、どこからはコメント（ドキュメント）ではないのかが簡単に分かる。しかも必要なのは包含関係（#*は#*の下には入らない、など）を定義しておくことだけで、あとの処理はWikiFormeにお任せである。

というわけでWikiFormeを使えば、このwfdocのようなソースコードと一体になったドキュメントを処理するプログラムも、非常に簡単に作れてしまう。
自家製ツールに組み込むのも簡単（WikiForme 0.5リリース -> 自分のアプリケーションでWikiFormeを使う）。
皆様おひとついかがでしょうか。

*1:wfdocはarticle.4me記法に書き出しているだけで、article.4me記法を使ってさらにWikiFormeで処理するとHTMLが出てくる。今のところリンクの張り方の関係でHTMLだが、article.4meを改良すればSmartDocやDocBookにも出力できる。

Treasure Data MessagePack Embulk Fluentd @twitter

XMLの自動整形

wfdoc