このドキュメントでは、写真管理用データ形式 Fokan と、 Fokan データから HTML ファイルを生成するツール fokan2html について述べる。
目次
Fokan とは、筆者がアメリカ大陸を自転車で旅行したときにデジカメで撮影した 大量の写真を管理するために定義したデータ形式である。 写真管理 → Photograph Kanri → Fokan。 後で説明する fokan2html というソフトウェアを用いることで Fokan データから HTML ファイルを自動生成することが出来る。
Fokan データの例を示す。:
- Title.ja: チリ / サンティアゴ州 Title.en: Chile / Santiago - Foto: imgp0149 imgp0151 Date: 2007-10-23 Desc: Santiago, Aeropuerto Comodoro Arturo Merino Benitez, Desc.ja: サンティアゴに到着。荷物受取り場 Desc.en: Arrived at Santiago. - Foto: imgp0152 Date: 2007-10-23 Desc: Santiago, Aeropuerto Comodoro Arturo Merino Benitez, Desc.ja: 空港の前 Desc.en: Front of the airport. - Foto: imgp0153 imgp0154 imgp0155 imgp0156 Date: 2007-10-23 Desc: Santiago, Desc.ja: 空港からサンティアゴ市街への道 Desc.en: Way from airport to Santiago city center. ...
これだけ見れば意味も書き方も大体想像できると思う。 詳しくは次項に記載する。
Fokan データの形式は YAML に準拠している。YAMLにおける注意点として以下のことが挙げられる。
Fokan データでは、最上位はリスト、リストの各要素はハッシュである。 それ以上のネストはしない。 最上位のリストの各要素を「Fokan 要素」または単に「要素」と呼ぶことにする。 また Fokan 要素であるハッシュのキーを「フィールド名」、 値を「フィールド値」、両方ペアで「フィールド」と呼ぶことにする。
Fokan データの基本形式:
# Fokan 要素1 - フィールド名1: フィールド値11 # フィールド11 フィールド名2: フィールド値12 # フィールド12 ... # Fokan 要素2 - フィールド名1: フィールド値21 # フィールド21 フィールド名2: フィールド値22 # フィールド22 ... ...
注: YAMLではシャープ(#)から行末まではコメントである。
Fokan で使用できるフィールドの種類を下表に示す。
| フィールド名 | フィールド値 |
|---|---|
| Index | 目次ページのタイトル |
| Title | セクションタイトル |
| Sub | サブセクションタイトル |
| Foto | 写真ファイル名(複数指定可) |
| Date | 写真の日付 |
| Desc | 説明 (単体または他フィールドと組合せて使う) |
このうち、Index、Title、Sub、Foto は同一要素内に混在してはならない。
各フィールドの使い方について以下に詳しく説明する。
fokan2html が生成する目次ページにつけるタイトルを指定する。 Index フィールドと同じ要素内にある Desc フィールドには 目次ページに挿入する説明文を記述できる(現在未実装)。:
- Index: アメリカ大陸自転車旅行の写真 Desc: 全部で10000枚くらいあります。気長に見てね。
セクションタイトルを指定する。 Title フィールドを含む要素から次の Title フィールドを含む 要素の直前までが1つのセクションである。 Title フィールドと同じ要素内にある Desc フィールドには そのサブセクションに対する説明を記述できる。:
- Title: カナダ Desc: このページにはカナダで撮った写真を載せてあります。
サブセクションタイトルを指定する。 Sub フィールドを含む要素から次の Sub または Title フィールドを含む要素の直前までが1つのサブセクションである。 Sub フィールドと同じ要素内にある Desc フィールドには そのサブセクションに対する説明を記述できる。:
- Sub: バンクーバ近郊
Desc: バンクーバから200km西のホープまでは平地である。
ホープから先は渓谷の道で徐々に標高を上げていく。
カムループスまで高速道路が並行しているためか、
一般ハイウェイの交通量は少ない。
写真ファイル名を指定する。 複数のファイル名を空白で区切って記述することが出来る。 Foto フィールドと同じ要素内にある Date フィールドには写真を撮った 日付を記述でき、Desc フィールドには写真の説明を記述できる。:
- Foto: imgp0001.jpg Date: 2010-03-01 Desc: バンクーバ市街 - Foto: imgp0002.jpg imgp0003.jpg imgp0004.jpg Date: 2010-03-01 Desc: バンクーバ 〜 メープル・リッジ間 - Foto: imgp0005.jpg imgp0006.jpg Date: 2010-03-02 Desc: ここで野宿
この例を見ると、全てのファイル名には拡張子 .jpg が付いているが、 .jpg が無くても実際のファイルを一意に特定することが出来そうである。 そのような場合、 .jpg を省略して記述しても良い。:
- Foto: imgp0001 Date: 2010-03-01 Desc: バンクーバ市街 - Foto: imgp0002 imgp0003 imgp0004 Date: 2010-03-01 Desc: バンクーバ 〜 メープル・リッジ間 - Foto: imgp0005 imgp0006 Date: 2010-03-02 Desc: ここで野宿
でも、もし imgp0001.png という写真ファイルが同じ Fokan データの中に 存在する場合は imgp0001 の実際のファイル名が imgp0001.jpg なのか imgp0001.png なのか特定できなくなるので省略してはいけない。
同じ Fokan データの中に拡張子付きのファイル名と拡張子無しの ファイル名を混在させてはいけない。以下の例は不正である。:
- Foto: imgp0001.jpg # こっちは拡張子付きなのに Date: 2010-03-01 Desc: バンクーバ市街 - Foto: imgp0002 imgp0003 imgp0004 # こっちは拡張子がない。これは不正 Date: 2010-03-01 Desc: バンクーバ 〜 メープル・リッジ間
この例のように全てのファイル名が imgp で始まっているのならば imgp も省略して 0001, 0002 のように書くことも出来る。
写真ファイル名の先頭にピリオド(.)を付加すると、 fokan2html はそのファイルを隠しファイルとして処理する。 fokan2html のデフォルトでは隠しファイルの写真は HTML ページの中には 含まれない(-a オプションで含まれるようになる)。:
- Foto: .imgp0001 Date: 2010-03-01 Desc: バンクーバ市街 - Foto: imgp0002 .imgp0003 imgp0004 Date: 2010-03-01 Desc: バンクーバ 〜 メープル・リッジ間 - Foto: imgp0005 imgp0006 Date: 2010-03-02 Desc: ここで野宿
この例では、 imgp0001.jpg と imgp0003.jpg が隠しファイル として扱われる。 fokan2html に -a オプションを付けなかった場合、 これらのファイルはHTML ページからは除去される。 先頭の要素は有効なファイル名がないため、その要素自体が除去される。 なお、この機能があるため、ファイル名の先頭にピリオド(.)を使えない制約あり。
単体または他のフィールドとの組合せで使用する。
上記のフィールド名の後ろにピリオドと言語コードを付加したフィールドは、 言語別フィールドである。:
- Foto: imgp0001 Date: 2010-03-01 Desc.ja: バンクーバ市街 Desc.en: In Vancouver city. - Foto: imgp0002 imgp0003 imgp0004 Date: 2010-03-01 Desc: BC-HWY7, Desc.ja: バンクーバ 〜 メープル・リッジ間 Desc.en: from Vancouver to Maple Ridge. - Foto: imgp0005 imgp0006 Date: 2010-03-02 Desc: Maple Ridge, Desc.ja: ここで野宿 Desc.en: Sleeped here.
この例では、Desc.ja は日本語の説明、Dessc.en は英語の説明を記述する ために使用している。言語コードの付いていない普通の Desc は、 全ての言語に共通な説明を記述するために使用する。
fokan2html では、 -l <言語コード> オプションにより生成するページの 言語を選択できる。例えば -l ja を指定すると、上の例では順に:
バンクーバ市街 BC-HWY7, バンクーバ 〜 メープル・リッジ間 Maple Ridge, ここで野宿
がそれぞれ写真の説明文として HTML ファイルに格納される。
他のフィードでも同様に言語別フィールドを記述できる。 例えば Foto フィールドで以下のように指定すれば、:
- Foto.ja: imgp0001 Foto.en: imgp0002
fokan2html のオプション -l ja を指定したときは imgp0001 の写真が、 -l en を指定したときは imgp0002 の写真が HTML ページに組み込まれる (確認してないけど、たぶん)。
ja や en などの言語コードは ISO 639 で定義されるものであること。
fokan2html は Fokan データから HTML ファイルを生成するツールである。
とりあえず fokan2html を実行してみる。:
$ fokan2html
usage: fokan2html [options] file ... [options] file ... ...
-a embed all photos including hidden photos
-A do not embed hidden photos (default)
-c <stylesheet> stylesheet (may appear more than once) []
-d <dst_file_prefix> generated file prefix []
-i <index_file> index page file [<dst_file_prefix>index.html]
-l <lang> language code []
-n <max_elems> max number of elements per page [20]
-p <emb_foto_prefix> embeded photo file prefix []
-s <emb_foto_suffix> embeded photo file suffix []
-P <ext_foto_prefix> external photo file prefix []
-S <ext_foto_suffix> external photo file suffix []
-Q disable external photo (default disabled)
-v print version
-w print verbose messages
何にしても入力データがなければ始まらない。 前提として、今カレントディレクトリに以下の写真ファイルがあるとする。:
$ ls imgp0001.jpg imgp0003.jpg imgp0005.jpg imgp0002.jpg imgp0004.jpg imgp0006.jpg
そして、これらの写真を説明する以下のような Fokan ファイル (Fokan データを格納したファイル)を同じディレクトリに作成する。 このファイルの文字コードは UTF-8 でなけれならない。 ファイル名は canada-foto.yml としよう。:
- Title.ja: カナダの写真 Title.en: Pictures of Canada - Foto: imgp0001 Date: 2010-03-01 Desc.ja: バンクーバ市街 Desc.en: In Vancouver city. - Foto: imgp0002 imgp0003 imgp0004 Date: 2010-03-01 Desc: BC-HWY7, Desc.ja: バンクーバ 〜 メープル・リッジ間 Desc.en: from Vancouver to Maple Ridge. - Foto: imgp0005 imgp0006 Date: 2010-03-02 Desc: Maple Ridge, Desc.ja: ここで野宿 Desc.en: Sleeped here.
fokan2html にこのファイル名を指定して実行してみる。 何をしているか表示したいので -w オプションも付ける。:
$ fokan2html -w canada-photo.yml -- fokan2html: parsing canada-photo.yml -- fokan2html: creating 001-001.html -- fokan2html: creating index.html $ ls 001-001.html imgp0002.jpg imgp0005.jpg canada-photo.yml imgp0003.jpg imgp0006.jpg imgp0001.jpg imgp0004.jpg index.html
表示された通り、2つのファイル 001-001.html と index.html が作られた。 001-001.html が写真ページ、 index.html が全体の目次である。 ウェブブラウザで index.html を開いてみる。:
Index
1. no title
~~~~~~~~
no title って何だ? まあいいや。 no title のリンクをクリックすると 001-001.html の内容が表示される。:
no title [2010-03-01] imgp0001 BC-HWY7, [2010-03-01] imgp0002 imgp0003 imgp0004 Maple Ridge, [2010-03-02] imgp0005 imgp0006
残念ながら写真は表示されず、 代わりにファイル名がそのまま表示されただけである。
上手く行かない理由を書くのが面倒なので正解を示す。 こうやればいい。:
$ fokan2html -w -l ja -s .jpg canada-photo.yml -- fokan2html: parsing canada-photo.yml -- fokan2html: creating 001-001.html -- fokan2html: creating index.html
オプション -l ja は言語コード ja の指定、 -s .jpg は ファイル名の末尾に .jpg を付加することを指示するものである。 ブラウザで index.html を開いてみよう。:
Index
1. カナダの写真
~~~~~~~~~~~~
今度は上手くいった。 「カナダの写真」のリンクをクリックすると 001-001.html にジャンプする。 さっきはファイル名しか表示されていなかったところに写真が表示される はずである。
オプション -l ja の代わりに -l en を指定すると 同じファイル名で英語ページが作成されるのだが、 ここでは別のファイル名に出力してみよう。 -d オプションを使用する。:
$ fokan2html -w -l en -s .jpg -d en/ canada-photo.yml -- fokan2html: parsing canada-photo.yml -- fokan2html: creating en/001-001.html -- fokan2html: creating en/index.html
ディレクトリ en が作られ、その下にファイルが生成された。 en/index.html をブラウザで開いてみる。:
Index
1. Pictures of Canada
~~~~~~~~~~~~~~~~~~
そして、リンクをクリックと en/001-001.html の内容が表示される。:
Pictures of Canada In Vancouver city. [2010-03-01] imgp0001.jpg BC-HWY7, from Vancouver to Maple Ridge. [2010-03-01] imgp0002.jpg imgp0003.jpg imgp0004.jpg Maple Ridge, Sleeped here. [2010-03-02] imgp0005.jpg imgp0006.jpg
ファイル名が表示されるだけで写真は表示されない。 001-001.html が置かれているディレクトリと写真ファイルが 置かれているディレクトリが異なるためである。 写真ファイル名の頭に ../ を付加するために -p オプションを使用する。:
$ fokan2html -w -l en -s .jpg -d en/ -p ../ canada-photo.yml -- fokan2html: parsing canada-photo.yml -- fokan2html: creating en/001-001.html -- fokan2html: creating en/index.html
これで上手く行った。
fokan2html [options] <fokan_file> ... [options] <fokan_file> ... ...
引数の <fokan_file> には Fokan ファイル(Fokan データを格納したファイル) を指定する。Fokan ファイルは複数指定することができ、指定した順に処理される。 各 Fokan ファイルには、それよりも前に現れたオプションが順に適用される。 これにより、ファイルごとに異なるオプションを適用することが可能である。
Fokan ファイルの文字コードは UTF-8 でなければならない。 それ以外の文字コードを使用している場合はあらかじめ UTF-8 に変換しておくこと。
以下にオプションの詳細を説明する。必須のオプションは存在しないが、 デフォルト値は気が効いていないので、何らか指定することになるだろう。
隠し写真ファイルは写真ページに埋め込まない(-a の打ち消し)。 ある Fokan ファイルに対して -a を指定したあと、 別のファイルでそれを無効にしたいときにこのオプションを使用する。:
$ fokan2html -a canada.yml -A usa.yml
この例では、 canada.yml に記述された写真ファイルは全て写真ページに 埋め込まれるが、 usa.yml に記述された隠し写真ファイルは除外される。
HTML ファイル名の先頭を <dst_file_prefix> とする。 写真ページの HTML ファイル名は <dst_file_prefix><section_number>-<page_number>.html となる。 <section_number> はセクションの通し番号、 <page_number> はセクションごとのページの通し番号であり、 どちらも10進数3桁表記である。 <dst_file_prefix> のデフォルトは空文字列である。
例えば、オプション -d out/photo を指定すると、ディレクトリ out の下に以下のようなファイル名の HTML ファイルが生成される。:
photo001-001.html セクション1のページ1 photo001-002.html セクション1のページ2 ... photo002-001.html セクション2のページ1 photo002-002.html セクション2のページ2 ... ...
生成する目次ページの HTML ファイル名を <index_file> とする。 デフォルトは <dst_file_prefix>index.html 。
目次ページから写真ページへのハイパーリンクには、 目次ページの HTML ファイルから写真ページの HTML ファイルへの 相対パスが格納されることに注意。
言語コードを <lang> とする。デフォルトは空文字列。 <lang> は ISO 639 で定義される言語コードであり、 例えば ja は日本語、en は英語を表す。
例: Fokan ファイルに以下のような要素が含まれているとき、:
- Foto: imgp0005 Date: 2010-03-02 Desc: Maple Ridge, Desc.ja: ここで野宿 Desc.en: Sleeped here.
オプション -l ja を指定すると「Maple Ridge, ここで野宿」、 オプション -l en を指定すると「Maple Ridge, Sleeped here」、 それ以外のときは「Maple Ridge,」が写真 imgp0005 の説明として 写真ページに埋め込まれる。
他の全てのフィールドについても同様に機能する。
各写真ファイル名の先頭と末尾にそれぞれ文字列 <emb_foto_prefix> 、 <emb_foto_suffix> を付加したものを 写真ファイルの URI としてページに埋め込む。 どちらもデフォルトは空文字列。
写真ファイルの置き場所が HTML ファイルの置き場所と異なるときは パスの部分を補うために -p <パス>/ を指定する必要がある。 また、Fokan データの中で写真ファイルの拡張子を省略して記述している ときは拡張子を補うために -s .<拡張子> を指定する必要がある。
例えば、Fokan ファイルが以下のような要素を含むとき、:
- Foto: imgp0001 Desc: 何かの写真
オプション -p http://dokoka.jp/ -s .jpg を指定すると、 http://dokoka.jp/imgp0001.jpg が写真ファイルとして HTMLファイルに埋め込まれる。
外部リンクを有効にし、各写真ファイル名の先頭と末尾にそれぞれ文字列 <ext_foto_prefix> 、 <ext_foto_suffix> を付加したものを リンク先の URI とする。デフォルトは外部リンク無効。 どちらか一方のオプションのみ指定されたとき、他方は空文字列となる。
外部リンクが有効なとき、ページ上の写真をクリックすると 対応するリソースへジャンプする。 主な用途は、ページ上には縮小写真を表示しておき、 その写真をクリックするとオリジナルの写真を表示させるような場合である。
例えば、Fokan ファイルが以下のような要素を含むとき、:
- Foto: imgp0001 Desc: 何かの写真
オプション -p /photo/small/ -s .jpg -P /photo/orig -S .jpg を指定すると、 /photo/small/imgp0001.jpg が写真ファイルとして ページに埋め込まれ、その写真から /photo/orig/imgp0001.jpg にリンクが張られる。
-P, -S の指定は Fokan ファイル内に記述された全ての 写真ファイル名に対して一律に適用される。 一部の写真だけリンクを有効にしたり無効にしたりはできない。
Title フィールドに記述された文字列(セクションタイトル)は HTML ヘッダの <title> 要素、および HTML ボディの先頭に <h1> 要素として挿入される。
セクションが複数ページに分割されるときは、 ページ番号を示す文字列 [1], [2], ... がセクションタイトルの後ろに 付加される。
1つのページに複数のセクションが入ることはない。
Sub フィールドに記述された文字列(サブセクションタイトル)は <h2> 要素として挿入される。 Sub フィールドの前後の要素でページ分割が発生したときは、 サブセクションタイトルは後ろのページの先頭に挿入される(未確認…)。
サブセクション内でページ分割が発生したときに、後ろのページの 先頭にサブタイトルを挿入すべきか否か(現状はやってない)。
Foto フィールドに記述された写真ファイル名と、 同要素内にて Date フィールドに記述された撮影日 および Desc フィールドに記述された写真の説明は、 以下の形式で HTML の中に挿入される。:
<div class="fokan-foto-elem"> <p>写真の説明 [撮影日]</p> <img src="写真パス1" alt="写真パス1" /> <img src="写真パス2" alt="写真パス2" /> ... </div>
「写真パス」は Foto フィールドに記述された各写真ファイル名の 前後に -p, -s オプションで指定された文字列を付加したものである (オプション -p, -s の説明を参照)。
オプション -P, -S により外部リンクが有効なときは以下のようになる。:
<div class="fokan-foto-elem"> <p>写真の説明 [撮影日]</p> <a href="外部リンクパス1"><img src="写真パス1" alt="写真パス1" /></a> <a href="外部リンクパス2"><img src="写真パス2" alt="写真パス2" /></a> ... </div>
「外部リンクパス」は Foto フィールドに記述された各写真ファイル名の 前後に -P, -S オプションで指定された文字列を付加したものである (オプション -P, -S の説明を参照)。
1段のみの番号付きリストで、リストの1アイテムに1セクションが対応。 セクションが1ページのときは、セクションタイトルを表示し その写真ページへのリンクを張る。 セクションが複数ページのときは「セクションタイトル [1] [2] [3] ...」 と表示し、各数字から対応する写真ページへのリンクを張る。
例えば、写真ページが以下の HTML ファイルで構成されているとき、:
セクション1: out-001-001.html (1ページのみ) セクション2: out-002-001.html out-002-002.html out-002-003.html セクション3: out-003-001.html out-003-002.html
目次の HTML は以下のようになる。:
<ol>
<li>
<a href="out-001-001.html">セクション1のタイトル</a>
</li>
<li>
<a href="out-002-001.html">セクション2のタイトル [1]</a>
<a href="out-002-002.html">[2]</a>
<a href="out-002-003.html">[3]</a>
</li>
<li>
<a href="out-003-001.html">セクション3のタイトル [1]</a>
<a href="out-003-002.html">[2]</a>
</li>
</ol>
写真ページの HTML ファイルが目次ページの HTML ファイルと異なる ディレクトリに出力されるとき、 目次には目次ページから写真ページへの相対パスが格納される。