5. docbook 形式のファイル

docs というディレクトリ以下に DocBook 形式の文書群が格納されています。

例えば、この文書はdocs/Document-HOWTO/ja/Doucment-HOWTO.xml という DocBook 形式のファイルで書かれています。 この文書に変更を加えるときは、docs/Document-HOWTO/ja に移動し、 Doucment-HOWTO.xml を編集します。

このディレクトリ以下の文書は、基本的に DocBook という XML Document Type Definition(DTD -- 文書型定義)にしたがって書かれた xml ファイルです。 Web で見えている文書はこの文書も含めて、ソースの xml ファイルから xsl 変換により生成された html です。

DocBook 自体の解説は 実用 DocBook 入門 や、 LDP Author Guide などが Linux JF Project より公開されています。

5.1. DocBook スタイルシート

5.1.1. スタイルシートとは

この文書は、ここにあるのですが、 これをブラウザで見ると大変なことになっていると思われます。

これを このように変換するためには、 スタイルシートというものを使用します。

DocBook で使用できるスタイルシートには dsssl というものと xslt というものがあるのですが、 Momonga Project ではスタイルシートのメンテナンスの簡便性をとって xslt を使用しています。

手元に xslt 変換が可能な環境があれば、http://www.momonga-linux.org/ においたときの文書の見栄えを手元で確認できます。 また、文書更新後手元で一度変換をかけてみると、 文書の構文エラー等でサーバ側で html に変換できないという事態を未然に防ぐことができます。

5.1.2. 使用するスタイルシート

http://www.momonga-linux.org/ で実際に変換に使用されるスタイルシートも svn で管理され、 docs/docbook.xsl docs/onehtml.xsl として commit されています。

これらのスタイルシートは "ドライバ" であり、スタイルシート本体は docbook-style-xsl-version-releasem.noarch.rpm パッケージに含まれます。 [3]

5.1.3. 実際に変換してみる

3.3.2.「docs ディレクトリ」を参照し Makefile を作成してください。 その後 docsmake すると、 すべてのドキュメントを html に変換します。この作業にはけっこうな時間がかかりますから、 ある .xml ファイルだけ出来ばえを確認したいなら、そのファイルのあるディレクトリで make するとよいでしょう。

完了すると各ドキュメントのディレクトリの下に

  • index.html

  • index.htmlからリンクされる各セクション毎の html ファイル

  • changelog.html

  • ディレクトリ名_all.html

  • ディレクトリ名.txt

ができあがります。



[3] ここでの "ドライバ" とは、スタイルシートに適切なパラメータをわたして呼び出してくれるもの。 程度の意味でとらえてください。