DocBook 要素のうちよく使われるものを以下で説明します．ただし，説明は 簡単かつ不十分です．必要と思うタグが見つかればリストに追加するつもりな ので，この節はこの先大きくなっていくことでしょう．筆者自身もまだ DocBook の初心者であり，全ての要素を思った通りに使えている保証はない点 に注意してください．言い換えれば，この文書の内容は全部間違っているか もしれません ;->
DocBook の全ての "article" 文書は article ヘッダを含んでいなければなり ません．article ヘッダには文書の題名，著者，版の履歴や文書の概要などが 含まれます．
artheader: "artheader" 要素には， 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> |
この節の内容はさらに追加する予定です．