tunahtml - HTMLリンカ

概要

tunahtml は複数の HTML ファイルをリンクするツールである。 ユーザが記述したコンフィグスクリプトの内容に従い、 HTML ファイルの中にページ移動のためのリンクを埋め込む。

使用例

今、カレントディレクトリに以下の HTML ファイルが置いてあったとする。

それぞれは独立した HTML ファイルであり、 ウェブブラウザでページの内容を表示することができるが、 ハイパーリンクされていないためページ間で移動することができないものとする。 また、HTML ファイルの文字コードは全て UTF-8 とする。

ここで、同じディレクトリに以下のような内容のファイル (コンフィグファイル)を作成する。 ファイル名は config.rb としておこう。:

lang "ja"
page {
  file "index.html"
  page { file "canada.html" }
  page { file "usa.html" }
  page { file "mexico.html" }
  page { file "route-canada.html" }
  page { file "route-usa.html" }
  page { file "route-mexico.html" }
}

このファイルはページ間の階層構造の関係を表している。 最上位に index.html (トップページ)、 その一段下に残りのページが入るような関係である。

ファイルを作成したら、次のコマンドを実行する。:

$ tunahtml -f config.rb

その結果、以下のファイルが新しく生成された。

これらは、元のファイル名の先頭に tuna- を付加したものであり、 元のファイルを加工した結果が格納されている。

tuna-index.html をブラウザで開くと以下のような内容のページが表示される。:

トップページ                                 ← (1) ナビゲーション
[前ページ] [次ページ]
-------------------------------------------
ここはサンプルデータのトップページです。     ← (2) 元からあった部分

 - カナダの基本情報
   ~~~~~~~~~~~~~~~~
 - アメリカの基本情報
   ~~~~~~~~~~~~~~~~~~
 - メキシコの基本情報                        ← (3) 目次
   ~~~~~~~~~~~~~~~~~~
 - カナダのルートデータ
   ~~~~~~~~~~~~~~~~~~~~
 - アメリカのルートデータ
   ~~~~~~~~~~~~~~~~~~~~~~
 - メキシコのルートデータ
   ~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------
トップページ                                 ← (4) ナビゲーション
[前ページ] [次ページ]

このうち、元の index.html に書かれていたのは (2) の部分のみであり、 (1)と(4)のナビゲーション、(3)の目次は tunahtml により挿入されたものである。 目次は下位ページへのリンクになっている。

ところで、目次の中の「カナダの基本情報」などの文字列は、 HTML ファイルの <title> 要素から抽出したものである。 同様にナビゲーション部の「トップページ」は index.html の <title> 要素から抽出したものである。

では、目次の中の「アメリカの基本情報」のリンクをクリックしてみる。 その結果、tuna-usa.html の内容が表示される。:

トップページ > アメリカの基本情報            ← (1) ナビゲーション
~~~~~~~~~~~~
[前ページ] [次ページ]
~~~~~~~~~~ ~~~~~~~~~~
-------------------------------------------
アメリカの基本情報

田舎には白人が多いが都市に入ると急激に黒人   ← (2) 元からあった部分
が増える。しかし中国人はどこにでもいる。

田舎には変な警察官がいるので気をつけた方が
良い。

レストランでチップを払う必要はない。

-------------------------------------------
トップページ > アメリカの基本情報            ← (3) ナビゲーション
~~~~~~~~~~~~
[前ページ] [次ページ]
~~~~~~~~~~ ~~~~~~~~~~

このページには下位ページがないため目次は挿入されていない。 一方、ナビゲーションにはトップページと現ページのタイトルが表示されている。 「トップページ」をクリックすれば tuna-index.html に戻る。 2行目の「前ページ」をクリックすると tuna-canada.html へ、 「次ページ」をクリックすると tuna-mexico.html へジャンプする。

コマンドの使い方

コマンドの使い方:

tunahtml [options] [<target_file or dir> ...]

options:
  -e <config_script>  コンフィグスクリプト (複数回現れてもよい)
  -f <config_file>    コンフィグファイル (複数回現れてもよい)
  -v                  バージョン表示
  -w                  冗長メッセージ表示

tunahtml は、-e および -f オプションで指定された コンフィグスクリプトを全て評価したあと、 その結果に従ってリンク処理を行ない、加工したファイルを出力する。

-e および -f オプションは複数回現れてもよく、現れた順に評価される。 コンフィグスクリプトの書き方については次節で説明する。

-e <config_script>

評価するコンフィグスクリプトを文字列で直接指定する。

使用例:

