4.4. DocBook エレメントの使い方

DTD を解析して、それに基づいてエレメントを挿入する 機能の付いたエディタを利用すると、カーソル位置で特定のエレメントを使えるか どうかが分かるのでかなり便利です。これなら、文書のどこにも無効なエレメントを 入れることがなくなります。

将来変更があってもなるべく簡単に移行できるように、文書の作成者は、 DocBook DTD の XML バージョンとの互換性をできるだけ 保つように心がけたほうがいいでしょう。つまり、エレメント名には大文字を 使い、属性内ではダブルクオートでくくり、"短縮タグ"(下記参照)は 使わないようにして、終了タグも省略しないようにしましょう。(psgml + emacs のような)自動でタグを挿入するツールの大部分は、こうしたルールに自動的に 従っているか、ちょっと設定するだけで従います。

タグの最小化(minimization)にはいくつかのやり方 があります。 空タグ(empty tag)もそれにあたります。タグの最小化の例としては、終了タグを入れ るかわりに、</> とだけ打つことです。以前にも述 べましたが、他にも、タグの省略(tag omission)というのがあります。次にその両方の 例を挙げます。


<para>強調タグを例にとると、まず、<emphasis>ここ</>では終了タグが省略され、
さらに、<>ここ</>では空タグも使われています。</para>

個々の文書型には特定の構造があるので、そうした文書の例はのちほど紹介 します。(Section 4.11参照)

上記の説明を考慮した上で、次に DocBook を使って文書を書く方法を説明して いきます。

4.4.1. 便利なコマンド

Table 4-1では、一般的な文書を作成する 際に便利なコマンドを一覧表示しています。ただ、いくつかのエレメントは、 特定の文脈でのみ有効であることを忘れないでください。

(訳注: 下記 Table 4-1 では、<to> </to> と書かれた部分がありましたが、そのまま使うとエラーに なり紛らわしいので、<para></para> に修正しています。)

Tip: 変換するフォーマットが変わると、特定のタグでの表示結果も変わることが ときどきあります。DocBook で初めて文書を作成する場合は、公開前に、いくつかの フォーマットで作成した文書がどういう体裁になるのかを確認したほうがよいで しょう。

Note: 変換結果は、変換の際に使ったスタイルシートに依存するので、マークアップ はできるだけたくさん使うことをお薦めします。標準のスタイルシートでは 出力結果にあまり違いが見えないときでも、そうしたタグを目立たせる特定の 出力フォーマットがあるかもしれないからです。


Table 4-1. 便利なコマンド

用途コマンド出力結果
メールアドレス<email> address@domain</email>
著者について<author>...</author>(下記の例を参照)
著者名
<firstname>First_Name</firstname>
<othername>Middle_Name</othername>
<surname>Surname</surname>
              
First Name Middle Name Surname
キー名(キーボード上の表記)<keycap>F1</keycap>F1
キーのシンボル名<keysym>KEY_F1</keysym>KEY_F1
キーのコード<keycode>0x3B</keycode>0x3B
キー入力
<keycombo>
   <keycap>Ctrl</keycap>
   <keycap>S</keycap>
</keycombo>
              
Ctrl-S
プログラムメニュー<guimenu> ファイル</guimenu>ファイル
メニューアイテム<guimenuitem>保存</guimenuitem>保存
メニュー選択
<menuchoice>
   <shortcut>
      <keycombo>
         <keycap>Ctrl</keycap>
         <keycap>S</keycap>
      </keycombo>
   </shortcut>
   <guimenu>ファイル</guimenu>
   <guimenuitem>保存</guimenuitem>
</menuchoice>
              
ファイル->保存 (Ctrl-S)
マウスボタン<mousebutton>left</mousebutton>left
コマンド名<command>comando</command>command
アプリケーション名<application>application</application>application
参考文献表示<citation>reference</citation>[reference]
引用
<blockquote>
   <attribution>著者名</attribution>
   <para>引用文</para>
</blockquote>
              

 

引用文

 
--著者名 

索引右記参照 Section 4.5参照
ファイル名
<filename>file</filename>
file
ディレクトリ
<filename id="directory">directory</filename>
directory/
強調[a]
<emphasis>text</emphasis>
text
脚注
<footnote>
   <to>脚注文</to>
</footnote>
(この表組に最後を参照)
URL
<ulink url="http://www.conectiva.com>Conectiva S.A.</>
Conectiva S.A.
マーク付き箇条書き
<itemizedlist>
   <listitem>
      <para>アイテム</para>
   </listitem>
   <listitem>
      <para>アイテム</para>
   </listitem>
</itemizedlist>

  • アイテム

  • アイテム

番号付き箇条書き
<orderedlist>
   <listitem>
      <para>アイテム</para>
   </listitem>
   <listitem>
      <para>アイテム</para>
   </listitem>
</orderedlist>

  1. アイテム

  2. アイテム

書き分けた箇条書き
<segmentedlist>
   <title>2 進数から 10 進数への変換表</title>
   <segtitle> 2 進数</segtitle>
   <segtitle>10 進数</segtitle>
   </seglistitem><seg>00</seg><seg>0</seg>
   </seglistitem>
   <seglistitem><seg>01</seg><seg>1</seg>
   </seglistitem>
   <seglistitem><seg>10</seg><seg>2</seg>
</segmentedlist>

2 進数から 10 進数への変換表

進数: 00

10 進数: 0

進数: 01

10 進数: 1

進数: 10

10 進数: 2

見出し付き箇条書き
<variablelist>
   <varlistentry>
      <term>見出し 1</term>
      <listitem>
         <para>説明</para>
      </listitem>
   </varlistentry>
   <varlistentry>
      <term>見出し 2</term>
      <listitem>
         <para>説明</para>
      </listitem>
   </varlistentry>
</variablelist>

見出し 1

説明

見出し 2

説明

シンプルな箇条書き
<simplelist type="horiz" columns="3">
   <member>1</member>
   <member>2</member>
   <member>3</member>
   <member>4</member>
   <member>5</member>
   <member>6</member>
</simplelist>
<simplelist type="inline">
   <member>A</member>
   <member>B</member>
   <member>C</member>
   <member>D</member>
   <member>E</member>
   <member>F</member>
</simplelist>

123
456

A, B, C, D, E, F
画像右記参照Section 4.6参照
表組み右記参照Section 4.7参照
プログラムへのコメント挿入右記参照Section 4.8参照
用語集
<glossentry>
   <glossterm>Term</glossterm>
   <glossdef>
      <para>Definition</para>
   </glossdef>
</glossentry>
この文書の巻末にある用語集参照
相互参照
<section id="secao">
...
</section>
<section id="reference the other section">
...
<para>Please, see<xref linkend="secao"> for more information.
</para>
(画像等の出力結果欄参照)
Notes:
a. 強調表示にはいつくかの方法があります。斜体の太字が最も一般的ですが、 DocBook では斜体しかサポートしていません。太字を使うには、利用している スタイルシートに設定を追加する必要があります。