uink version 0.0.2

      Copyright (C) Katsuhiro Ueno 2000
      Mar 13, 2000

      $Id: README-uink,v 1.2 2000/06/16 08:45:38 katsu Exp $


== 1. uink とは？

  uink は、テキスト文書を整形するためのプリプロセッサ(?) です。
  もはやプリプロセッサとは呼べないシロモノと化しているかもしれませんが、
  プリプロセッサを意識して作ったのは確かです。

  命令埋め込み型のプリプロセッサとは違い、実際の文書とは別に
  「テンプレート」を用意し、それを各文書に適用することで
  前処理や整形処理を行います。
  複数のテキスト文書のフォーマットを統一するのに最適です。
  反面、CGI 等の内容を動的に生成するような目的には向いていません。

  文書の構造を表現することを重視した XML/SGML とは畑が異なります。
  uink と XML/SGML をうまく組み合わせれば、XML/SGML で文書内容の
  構造化を図りつつ uink で XML/SGML ソースの体裁を保つ、といった
  こともできそうです。


== 2. 必要なモノ (多分)

  ruby-1.4.3 以降


== 3. インストール方法

  特になし。

  uink のパーミッションや最初の一行を適当に変更して
  パスの通ったディレクトリに置くとかすれば OK です。


== 4. 開発動機

  複数の文書を同じフォーマットに統一したい時ってよくあると思います。
  例えば「ヘッダーやフッターを統一したい、さらには将来の変更にも
  柔軟に対応したい」とか。こういう目的にはプリプロセッサを使ってやると
  作業量も減って幸せになれるのですが、いくつかプリプロセッサを
  物色しているうちに、疑問点や不満に思う点が出てきました。

  例えば…

    1. プリプロセッサの命令を覚えないと使えない。

         これは当たり前 (^^;。しかし、個人ではいいとしても
         複数人で文書を管理する時には問題になります。
         プリプロセッサの使える人だけが作業するか、
         全員がプリプロセッサの使い方を覚えないといけません。

    2. プリプロセッサが無いと使えない。

         これも当たり前なんですが(笑)、特にマイナーなものの場合は
         そのプリプロセッサが使える環境より使えない環境のほうが
         圧倒的に多いはず。複数人の場合は作業できる人が限定されて、
         1. と同じ理由でドツボ。

    3. プリプロセッサ命令が埋めこまれていて見にくい (or 醜い)。

         HTML 文書等のはっきり構造化された文書では
         プリプロセッサ命令によって構造が乱されてしまいます。
         編集後、直に文法チェッカーにかけられなくて、やる気喪失。
         ちゅーか、脇役に過ぎないはずなのに実際の文書の中身より
         しっかり自己主張するプリプロセッサ命令ってウザくない？(笑)

    4. ソースと出力の同期を取る必要がある。

         ソースをいくらいじってもプリプロセッサに通さなければ
         意味がありません。つまり、どんな些細な変更でも
         いちいちプリプロセッサを起動しないと出力を確認できないわけです。
         これが非常に面倒臭い。コンパイルは好きですか？

    5. 出力のほうに変更が加えられても対応できない。

         ソースに加えられた変更を出力に反映することはできても、
         出力に加えられた変更をソースに反映することは困難です。
         ソースと出力を管理する主体がそれぞれ異なる場合とかだと
         ひょっとするとヤバいかも。

  …などなど。

  既存のプリプロセッサは、このような問題点を抱えているものが
  ほとんどのように思いました。僕はこの問題のためにプリプロセッサを
  使うのを渋っていたんですが、そうこうしているうち、ある日突然、
  命令の埋め込みをやめればいいことに気づきました。

  その考え方を少し発展させ、具体的にカタチにしたのが uink です。
  従来の命令埋め込み型のプリプロセッサと違い、uink には
  次のような特長があります。

    1. 文書そのものは常に自己完結した形を保つ。

         uink によって文書の一部が削られたり、補助情報を追加されたり
         といったことはありません。
         uink を使うために命令を埋めこむ、といったこともありません。
         文書は常に uink から独立した形を維持します。

         おかげで、uink の使い方を知らなかろうが uink が
         使えない環境であろうが、はたまた将来 uink を使うのを
         やめようが (^^;;; 全然問題無しです。

    2. 出力をそのまま入力にできる。

         ソースを uink に通して得られた出力は、そのままで
         uink 可読の形式になっています。
         一旦出力を得られればソースは破棄しても構いません。

         ソースと出力が区分されないので、ソースと出力の同期を
         考える必要が無くなります。変更を加える対象は常に
         uink のソースです。

    3. 出力フォーマットを細かく指定できる。

         特に空白系は強いです。例えば、見出しの前の空行の数や
         インデントの深さ等を細かく制御することができます。
         XML & XSL 程の自由度は無いにせよ、文書を全く別の
         フォーマットに変換することもできます。


  さて、ここまで長々と開発動機なんかを書いてきたわけですけど、
  ダラダラと長いのにはワケがあります。
  こういった考え方や動作を簡潔に表す言葉が思いつかないんです (汗;;

  おかげで同種のプログラムが存在するかどうかを調べることが
  できないばかりか、スクラッチするにしろプログラム名をどうするか
  非常に悩みました。

  ワケの分からないコトバをいくつか考えてはみたんですが、
  結局「うまく言えないけど」から取って "uink"。
  「ウィンク」じゃありません。「ういんく」です。

  # ふつー頭の `u' は「う」と読まないらしい…
  # `u' を「ア」と読む場合は末尾の `k' を発音せずに `i' を長音化すると
  # いい感じかも(笑)。


  uink は (少なくとも僕にとっては) 非常に実験色の強いプログラムです。
  些細なことでも構いませんので、ご意見を頂ければ幸いです。


== 5. 使い方

  uink -h
  uink --help

    ヘルプメッセージを表示します。

  uink --version

    バージョン情報を表示します。

  uink [options] -s <template>

    <template> から新しい文書の雛型を作成します。

  uink [options] <template> <filename>

    <template> に従って <filename> を解析し、前処理を行います。

  [options] に指定できるオプションは次の通り。

    -J, -S, -E

      出力の文字コードを指定します。

        -J: ISO-2022-JP or ISO-2022-JP-2
        -S: shift JIS
        -E: EUC-JP

      uink の文字コードの処理には若干クセがあります。
      詳しくは後述します。(6. 参照)

    -U

      入力、出力共に UTF-8 であると仮定して処理します。
      Ruby を UTF-8 モード ($KCODE='U') に切り換えるだけで、
      文字コードの変換その他は行いません。

    -N

      文字コードに注意を払いません。
      Ruby 自体も漢字を処理しないモード ($KCODE='N') になります。

    -o

      処理が正常に終了した場合、出力でソースを上書きします。
      前のソースはファイル名の末尾に ~ をつけて保存されます。

    -O

      -o と同じですが、バックアップを残しません。

    -D VAR1=VAR2

      不定部分 VAR1 に不定部分 VAR2 の内容をコピーします。
      テンプレート内の %% sync の `=' 指定と同じです。

      -t オプションを使用する際、不定部分の対応を部分的に変更するのに
      使用すると便利です。

    -t <dest-template>

      文書のフォーマットを <template> から <dest-template> に
      変換します。具体的には、<template> を用いて <filename> を
      解析した後 <dest-template> を用いて出力します。

      <dest-template> 内の不定部分は、ブロックと名前の対応する
      <template> の不定部分で埋められます。対応する不定部分が
      存在しない場合はエラーとなります。


== 6. 文字コードに関する注意

  uink は入力ファイルで使われている文字コードを自動認識し、
  一旦 EUC-JP に変換してから処理しています。
  ただし、G2 領域 (いわゆる半角カナのコード領域) を EUC-JP で
  表現できない文字をエスケープする領域として利用しているため、
  半角カナの使用には注意する必要があります。

  Shift JIS や EUC-JP のみで使用するのであれば特に問題はありませんが、
  ISO-2022-JP 系のコードが絡んでくる場合は半角カナを正しく処理できません。
  その代わり ISO-2022-JP-2 に含まれる EUC-JP で表現できない文字は
  正しく処理できます。(エラーメッセージは化けます)


  半角カナの使用について:

     入力 ＼ 出力  |  EUC-JP  | ShiftJIS | ISO-2022-JP 系
    ---------------+----------+----------+----------------
        EUC-JP     |    ○    |    ○    |      ×
       ShiftJIS    |    ○    |    ○    |      ×
    ISO-2022-JP 系 |    ×    |    ×    |      ○ (*)

     ○ … 半角カナを正しく処理できる
     × … 半角カナを使うと文字化け等が起こる

     (*) ちゅーか ISO-2022-JP の仕様では半角カナは使えません(笑)


  -U または -N オプションをつけて起動した場合は、
  文字コードの判別・変換を行いません。


== 7. uink を使った生活

  1. まずは、テンプレートを用意しましょう。
     スクラッチするより既存の文書から起こしたほうが楽なようです。
     テンプレートの書き方については Manual.ja を参照して下さい。
     例として、この README のテンプレートが example/readme.kat に
     あります。

  2. uink -s で雛型を作成します。
     出力された雛型を元に、適当に文書を書きます。
     テンプレートの書き方にもよりますが、厳密にテンプレートに沿って
     書く必要はありません。ある程度は uink が補正してくれます。
     uink -s example/readme.kat とした結果が example/example1.txt、
     それを編集した例が example/example2.txt です。

  3. 書いた文書を uink に通します。
     uink はテンプレートに従って文書を整形し、出力します。
     例えば、uink example/readme.kat example/example2.txt とすると
     example/example3.txt のような出力を得られます。

  4. 正しい出力を得られたなら、ソースは破棄しても構いません。
     むしろ積極的に破棄することをお薦めします。
     得られた出力はそのまま uink のソースとしても使えますので、
     今後文書を変更する際には、この出力に対して変更を行います。
     example3.txt にさらに変更を加えた例が example/example4.txt です。

  5. 変更を加えた後、再び uink に通します。
     出力はまた uink のソースになります…と、このように 4. と 5. の
     作業を延々と繰り返すことで、文書を作成するわけです。
     example/example4.txt を uink に通すと example/example5.txt を
     出力します。


  6. 文書のフォーマット自体を変更したい場合、パターンマッチに
     影響を及ぼさないような些細な変更であれば (空行や空白の数等)
     テンプレートを直接修正することで対応できます。
     そうでなければ、新しくテンプレートを用意し -t オプションを
     用いてテンプレートの変換を行います。
     example5.txt を readme.kat から example/readme2.kat に変換した
     結果が example/example6.txt です。
     コマンドラインは、
       uink readme.kat -t readme2.kat -D Footer:copyright=Header:copyright
       example6.txt
     こんな感じ。(-D オプションがミソ)


== 8. ToDo

  (-) ちゃんとしたマニュアルを書く。 (^^;;;;
  (-) 用語の選択や使い方が甘いような気もする。
  (-) テンプレートのインクルード、インポート機能。
  (-) センタリングとか？ plain2 的な要素を盛り込むと良さげかも。
  (-) ブロックの補完とかもできるかも？
  (-) 条件分岐 (if 〜 else 〜 endif) とかも必要？
  (-) なんだか全体的にアクが強いような気がする。
      細部を調整する必要あり。
  (-) なんといっても遅い。重い。まぁ、テキスト全体を
      二次元的な正規表現 (おぉ、なんかカッコイイ :-) に
      マッチさせようとしている訳だから、やってる事自体がかなり
      キツいんだけど、もうちょっと何とかしたいっすね。


== 9. 配布条件

  Ruby の配布条件と同じです。


----
last modified on: Mon Jun 12 17:35:51 JST 2000