DocBook5 で WebHelp を作る

(2014.9)

技術文書を作成するための標準フォーマット DocBook で文書を作り, それをいわゆる WebHelp として表示できるようにしてみます。

DocBook

DocBookは, XMLフォーマットで, 技術文書を作成するための業界標準の一つです。DocBookで文書を作成すれば, PDF, HTML, などなどに変換することができます。

また, DocBookを基礎としたツール (tool chain) として, Publican があります。例えば, RedHat社のドキュメントは, すべて Publicanで作られています。

以下では, Publican ではなく, XML関連のツールを使って, WebHelpを作ってみます。WebHelpは, この画面のように, 目次と内容が１ページになった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 XMLファイルの作成

DocBook文書を作ります。

試しに, 次の2つのファイルを用意します。

doc1.xml::

HTML/XML
[RAW]
  1. <?xml version="1.0" encoding="utf-8"?>
  2. <book xmlns="http://docbook.org/ns/docbook" version="5.0"
  3. xmlns:xi="http://www.w3.org/2001/XInclude">
  4. <info>
  5. <title>My first どきゅめんと</title>
  6. <author>
  7. <personname>
  8. <firstname>Hisashi</firstname><surname>Horikawa</surname>
  9. </personname>
  10. </author>
  11. </info>
  12. <xi:include href="chap1.xml" />
  13. </book>

chap1.xml::

HTML/XML
[RAW]
  1. <chapter xmlns="http://docbook.org/ns/docbook">
  2. <title>チャポター1</title>
  3. <para>ふがふが</para>
  5. <!-- http://www.docbook.org/tdg5/en/html/imagedata.html -->
  6. <mediaobject>
  7. <imageobject>
  8. <imagedata fileref="./images/picture.png" />
  9. </imageobject>
  10. <textobject><phrase>alternate text</phrase></textobject>
  11. </mediaobject>
  12. </chapter>

ルート要素として, book または article を置きます。

book の場合は, part, chapter要素で章を分けます。article を bookの子要素としても構いません。

article要素では, class属性で次の値を指定して, その記事のカテゴリを示すことができます。(optional)

  • faq
  • journalarticle
  • productsheet
  • specification
  • techreport
  • whitepaper

妥当性検証 (Validation)

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 ファイルを整形してみます。

html/chunk.xsl

次のようにすると, 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

では, 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

XMLスタイルシートのカスタマイズ

スタイルシート (XSLファイル) のカスタマイズは, 例えば,