WikiForme 0.5 リリース

構造化Wiki記法パーサWikiFormeのバージョン0.5をリリースします。
今回のバージョンはコマンドライン版に加えて、新たにWindows GUI版とWeb版が加わりました。

• wikiforme-web-0.5.0.zip（Web版）
• wikiforme-w32-0.5.0.zip（Windows GUI版）
• wikiforme-cli-0.5.0.tar.gz（コマンドライン版）
• wikiforme-src-0.5.0.tar.gz（ソースコード）

Web版のデモ

Web版のデモが↓このサイトに置いてあります。誰でも編集できるようになっています。

• WikiFormeデモページ
• WikiFormeデモページを編集
• WikiFormeデモページのパスワード管理画面

WikiFormeとは？

WikiFomreは、いわゆる「Wiki記法」で書かれた文章を、HTMLやSmartDoc、DocBookなどのフォーマットに変換するソフトウェアです。SmartDocはTeXに変換することができるので、Wiki記法からTeX文章を作成することもできます。

Wiki記法をHTMLに変換してくれるソフトウェアは世の中に溢れかえるほど存在しますが、WikiFormeは「章」や「節」などの文章構造を解析することでより豊かな表現を記述でき、かつより多くの出力フォーマットに変換できます。

構造化による表現力

従来のWiki記法エンジンは、「*は見出し」「-は箇条書き」といった簡単な１対１の対応でWiki記法をHTMLに変換していました。これでは入れ子構造を持たない簡単なフォーマットしか記述することはできません。
たとえば、↓このようなWiki記法の文章を変換するときに、

*構造化Wiki記法の利点
+複雑な入れ子構造を簡単に記述できる
複雑な入れ子構造を表現することができます。
しかし文章を書くときには従来のWiki記法とまったく同じように記述できます。
+多様な文章フォーマットに変換できる
DocBookのような文章構造を厳格に規定するフォーマットにも変換できます。

従来のWiki記法では、↓このように変換されるのが限界でした。

<見出し>構造化Wiki記法の利点</見出し>
<箇条書き>複雑な入れ子構造を簡単に記述できる</箇条書き>
<段落>複雑な入れ子構造を表現することができます。</段落>
<段落>しかし文章を書くときには従来のWiki記法とまったく同じように記述できます。</段落>
<箇条書き>多様な文章フォーマットに変換できる</箇条書き>
<段落>DocBookのような文章構造を厳格に規定するフォーマットにも変換できます。</段落>

しかしWikiFormeでは、↓このように変換することができます。

<章>
  <タイトル>構造化Wiki記法の利点</タイトル>
  <箇条書き>
    <箇条>
      <見出し>複雑な入れ子構造を簡単に記述できる</見出し>
      <段落>複雑な入れ子構造を表現することができます。</段落>
      <段落>しかし文章を書くときには従来のWiki記法とまったく同じように記述できます。</段落>
    </箇条>
    <箇条>
      <見出し>多様な文章フォーマットに変換できる</見出し>
      <段落>DocBookのような文章構造を厳格に規定するフォーマットにも変換できます。</段落>
    </箇条>
  </箇条書き>
</章>

Windows GUI版を使ってみる

前置きはこのぐらいにしておいて、とりあえずダウンロードして使ってみてください。

スクリーンショット（実寸大）：

まずは↓このファイルをダウンロード。

• wikiforme-w32-0.5.0.zip（Windows GUI版）

zipで圧縮されているので、展開して中身を取り出してください。中には「WikiForme.exe」という実行ファイルと、「article.4me」フォルダ（記法バンドル）、それから「example.txt」という名前でWiki記法で書かれたサンプル文章が入っています。
WikiForme.exeを起動して、「記法バンドル」のところで「article.4me」を選択してください。そして「example.txt」をドラッグ＆ドロップすると、HTMLに変換されます。出力フォーマットでSmartDocを選べば、SmartDocに変換されます。とっても簡単！

「ドロップレットを作成」ボタンは、いちいちWikiFormeを起動せずに、アイコンに文章をドラッグ＆ドロップするだけでファイルを変換できるようにする「ドロップレット」を作成します。ドロップレットの保存先に「%USERPROFILE%\SendTo\WikiFormeでHTMLに変換.bat」と入れると、「送る」メニューから文章を変換できるようになります。

コマンドライン版でTeXに変換してみる