$ tunahtml -e 'page{file "canada.html"}; page{file "usa.html"}'

この例の場合、以下のようにスクリプトを分解して指定してもよい。:

$ tunahtml -e 'page{file "canada.html"}' -e 'page{file "usa.html"}'

1つ目のスクリプトは tunahtml が起動したときのカレントディレクトリで 評価される。各スクリプトの終了時のカレントディレクトリがそのまま 後続のスクリプト評価時のカレントディレクトリとなる。:

$ pwd
/home/fujiyosi/tmp
$ tunahtml -e 'puts Dir.pwd; Dir.chdir "/usr"' -e 'puts Dir.pwd'
/home/fujiyosi/tmp
/usr

コンフィグスクリプトの文字コードは UTF-8 でなければならない。

-f <config_file>

コンフィグファイル(＝コンフィグスクリプトを格納したファイル)を指定する。

使用例:

$ tunahtml -f ~/www/ja/config.rb -f ~/www/en/config.rb

この例では、~/www/ja/config.rb と ~/www/en/config.rb が 順に評価される。

各コンフィグファイルが評価されるとき、カレントディレクトリは そのコンフィグファイルと同じディレクトリにセットされ、 評価が終了すると元のディレクトリに戻る。 そのため、コンフィグファイルの中でカレントディレクトリを変更しても 他のスクリプトの評価には影響しない。

コンフィグファイルの文字コードは UTF-8 でなければならない。

オプション -e と -f を一緒に使用する例を以下に示す。:

$ tunahtml -e 'lang "ja"; dst_default nil' -f config.rb

最初に lang "ja" により言語を日本語に設定し、 dst_default nil により HTML ファイルの上書きを指示した上で config.rb を評価している。

<target_file or dir>

コンフィグスクリプトで定義された内部リンクページのファイルのうち、 実際に加工して出力するファイル名を指定する。 ディレクトリ名を指定したときは、そのディレクトリより下の全ての ファイルが対象となる。 1つも指定しなかったときは全てのファイルが対象となる。

存在しないファイル名を指定するとエラーになる。 存在するファイルかディレクトリであれば、 コンフィグファイル内で定義されていなくてもエラーにはならない。

例:

$ cat config.rb
dst_default nil
page {
  file "index.html"
  page { file "canada.html" }
  page { file "usa.html" }
  page { file "mexico.html" }
  page { file "route/route-canada.html" }
  page { file "route/route-usa.html" }
  page { file "route/route-mexico.html" }
}

$ tunahtml -f config.rb index.html route

この例では、index.html、 route/route-canada.html、 route/route-usa.html、route/route-mexico.html は加工されるが、 canada.html、usa.html、mexico.html は加工されない。

コンフィグスクリプトの書き方

tunahtml のプログラムは Ruby で書かれている。 そして、コンフィグスクリプトもまた Ruby のスクリプトである。 tunahtml では、あるインスタンスメソッドの中で instance_eval() を使ってコンフィグスクリプトの内容を評価している。 従って、Ruby でインスタンスメソッドの定義の中で使える記述は全て有効である。

例えば、最初の例で使用したコンフィグスクリプト:

lang "ja"
page {
  file "index.html"
  page { file "canada.html" }
  page { file "usa.html" }
  page { file "mexico.html" }
  page { file "route-canada.html" }
  page { file "route-usa.html" }
  page { file "route-mexico.html" }
}

は、以下のように書き換えることもできる。:

lang "ja"
page {
  file "index.html"
  kuni = ["canada", "usa", "mexico"]
  kuni.each {|k| page {file "#{k}.html"} }
  kuni.each {|k| page {file "route-#{k}.html"} }
}

余計にややこしくなった感じもするが、 ファイル数が増えてくるとこのようなやり方は有用である。

コンフィグスクリプトでは、コンフィグ用のメソッドを用いてページ間の 階層構造と各ページのファイル名などの属性を設定していく。 コンフィグ用メソッドの一覧を下表に示す。

page、include、root 以外のメソッドは 引数を指定したらその値を設定し、 引数を指定しなければ現在の設定値を返す。 Ruby で一般的に使われる 属性=(値) 形式のセッターは定義されない。

dst_default、index_depth、lang の設定値は、 上位ページの設定値が下位ページでの初期値として引き継がれる。 下位ページで行なった設定が上位ページに影響することはない。

コンフィグスクリプトの文字コードは UTF-8 でなければならないので注意。

