実用 DocBook 入門 Deb Richardson Open Source Writers Group deb@oswg.org 日本語訳: The Linux JF Project JF@linux.or.jp Revision History Revision 0.1 Nov 14 1999 Revised by: dlr Initial, incomplete, draft Revision 0.1.j-1 Feb 19 2000 First try to translation これは DocBook の使い方の実用的な入門書であり，初心者を念頭に置いて書かれて います．将来的にはこの文書は実作業に基づいたタグのリファレンスや，より多く の例を含むようになるでしょう． ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Table of Contents 著作権とライセンスについて はじめに ツール はじめてみよう 例題をステップ・バイ・ステップで学ぼう 要素のリファレンス まとめとさらなる参考文献 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" と書いたメールを 以下のアドレス宛に送ってください: 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 ページの例

これは見出しです

これは HTML ページの最初の段落です．

これは HTML ページの 2 番目の段落です．

マークアップタグは，"<" と ">" の括弧で括られた部分です．マークアップの「開 始」タグ(ページ内で「要素(element)」の始まりを表す) は単に "<" と ">" の括 弧で括られ，「終了」タグ(要素の終わりを表す)は "" で括られます．開 始タグとその対になる終了タグに挟まれている部分は全て，ページ内において完成 した「要素」となります． では「要素」とは何でしょうか? 文書要素は単に文書内の項目であり，項目を挟む タグによって定義されます．例えば HTML の完全な "H1" (見出しレベル 1)要素を 以下に示します:

これはレベル 1 の見出しです

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

これはレベル 1 の見出しです

これは段落です．

