wiki:DocBookXML

Version 17 (modified by yasumichi, 15 years ago) (diff)

--

DocBook XMLに関するメモ

オンラインマニュアルの作成にDocBook XMLを使用しています。

インストールガイドのソースはprojects/install-guide/trunkで閲覧できます。チェックアウトする場合は、以下のコマンドを使用してください。

$ svn co http://trac.vinelinux.org/repos/projects/install-guide/trunk install-guide

オンラインマニュアルのソースはprojects/Vine-manual/trunkから閲覧できます。チェックアウトする場合は、以下のコマンドを使用してください。

$ svn co http://trac.vinelinux.org/repos/projects/Vine-manual/trunk Vine-manual

DocBook 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として利用しています。

<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.filename1 に設定すると id属性を利用して出力ファイル名を決定する事ができます。

custom.xslの後半では、xsl:template を利用して Q&A セットの出力方法をカスタマイズしています。これは、参考文献で紹介する DocBook XSL: The Complete Guide Chapter 28. Q and A setsから拝借しました。

参考文献