dst_default nil
page {
  title("トップページ"); file("index.html")
  page { title("カナダ"); file("canada.html") }
  page { title("アメリカ"); file("usa.html", :nolink) }
  page { title("メキシコ"); file("mexico.cgi?mode=1", :nolink) }
  page {
    title("ベリーズ")
    file("http://en.wikipedia.org/wiki/Belize", :extern)
  }
}

- カナダ      ← "canada.html" へのリンク
  ~~~~~~
- アメリカ    ← "usa.html" へのリンク。別ウィンドウで表示
  ~~~~~~~~
- メシキコ    ← "mexico.cgi?mode=1" へのリンク。別ウィンドウで表示
  ~~~~~~~~
- ベリーズ    ← "http://en.wikipedia.org/wiki/Belize" へのリンク。
  ~~~~~~~~       別ウィンドウで表示

HTMLファイルの加工内容

内部リンクページには目次とナビゲーションが挿入される。

加工前の HTML ファイルの文字コードは UTF-8 を前提としている。 それ以外の文字コードのファイルは、加工した際に文字化けを起こすかも知れない。

目次部とナビゲーション部には XHTML 形式のデータが挿入される。 XHTML とそうでない HTML のデータが混在していてもブラウザは期待通り 表示してくれるとは思うが、自信はない。

目次

HTMLボディの末尾に以下のような形で挿入される。:

<div class="tunahtml-toc">
  <ul>
    <li>
      <a href="ファイル1">タイトル1</a>
      <ul>
        <li><a href="ファイル2">タイトル2</a></li>
        <li><a href="ファイル3">タイトル3</a></li>
        ...
      </ul>
    </li>
    <li>
      ...
    </li>
    ...
  </ul>
</div>

ファイル1、ファイル2、... は下位ページのファイルへの相対パス、 タイトル1、タイトル2、... はそれらのページタイトルである。 擬似ページならば <a> 要素はなく単にタイトル文字列が入るだけである。

但し、<div class="tunahtml-toc ..."> の要素が既に存在するときは、 その <div> 要素が上記の内容に書き換えられる。位置は移動しない。

上部ナビゲーション

HTMLボディの先頭に以下のような形で挿入される。:

<div class="tunahtml-head tunahtml-navi">
  <p>
    <a href="ファイル名1">タイトル1</a> &gt;
    <a href="ファイル名2">タイトル2</a> &gt;
    ...
  </p>
  <p>
    <a href="前頁のファイル名">[前ページ]</a>
    <a href="次頁のファイル名">[次ページ]</a>
  </p>
  <hr />
</div>

ファイル名1、ファイル名2、... には上位ページのファイルへの相対パス、 タイトル1、タイトル2はそれらのページタイトルである。 擬似ページならば <a> 要素はなくタイトル文字列が入るだけである。

但し、<div class="tunahtml-head ..."> の要素が既に存在するときは、 その <div> 要素が上記の内容に書き換えられる。位置は移動しない。

下部ナビゲーション

HTMLボディの末尾に以下のような形で挿入される。:

<div class="tunahtml-tail tunahtml-navi">
  <hr />
  <p>
    <a href="ファイル名1">タイトル1</a> &gt;
    <a href="ファイル名2">タイトル2</a> &gt;
    ...
  </p>
  <p>
    <a href="前頁のファイル名">[前ページ]</a>
    <a href="次頁のファイル名">[次ページ]</a>
  </p>
  <hr />
</div>

中身は上部ナビゲーションと同じである。

但し、<div class="tunahtml-tail ..."> の要素が既に存在するときは、 その <div> 要素が上記の内容に書き換えられる。位置は移動しない。

問題点・課題・検討事項など

• タイトル文字列の抽出と目次とナビゲーションの挿入処理は 適当な正規表現によるインチキ暫定版。 そのため、HTMLファイルの内容によっては上手く行かない可能性が残っている。 しかし、一部のファイルのためだけにクソまじめにパーシングすることで 全部の処理時間が増えるのは嬉しくない。
• コンフィグファイルのエラーで全バックトレースが表示されるのはうっとおしい。 コンフィグファイルのところまででバックトレースを打ち切るにはどうすれば良い？
• [次ページ][[前ページ]などの言語依存の文字列は設定可能にしたい。
• フレームページもリンクセットに入れられる仕組が欲しい。 また、CGI や PHP のページだってフレーム使えばやってでけんことはないはず。
• index_depth で指定すべき目次の深さは2種類ある。 1つはカレントページに挿入する目次の最大深さの指定。 もう1つは上位ページの目次にカレントページより下をどの深さまで 見せるかの指定。現在は両者がごちゃまぜになっている。