Persica （ペルシカ）はテキストファイルから HTML ファイルを静的に生成するためのスクリプトです。予めスキンファイルと呼ばれる雛形に、ヘッダやフッタ、サイドメニューなど、他のページと共通する箇所を記述しておくことで機械的な作業を減らし、本文の記述に集中できます。
実行環境として ruby1.8.1 以上がインストールされている必要があります。
アーカイブを展開し適当なディレクトリに配置した上でパスを通します。
persica ディレクトリ配下の構成は以下の通りです。
persica/
+-- persica.rb
+-- persica.conf
|
+-- plugin/
| +-- amazon.rb
| +-- default.rb
|
+-- skin/
| +-- default.skin
| +-- default.css
|
+-- doc/
+-- manual.css
+-- history.html
+-- persica.html
まずは作業用のディレクトリを用意し、persica.conf と skin ディレクトリをコピーします。Persica はカレントディレクトリの persica.conf を参照します。内容は必要に応じて修正してください。
以下に標準的な構成を示します。
作業用ディレクトリ/
+-- persica.conf
|
+-- skin/
| +-- default.skin
| +-- default.css
|
+-- src/
| +-- テキストファイル
| +-- テキストファイル
| +-- テキストファイル
| :
|
+-- html/ ← 自動生成
+-- HTML ファイル
+-- HTML ファイル
+-- HTML ファイル
:
以下の情報は主にスキンファイルで使用されます。
e.g. $site_name = "asagi box"
e.g. $author = "Keiju Asagi"
e.g. $author_email = "k.asagi@nifty.com"
実行時に必要となる情報です。
e.g. $charset = "EUC-JP"
e.g. $source_dir = "src"
e.g. $result_dir = "html"
e.g. $skin_file = "default.skin"
特に変更の必要はありません。
$source_dir にテキストファイルを配置し、persica.rb を実行します。
$ ruby persica.rb
変更のあったファイルだけが変換され、$result_dir に HTML ファイルが作成されます。ディレクトリ構成はそのまま $result_dir に反映されます。また、suffix が .txt 以外のファイルはそのままコピーされます。
スキンファイルが変更された場合など、テキストファイルの変更の有無に関わらず、全てのファイルを変換したい場合は -f オプションを付けて実行します。
$ ruby persica.rb -f
新規にファイルを追加した場合や既存のファイルを削除した場合、Ls プラグインや Naviプラグインなど、他のページで使用しているプラグインの出力に影響する場合がありますので、少なくとも一度は-fオプション指定で実行することをお勧めします。
-c オプションで persica.conf 以外の設定ファイルを指定することも出来ます。
$ ruby persica.rb -c another.config
スキンファイルは Persica が出力する HTML の雛形となります。Persica が出力する HTML は <body>〜</body> に挿入することを想定していますので、DOCTYPE 宣言や HEAD 部、BODY タグ自体はスキンファイルに記述することになります。
スキンファイルでは、設定ファイルのサイト情報に加えて以下の変数が使用できます。値を参照するには #{変数} と書きます。
<link rel="stylesheet" href="#{$depth}default.css" type="text/css" />
<meta name="WWWC" content="#{update_info}" />
<h1>#{title}</h1>
<body>
<h1>#{title}</h1>
<div id="top">
#{document}
</div>
</body>
テキストファイルの一行目はタイトル行となります。
Sample: サンプル [[2005.01.05]]
二行目以降が本文となります。
text: \<a href="http://homepage1.nifty.com/asagi/">asagi box</a> ↓↓↓ html: <a href="http://homepage1.nifty.com/asagi/">asagi box</a>
text: {{&link(asagi box, http://homepage1.nifty.com/asagi/);}}
↓↓↓
html: &link(asagi box, http://homepage1.nifty.com/asagi/);
テーブルを記述する方法はありません。HTML を直接記述し、直接出力（行頭を \）で代用します。
プラグインにはインラインプラグインとブロックプラグインの二種類があります。パラメータの有無はそれぞれのプラグインに依存します。
インラインプラグインはテキスト内に記述することが可能です。セミコロンを忘れるとプラグインとして認識されません。
&br;
改行（<br />）を挿入します。ブロックプラグインとしても使用できます。
&link(文字列, URL など);
文字列にリンクを張ります。
&monospace(文字列);
英数字文字列を等幅フォント（monospace）で表示します。
&ruby(ルビ){文字列};
文字列にルビを振ります。<ruby> タグ非対応ブラウザでは括弧書きで表示されます。
&size(サイズ){文字列};
文字列を指定サイズ（px）で表示します。
ブロックプラグインは必ず行頭に書かなければなりません。セミコロンは不要です。
#br
改行（<br />）を挿入します。インラインプラグインとしても使用できます。
#contents(見出し)
そのページ内の見出し一覧を出力します。パラメータは目次の見出しの文字列で、省略可能です。
#date
そのファイルの作成日です。タイトル行の日付が右詰で表示されます。
#hr
マイナス四個よりも短い水平線が引かれます。
#ls(接頭辞, オプション)
接頭辞から始まるファイルのタイトルを一覧表示します。オプションは "r" のみ指定可能で、逆順表示となります。オプションは省略可能です。
#mdate
そのファイルの更新日です。ファイルの内容が最後に変更された日付が右詰で表示されます。
#navi(接頭辞, トップ)
トップページと前後のファイルにリンクを貼ります。関連ファイルの接頭辞を揃えて末尾を数字にしておくのが安全です。ディレクトリをまたいだ使用は考慮されていません。
#recent(件数)
更新情報を指定件数分出力します。このプラグインを使用したファイルは常時変換指定（タイトル行の行頭に「!」を付与） することをお勧めします。
Persica は Ruby ライセンスに基づくフリーソフトウェアであり、作者は当プログラムの使用によるいかなる損害に対しても責任を負いません。
Persica への意見、要望、バグ報告は歓迎します。k.asagi@nifty.com までお送り下さい。