読者です 読者をやめる 読者になる 読者になる

WikiForme 0.5 開発裏話 4

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

XMLの自動整形

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


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


気の利いているのは、インライン要素っぽい要素はインデントを付けない点。たとえば↓このような1行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」の関連を読み取って、1ページ = 1要素 にしてHTML*1に出力してくれる。「[block:chapter_format]」どは自動でリンクになる。


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

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

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


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

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