3.2. FreeBSD doc tree
FreeBSD Documentation Project(FDP) に関する資料によると、 FDP が管理する Documentation Set は マニュアルページ、FreeBSD FAQ, FreeBSD Handbook, FreeBSD Tutorials とされています。これらの位置付けについては、 docproj のウェブページや、 FreeBSD Documentation Project 入門などの一次資料を参照してください。 ここでは、それらが格納されているディレクトリの構造に主眼をおいて解説します。
FreeBSD の doc tree に含まれている文書は、 CVS repository 上で doc/ 以下にあたります。 これらの文書は汎用性を持たせるために、 すべて SGML 文書として管理されています。
SGML 文書は、後述する SGML 処理系によって可読文書形式に変換されます。 具体的には DSSSL と連係させることで SGML 文書から HTML, RTF, PostScropt, PDF 形式の文書を生成することを可能にしています。 WWW で公開されている文書はこのように SGML 文書から生成されているわけですが、この変換に関しては後ほど詳しく扱います。
3.2.1. doc/ の構成
最初に、ディレクトリ構成から考えていきます。 doc/ 直下には、 図のように各言語に対応するディレクトリ[1]が存在します。 これは lang.encoding/ というルールで名前が付けられています。 図に書かれているのは日本語と英語のディレクトリだけですが、 実際にはロシア語、フランス語、スペイン語といったような、 他の言語のディレクトリもいくつかあります。 同一言語でエンコーディングの異なるディレクトリも原理的に存在できますが、 2000/03 に時点ではそのようなディレクトリはありません。
これらのディレクトリはそれぞれ、 英語版を中心に同じ階層構造を持つようにつくられています。 たとえば、doc/ja_JP.eucJP/books/handbook/book.sgml は、doc/en_US.ISO_8859-1/books/handbook/book.sgml に対応する翻訳文書です。
また、doc/ 直下には、 各言語に対応する翻訳文書を格納するディレクトリの他に、 すべての言語で共通して用いられるファイル群が格納されている share/ があります。 具体的には、DocBook(SGML) の DTD, DSSSL の DTD, doc/ ツリー構築のための Makefile です。
 |
これらのファイルは、doc/ の構築に用いられるものです。構築の概要については後述します。 |
3.2.2. doc/ja_JP.eucJP/ の構成
FreeBSD doc-jp の興味の対象は、英語版と日本語版、 すなわち doc/en_US.ISO_8859-1/ と doc/ja_JP.eucJP/ です。そこで次に、現在の doc/ja_JP.eucJP/ の構成から見てみることにします。
各言語の対応するディレクトリの下にある構造は、基本的に同一です。
日本語版ディレクトリには、 翻訳が終了して保守されている FreeBSD FAQ/Handbook と、 現在公開のための準備が進められている FreeBSD Tutorials が保存されています。 ディレクトリは、大きく分けて books/ と articles/ に分類され[2]、 さらにその下に文書毎のディレクトリが存在します。
また、man/ には JPMAN プロジェクトの成果物である、 日本語版マニュアルが保存されています。 マニュアルページに関しては独立したプロジェクトが管理していますので、 doc-jp としてこのディレクトリを扱うことは基本的にありません。
3.2.3. 日本語版文書に共通して追加する要素
日本語版文書は、原則として英語版 SGML 文書の本文部分を翻訳したものになっていますが、 文書を管理する目的で、いくつか特有の記述を追加しています。 これは翻訳チームが行なわなければならない作業として 決められていることですので注意してください。
doc-jp の signature
まず一つ目は、FreeBSD Japanese Documentation Project の signature です。具体的には、次のような SGML コメントをなるべく文の先頭の方に追加します。
<!-- The FreeBSD Japanese Documentation Project --> |
もし、FreeBSD Documentation Project の signature が存在する場合は、それに併記する形で挿入します。
<!--
The FreeBSD Documentation Project
The FreeBSD Japanese Documentation Project
-->
|
original revision
日本語版は、独自の RCS revision で管理されているため、 対応する原文の original revision を、別の形で保存します。 これも同様に、次のような SGML のコメントタグに埋め込む形で実現されます。
<!-- Original revision: 1.22 --> |
以上の二点の追加は、コメントとして独立している必要はありません。 典型的な例を次に示します。
<!--
The FreeBSD Documentation Project
The FreeBSD Japanese Documentation Project
Original revision: 1.83
-->
|
それでは次に、具体的に各文書の構造を見て行きましょう。
3.2.4. FreeBSD Handbook 日本語版
FreeBSD Handbook 日本語版は、 books/handbook/ 以下に存在しています。 構造は、図のようになっています。
Handbook は、いくつかのファイルに分割されています。 中心となる文書は book.sgml
であり、 各 chapter に対応する部分は、 さらに下のディレクトリに置かれています。
この各 chapter に対応するファイルは、すべて同じファイル名 chapter.sgml になっています。
基本的に英語版の構造を踏襲していますが、 日本語版では、英語版に加えて jcontrib/
という、 doc-jp への貢献者をリストアップした chapter が追加されています。
分割された文書は、book.sgml にある SGML の実体参照によって統合されています。
そのため、各 chapter の部分は SGML 文書として独立していません。 これは、chapter 毎の部分構築ができないことを意味します。
|
実体参照とは、マクロや C 言語の #define に近い SGML の概念です。 SGML の言語構造については、SGML の章を参照してください。 |
book.sgml の実体参照の利点は、 順番の変更や chapter
の追加が容易に行なえるというところにあります。 すべての chapter.sgml を book.sgml に統合する必要もありません。 その場合、参照されない chapter.sgml は、文書の構築に寄与しなくなり、 実質的に「利用されない文書」になります。
このように、Handbook は book.sgml+ */chapter.sgml で構成されていまが、 これらのファイルに加え、直接文書を構成しないファイルとして *.ent と *.decl というファイルがあります。
*.ent は、 各文書で共通に使われる実体参照を集めたものです。 これは book.sgml によって利用されます。
| chapters.ent | 分割された */chapter.sgml を定義しているファイル |
| authors.ent | 文書の作者の名前と email アドレス |
| jauthors.ent | doc-jp への貢献者の名前と email アドレス |
| mailing-lists.ent | FreeBSD.org が主宰する mailing list |
| newsgroups.ent | FreeBSD に関連する NewsGroup |
*.decl は、 分割された SGML 文書ファイルを編集するためのものです。 */chapter.sgml は SGML 文書として独立しておらず、DTD が書かれていません。 そこで、Emacs の psgml-mode は、この *.decl から DTD を取得します。 これは Emacs の psgml-mode でのみ利用されるもので、 文書の構成には直接関係するものではありません。
3.2.5. FreeBSD FAQ 日本語版(作業中)
FreeBSD FAQ は、books/faq に存在しています。 構造は基本的に Handbook
と同じですが、 chapter がありません。つまり、文書は book.sgml の単一ファイルになっています。
3.2.6. FreeBSD Tutorials 日本語版(作業中)
FreeBSD Tutorials は、 books/articles 以下に存在します。 このディレクトリには、さらに文書毎に対応するサブディレクトリがあり、 文書本体は aritcles.sgml という、単一のファイルになっています。