この文書では、追跡データの仕様と、 追跡データから HTML ファイルを生成するツール twsk2html について述べる。
追跡データとは、旅行中に訪れた場所、移動した経路などの情報を 記録するために筆者が適当に定義したデータ形式である。 Twsk データまたは単に Twsk と呼ぶこともある。
後で説明する twsk2html というソフトウェアを用いることで、 追跡データから HTML ファイルを自動生成することができる。
追跡データの例を示す。:
- Area: <5,-34,-35,-74> Area.ja: ブラジル Area.en: Brazil - Subarea: <-16,-50,-24,-58> Subarea.ja: マット・グロッソ・ド・スウ州 Subarea.en: Mato Grosso do Sul - Date: 2008/06/08..10 Via: .. Ponta Porã <-22.54479449555067,-55.72486639022827> Distance: 35km/4h - Date: 2008/06/11 Via: .. <-22.360217,-55.22943> Via.ja: Ponta Porãから70km東 Via.en: 71km east from Ponta Porã Distance: 71km/5h - Date: 2008/06/12..13 Via: .. Dourados <-22.230841422237663,-54.81429398059845> Distance: 56km/5h - Date: 2008/06/14 Via: .. Rio Brilhante <-21.800711493211775,-54.537248611450195> Distance: 70km/5h - Date: 2008/06/15 Via: .. Anhanduí <-20.986194060556812,-54.50545907020569> Distance: 105km/8h ...
追跡データの形式は YAML に準拠している。YAMLにおける注意点として以下のことが挙げられる。
追跡データでは、最上位はリスト、リストの各要素はハッシュである。 それ以上のネストはしない。 最上位のリストの各要素を「Twsk 要素」または単に「要素」と呼ぶことにする。 また Twsk 要素であるハッシュのキーを「フィールド名」、 値を「フィールド値」、両方ペアで「フィールド」と呼ぶことにする。
追跡データの基本形式:
# Twsk 要素1 - フィールド名1: フィールド値11 # フィールド11 フィールド名2: フィールド値12 # フィールド12 ... # Twsk 要素2 - フィールド名1: フィールド値21 # フィールド21 フィールド名2: フィールド値22 # フィールド22 ... ...
注: YAMLではシャープ(#)から行末まではコメントである。
追跡データで正式に定義されているフィールドの種類を下表に示す。 実際にはこれ以外のフィールドを勝手に定義して使っても問題はない。 フィールド名は大文字、小文字の区別はしない。
| フィールド名 | フィールド値 |
|---|---|
| Index | 目次ページのタイトル |
| Area | エリア名とその座標 |
| Subarea | サブエリア名とその座標 |
| Date | 訪問日 |
| Via | 経由地および滞在地の地名とその座標。複数指定可。 |
| Distance | 移動距離、所要時間 |
| Note | 備考、メモ書きなど |
Via、Distance、Note は1セットで同一要素内に記述しなければならない。 残りのフィールドは同一要素に含めても良いし、別々の要素で記述しても良い。
Area、Subarea、Date フィールドは、最後に現れたフィールド値がそれ以降の データに対するデフォルト値である。 例えば以下のデータの場合、:
- Area: 岐阜県 - Date: 2010/03/10 Via: .. 岐阜市 - Date: 2010/03/11 Via: .. 美濃市 - Date: 2010/03/12 Via: .. 郡上市 - Area: 福井県 Date: 2010/03/13 Via: .. 大野市 - Date: 2010/03/14 Via: .. 勝山市
3/10の岐阜市、3/11の美濃市、3/12の郡上市まではエリアは岐阜県であり、 3/13の大野市、3/14の勝山市ではエリアは福井県となる。 但し、Subarea フィールドに値を指定したあと、Area フィールドが現れると Subarea フィールドの値はその時点で無効となる(クリアされる)。
情報として必要のないフィールドは記述する必要はないが、 最低限 Date と Via は記述しなければ追跡データの情報として意味がない。
各フィールドの使い方について以下に詳しく説明する。
twsk2html が生成する目次ページにつけるタイトルを指定する。:
- Index: 追跡ルートマップ
エリア名とその座標を以下の形式で記述する。:
エリア名 <緯度1,経度1,緯度2,経度2>
そのエリアを含む緯度範囲の最小値と最大値を緯度1と緯度2に記述する。 どちらが最小でどちらが最大でも構わない。 同様に、経度範囲の最小値と最大値を経度1と経度2に記述する。
緯度/経度の単位は「度」、度より細かい値は小数で記述する。 北緯と東経はプラス、南緯と西経はマイナスの数値で記述する。
例えば、エリア名が「カナダ」、緯度範囲が北緯41〜70度、 経度範囲が西経52〜143度のときは以下のように記述できる。:
- Area: カナダ <41,-52, 70,-143>
言い換えると、メルカトル図法の地図でそのエリアを囲む長方形の 右下角の座標が(41,-52)、左上角の座標が(70,-143)である。
座標(<...> の部分)は省略しても良い。 また、エリア名と緯度経度の位置は入れ換えて記述しても良い。:
- Area: <70,-143,41,-52> カナダ
これは言語別フィールドを使って複数の言語で地名を書くときに役に立つ。 詳しくは言語別フィールドの説明を参照。
日付を記述する。形式は YYYY/MM/DD または YYYY-MM-DD (YYYYは西暦の年、MMは月(1〜12)、DDは日にち(1〜31))。 年月(YYYY、MM)は省略することができ、その場合は直前に指定された 年月と同じであるとみなす。
開始日 .. 終了日 の形式により期間を表すこともできる。
以下は有効な Date フィールドの例である。:
- Date: 2010-03-01 # 2010年3月1日 - Date: 2010/3/1 # 2010年3月1日 - Date: 3/2 # 2010年3月2日 (年を省略) - Date: 3 # 2010年3月3日 (年月を省略) - Date: 2010/3/4..8 # 2010年3月4日〜2010年3月8日 - Date: 2010-3-9 .. 4-9 # 2010年3月9日〜2010年4月9日 - Date: 2010/4/10..2011/5/5 # 2010年4月10日〜2011年5月5日
経由地および滞在地の地名と座標を記述する。形式は:
コネクタ 地名 <緯度,経度>
を経由した地点の順に並べたもの。
コネクタは地図上でルートの描画方法を指示するためのものであり、 現状は以下のいずれかが定義されている。
先頭の地点のコネクタのみ省略可能であり、その場合は // となる。
地名と座標(<...> の部分)はどちらか一方を省略しても良い。 また、地名と座標の位置は入れ換えて記述しても良い。
具体例:
- Date 2010/04/01
Via: 岐阜 <35.409759, 136.756782>
.. 尾張一宮 <35.302062, 136.797509>
.. 名古屋 <35.171037, 136.881794>
- Date: 2010/04/02
Via: .. 金山 <35.143002, 136.901235>
.. 大府 <35.008522, 136.961832>
.. 刈谷 <34.990698, 137.009639>
- Date: 2010/04/03
.. 安城 <34.960316, 137.086544>
// 岡崎 <34.925736, 137.157568>
.. 蒲郡 <34.823069, 137.226362>
.. 豊橋 <34.762803, 137.382402>
この例では、4/1 は岐阜、尾張一宮を経由して名古屋まで移動し、 4/2 は金山、大府を経由して刈谷まで移動し、 4/3 は安城、岡崎、蒲郡を経由して豊橋まで移動したことを示している。 岐阜〜安城間および岡崎〜豊橋間はコネクタに .. が指定されているため、 地図上で地点間を結ぶ線が描画されることになる。 安城〜岡崎間はコネクタに // が指定されているため線は描画されない。
移動距離と所要時間を 距離/所要時間 の形式で記述する。 距離の単位 km、時間の単位 h をそれぞれ末尾に付加すること。 これらの単位より細かい数値は小数で記述する。
具体例としては 73km/6h, 125km/10.5h など。 所要時間は省略しても良い。
twsk2html では現状このフィールドは使用していない。
備考、メモ書きなど、任意の文字列を記述する。
twsk2html では現状このフィールドは使用していない。
フィールド名の後ろにピリオドと言語コードを付加したフィールドは、 言語別フィールドである。:
- Area: <35.124401, 136.235961, 36.493077, 137.723236> Area.ja: 岐阜県 Area.en: Gifu - Date: 2010/05/02 Via: .. <35.741113, 136.947584> Via.ja: 郡上市 Via.en: Gujo City
この例では、Area.ja には日本語のエリア名、Area.en には英語のエリア名を 記述している。言語コードの付いていない普通の Area には言語に依存しない情報、 ここでは座標を記述するために使用している。 Via フィールドについても同様である。
twsk2html では、 -l <言語コード> オプションにより出力する HTML ファイルの言語を選択できる。 例えば -l ja を指定すると、上の例は、:
- Area: <35.124401, 136.235961, 36.493077, 137.723236> 岐阜県 - Date: 2010/05/02 Via: .. <35.741113, 136.947584> 郡上市
と記述したのと同等に処理される。 (Area、Subarea、Via フィールドでは地名と座標の記述位置はどちらが先でも良い)。
ja や en などの言語コードは ISO 639 で定義されるものであること。
twsk2html は追跡データからHTMLファイルを生成するツールである。
とりあえず twsk2html を実行してみる。:
$ twsk2html
** No Twsk file specified
usage: twsk2html [options] <twsk_file> ...
-c <stylesheet> stylesheet (may appear more than once)
-d <dst_file_prefix> generated filename prefix []
-l <lang> language code []
-m <mode> mode (gmap2|gmap3) [gmap2]
-g <gmap_key> Google Maps API key (only for gmap2) []
-x Y1,X1,Y2,X2 initial view area on map [-90,-180,90,180]
-v print version
-w print verbose messages
何にしても入力データがなければ始まらない。 ここでは、以下のような追跡データを作成し、 ashiato.yml というファイル名で保存しておく。 文字コードは UTF-8 でなければならない。:
- Index.ja: 旅の足跡
Index.en: Footprint of my trip
- Area: <45.36, 146.25, 25.72, 126.73>
Area.ja: 日本
Area.en: Japan
- Subarea: <35.06, 136.23, 36.44, 137.73>
Subarea.ja: 岐阜県
Subarea.en: Gifu Pref.
- Date: 2001/5/29
Via: Gifu <35.4105, 136.7567>
- Date: 2001/5/30..31
Via: .. Gujo <35.7423, 136.9480>
- Date: 2001/6/1
Via: .. Shirakawa <36.2722, 136.8992>
- Subarea: <36.25, 136.75, 37.02, 137.81>
Subarea.ja: 富山県
Subarea.en: Toyama Pref.
- Date: 2001/6/2
Via: .. Takaoka <36.7413, 137.0159>
- Subarea: <36.61, 137.58, 38.58, 139.90>
Subarea.ja: 新潟県
Subarea.en: Niigata Pref.
- Date: 2001/6/3
Via: .. Kurobe(Toyama) <36.8705, 137.4348>
// Itoigawa <37.0439, 137.8612>
.. Naoetsu <37.1712, 138.2440>
- Date: 2001/6/4
Via: .. Niigata <37.9119, 139.0618>
twsk2html にこのファイル名 ashiato.yml を指定して実行してみる。 日本語のページを作成するために -l ja オプションを付ける。 何をしているか表示したいので -w オプションも付ける。:
$ twsk2html -l ja -w ashiato.yml -- twsk2html: parsing ashiato.yml -- twsk2html: creating 200105.html -- twsk2html: creating 200106.html -- twsk2html: creating index0.html -- twsk2html: linking month pages -- tunahtml: writing /home/fujiyosi/tmp/tmp/index0.html -- tunahtml: writing /home/fujiyosi/tmp/tmp/200105.html -- tunahtml: writing /home/fujiyosi/tmp/tmp/200106.html -- twsk2html: creating mapapi.js -- twsk2html: creating route.js -- twsk2html: creating map.html -- twsk2html: creating index.html
その結果、以下のファイルが作成された。:
index.html - フレームトップページのHTML index0.html - 目次ページのHTML 200105.html - 2001年5月のページのHTML 200106.html - 2001年6月のページのHTML map.html - 地図ページ mapapi.js - 地図ページで使うJavaScript route.js - ルートデータのJavaScript
ブラウザで index.html を開いてみる。 ウィンドウの左半分のフレームには目次ページが表示される。 右半分のフレームにはインターネットに接続されている環境では Google Maps の世界地図が表示されるはず。
大体こんな感じになっている。:
+-------------------------------+-------------------------------+ | 旅の足跡 | | | [前ページ][次ページ] | | | ----------------------------- | | | 旅の足跡 | | | | | | - 2001年5月 - 日本 | | | ~~~~~~~~~~~~~~~~ | Google Maps の地図 | | - 2001年6月 - 日本 | | | ~~~~~~~~~~~~~~~~ | | | ----------------------------- | | | 旅の足跡 | | | [前ページ][次ページ] | | | | | | | | | | | +-------------------------------+-------------------------------+
もし文字化けをしていたら、 ashiato.yml の文字コードが UTF-8 でない 可能性が高い。
目次の最初の項目をクリックすると2001年5月のページが左側のフレームに 表示される。:
+-------------------------------+-------------------------------+ | 旅の足跡 > 2001年5月 | | | [前ページ][次ページ] | | | ----------------------------- | | | 2001年5月 | | | | | | 日本 / 岐阜県 | | | ~~~~ ~~~~~~ | Google Maps の地図 | | 5/29 Gifu | | | ~~~~ | | | 5/30-31 Gujo | | | ~~~~ | | | ----------------------------- | | | 旅の足跡 > 2001年5月 | | | [前ページ][次ページ] | | | | | +-------------------------------+-------------------------------+
ここで「日本」をクリックしてみよう。 その結果、右側の地図がズームアップして日本列島が表示される。 また「岐阜県」をクリックすると岐阜県の周辺が表示される。 この表示範囲の座標は追跡データに記述した座標から得たものである。
地図上には岐阜市から新潟に向かって青い線が描かれている。 途中、富山県の黒部と新潟県の糸魚川の間だけ線が途切れている。 これは、追跡データの最後から二番目の要素の中で Itoigawa のコネクタが // になっているためである。 それ以外のところは .. になっているため線が引かれた。
「Gifu」をクリックすると、 地図で岐阜市の中心部あたりにマーカが表示される。 次に「Gujo」とクリックすると岐阜市のマーカが消えて郡上八幡のあたりに マーカが表示される。 表示されているマーカをクリックするとマーカが消える。 また、クリックした地名の場所が地図の範囲外のときは、 地図の表示が自動的にその場所に移動する。
左側のページの最上部と最下部に表示されているのはページ移動のための ナビゲーションである。 「次ページ」をクリックすると2001年6月のページが表示され、 「旅の足跡」をクリックすれば目次ページに戻る。
twsk2html [options] <twsk_file> ...
オプション:
-c <stylesheet> スタイルシート(複数回指定可)
-d <dst_file_prefix> 生成するファイル名のプリフィックス []
-l <lang> 言語コード []
-m <mode> モード (gmap2|gmap3) [gmap2]
-g <gmap_key> Google Maps API キー (gmap2モードのみ) []
-x Y1,X1,Y2,X2 地図の初期表示範囲の座標 [-90,-180,90,180]
-v バージョンを表示
-w 冗長メッセージを表示
<twsk_file> には追跡ファイル(追跡データを格納したファイル)を指定する。 追跡ファイルは複数指定することができ、指定した順に処理される。 追跡ファイルの文字コードは UTF-8 でなければならない。 それ以外の文字コードを使用している場合はあらかじめ UTF-8 に変換しておくこと。
以下にオプションの詳細を説明する。
HTML ファイル名の先頭に <dst_file_prefix> を付加する。 デフォルトでは何も付加しない。 twsk2html が生成するファイルは以下のものがある。
| ファイル名 | 役割 |
|---|---|
| index.html | フレームトップHTML |
| index0.html | 目次ページ |
| YYYYMM.html | 月別ページ。 YYYY は年4桁、 MM は月2桁。 例えば2006年4月のページは 200604.html となる。 |
| map.html | 地図ページ。Google Maps の地図を表示する。 |
| mapapi.js | 地図の表示&操作用の JavaScript の API |
| route.js | ルートデータの JavaScript |
例えば -d out- を指定したとき、ファイル名は out-index.html, out-index0.html, out-YYYYMM.html, out-map.html, out-mapapi.js, out-route.js となる。
ディレクトリを指定することも可能である。 例えば -d trace/ を指定するとディレクトリ trace が作られ、 その下にファイルが出力される。
このオプション以外にファイル名を変更する方法は今のところ無い。
言語コードを文字列 <lang> とする。 デフォルトは空文字列(但し、処理によっては en となる)。 <lang> は ISO 639 で定義される言語コードであり、 例えば ja は日本語、en は英語を表す。
例えば、追跡ファイルに言語別フィールドを持つ以下のような要素が 含まれているとき、:
- Area: <70,-143,41,-52> Area.ja: カナダ Area.en: Canada
オプション -l ja を指定すると Area: <70,-143,41,-52> カナダ 、 オプション -l en を指定すると Area: <70,-143,41,-52> Canada と記述したのと同等に処理される。 Area 以外のフィールドについても同じである。
現在の実装では <lang> が ja のときは月別ページのタイトルと ナビゲーションが日本語表記になるが、それ以外のときは英語になる。
地図ページのモードを指定する。現在サポートしているモードは以下の通り。
| <mode> | 意味 |
|---|---|
| gmap2 | Google Maps API バージョン2 を使用 (デフォルト) |
| gmap3 | Google Maps API バージョン3 を使用 |
モード(<mode>)が gmap2 のとき、 Google Maps API キーを指定する。 Google Maps API キーは、Google Maps のサイトから取得すること。
Google Maps API キーは昔はどうだったか良く知らないが、 現在は指定しなくても地図を表示できるようである(本当か?)。