(2014.9)
技術文書を作成するための標準フォーマット DocBook で文書を作り, それをいわゆる WebHelp として表示できるようにしてみます。
DocBookは, XMLフォーマットで, 技術文書を作成するための業界標準の一つです。DocBookで文書を作成すれば, PDF, HTML, などなどに変換することができます。
また, DocBookを基礎としたツール (tool chain) として, Publican があります。例えば, RedHat社のドキュメントは, すべて Publicanで作られています。
以下では, Publican ではなく, XML関連のツールを使って, WebHelpを作ってみます。WebHelpは, この画面のように, 目次と内容が1ページになったHTMLです。
いずれも, Fedora 20 Linuxでパッケージが用意されています;
パッケージ | 内容 |
---|---|
docbook5-style-xsl | DocBook5文書を, HTMLなどのフォーマットに変換するためのスタイルシート集。 |
docbook5-schemas | DocBook 5.xのスキーマ。文書の検証に利用 |
fop | PDFに変換するときに使用. XSLでフォーマット。 |
libxslt | スタイルシートを適用するための xsltprocコマンド。 |
msv-msv | Multi-Schema Validator. XML文書の検証用のコマンド。Relax NG, Schematronに対応. msvでは, 文書の一部として取り込む xinclude の参照先を検証しない。xmllintと組み合わせる。 |
libxml2 | xmllintコマンド。xmllintはSchematronをサポートしていないため, これだけではDocBook文書を検証できない. |
DocBook文書を作ります。
試しに, 次の2つのファイルを用意します。
doc1.xml::
chap1.xml::
ルート要素として, book または article を置きます。
book の場合は, part, chapter要素で章を分けます。article を bookの子要素としても構いません。
article要素では, class属性で次の値を指定して, その記事のカテゴリを示すことができます。(optional)
DocBook文書を作ったら, 妥当性を検証します.
ただ, 簡単にはいきません。
DocBook5のスキーマは Relax NG + Schematron で書かれているため, まともな検証器としては, msv コマンドぐらいしかありません。しかし, msv は XInclude をサポートしていないため, XInclude を使って文書を書いた場合は, xmllint コマンドも組み合わせます。
例えば次のようにします。
$ msv /usr/share/xml/docbook5/schema/rng/5.0/docbook.rng chap1.xml $ xmllint --xinclude doc1.xml > tmp $ msv /usr/share/xml/docbook5/schema/rng/5.0/docbook.rng tmp
msvには, docbookxi.rng ではなく docbook.rng をスキーマとして与えます。また, XInclude は, xmllint コマンドに展開させます。
まずinclude されるほうのXML文書を検証し, 最後に一つにまとめて再度, 検証します。
いちいち2コマンドを打つのは間抜けなので, 1アクションで検証できるスクリプトを書いてもいいでしょう。
DocBook文書を作ったら, 表示用のフォーマットに変換します。
Fedora 20 Linux では, 整形用のスタイルシート集のパッケージは docbook5-style-xsl です。/usr/share/sgml/docbook/xsl-ns-stylesheets/ 以下にインストールされます。
整形には, xsltproc コマンドを使います。
ここでは, docbook5-style-xsl パッケージの readme.xml ファイルを整形してみます。
次のようにすると, docsディレクトリ以下に, チャプターごとにファイルを分けて, HTMLで生成されます。
$ cp -r /usr/share/sgml/docbook/xsl-ns-stylesheets-1.78.1/webhelp/docsrc . $ xsltproc -o docs/ --xinclude /usr/share/sgml/docbook/xsl-ns-stylesheets/html/chunk.xsl docsrc/readme.xml Writing ch01.html for chapter Writing ch02s02.html for section Writing ch02s03.html for section Writing ch02s04.html for section Writing ch02s05.html for section Writing ch02.html for chapter Writing ch03s02.html for section Writing ch03.html for chapter Writing ch04.html for chapter Writing ch05s02.html for section Writing ch05.html for chapter Writing ix01.html for index Writing index.html for book
--xinclude を指定しないと, Element include in namespace 'http://www.w3.org/2001/XInclude' encountered in book, but no template matches. というエラーが出ます.
では, WebHelpを作ってみます。
$ mkdir doc-webhelp $ xsltproc -o doc-webhelp/ --xinclude /usr/share/sgml/docbook/xsl-ns-stylesheets/webhelp/xsl/webhelp.xsl docsrc/readme.xml language: en Writing docs/ch01.html for chapter Writing docs/ch02s01.html for section Writing docs/ch02s02s01.html for section Writing docs/ch02s02.html for section Writing docs/ch02s03.html for section Writing docs/ch02s04.html for section Writing docs/ch02s05.html for section Writing docs/ch02.html for chapter Writing docs/ch03s01.html for section Writing docs/ch03s02s01.html for section Writing docs/ch03s02.html for section Writing docs/ch03.html for chapter Writing docs/ch04.html for chapter Writing docs/ch05s01.html for section Writing docs/ch05s02.html for section Writing docs/ch05.html for chapter Writing docs/ix01.html for index Writing docs/index.html for book Writing docs/search/l10n.js
WebHelpの表示には, HTMLスタイルシートが必要です。
$ cp -r /usr/share/sgml/docbook/xsl-ns-stylesheets/webhelp/template/common doc-webhelp/docs
スタイルシート (XSLファイル) のカスタマイズは, 例えば,