2009-06-07T21:27:39の更新内容

works/tools/pakina/index.wiki.txt

current previous
1,329 0,0
+
*pakina
+
**概要
+
[[PukiWiki記法:http://pukiwiki.sourceforge.jp/?整形ルール]]および[[はてな記法:http://hatenadiary.g.hatena.ne.jp/keyword/はてな記法一覧]]で書かれたのテキストをXHTML(XML)へ整形するコマンドラインツールです。
+

                  
+
当サイトのページはpakinaを拡張したものを使って生成しています。
+

                  
+
***ダウンロード
+
#googleadunit
+
-${smdncms:distfilelink,pakina-0.3-bin.tar.gz,version 0.3 バイナリ}
+
-${smdncms:distfilelink,Smdn.Formats.Notations-0.3-src.tar.bz2, version 0.3 ソース}
+

                  
+
***必須環境
+
-.NET Framework 2.0以上またはMono 2.0以上
+

                  
+
***動作確認済み環境
+
-Ubuntu 9.04 + Mono 2.5
+
-確認はしていませんが、Windowsでも恐らく動作すると思います
+

                  
+
***変更履歴
+
:version 0.3|公開
+

                  
+
***簡単な使い方
+
PukiWiki記法のファイルFrontPage.txtを変換し、FrontPage.xhtmlにUTF-8で出力するには、
+
#code{{
+
pakina.exe -i FrontPage.txt -if pukiwiki -o FrontPage.xhtml -oe utf-8
+
}}
+
とします。
+

                  
+
また、標準入出力を使った変換もできるので、nkfを使ってEUC-JP版PukiWikiのFrontPageを変換するには、
+
#code{{
+
nkf -Ew wiki/46726F6E7450616765.txt | mono pakina.exe -if pukiwiki > FrontPage.xhtml
+
}}
+
とできます。 ただ、pakinaで入力のエンコーディング指定もできるので、単に、
+
#code{{
+
mono pakina.exe -i wiki/46726F6E7450616765.txt -ie euc-jp -if pukiwiki > FrontPage.xhtml
+
}}
+
とすることもできます。
+

                  
+
オプションの一覧と説明は
+
#code{{
+
pakina.exe --help
+
}}
+
で表示できます。
+

                  
+
***出力サンプル
+
#code(,Sandbox.txt){{
+
#nofollow
+
#norelated
+
* SandBox: お砂場(練習ページ)です [#v299c566]
+
|SEO SPAMボットの攻撃対象になるため、デフォルトでこのページは凍結されています。|
+

                  
+
#contents
+

                  
+
* ''見出し'' [#n151e840]
+

                  
+
* 大見出し 1 [#a6dc7f79]
+

                  
+
** 中見出し 1-1 [#qa1c1e8c]
+

                  
+
*** 小見出し 1-1-1 [#k28ac390]
+
- 項目1
+
- 項目2
+
- 項目3
+

                  
+
段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1
+
段落1段落1段落1段落1段落1段落''強調''1段落1段落1段落1段落1段落1
+
段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1
+

                  
+
段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2
+
段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2
+
段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2
+

                  
+
** 中見出し 1-2 [#zcbf4116]
+
:用語1|いろいろ書いた解説文1と''強調単語''
+
段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1
+
段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1
+
段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1
+
:用語2|いろいろ書いた解説文2
+
:用語3|いろいろ書いた解説文3
+

                  
+
-----------------------------------------
+
}}
+

                  
+
#code(xml,Sandbox.xhtml){{
+
<?xml version="1.0" encoding="utf-8"?>
+
<html>
+
  <head>
+
    <title>Sandbox.txt</title>
+
  </head>
+
  <body xmlns:pukiwiki="http://smdn.invisiblefulmoon.net/works/tools/pakina/notations#pukiwiki">
+
    <pukiwiki:plugin pukiwiki:type="block" pukiwiki:name="nofollow" pukiwiki:arguments="">#nofollow</pukiwiki:plugin>
+
    <pukiwiki:plugin pukiwiki:type="block" pukiwiki:name="norelated" pukiwiki:arguments="">#norelated</pukiwiki:plugin>
+
    <h2> SandBox: お砂場(練習ページ)です <a href="#v299c566" id="v299c566" title="v299c566" class="anchor_super">&dagger;</a></h2>
+
    <table>
+
      <tbody>
+
        <tr>
+
          <td>SEO SPAMボットの攻撃対象になるため、デフォルトでこのページは凍結されています。</td>
+
        </tr>
+
      </tbody>
+
    </table>
+
    <pukiwiki:plugin pukiwiki:type="block" pukiwiki:name="contents" pukiwiki:arguments="">#contents</pukiwiki:plugin>
+
    <h2> <strong>見出し</strong> <a href="#n151e840" id="n151e840" title="n151e840" class="anchor_super">&dagger;</a></h2>
+
    <h2> 大見出し 1 <a href="#a6dc7f79" id="a6dc7f79" title="a6dc7f79" class="anchor_super">&dagger;</a></h2>
+
    <h3> 中見出し 1-1 <a href="#qa1c1e8c" id="qa1c1e8c" title="qa1c1e8c" class="anchor_super">&dagger;</a></h3>
+
    <h4> 小見出し 1-1-1 <a href="#k28ac390" id="k28ac390" title="k28ac390" class="anchor_super">&dagger;</a></h4>
+
    <ul>
+
      <li> 項目1</li>
+
      <li> 項目2</li>
+
      <li> 項目3</li>
+
    </ul>
+
    <p>段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落<strong>強調</strong>1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1</p>
+
    <p>段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2段落2</p>
+
    <h3> 中見出し 1-2 <a href="#zcbf4116" id="zcbf4116" title="zcbf4116" class="anchor_super">&dagger;</a></h3>
+
    <dl>
+
      <dt>用語1</dt>
+
      <dd>いろいろ書いた解説文1と<strong>強調単語</strong> <em>注釈1: WikiName</em>段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1段落1</dd>
+
      <dt>用語2</dt>
+
      <dd>いろいろ書いた解説文2 <em>注釈2: <pukiwiki:alias pukiwiki:name="SandBox" pukiwiki:aliasto="">[[SandBox]]</pukiwiki:alias>へのリンク</em></dd>
+
      <dt>用語3</dt>
+
      <dd>いろいろ書いた解説文3 <em>注釈3: 注釈の中にも<em>注釈の注釈を</em>作ることができます</em></dd>
+
    </dl>
+
    <hr />
+
  </body>
+
</html>
+
}}
+

                  
+
テスト兼デモ用のページ[[misc/testpages/pukiwiki]]および[[misc/testpages/hatena]]もご参照ください。((一部で本ツールに含まれない拡張を使っている箇所があります))
+

                  
+
***注意点・補足
+
このツールはPukiWiki記法のテキストをXHTMLにフォーマットするだけの機能しかありません。 PukiWikiで作成されたものから完全なXHTMLページを生成するためには、他のXHTMLエディタと組み合わせるかフォーマッタを拡張して使用する必要があります。
+
-ほとんどのプラグインはXHTMLには展開しません
+
--代わりに、他のXMLエディタで編集・置換できるようpukiwiki:plugin要素に変換します
+
--&amp;br;や&amp;smile;などの文字参照に類するもの、&amp;sub{};や#refなどはXHTMLに変換します
+
-装飾等は行いません
+
--LEFT: SIZE: &amp;color(){};といった記法で定義されているものは装飾済みのXHTMLに変換します
+

                  
+
またページ間のリンク等や添付ファイルの処理も行いません。
+
-エイリアス・ページ名などはアンカーには変換しません
+
--エイリアス・ページ名はプラグイン同様、pukiwiki:alias要素に変換します
+
--WikiNameは通常のテキスト、InterWikiは通常のアンカーとして変換します
+
-添付ファイルを扱う機能はありません
+
--添付ファイルのインポートを行うには[[PukiWikiはいかが? :: ハック/05-ファイル名コンバートツール:http://www.aksum.jp/pukiwiki/index.php?ハック/05-ファイル名コンバートツール]]で公開されているツール等をお使いください
+

                  
+
そのほかの注意点。
+
-CSV形式の表組み記法、入れ子になった記法など、一部未サポートの記法があります
+
-XHTMLでは表現できない要素(プラグインなど)には以下の接頭辞およびURIを用いています
+
--PukiWiki記法: 接頭辞pukiwiki, http://smdn.invisiblefulmoon.net/works/tools/pakina/notations#pukiwiki
+
--はてな記法: 接頭辞hatena, http://smdn.invisiblefulmoon.net/works/tools/pakina/notations#hatena
+
--これらの要素のDTDなどは用意していません
+

                  
+
***実装予定
+
-XHTML以外のフォーマットでの出力機能(HTML5、プレーンテキストなど)
+
-記法間の相互変換機能
+
-PukiWikiの$line_breakの設定をオプションで指定できるようにする
+
-はてな記法のパーサ・フォーマッタはおまけ程度に作ったもので、不完全です
+
--将来的にははてな記法のサポートを止めて、[[adiaryのさつき記法:http://adiary.org/parser/]]に置き換えるかもしれません
+

                  
+
なお、GUIは必要ないと思うので今のところ実装する予定はありません。
+

                  
+
**使い方の詳細
+
***入出力のオプション
+
:-i, -o|入力ファイル・出力ファイルを指定します。 省略した場合、もしくは'-'を指定した場合はファイルの代わりに標準入力・標準出力を使います。
+
:-if, -of|入力ファイル・出力ファイルの記法を指定します。 デフォルトは'pukiwiki'です。 最新のバージョンでは'pukiwiki'および'hatena'のみ使用可能です。
+
~--list-notationsで使用できる記法の一覧を表示します。
+
:-ie, -oe|入力ファイル・出力ファイルのエンコーディングを指定します。 入力のデフォルトはシステムで使われているエンコーディング、出力のデフォルトはUTF-8です。
+
出力ファイルにBOMを出力するかどうかも-oeオプションで指定できます。 詳しくは--list-charsetsで確認してください。
+

                  
+
***インデントと改行のオプション
+
:--no-indent|インデントおよび改行をしないようにします。
+
:--indent-spaces[=<number>]|空白を使用してインデントするようにします。 オプションで空白の個数を指定できます。
+
:--indent-tabs[=<number>]|タブを使用してインデントするようにします。 オプションでタブの個数を指定できます。
+
:--newline[=(CR/LF/CRLF)]|改行するようにします。 オプションで改行文字を指定できます。
+

                  
+
***XHTMLのオプション
+
:--title=<title>|<title>タグのテキストを指定します。 デフォルトでは入力ファイル名を使用します。
+
:--fragment|XML宣言と<html>タグおよび<head>タグを省略して出力します。 <body>タグのみが出力されます。
+
:--doc-element=<name>|--fragmentを指定した場合のみ有効です。 出力するXMLのルート要素の名前を指定します。 デフォルトはbodyです。
+
:--doc-namespace-uri=<uri>|--fragmentを指定した場合のみ有効です。 出力するXMLのルート要素の名前空間のURIを指定します。 デフォルトはXHTML(http://www.w3.org/1999/xhtml)です。
+
:--doc-prefix=<prefix>|--fragmentを指定した場合のみ有効です。 出力するXMLのルート要素の接頭辞を指定します。 デフォルトは指定なしです。
+
:--preserve-pre-whitespaces|<pre>タグに属性'xml:space="preserve"'を追加します。 XHTMLのDTDを参照しないXMLパーサが、<pre>タグ内の空白や改行を無意味なものと判断して勝手に削除してしまわないようにしたい場合などに指定します。
+

                  
+
***その他のオプション
+
:-h, --help|すべてのオプションとデフォルト値を表示します。
+

                  
+
***複数ページの一括変換(改ページ)
+
入力に改ページ(Form Feed, \u000c, Ctrl+L)の制御文字のみの行を含む場合、それを区切りとして複数のページを変換することが出来ます。 例えばスクリプトからいくつものページを変換したい場合などで改ページを用いると、ページ毎にpakinaを起動する場合よりもオーバーヘッドが減るのでより早く処理できます。
+

                  
+
改ページを用いた場合、入力に改ページが見つかった時点までのテキストを変換した結果が出力され、最後に改ページで終わる行が出力されます。 次のコードは、rubyスクリプトで複数のページを変換・表示する例です。
+
#code(rb){{
+
pages = [
+
<<PAGE1 ,
+
*page1
+
+test
+
++test
+
PAGE1
+

                  
+
<<PAGE2 ,
+
*page2
+
 pre
+
 pre
+
 pre
+
PAGE2
+

                  
+
<<PAGE3 ,
+
*page3
+
page3
+
PAGE3
+
]
+

                  
+
io = IO.popen("mono pakina.exe -if pukiwiki --fragment", "r+")
+

                  
+
pages.length.times do |i|
+
  io.write(pages[i])
+

                  
+
  if i == pages.length - 1
+
    io.close_write
+
  else
+
    io.puts "\x0c\n" # CTRL+L
+
  end
+

                  
+
  print "\n=========[page #{i}]=========\n"
+

                  
+
  while true
+
    line = io.gets
+

                  
+
    break unless line
+

                  
+
    ff = line.index("\x0c")
+

                  
+
    if ff
+
      print line[0, ff]
+
      break
+
    else
+
      print line
+
    end
+
  end
+
end
+

                  
+
io.close_read
+
}}
+

                  
+
出力結果はこのようになります。
+

                  
+
#prompt{{
+

                  
+
=========[page 0]=========
+
<body>
+
  <h2>page1</h2>
+
  <ol>
+
    <li>test<ol><li>test</li></ol></li>
+
  </ol>
+
</body>
+
=========[page 1]=========
+
<body>
+
  <h2>page2</h2>
+
  <pre>pre
+
pre
+
pre</pre>
+
</body>
+
=========[page 2]=========
+
<body>
+
  <h2>page3</h2>
+
  <p>page3</p>
+
</body>
+
}}
+

                  
+
なお、改ページを使う場合はページ毎にオプションを変えることはできません。
+

                  
+
**パーサ・フォーマッタの拡張方法
+
pakinaは実行ファイルのあるディレクトリとカレントディレクトリにあるアセンブリを読み込みます。 アセンブリにSmdn.Formats.Notations.Notationクラスの派生クラスが含まれている場合、そこからパーサ・フォーマッタを作成してpakinaで使用できるようになっています。
+

                  
+
***PukiWiki記法フォーマッタの拡張方法
+
ここでは例として, &amp;date;, &amp;time;, &amp;now;の各プラグインを現在の日付、時刻、日時を表すテキストに変換するように拡張する方法を紹介します。
+

                  
+
まずSmdn.Formats.Notations.PukiWiki.Notationクラスの派生クラスを作成し、拡張したフォーマッタExtendedPukiWikiXhtmlFormatterのインスタンスを返すようにします。
+
#code(cs){{
+
public class ExtendedPukiWikiNotation : Smdn.Formats.Notations.PukiWiki.Notation {
+
  public override Smdn.Formats.Notations.XhtmlFormatter CreateXhtmlFormatter()
+
  {
+
    return new ExtendedPukiWikiXhtmlFormatter();
+
  }
+
}
+
}}
+

                  
+
次に、ExtendedPukiWikiXhtmlFormatterの実装を記述します。 プラグインの場合、FormatPluginNodeメソッドをオーバーライドすることで任意の形式にフォーマットできます。
+
#code(cs){{
+
using System;
+
using System.Collections.Generic;
+
using System.Xml;
+

                  
+
using Smdn.Formats.Notations.PukiWiki;
+
using Smdn.Formats.Notations.PukiWiki.Dom;
+

                  
+
public class ExtendedPukiWikiXhtmlFormatter : Smdn.Formats.Notations.PukiWiki.XhtmlFormatter {
+
  protected override IEnumerable<XmlNode> FormatPluginNode(XmlDocument xml, Plugin plugin)
+
  {
+
    switch {
+
      case "date":
+
        return new XmlNode[] {xml.CreateTextNode(string.Format("built date: {0}", DateTime.Now.ToLongDateString()))};
+
      case "time":
+
        return new XmlNode[] {xml.CreateTextNode(string.Format("built time: {0}", DateTime.Now.ToLongTimeString()))};
+
      case "now":
+
        return new XmlNode[] {xml.CreateTextNode(string.Format("built: {0}", DateTime.Now.ToString()))};
+
      default:
+
        return base.FormatPluginNode(xml, plugin);
+
    }
+
  }
+
}
+
}}
+

                  
+
最後に、上記二つのコードを一つのアセンブリとしてコンパイルし、pakina.exeと同じディレクトリに配置します。 うまくいけば、--list-notationsで
+
#prompt{{
+
available notations:
+
  pukiwiki        ExtendedPukiWikiNotation
+
  hatena          Smdn.Formats.Notations.Hatena.Notation
+
total 2 notations
+
}}
+
のように表示されるはずです。 変換結果も、
+
#prompt{{
+
$ echo "&time;&br;&now;" | mono ./pakina.exe --fragment
+
<body>
+
  <p>built time: 17:44:33<br />built: 2009/06/07 17:44:33</p>
+
</body>
+
}}
+
となります。
+

                  
+
***独自のパーサ・フォーマッタの作成方法
+
準備中。 Smdn.Formats.Notations.PukiWikiのソースを参照してください。
+