試験運用中なLinux備忘録・旧記事

はてなダイアリーで公開していた2007年5月-2015年3月の記事を保存しています。

DocBook XML文書からXHTMLへの変換をカスタマイズ(コード中などにおける注釈の表示)

DocBook

カスタマイズをする準備として、ディレクトリ構成を準備する。

[xml]-+-[custom-xsl]-+-<xhtml-common.xsl> (XHTML変換共通設定)
      |              +-<xhtml-single.xsl> (XHTML単独ファイル固有設定)
      |              +-<xhtml-multi.xsl>  (XHTML複数ファイル固有設定)
      |
      +-[doc]-[cotest]-<cotest.xml>       (以下に載せたサンプル文書)
      |
      +-[css]-<docbook.css>               (XHTML文書が参照するカスタムCSS)
      |
      +-[callouts]-<1.gif>など            (番号の画像ファイル)
      |
      +-<xsl-stylesheets>                 (docbook-xslのディレクトリへのリンク)

テキストファイルの内容を書くブロック(programlisting要素やscreen要素など。詳細はcoのページの「Parents」を参照)に、注釈のような感じで、下に用意する説明文リスト(calloutlist要素)の該当部分(対応するcallout要素)と相互にリンクを張ることができるのだが、その表示についてのカスタマイズができる。

以下、サンプル文書。

ファイル名: cotest.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
          "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<?xml-stylesheet href="../../wysiwygdocbook/custom.css" type="text/css"?>
<article lang="ja">
 <articleinfo>
  <title>サンプル</title>

  <abstract>
   <para>Calloutのサンプル</para>
  </abstract>
 </articleinfo>

 <sect1 id="cotest">
  <title>Calloutのテスト</title>
  <example id="ex.cotest">
   <title>ディレクトリ構成例</title>
   <programlisting>
  [xml]-+-[custom-xsl]-+-&lt;xhtml-common.xsl&gt; <co id="xht_c.co.ex.cotest" linkends="xht_c.le.ex.cotest"/>
        |              +-&lt;xhtml-single.xsl&gt; <co id="xht_s.co.ex.cotest" linkends="xht_s.le.ex.cotest"/>
        |              +-&lt;xhtml-multi.xsl&gt; <co id="xht_m.co.ex.cotest" linkends="xht_m.le.ex.cotest"/>
        |
        +-[doc]-[cotest]-&lt;cotest.xml&gt; <co id="doc.co.ex.cotest" linkends="doc.le.ex.cotest"/>
        |
        +-[css]-&lt;docbook.css&gt; <co id="css.co.ex.cotest" linkends="css.le.ex.cotest"/>
        |
        +-[callouts]-&lt;1.gif&gt;など <co id="numimg.co.ex.cotest" linkends="numimg.le.ex.cotest"/>
        |
        +-&lt;xsl-stylesheets&gt; <co id="xsllnk.co.ex.cotest" linkends="xsllnk.le.ex.cotest"/></programlisting>
   <calloutlist>
    <callout id="xht_c.le.ex.cotest" arearefs="xht_c.co.ex.cotest">
     <para>XHTML変換共通設定</para>
    </callout>
    <callout id="xht_s.le.ex.cotest" arearefs="xht_s.co.ex.cotest">
     <para>XHTML単独ファイル固有設定</para>
    </callout>
    <callout id="xht_m.le.ex.cotest" arearefs="xht_m.co.ex.cotest">
     <para>XHTML複数ファイル固有設定</para>
    </callout>
    <callout id="doc.le.ex.cotest" arearefs="doc.co.ex.cotest">
     <para>以下に載せたサンプル文書</para>
    </callout>
    <callout id="css.le.ex.cotest" arearefs="css.co.ex.cotest">
     <para>XHTML文書が参照するカスタムCSS</para>
    </callout>
    <callout id="numimg.le.ex.cotest" arearefs="numimg.co.ex.cotest">
     <para>番号の画像ファイル</para>
    </callout>
    <callout id="xsllnk.le.ex.cotest" arearefs="xsllnk.co.ex.cotest">
     <para>Docbook XSLのディレクトリへのリンク</para>
    </callout>
   </calloutlist>
  </example>
 </sect1>

 <sect1 id="cotest2">
  <title>Calloutのテスト2</title>
  <example id="ex.cotest2">
   <title>ディレクトリ構成例</title>
   <programlistingco>
    <areaspec>
     <area id="xht_c.ex.cotest2" coords="1"/>
     <area id="xht_s.ex.cotest2" coords="2"/>
     <area id="xht_m.ex.cotest2" coords="3"/>
     <area id="doc.ex.cotest2" coords="5"/>
     <area id="css.ex.cotest2" coords="7"/>
     <area id="numimg.ex.cotest2" coords="9"/>
     <area id="xsllnk.ex.cotest2" coords="11"/>
    </areaspec>
    <programlisting>
  [xml]-+-[custom-xsl]-+-&lt;xhtml-common.xsl&gt;
        |              +-&lt;xhtml-single.xsl&gt;
        |              +-&lt;xhtml-multi.xsl&gt;
        |
        +-[doc]-[cotest2]-&lt;cotest2.xml&gt;
        |
        +-[css]-&lt;docbook.css&gt;
        |
        +-[callouts]-&lt;1.gif&gt;など
        |
        +-&lt;xsl-stylesheets&gt;</programlisting>
    <calloutlist>
     <callout arearefs="xht_c.ex.cotest2">
      <para>XHTML変換共通設定</para>
     </callout>
     <callout arearefs="xht_s.ex.cotest2">
      <para>XHTML単独ファイル固有設定</para>
     </callout>
     <callout arearefs="xht_m.ex.cotest2">
      <para>XHTML複数ファイル固有設定</para>
     </callout>
     <callout arearefs="doc.ex.cotest2">
     <para>以下に載せたサンプル文書</para>
     </callout>
     <callout arearefs="css.ex.cotest2">
      <para>XHTML文書が参照するカスタムCSS</para>
     </callout>
     <callout arearefs="numimg.ex.cotest2">
      <para>番号の画像ファイル</para>
     </callout>
     <callout arearefs="xsllnk.ex.cotest2">
      <para>Docbook XSLのディレクトリへのリンク</para>
     </callout>
    </calloutlist>
   </programlistingco>
  </example>
 </sect1>

