プロジェクトドキュメントを管理するには

Fossil はプロジェクトのドキュメントを保管しておくための組み込みの wiki を用意しています。これでほとんどの用途には十分なはずです。 wiki ドキュメントで間に合っているならば、これ以降を読む必要はありません。

また、fossil はソースツリー内のファイルによる埋め込みドキュメントもサポートしています。この方法にはいくつかの有利な点があります:

ドキュメントファイルはソースコードと一緒にバージョン管理されるため、リリースの際にどのドキュメントがどのバージョンなのか明確に認識することができます。

ドキュメントファイルは、webベースの wiki エディタでなく、読者の好きなエディタで編集することができます。

チェックイン権限を持つユーザのみがドキュメントを変更できます。 (これが有利か不利かについてはプロジェクトによります。)

これから、ソースツリー内のファイルに書かれたドキュメントのことを「埋め込みドキュメント(embedded document)」と呼ぶことにします。

埋め込みドキュメントに関する fossil のサポート

fossil のWeb インターフェースは埋め込みドキュメントを「/doc」ページとして扱います。埋め込みドキュメントの fossil での URL は次のようになります:

<baseurl>/doc/<version>/<filename>

ここで <baseurl> は fossil Web サーバへの URL です。例として、fossilプロジェクト自身への <baseurl> は http://www.fossil-scm.org/fossilまたは http://www.hwaci.com/cgi-bin/fossilです。もしWebサーバを "fossil server" コマンドで起動した場合、 <baseurl> は、通常 http://localhost:8080/ となります。

<version> はアクセスしたいドキュメントを含むチェックインIDの何らかの一意なプレフィックスです。もしくは <version> はドキュメントの最新版を含む branch の名前でも構いません。あるいは <version> は "tip" か "ckout" のどちらかのキーワードであってもよいです。ここで "tip" キーワードは最新のチェックインを示します。これはドキュメントの最新版を見付けるのに便利です。また、"ckout" キーワードは、チェックインされたファイルではなく、現在のローカルソースツリー上のドキュメントを示します。 "ckout" キーワードは、通常は "fossil server" あるいは "fossil ui" を使ってサーバを起動した場合にのみ有効です。これは現在編集中でチェックインしていないバージョンのドキュメントを見るのに使います。

最後に <filename> 要素はドキュメントへの(ソースツリーの) ルートからのフルパスを指定します。

これらドキュメントの MIME タイプはファイルのサフィックスによって決定されます。 Fossil は現在 192 の拡張子を判別でき、".css", ".gif", ".htm", ".html", ".jpg", ".jpeg", ".png", ".txt" などのようなものを認識します。

最後が ".wiki" で終わる名前を持つドキュメントは wiki ページと同様のフォーマットを認識します。これは段落やリスト、リンクを含む HTML の安全なサブセットとなります。また、".wiki" と ".txt" ページについては fossil の標準的なヘッダとフッタを付加して表示されます。その他の MIME タイプについては、解釈、付加、変更など無しでそのまま直接ブラウザへ送られます。

例

今読者が読んでいるこのファイルも埋め込みドキュメントの例です。 fossil ソースツリー上でのファイル名は "www/embeddeddoc.wiki" です。おそらく読者はこのファイルを次のような URL で見ているでしょう:

http://www.fossil-scm.org/index.html/doc/tip/www/embeddeddoc.wiki.

このパスの最初の要素である "http://www.fossil-scm.org/index.html" がベースURL です。もしかすると、本来は次のように入力したかもしれません: http://www.fossil-scm.org/ このサイトの Webサーバは自動的にこのリンクに "index.html" を付加してリダイレクトします。 www.fossil-scm.org の "index.html" は実際には CGI スクリプトです。 (名前に惑わされないでください) これは fossil の Web サービスが CGI モードで実行されています。実際の "index.html" CGI スクリプトの内容はこうです:

#!/usr/bin/fossil
repository: /fossil/fossil.fossil

これは fossil web server の三種類のセットアップのうちの一つです。

URL の "/tip/" の部分は一番最近にチェックインされた版のファイルを使うように fossil に指示しています。もし、この文書の古い版を見たければ "/tip/" の部分を見たいチェックインの名前と入れ替えます。例えば、9be1b00392のチェックイン時の内容を見たければ、 "/tip/" を単純に "/9be1b00392/" と入れ替えれば済みます。また、この他にもバージョンのシンボリック名やブランチ名を指定することもできます。この例としては "/tip/" を "/trunk/" とすることで、"trunk" ブランチ中の最新のファイルを指定できます。 (これを書いている時点では fossil の自己ホスティングには "trunk" ブランチしか存在しないため、"trunk" と "tip" は同じものを指していることになります。しかし、複数のブランチがあるプロジェクトではこれらは別のものを指す場合もあります。)

このドキュメントの元ファイルは fossil ソースツリー上において "www/embeddeddoc.wiki" に置かれており、URL の最後の部分はこれを示しています。

このドキュメントを書きながら、私は Webサーバをfossil serverコマンドで起動し、firefox でhttp://localhost:8080/doc/ckout/www/embeddeddoc.wiki を見ながらチェックしています。私はこの作業を "www/embeddeddoc.wiki" ファイルの最初のチェックインより前に行っています。 "ckout" キーワードを "/doc" に続くバージョン番号として使うことでリポジトリに変更をコミットする前に、複数のファイルの複数の変更点を見ることができます。