## 実用 DocBook 入門

Deb
Richardson
Open Source Writers Group

                deb@oswg.org

The Linux JF Project
日本語訳

                JF@linux.or.jp

0.1
Nov 14 1999
dlr
Initial, incomplete, draft
0.1.j-1
Feb 19 2000
First try to translation

これは DocBook の使い方の実用的な入門書であり，初心者を念頭に置いて 書かれています．将来的にはこの文書は実作業に基づいたタグのリファレンス や，より多くの例を含むようになるでしょう．

## 著作権とライセンスについて

Copyright (c) 1999 by Deb Richardson. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v0.4 (8 June 1999) or later (the latest version of which is available at http://www.opencontent.org/openpub/).

この文書の現在の「マスター」の版は http://www.oswg.org にある Open Source Writers Group の WWW サイトから入手できます．

## はじめに

Open Source Writers Group (OSWG - http://www.oswg.org) では， DocBook という SGML Document Type Definition (DTD, 文書型定義) を 全ての文書の標準の「ソース」形式として使っています．ここでいう文書には 書籍，記事，論文，FAQ, HOWTO 文書，mini-HOWTO 文書などが含まれます．

DocBook が使われる理由はいろいろあります――DocBook は表現力のある DTD であり，技術文書やその他の文書に対するほとんど全ての要件を満たしており， オープンソースやオープンコンテントの情報のための標準の DTD の地位を 急速に獲得しつつあります．また，DocBook のインスタンスを処理する オープンソースのツールもたくさんあり，その中には非常にうまく動作するも のもあります．さらに，Norman Walsh が作成した modular DocBook stylesheets はフリーに入手できる上に非常に完成度が高く，開発も活発です． これらの事情により，DocBook は標準の SGML DTD として注目すべき選択肢と なっています．

この文書は DocBook を使って文書をマークアップするための簡単な入門であ り，Open Source Writers Group の CVS (協調バージョン管理システム) に入っ ています．いかなる種類であれフリーのオープンコンテントな文書に関する 作業を行っている全ての著者や著者グループは，この CVS を自由に入手でき ます．CVS システムと OSWG の文書ライセンスの方針について詳しく知りたけ れば，http://www.oswg.org に ある OSWG の WWW サイトをご覧になってください．

より完全な DocBook のリファレンスについては http://www.docbook.org をご覧ください．このサイトは Norman Walsh の DocBook: The Definitive Guide (O'Reilly http://www.oreilly.com 発行) の電子版の一次サイトです．どうせなら近所の書店(実際の書店でも バーチャルな書店でも)に行って書籍版を注文するとよいでしょう．DocBook の素晴らしい世界を深く知ろうと思っているなら，お金を払って Norman の本 を買う価値は絶対にあります．

マークアップ言語の初心者であれば， DocBook: The Definitive Guide の少なくとも最初の 2 つの章は読んでおくことをお勧めします．これらの章 では HTML, SGML, XML の概要と構造的・意味的なマークアップに関係する 主な概念の入門的な説明が書かれています．

## ツール

SGML に関連するツールは大きく分けて 2 種類あります――SGML 文書を作る ためのツールと，SGML 文書を処理するためのツールです．両者は大きく異な る種類のツールです．というのも，まったく違うことをするツールだからです．

### オーサリング用ツール

「」の節 で述べたように，DocBook の文書を作成するための特殊なツールは実は必要あ りません．実際のところ，今の時点ではお気に入りのテキストエディタを使う のがもっとも確実な方法です．DocBook の文書はプレーンテキストの ASCII ファイルでなければならず，特殊なバイナリフォーマットであってはなりませ ん．したがって，vi, emacs, notepad, textpad が使えますし，プレーン ASCII ファイルが出力できればその他のどんなテキストエディタでも使えます．

手動でタグを打つことなく DocBook や他の種類の SGML 文書を作成できるよ うなツールがいくつか開発中です．しかし現時点では，これらのツールは入手 できないか，あるいは入手可能であっても十分な信頼性を持っていません． 今のところは単にテキストエディタを使い，マークアップのタグは手動で追加 する方法がお勧めです．これは多少面倒ではありますが，難しくはありません． 得られる結果はきっと費した時間に見合うだけのものになります．

### 処理ツール ―― DocBook Tools

SGML 処理ツールは，SGML 文書を他の形式に変換するために使うスクリプトと プログラムのセットです．整形処理が行われて文書の最終版が生成されるのは， この処理の段階です．

OSWG では「DocBook Tools」というパッケージを使って文書群の一部の DocBook インスタンスを処理しています．このパッケージには たくさんのプログラムの使用を簡略化するためのスクリプト群が含まれており， HTML, PDF, PS, RTF, DVI, TeX を含む各種出力形式のファイルを簡単に作成 できます．

#### DocBook Tools の入手

DocBook Tools に必要なパッケージ全ては http://sourcware.cygnus.com/docbook-tools/ から入手できます．

#### DocBook Tools のインストール

残念ながら，DocBook Tools のインストールと設定は(今のところ)この文書の 対象ではありません．作業の補助と文書については DocBook Tools の WWW ペー ジを参照してください．何か問題があれば，"docbook-tools-discuss" という DocBook Tools のメーリングリストを利用してください．他の DocBooks Tools ユーザからの手助けが得られることでしょう．購読に関する情報はこの サイトにあります．

docbook-tools-discuss メーリングリストで必要な手助けが得られなければ， oswg-docbook メーリングリストに参加して，ここで質問してください．この メーリングリストを購読するにはメールの Subject 行に "subscribe" と書い たメールを以下のアドレス宛に送ってください:

    oswg-docbook-request@oswg.org

#### DocBook Tools の利用

DocBook Tools の利用はとても簡単です．パッケージをインストールすると パッケージ群が `/usr/bin` に インストールされます．パッケージに含まれる各スクリプトは DocBook 文書 を別の出力形式に変換します．スクリプトには以下のようなものがあります:

- `db2html` - DocBook から HTML に変換

- `db2dvi` - DocBook から DVI に変換

- `db2pdf` - DocBook から PDF に変換

- `db2ps` - DocBook から PS に変換

- `db2rtf` - DocBook から RTF に変換

これらのスクリプトの使用方法は非常に簡単で，スクリプト名と処理したい DocBook ファイル名を単にコマンドライン上で指定するだけです． たとえば以下のように指定します:

    $ db2html my-document.sgml

これで何か問題があれば，先に紹介したどちらかのメーリングリストで質問す るとよいでしょう．

## はじめてみよう

DocBook DTD を使って文書をマークアップするためには特殊なツールはまった く必要ありません．SGML ファイル(普通は .sgml か .sgm という ファイル名拡張子が付いています)は実は単なるプレーンテキストの ASCII ファイルに過ぎず，テキスト中に SGML の「タグ」が散らばっているだけです． 筆者としては，読者の皆さんが DocBook のマークアップを行う際にはお気に 入りのテキストエディタ(vi, emacs, notepad など何でも)を使うことを強く お勧めします．ファイルが ASCII 形式のプレーンテキストであることは非常 に重要です．したがって，本格的なワープロは機能が余計なだけではなく， ASCII でないファイルを作ってしまうことがあります．ですからテキストエディタ を使いましょう．これが最良かついちばん簡単な方法です．

DocBook でマークアップされた文書は色々な点で HTML そっくりに見えます． 例えば，以下にごく簡単な HTML ページを示します:

    <html>
    <head>
    <title>HTML ページの例</title>
    </head>
    <body bgcolor="#000000">
    <h1>これは見出しです</h1>
    <p>
    これは HTML ページの最初の段落です．
    </p>
    <p>
    これは HTML ページの 2 番目の段落です．
    </p>
    </body>
    </html>

マークアップタグは，"<" と ">" の括弧で括られた部分です． マークアップの「開始」タグ(ページ内で「要素(element)」の始まりを表す) は単に "<" と ">" の括弧で括られ， 「終了」タグ(要素の終わりを表す)は "" で括られます． 開始タグとその対になる終了タグに挟まれている部分は全て， ページ内において完成した「要素」となります．

では「要素」とは何でしょうか? 文書要素は単に文書内の項目であり， 項目を挟むタグによって定義されます．例えば HTML の完全な "H1" (見出し レベル 1)要素を以下に示します:

    <h1>これはレベル 1 の見出しです</h1>

要素は他の何らかの要素を含むこともできます．これは DTD によって定義さ れます．例えば，HTML の "body" 要素は見出し(heading)，段落(paragraph)， 列挙(list)等の様々な要素を含みます．例を示します:

    <body>
    <h1>これはレベル 1 の見出しです</h1>
    <p>
    これは段落です．
    </p>
    </body>

この例では "h1" 要素と "p" 要素が "body" 要素に含まれているのが分かる と思います．

しかし，HTML と DocBook SGML が似ている点はせいぜいこの程度です． HTML は主に HTML ブラウザで表示した時のページの整形と見栄えを定義する ために使われるマークアップ言語です．HTML はタグの組合せやタグが厳密に 持つべき構造についてはかなりいい加減です．

これに対して，DocBook SGML は文書の整形の仕方ではなく文書の構造を定義 するために使われるマークアップ言語です．DocBook には，要素を "bold" や "italic" にするためのタグはありません．その代わりに，各要素がどのよう に見えるべきかではなく，各要素に「何が」入っているのかを定義することに よって文書をマークアップしていきます．DocBook のごく簡単な例を以下に示 します:

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
    <article>

       <artheader>
          <title>これは文章の題名です</title>
       </artheader>

       <sect1>
          <title>これはレベル 1 の章の題名です</title>
          <para>
          これは最初の段落です．
          </para>
          <para>
          これは 2 番目の段落です．
          </para>
       </sect1>

    </article>

ご覧の通り，整形に関する情報は文書中にはありません．

"article" タグはその文書が article (記事)であることを表します． 文書中の他の全ての要素はこの「ルート(root, 根の)」要素に含まれます． 最初の "title" タグのペアは記事のタイトルを示し，このペアは "artheader(article header)" 要素に含まれます．2 番目の "title" タグの ペアは "sect1" 要素に含まれており，この節の題名を表します．

さて，一番最初にある "DOCTYPE" タグは何でしょうか? これは 「文書型定義(document type declaration)」といって，その文書が どんな種類の SGML 文書であるかを定義する方法であり，マークアップのため にどの DTD を使うかを示します．しかし，文書型定義の何たるかを理解しな ければならないわけではなく，DocBook を使ってマークアップする全ての文書 の先頭に必ず置けばそれで十分です．作成する文書の種類によっては "DOCTYPE" の次の単語は変更する必要があるかもしれません――この例では "article" ですが，"book", "chapter", "refentry" その他を書いてもかまい ません．

OSWG の文書群について見ると，もっとも多い文書の型は "article" です． article は HOWTO, mini-HOWTO, 雑誌の記事，論文などを含みます． "article" は実際には，ある程度決まった文章量と構造の複雑さをもった文書 に使うための一般的なクラスです．マニュアルページ("man" ページ)や普通の 書籍を書くのでなければ，あなたが OSWG の文書を書く時には "article" を 使う機会がいちばん多いでしょう．

## 例題をステップ・バイ・ステップで学ぼう

さて，これから簡単な DocBook の文書を作成する手順を一通り眺めてみましょ う．この例にはよく使われる DocBook の要素がいくつか含まれていますし， DocBook でマークアップされた文書がどう見えるかもだいたいわかります．

DocBook の要素とその使い方のもっときちんとした一覧が欲しければ， または Norman Walsh の DocBook: The Definitive Guide を見てください．後者は http://www.docbook.org で入手できます．

### ステップ 1: 文書型定義(DTD)を含める

"article" をマークアップするものとして，文書に最初に入れるべきものは文 書型定義です．

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

### ステップ 2: 「ルート」要素の追加

その次は，「ルート」要素を定義しなければなりません．ルート要素は 文書中の他の要素を全て含みます．article の場合は，ルート要素はそのまま "article" となります．したがって，文書型定義の後に "article" タグと その終了タグを追加します．

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
    <article>

    </article>

文書に追加される他の全ての要素は "article" タグに含まれるので， 文書が完成した時には，文書の最後のタグは "`</article>`" になるはずです．

### ステップ 3: article ヘッダの追加

次は「ヘッダ」情報をいくつか追加するとよいでしょう．ヘッダ情報には文書 の題名，著者の名前やメールアドレス，文書の版の履歴などが含まれます． 今のところは，文書の題名と著者の名前を追加するだけにしておきましょう．

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
    <article>

    <artheader>
       <title>夏休みの思い出</title>
       <author>
          <firstname>Deb</firstname>
          <surname>Richardson</surname>
       </author>
    </artheader>

    </article>

### ステップ 4: 最初のレベルの節の追加

ヘッダ情報の追加ができたら，次はレベル 1 セクションの内容を題名付きで 書き加えましょう．

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
    <article>

    <artheader>
       <title>夏休みの思い出</title>
       <author>
          <firstname>Deb</firstname>
          <surname>Richardson</surname>
       </author>
    </artheader>

    <sect1>
    <title>5 月</title>
    <para>
    ぼくの夏休みは 5 月 14 日に始まった．卒業式のすぐ後だ．
    大学を卒業したのはいいけれど仕事がなく，かなり借金もあったので，ぼくは
    たぶん就職しなきゃいけないと思った．5 月のほとんどは，すごそうに聞こえ
    るけれどひどく曖昧な技術や業績を履歴書に書き連ね，それを電話帳に載って
    いる会社に片っ端から送り付けて過ごした．
    </para>
    </sect1>

    </article>

たぶん，そろそろコツが分かってきたのではないかと思います．

### ステップ 5: サブセクションとサブサブセクションの追加

サブセクションやサブサブセクションの追加も簡単です．2 レベルの セクションは "sect2" タグで開始・終了し，3 レベルのセクションは "sect3" タグで開始・終了します．それ以降も同じです． 標準の DocBook DTD は 5 レベルまでのセクションにしか対応していないので， "sect6", "sect7" やそれ以降のタグはありません．しかし，非常に長くて専 門的な本を書かない限りは，5 レベルを超えるセクションが必要になることは たぶんないでしょう．

各レベルのセクションは自身より高いレベルのセクションに含まれていなけれ ばなりません．したがって，レベル 2 セクションはレベル 1 のセクションに 含まれていなければなりません．他も同じです．以下に例を示します:

    <sect1>
    <title>5 月</title>
    <para>
    ぼくの夏休みは 5 月 14 日に始まった．卒業式のすぐ後だ．
    大学を卒業したのはいいけれど仕事がなく，かなり借金もあったので，ぼくは
    たぶん就職しなきゃいけないと思った．5 月のほとんどは，すごそうに聞こえ
    るけれどひどく曖昧な技術や業績を履歴書に書き連ね，それを電話帳に載って
    いる会社に片っ端から送り付けて過ごした．
    </para>

    <sect2>
    <title>ぼくの履歴書</title>
    <para>
    ぼくの履歴書は 4 ページで，主にぼくの学歴と職歴を書いていた．
    この履歴書はどう見ても貧弱だった．
    </para>

    <sect3>
    <title>職歴</title>
    <para>
    ぼくがしたことがある仕事はほとんどが外食産業だった．
    志の高い作家の多くと同じように，ぼくは成長期のほとんどを机を拭くことと
    ケチなチップに文句を言うことで過ごした．
    </para>
    </sect3>

    </sect2>

    </sect1>

見ての通り，この例は 3 つの終了タグで終わっています――各レベルの セクションは，高いレベルのセクションに含まれています．つまり「入れ子」 になっています．

## 要素のリファレンス

DocBook 要素のうちよく使われるものを以下で説明します．ただし，説明は 簡単かつ不十分です．必要と思うタグが見つかればリストに追加するつもりな ので，この節はこの先大きくなっていくことでしょう．筆者自身もまだ DocBook の初心者であり，全ての要素を思った通りに使えている保証はない点 に注意してください．言い換えれば，この文書の内容は全部間違っているか もしれません ;->

### article ヘッダ要素

DocBook の全ての "article" 文書は article ヘッダを含んでいなければなり ません．article ヘッダには文書の題名，著者，版の履歴や文書の概要などが 含まれます．

#### article ヘッダ

`artheader`: "artheader" 要素には， article ヘッダを構成する他の要素が全て含まれています．

#### article の題名

`title`: article ヘッダに含まれる "title" 要素は文書の題名を定義します．したがって， 101 Stupid Ferret Tricks という文書を書いているのであれば，article ヘッダは以下のようになるでしょ う:

    <article>
       <artheader>
          <title>101 Stupid Ferret Tricks</title>
       </artheader>

    ...

    </article>

#### 著者に関する情報

`author` は著者に関連する全ての情報を 含む要素です．この情報には著者の姓や名前，メールアドレス，所属組織など が含まれます．これらの情報は別々の "author" 要素としてマークアップされ ます．これはちょっと面倒に見えますが，そうする価値はあります． マークアップが包括的になればなるほど，文書を処理した時に得られる情報も 多くなります．

とりあえず著者の姓と名前，所属組織，メールアドレスを含む article ヘッ ダの例を示しましょう．普通必要なのは名前とメールアドレスだけですが， 他の情報があってもかまいません．今のところは簡単に行きましょう:

    <article>
       <artheader>

          ...

          <author>
             <firstname>Deb</firstname>
             <surname>Richardson</surname>
             <affiliation>
                <orgname>Open Source Writers Group</orgname>
                <address>
                   <email>deb@oswg.org</email>
                </address>
             </affiliation>
          </author>

          ...

       </artheader>

    ...

    </article>

#### 文書の版に関する情報

ほとんどの技術文書は，著者が文書を改善・更新するたびに版が増えていきま す．読者に文書の版が分かるようにするため，技術文書には版数やその他の 情報が含まれていることがよくあります．DocBook の article では 版に関する情報は article ヘッダの一部であり， `revhistory` 要素に含まれます． 以下に例を示します:

    <article>
       <artheader>

          ...

          <revhistory>

             <revision>
                <revnumber>0.1</revnumber>
                <date>19 June 1999</date>
                <authorinitials>dr - deb@oswg.org</authorinitials>
                <revremarks>
                   First draft, incomplete
                </revremarks>
             </revision>

             <revision>
                <revnumber>0.2</revnumber>
                <date>20 Sept 1999</date>
                <authorinitials>dr</authorinitials>
                <revremarks>
                   Updated section 14, added section 11.5
                </revremarks>
             </revision>

          </revhistory>

          ...

       </artheader>

    ...

    </article>

#### 文書の要約

多くの人は文章に要約を付けます．要約は普通は 1 段落の長さを超えること がない短いまとめであり，文書の内容を読者に示します．DocBook の article では要約は article ヘッダの一部であり， `abstract` 要素に含まれます．

    <article>
       <artheader>

       ...

          <abstract>
             <para>
                この文書は Linux カーネルを起動する際に行われる手順を説明
                します．この種の情報はシステムの機能には関係ありませんが，
                様々なアーキテクチャにおいてシステムを起動させる方法は興味
                深いと思われます．
             </para>
          </abstract>

       ...

       </artheader>

    ...

    </article>

### プログラム，ファイル名，コマンド等のマークアップ

コンピュータ関連の書類や文書を書く際には，プログラムの例やファイル名， コマンド，その他のコンピュータ関係の言葉を文書内で書かなければならない ことがよくあるでしょう．DocBook は――技術文書を書くために設計されてい るので――こういった言葉を専用の要素としてマークアップするためのタグを 持っています．

#### プログラムの例

複数行に渡るプログラムの例を文書に入れる時は `programlisting` タグを使います． レベル 1 セクションの一部として使う例を示します:

    <sect1>
    <para>
    例を示します:
    </para>

    <programlisting>
    if [ $# -eq 1 ]
    then
      if [ ! -r $1 ]
      then
        echo Cannot read \"$1\".  Exiting. >&2
        exit 1
      fi
    fi
    </programlisting>

    </sect1>

`programlisting` タグは普通， 空白文字や整形の状態が保存されたままレンダリングされるように処理されま す．また，クーリエ等の固定幅フォントが使われます．

SGML, XML, HTML の例を文書に入れる場合には，その中に含まれるタグを パーザが無視するように少し特殊なマークアップを行う必要があります． この特殊なマークアップとは CDATA マーカといって， `programlisting` 開始タグの後に直接表 れて `programlisting` 終了タグの直前で 終わります．

    <programlisting>
    <![CDATA[

    <html>
    <head>
    <title>WWW ページのタイトル</title>
    </head>

    <body bgcolor="#ffffff">
    WWW ページの内容
    </body>
    </html>

    ]]>

    </programlisting>

CDATA マーカの始まりは "`<![CDATA[`" であり，CDATA マーカの終わりは "`]]>`" である点に注意してください． 始まりと終わりの CDATA マーカに挟まれた全てのマークアップは処理ツール に無視され，単に普通のテキストの一部であるかのように扱われます．

#### ファイル名とディレクトリ

DocBook 内ではファイル名は `filename` を使って十分にマークアップしてください． ディレクトリも同じタグでマークアップしますが，属性として `class="directory"` を追加してください． 以下のようにします:

    <para>
    DocBook Tools をインストールする際には，たくさんのファイルが
    <filename class="directory">/usr/bin</filename> にインストールされます．
    インストールされるファイルは
    <filename>db2html</filename> や <filename>db2pdf</filename>
    等です．
    </para>

#### コマンド

コマンドやコマンド行をマークアップする時には，見たままの名前の `command` タグを使います．使い方は以下の通りです:

    <para>
    HTML 出力を DocBook インスタンスから得たい時には，コマンド行から
    <command>db2html</command> コマンドを使ってください．
    </para>

コマンドが複数個の部分からできていて，その一部が実際には文書中で 「置き換え可能」なことがよくあります．つまり，コマンドを入力するユーザ が置き換えたり変更したりできる文字列を示す場合です．例を以下に示します:

    <para>
    HTML 出力を DocBook インスタンスから得たい時には，以下のコマンド行を入
    力してください:
    <command>db2html<replaceable>my-filename.sgml</replaceable></command>
    </para>

コマンドのオプションやフラグも別々にマークアップできます．

    <para>
    異なるスタイルシート群を使って DocBook インスタンスから HTML を 生成し
    たい場合には，コマンド行で "-d" オプションを使ってください:
    </para>

    <programlisting>
    <command>db2html <option>-d</option> </command>
    </programlisting>

この節の内容はさらに追加する予定です．

## まとめとさらなる参考文献

さて，DocBook をどのように使うのかをごく簡単に見てきました． この文書はこの先拡張し，様々なタグのリファレンスとこれらの使い方などを 増やしていきます．今のところは，OSWG の WWW サイトで入手できる `*.sgml` をいくつか見ることをお勧めします――大抵の 場合，DocBook を覚える近道は例を見ることです．OSWG が持っている `*.sgml` ファイルへのリンクは http://www.oswg.org/oswg-nightly にあります．

また，筆者は Norman Walsh の Docbook: The Definitive Guide を読むことをお勧めします．この書籍のオンライン版は http://www.docbook.org から入手できます．

質問や助けが必要であれば，OSWG の docbook に関する議論用の メーリングリストに参加するとよいでしょう．サブジェクト行に `subscribe` と書いたメールを

    oswg-docbook-request@oswg.org

宛に送ると購読できます．

## DocBook に関する他の情報源

### ネットワーク上の情報

TBD -- DocBook と SGML に関するネットワーク上のリソースを列挙

### ネットワーク以外の情報

TBD -- DocBook と SGML に関するネットワーク以外のリソースを列挙

## 日本語訳について

日本語訳は Linux Japanese FAQ Project が行いました． 翻訳に関するご意見は JF プロジェクト <JF@linux.or.jp> 宛に連絡してください．

改訂履歴を以下に示します．

0.1.j-1, Feb 19 2000
  翻訳:

    藤原 輝嘉 <fujiwara@linux.or.jp>

  校正:

    - 武井 伸光 <takei@cc.kochi-u.ac.jp>

    - 佐野 武俊 <kgh12351@nifty.ne.jp>