コマンドライン版はRubyが動く環境であればどこでも使えます。WikiFormeを使ってWiki文章をSmartDoc形式に変換して、SmartDoc形式をTeXに変換してみます。

ここではこんなWiki文章を変換してみます。変換結果を見る（PDF）

• example.txt

?title VIVER CORE

*VIVER Core Server
Linuxのディスクレスシステムを作るパッケージです。非常に簡単な手順でディスクレスシステムを構築できます。特殊なカーネルをコンパイル>したり、DHCPサーバーの設定を変更したりする必要はありません。

**インストール
[最新のVIVER Core Serverパッケージ>http://syuki.skr.jp/core/release/viver-core-server-0.0.5.i386.tar.gz]をダウンロードして展開するだけです。

まずは以下のコマンドをさくっと叩いて、WikiFormeとSmartDocをインストールしてください。

# SmartDocをダウロードしてインストール
wget http://smartdoc.jp/download/smartdoc-1.1.zip
echo -e "$HOME/lib/sdoc\n$HOME/bin\nyes"  | java -jar smartdoc-1.1.zip

# WikiFormeをダウンロードしてインストール
wget http://syuki.skr.jp/wikiforme/release/wikiforme-cli-0.5.0.tar.gz
tar zxvf wikiforme-cli-0.5.0.tar.gz
cd wikiforme-cli-0.5.0
ruby setup.rb all --prefix=$HOME

準備ができたら、PDFに変換してみます。

# Wiki記法→SmartDoc
wikiforme -b article -t smartdoc example.txt

# SmartDoc→TeX
sdoc -format:latex2e example.sdoc

# TeX→dvi
platex-utf8 example.tex

# dvi→PDF
dvipdfmx example.dvi

これで完了！example.pdfを開いてみてください。

Web版をサーバーにインストールする

WikiForme Web版には、Ruby CGI版とPHPスクリプト版があります。どちらも機能は同じですが、改造してみくなったときに使いやすい言語の方を使ってください。ちなみに私はRubyの方が好きです。
※BSD系のOSでは、PHP版はうまく動きません。Ruby版を使ってください。*1

まずは↓このファイルをダウンロードしてください。

• wikiforme-web-0.5.0.zip

zipアーカイブを展開すると、↓このような３つのディレクトリが出てきます。

public_html_rbcgi   # Ruby版
public_html_php     # PHP版
wikiforme           # wikiforme本体

サーバーにアップロードする前に、.htaccessファイルとconfig.rb（PHP版はconfig.php）ファイルをテキストエディタで開いて、内容を確認してください。

ドキュメントルート（URLがhttp://example.com/）にインストールする場合はそのままでOKですが、サブディレクトリの中（URLがhttp://example.com/~username/だったりhttp://example.com/subdir/だったりする場合）は、一部設定を書き換える必要があります。

たとえばURLがhttp://example.com/subdir/のところにインストールするときは、.htaccessとconfig.rb（config.php）を以下のように書き換えてください。

• .htaccess
  • 変更前

RewriteEngine On
RewriteCond %{REQUEST_URI} \.(html|htmlx)$
RewriteRule ^(.*)$ /index.cgi [L]
RewriteCond %{REQUEST_URI} \.txt$
RewriteRule ^(.*)$ /edit.cgi [L]

• • 変更後

RewriteEngine On
RewriteCond %{REQUEST_URI} \.(html|htmlx)$
RewriteRule ^(.*)$ /subdir/index.cgi [L]
RewriteCond %{REQUEST_URI} \.txt$
RewriteRule ^(.*)$ /subdir/edit.cgi [L]

※mod_rewriteが使えない場合は、他にもActionディレクティブを使う方法、PATH_INFOを使う方法、PATH_INFOとFancy URLを使う方があります。.htaccessファイルに設定方法とサンプルが書いてあるので、試してみてください。

• config.rb
  • 変更前

@url_root         = '/'
@wikiforme_dir    = '../wikiforme/'

• • 変更後

@url_root         = '/subdir'
@wikiforme_dir    = '../../wikiforme/'

設定できたら、サーバーにアップロードしてください。パーミッションは、

/public_html              # 755（PHP版の場合は777）
/public_html/.htaccess    # 644
/public_html/edit.cgi     # 755（PHP版の場合はedit.phpで644）
/public_html/index.cgi    # 755（PHP版の場合はindex.phpで644）
/public_html/config.rb    # 644
/public_html/example.css  # 644
/public_html/address.txt  # 644（PHP版の場合は666）
/public_html/index.txt    # 644（PHP版の場合は666）
/public_html/menu.txt     # 644（PHP版の場合は666）
/public_html/test.txt     # 644（PHP版の場合は666）
/wikiforme/               # 755
/wikiforme/の下            # ファイルは644、ディレクトリは755

と設定してください。

これでhttp://example.com/subdir/index.htmlにアクセスすると、index.txtに書かれたWiki記法がHTMLに変換されて表示されます。
Wiki記法にエラーがあると、index.htmlにアクセスしたときは何も表示されませんが、index.htmlの代わりにindex.htmlx（最後が.htmlではなく.htmlx）にアクセスするとエラーメッセージが表示されます。
index.txtにアクセスすると、ブラウザ上でページを編集することができます。新しいページを作るには、http://example.com/subidr/新しいページ名.txt にアクセスするとエディタ画面が開くので、保存ボタンを押して新しいページを作ってください。

SVN派、vim派の方へ

WikiForme Web版のCGIは、単純にアクセスされたファイルと同じ名前の.txtファイルを変換しているだけです。サーバーに.txt ファイルを置きさえすれば、新しいページを作ったり、ページを編集したりできます。つまり、SVNで.txtファイルをアップロードしても、サーバー上でvimを使って直に書いてもOKです。

変換結果はキャッシュされていますが、.txtファイルの更新日時を見て自動的にキャッシュを更新するので、明示的に何か指示する必要はありません。.htmlではなく.htmlxにアクセスすると、更新日時にかかわらずキャッシュを作り直します。

自分のアプリケーションでWikiFormeを使う

Rubyで書かれアプリケーションであれば、簡単にWikiFormeの機能を組み込むことができます。WikiFormeのソースコードの中に入っているsite_rubyディレクトリをRubyの$LOAD_PATHに加えて、require 'wikiforme'と書けば準備完了です。

• サンプル１

$LOAD_PATH.push( "/path/to/wikiforme/site_ruby" )
require 'wikiforme'

bundle_path = "/path/to/article.4me"
wiki_document = "example.txt"

result = nil
File.open(wiki_document) {|stream|
  # ここのstreamは、eachメソッドで１行ずつ取り出せるものであればOK
  # 文字列であればStringIOにする： stream = StringIO.new("*test\n本文本文…") 
  result = WikiForme.process(bundle_path, stream, :html)
}

puts result

• サンプル２（WikiFormeオブジェクトをキャッシュ）

$LOAD_PATH.push( "/path/to/wikiforme/site_ruby" )
require 'wikiforme'

bundle_path = "/path/to/article.4me"

wf = WikiForme.new(bundle_path)

result = nil
File.open("example1.txt") {|stream|
  result = wf.parse(stream).assemble.process(:html)
}
File.open("example2.txt") {|stream|
  result = wf.parse(stream).assemble.process(:html)
}

puts result

新しい記法を作る

WikiFormeは従来のWikiエンジンよりもずっと強力な記法プラグインシステムを持っています。そもそも見出し（章）や太字といった基本的な記法や、includeや自動図番号といった特殊な機能も、すべてプラグインで作られています。

article.4meディレクトリの中の、article.rbファイルに説明が書いてあるので、新しい記法を作ってみてください。

# 新しいブロック要素を作る
f = Format.block :notice

# 記法は !!
f.default_syntax = '!!'

# @contentsグループに属する
# これで章や節の中に含められるようになる
f.group :@contents

# HTMLへの変換メソッド
f.process_html {|text, children|
  # <div class="notice">ここにテキスト</div>
  XML[:div, {:class => 'notice'}, text.process]
}

# 新しいインライン要素を作る
f = Format.inline :sup

# 記法は^と^で囲む
f.default_syntax = %w[^ ^]

# HTMLへの変換メソッド
f.process_html {|text|
  # <sup>ここにテキスト</sup>
  XML[:sup, text.process]
}

*1:PHPのrealpath()関数を使ってリクエストされたパスを絶対パスに変換しているのですが、BSD系のOSでは存在しないパスにrealpath()を使うと、絶対パスではなくFALSEが返ってきてしまいます。これでは新しいページを作れません。解決策をご存じの方、ぜひ教えてください。