この例では "h1" 要素と "p" 要素が "body" 要素に含まれているのが分かると思い ます． しかし，HTML と DocBook SGML が似ている点はせいぜいこの程度です． HTML は主 に HTML ブラウザで表示した時のページの整形と見栄えを定義するために使われる マークアップ言語です．HTML はタグの組合せやタグが厳密に持つべき構造について はかなりいい加減です． これに対して，DocBook SGML は文書の整形の仕方ではなく文書の構造を定義するた めに使われるマークアップ言語です．DocBook には，要素を "bold" や "italic" にするためのタグはありません．その代わりに，各要素がどのように見えるべきか ではなく，各要素に「何が」入っているのかを定義することによって文書をマーク アップしていきます．DocBook のごく簡単な例を以下に示します:
これは文章の題名です これはレベル 1 の章の題名です これは最初の段落です． これは 2 番目の段落です．
ご覧の通り，整形に関する情報は文書中にはありません． "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" をマークアップするものとして，文書に最初に入れるべきものは文書型 定義です． ステップ 2: 「ルート」要素の追加 その次は，「ルート」要素を定義しなければなりません．ルート要素は文書中の他 の要素を全て含みます．article の場合は，ルート要素はそのまま "article" とな ります．したがって，文書型定義の後に "article" タグとその終了タグを追加しま す．
文書に追加される他の全ての要素は "article" タグに含まれるので，文書が完成し た時には，文書の最後のタグは "" になるはずです． ステップ 3: article ヘッダの追加 次は「ヘッダ」情報をいくつか追加するとよいでしょう．ヘッダ情報には文書の題 名，著者の名前やメールアドレス，文書の版の履歴などが含まれます．今のところ は，文書の題名と著者の名前を追加するだけにしておきましょう．
夏休みの思い出 Deb Richardson
ステップ 4: 最初のレベルの節の追加 ヘッダ情報の追加ができたら，次はレベル 1 セクションの内容を題名付きで書き加 えましょう．
夏休みの思い出 Deb Richardson 5 月 ぼくの夏休みは 5 月 14 日に始まった．卒業式のすぐ後だ． 大学を卒業したのはいいけれど仕事がなく，かなり借金もあったので，ぼくは たぶん就職しなきゃいけないと思った．5 月のほとんどは，すごそうに聞こえ るけれどひどく曖昧な技術や業績を履歴書に書き連ね，それを電話帳に載って いる会社に片っ端から送り付けて過ごした．
たぶん，そろそろコツが分かってきたのではないかと思います． ステップ 5: サブセクションとサブサブセクションの追加 サブセクションやサブサブセクションの追加も簡単です．2 レベルのセクションは "sect2" タグで開始・終了し，3 レベルのセクションは "sect3" タグで開始・終了 します．それ以降も同じです．標準の DocBook DTD は 5 レベルまでのセクション にしか対応していないので， "sect6", "sect7" やそれ以降のタグはありません． しかし，非常に長くて専門的な本を書かない限りは，5 レベルを超えるセクション が必要になることはたぶんないでしょう． 各レベルのセクションは自身より高いレベルのセクションに含まれていなければな りません．したがって，レベル 2 セクションはレベル 1 のセクションに含まれて いなければなりません．他も同じです．以下に例を示します: 5 月 ぼくの夏休みは 5 月 14 日に始まった．卒業式のすぐ後だ． 大学を卒業したのはいいけれど仕事がなく，かなり借金もあったので，ぼくは たぶん就職しなきゃいけないと思った．5 月のほとんどは，すごそうに聞こえ るけれどひどく曖昧な技術や業績を履歴書に書き連ね，それを電話帳に載って いる会社に片っ端から送り付けて過ごした． ぼくの履歴書 ぼくの履歴書は 4 ページで，主にぼくの学歴と職歴を書いていた． この履歴書はどう見ても貧弱だった． 職歴 ぼくがしたことがある仕事はほとんどが外食産業だった． 志の高い作家の多くと同じように，ぼくは成長期のほとんどを机を拭くことと ケチなチップに文句を言うことで過ごした． 見ての通り，この例は 3 つの終了タグで終わっています――各レベルのセクション は，高いレベルのセクションに含まれています．つまり「入れ子」になっています ． ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 要素のリファレンス DocBook 要素のうちよく使われるものを以下で説明します．ただし，説明は簡単か つ不十分です．必要と思うタグが見つかればリストに追加するつもりなので，この 節はこの先大きくなっていくことでしょう．筆者自身もまだ DocBook の初心者であ り，全ての要素を思った通りに使えている保証はない点に注意してください．言い 換えれば，この文書の内容は全部間違っているかもしれません ;-> article ヘッダ要素 DocBook の全ての "article" 文書は article ヘッダを含んでいなければなりませ ん．article ヘッダには文書の題名，著者，版の履歴や文書の概要などが含まれま す． article ヘッダ artheader: "artheader" 要素には， article ヘッダを構成する他の要素が全て含 まれています． article の題名 title: article ヘッダに含まれる "title" 要素は文書の題名を定義します．した がって， 101 Stupid Ferret Tricks という文書を書いているのであれば，article ヘッダは以下のようになるでしょう:
101 Stupid Ferret Tricks ...
著者に関する情報 author は著者に関連する全ての情報を含む要素です．この情報には著者の姓や名前 ，メールアドレス，所属組織などが含まれます．これらの情報は別々の "author" 要素としてマークアップされます．これはちょっと面倒に見えますが，そうする価 値はあります．マークアップが包括的になればなるほど，文書を処理した時に得ら れる情報も多くなります． とりあえず著者の姓と名前，所属組織，メールアドレスを含む article ヘッダの例 を示しましょう．普通必要なのは名前とメールアドレスだけですが，他の情報があ ってもかまいません．今のところは簡単に行きましょう:
... Deb Richardson Open Source Writers Group
deb@oswg.org
... ...
文書の版に関する情報 ほとんどの技術文書は，著者が文書を改善・更新するたびに版が増えていきます． 読者に文書の版が分かるようにするため，技術文書には版数やその他の情報が含ま れていることがよくあります．DocBook の article では版に関する情報は article ヘッダの一部であり， revhistory 要素に含まれます．以下に例を示します:
... 0.1 19 June 1999 dr - deb@oswg.org First draft, incomplete 0.2 20 Sept 1999 dr Updated section 14, added section 11.5 ... ...
文書の要約 多くの人は文章に要約を付けます．要約は普通は 1 段落の長さを超えることがない 短いまとめであり，文書の内容を読者に示します．DocBook の article では要約は article ヘッダの一部であり， abstract 要素に含まれます．
... この文書は Linux カーネルを起動する際に行われる手順を説明 します．この種の情報はシステムの機能には関係ありませんが， 様々なアーキテクチャにおいてシステムを起動させる方法は興味 深いと思われます． ... ...
プログラム，ファイル名，コマンド等のマークアップ コンピュータ関連の書類や文書を書く際には，プログラムの例やファイル名，コマ ンド，その他のコンピュータ関係の言葉を文書内で書かなければならないことがよ くあるでしょう．DocBook は――技術文書を書くために設計されているので――こ ういった言葉を専用の要素としてマークアップするためのタグを持っています． プログラムの例 複数行に渡るプログラムの例を文書に入れる時は programlisting タグを使います ．レベル 1 セクションの一部として使う例を示します: 例を示します: if [ $# -eq 1 ] then if [ ! -r $1 ] then echo Cannot read \"$1\". Exiting. >&2 exit 1 fi fi programlisting タグは普通，空白文字や整形の状態が保存されたままレンダリング されるように処理されます．また，クーリエ等の固定幅フォントが使われます． SGML, XML, HTML の例を文書に入れる場合には，その中に含まれるタグをパーザが 無視するように少し特殊なマークアップを行う必要があります．この特殊なマーク アップとは CDATA マーカといって， programlisting 開始タグの後に直接表れて programlisting 終了タグの直前で終わります． WWW ページのタイトル WWW ページの内容 ]]> CDATA マーカの始まりは "" で ある点に注意してください．始まりと終わりの CDATA マーカに挟まれた全てのマー クアップは処理ツールに無視され，単に普通のテキストの一部であるかのように扱 われます． ファイル名とディレクトリ DocBook 内ではファイル名は filename を使って十分にマークアップしてください ．ディレクトリも同じタグでマークアップしますが，属性として class= "directory" を追加してください．以下のようにします: DocBook Tools をインストールする際には，たくさんのファイルが /usr/bin にインストールされます． インストールされるファイルは db2html や db2pdf 等です． コマンド コマンドやコマンド行をマークアップする時には，見たままの名前の command タグ を使います．使い方は以下の通りです: HTML 出力を DocBook インスタンスから得たい時には，コマンド行から db2html コマンドを使ってください． コマンドが複数個の部分からできていて，その一部が実際には文書中で「置き換え 可能」なことがよくあります．つまり，コマンドを入力するユーザが置き換えたり 変更したりできる文字列を示す場合です．例を以下に示します: HTML 出力を DocBook インスタンスから得たい時には，以下のコマンド行を入 力してください: db2htmlmy-filename.sgml コマンドのオプションやフラグも別々にマークアップできます． 異なるスタイルシート群を使って DocBook インスタンスから HTML を 生成し たい場合には，コマンド行で "-d" オプションを使ってください: db2html この節の内容はさらに追加する予定です． ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ まとめとさらなる参考文献 さて，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 と書いたメールを 宛に送ると購読できます． ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DocBook に関する他の情報源 ネットワーク上の情報 TBD -- DocBook と SGML に関するネットワーク上のリソースを列挙 ネットワーク以外の情報 TBD -- DocBook と SGML に関するネットワーク以外のリソースを列挙 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 日本語訳について 日本語訳は Linux Japanese FAQ Project が行いました．翻訳に関するご意見は JF プロジェクト 宛に連絡してください． 改訂履歴を以下に示します． 0.1.j-1, Feb 19 2000 翻訳: 藤原輝嘉 校正: ☆ 武井伸光 ☆ 佐野武俊