[[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
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="example-book">
  <title>DocBookの例</title>
  <chapter id="example-chapter">
    <title>章の例</title>
    <para>段落の例です。</para>
    <sect1 id="example-sect1">
      <title>節の例</title>
      <para>chapterを分割するsect1の例です。</para>
    </sect1>
    <sect1>(中略)</sect1>
  </chapter>
  <chapter>(中略)</chapter>
  <appendix id="example-appendix">
    <title>付録の例</title>
    <para>(中略)</para>
  </appendix>
</book>
}}}

エンコーディングは、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
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>

	<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets/xhtml/chunk.xsl"/>
	<xsl:param name="html.stylesheet">vine.css</xsl:param>
	
	<xsl:param name="toc.section.depth">1</xsl:param>
	<xsl:param name="section.autolabel">1</xsl:param>
	<xsl:param name="section.label.includes.component.label">1</xsl:param>
	<xsl:param name="use.id.as.filename">1</xsl:param>
	<xsl:param name="admon.graphics">1</xsl:param>
	<xsl:param name="callout.graphics">1</xsl:param>
	<xsl:param name="callout.unicode">0</xsl:param>
	<xsl:param name="root.filename" />
	 
	<xsl:template match="question" mode="label.markup">
		<xsl:text>Q</xsl:text>
		<xsl:number level="multiple" count="qandaentry" format="1"/>
	</xsl:template>
	<xsl:template match="answer" mode="label.markup">
		<xsl:text>A</xsl:text>
		<xsl:number level="multiple" count="qandaentry" format="1"/>
	</xsl:template>
</xsl:stylesheet>
}}}

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.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]