</article>

programlistingco要素を使用した例を、2番目のsect1内にも入れたのだが、本家のサンプルの通りにやっても、何故かコード中に番号が表示されることはなく、サンプル全体をコピペしたものを変換してもダメだった。
上のほうのsect1に書いた方法では、コード中の注釈の入る位置にco要素をid属性とlinkend属性(値は下の注釈リストの該当項目のid属性の値)付きで書き、注釈リスト側(callout要素)でもid属性とarearefs属性(値は、それに対応しているコード内のco要素のid属性の値)を指定して書く。文字で説明すると分かりにくいが、お互いを関連付ける形となっている。

以下は、カスタムXSLに記述する設定例。
ファイル名: xhtml-common.xsl

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
...
<xsl:param name="callout.list.table" select="0"/>
<xsl:param name="callout.graphics" select="1"/>
<xsl:param name="callout.graphics.path" select="'../../callouts/'"/>
<xsl:param name="callout.graphics.number.limit" select="9"/>
<xsl:param name="callout.graphics.extension" select="'.gif'"/>
<xsl:param name="callout.unicode" select="0"/>
...

Calloutに関連するXSLスタイルシートのカスタマイズ項目
項目値
callout.list.table注釈リスト部分を 0:XHTMLのdt(Definition Term: 定義語)要素で記述 1:テーブルでレイアウトする
callout.graphics0:「(1)」のように、数字をかっこで囲んだリンクを使用 1:DocBook XSLのパッケージ内に用意されている、丸数字の画像を使用
callout.graphics.path番号の画像を含むディレクトリの場所。ドキュメントのツリーにDocBook XSLのディレクトリからリンクを張るか、コピペしてもよい
callout.graphics.number.limitこの数字を越えた番号は画像を使用しないようにする*1。ここでは、10以上の番号が読みにくいため、9にした
callout.graphics.extension使用する画像の拡張子(デフォルトは「'png'」)
callout.unicodeUnicode内の黒丸数字文字を使用(「callout.graphics」は0にする)
「callout.list.table」の値を0にすると、出力されたXHTMLの中でdd要素の中にp要素として注釈の文字列が入る形となり、番号のある行とその説明の間が空いてしまう場合があるので、必要に応じて、そのp要素を選択してマージン設定(0にするだけなので、単位は問わない)を行う必要かあるかもしれない。

ファイル名: docbook.css

div.calloutlist dl dd p
{
  margin-top: 0em;
}

丸数字については、Wikipediaの「丸数字」の項目を参照。表示のテストページとしても使える。

関連記事:

使用したバージョン: docbook-xsl-stylesheets 1.70.1

*1:自分で番号の画像を作る場合、その最大の番号を書く。デフォルトの画像は15番まであるので、ここのデフォルト値も15となっている