[[PageOutline]]
= !DocBook XMLに関するメモ =
オンラインマニュアルの作成に!DocBook XMLを使用しています。
インストールガイドのソースは[source:/projects/install-guide/trunk]で閲覧できます。チェックアウトする場合は、以下のコマンドを使用してください。
{{{
$ svn co http://trac.vinelinux.org/repos/projects/install-guide/trunk install-guide
}}}
オンラインマニュアルのソースは[source:/projects/Vine-manual/trunk]から閲覧できます。チェックアウトする場合は、以下のコマンドを使用してください。
{{{
$ svn co http://trac.vinelinux.org/repos/projects/Vine-manual/trunk Vine-manual
}}}
== !DocBook XMLの記述例 ==
{{{
#!text/xml
DocBookの例
章の例
段落の例です。
節の例
chapterを分割するsect1の例です。
(中略)
(中略)
付録の例
(中略)
}}}
エンコーディングは、UTF-8を使用してください。
== !DocBook XMLを別の形式に変換する ==
!DocBookに限った話ではないのですが、XMLファイルを別の形式に変換する場合、xsltprocコマンドを利用します。その基本構文は次の通りです。
{{{
$ xsltproc オプション XSLスタイルシート XMLファイル
}}}
!DocBook用のXSLスタイルシートは、/usr/share/sgml/docbook/xsl-stylesheets以下に用意されています。以下、HTMLファイルに変換する例を記述します。
=== 単一のHTMLファイルに出力する ===
{{{
$ xsltproc /usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl source.xml > dest.html
}}}
XSLスタイルシートに/usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xslを使用した場合、標準出力にHTMLを吐き出しますのでリダイレクトしています。
=== 複数のHTMLファイルに分割する ===
{{{
$ xsltproc /usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl source.xml
}}}
自動でファイル名が決定されます。
=== XSLスタイルシートパラメータを使用する ===
xsltprocのオプション '''--stringparam''' を使うとXSLスタイルシートパラメータを指定する事ができます。
==== 出力エンコーディングをeuc-jpにする ====
{{{
--stringparam chunker.output.encoding euc-jp
}}}
デフォルトの出力エンコーディングは UTF-8 です。
==== 出力を整形する ====
{{{
--stringparam chunker.output.indent yes
}}}
これを指定しないと出力されるHTMLソースは、可読性が最悪です。
== 標準のXSLスタイルシートを利用してカスタムスタイルシートを作成する ==
Vine-manualでは、以下のXSLスタイルシートを custom.xslとして利用しています。
{{{
#!text/xml
vine.css
1
1
1
1
1
1
0
Q
A
}}}
XSLスタイルシートは、ゼロから作成することも可能ですが、標準のスタイルシートはよくできていますのでそれを利用した方がいいでしょう。
この例では、標準のスタイルシートを編集せずに3行目の '''xsl:import''' で /usr/share/sgml/docbook/xsl-stylesheets/xhtml/chunk.xsl をインポートしています。
また、'''xsl:param''' を利用してスタイルシートパラメータをいくつか指定しています。例えば、'''use.id.as.filename''' を '''1''' に設定すると id属性を利用して出力ファイル名を決定する事ができます。
custom.xslの後半では、xsl:template を利用して Q&A セットの出力方法をカスタマイズしています。これは、[#参考文献 参考文献]で紹介する[http://www.sagehill.net/docbookxsl/index.html DocBook XSL: The Complete Guide]の[http://www.sagehill.net/docbookxsl/QandASetsHTML.html Chapter 28. Q and A sets]から拝借しました。
== author での出力順序 ==
author タグに role="family-given" と与えてやると姓名の順で出力される?(gnome-doc-utils では成功)
== 参考文献 ==
* [http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html DocBook: The Definitive Guide]
* [http://www.docbook.org/tdg51/en/html/docbook.html DocBook 5: The Definitive Guide]
* [http://www.sagehill.net/docbookxsl/index.html DocBook XSL: The Complete Guide]
* [http://www.ibm.com/developerworks/jp/opensource/library/os-eclipse-docbook/index.html Eclipse で DocBook XML を構築する]
* [http://www.ibm.com/developerworks/jp/xml/library/x-xslfo/ XSL-FOを使って文書を印刷用に加工する]
* [http://www.netfort.gr.jp/~dancer/column/writing-sgml.html.ja DocBook/SGML や DocBook/XML で文書を書く]
* [http://neverbird.sourceforge.jp/articles/docbook-intro.html DocBook文書を日本語で書く]
* [http://www.jbug.jp/cgi-bin/fswiki/wiki.cgi?page=DocBook%A5%E1%A5%E2 DocBookメモ - 日本JBossユーザ・グループ]
* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo Migrating your documentation to gnome-doc-utils]