オープン・ソース・プロジェクトの文書作成について考えたり、あるいはLinux Documentation Projectや Linuxなどのオープン・ソース・プロジェクトに関する資料用のページをブラウズしたことがある方は、おそらくDocBookについて聞いたことがあるでしょう。しかし、それが一体何であるかはご存知ないかもしれません。

DocBookとは

DocBookは、SGMLまたはXMLの文書型定義 (DTD) によって定義されたマークアップ言語です。基本的に、DocBookは文書の構造を記述するタグのセットです。DocBookタグはHTMLタグと似ているので、HTMLを使ったことがあれば、DocBookはまったくなじみのないものではないでしょう。DocBookはHTMLよりも少し複雑ですが、単一の文書から複数の形式を容易に表示できるため、プレーンHTMLよりもずっと役立ちます。この記事では、単純な記事 (文書) をDocBookで作成する方法と、SGML-tools Liteを使ってその文書からさまざまな種類のファイル形式を表示する方法について説明します。

DocBookは、1991年から、さまざまな形式で出回ってきました。もともとDocBookは、UNIXの文書交換を支援するために作成されました。それ以来、DocBookは4つのメジャー・バージョンが作成されており、現在はOrganization for the Advancement of Structured Information Standards (OASISという呼び方の方が知られている) によって管理されています。(『参考文献』を参照)

DocBookという用語は、マークアップ言語と、DocBook文書を他の形式に変換するのに使用するツールを表す、総称的な用語としても使われることがあります。技術的には、DocBookはDTDのみを表す用語ですが、SGML-tools Liteや他の変換ツールがなければ、DocBookはまったく役に立ちません。

上に戻る

なぜDocBookを使うのか

DocBookの主なセールス・ポイントは、移植性です。DocBookマークアップで作成された文書は、高価なツールを使わなくても、HTML、PostScript、PDF、RTF、DVI、およびプレーンASCIIテキストに、簡単即座に変換することができます。実際、DocBookとDocBookの処理に使うすべてのツールは、オープン・ソース・ライセンス下にあり、無料で入手できます。DocBook文書はプレーン・テキストで、文書をプレーンASCIIテキストで保管できる任意のテキスト・エディターやワード・プロセッサーで編集することができます。ワード・プロセッサーを使う場合は、DocBook文書をプレーン・テキストとして保管するように注意してください。そうしないと、正しく構文解析されません。文書を複数の形式 (たとえば、印刷形式やオンライン形式) で使用する場合は、DocBookがすばらしいソリューションであることが分かるでしょう。

DocBookのもうひとつの利点は、文書作成者が文書の書式設定やレイアウトについて心配しなくてもよくなることです。DocBookは、文書の構造だけを扱います。たとえば、文書作成者はDocBookマークアップを使って、<emphasis> タグで強調すべきテキストを示すだけです。文書変換後のフォーマットに応じて、強調部分はイタリック体、下線付き、あるいはボールド体になります。これで、文書作成者が文書作成時に心配することが1つ減ります。

上に戻る

DocBookによる文書の作成

DocBookによる文書の作成は簡単です。ここでは、SGMLのDTDを使った文書の作成について述べます。この記事の内容は、文書宣言部分を除いて、SGMLのDTDだけでなくXMLにも適用されます。

まず、お好きなテキスト・エディターを起動して、新しい文書を作成します。DocBook文書の最初の行は、文書宣言です。

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

どのDocBook文書も、有効と見なされるために文書宣言が必要です。これにより、SGML-tools Lite（または使用しているツール）は、使っているDTDのバージョンと、作成中の文書のタイプが分かります。

これから、文書に少し肉付けをします。まず、表題、作成者情報、および短い段落を入力します。この短い例では、基本的なDocBookタグ (またはエレメント) が使用されています。DocBookエレメントはHTMLタグに似ていますが、DocBookパーサーでの要求事項は、一般的なWebブラウザーよりもずっと多くなっています。HTML文書では、文書宣言がなくても済みますし、一部の「必須」タグを省略することさえできますが、DocBookではそのようなことは許されません。すべての必須エレメントを正しい順序で使用するように注意してください。

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
	<articleinfo>
	<title>A gentle guide to DocBook</title>
	<author>
		<firstname>Joe</firstname>
		<surname>Brockmeier</surname>
	</author>
	</articleinfo>
<sect1 label="1.0">
	<title>A brief introduction to DocBook</title>
<para>
If you've ever thought about writing documentation for an open source project...
</para>
</sect1>
</article>
            

ここで使われているほとんどのエレメントは、見てすぐに分かるようなものです。<firstname> や <surname> などの一部のエレメントは、親エレメント内にネストされたときにのみ有効です。例えば、<firstname> および <surname> エレメントは、親エレメント <author> 内でネストされているので有効ですが、<para> エレメント内で使用すると無効になります。

sectエレメントには、<sect1> ? <sect5> の5つのレベルがあります。HTMLでは <h1> タグから <h3> タグへ移ることができますが、DocBookでは、<sect1> から <sect3> エレメントへ移ることはできません。DocBookはHTMLよりもはるかに制約が多いです。

次のエレメントは <para> エレメントです。<para> は、paragraph (段落) を表しているので、覚えやすくなっています。大部分のDocBookエレメントは意味のある名称になっているので、DocBookで文書を1つか2つ作成した後に、共通のエレメントを確認する必要はおそらくないでしょう。

DocBookの一部のエレメントには、エレメントをさらに説明する属性を含めることもできます。上記の例の <sect1> エレメントには、label属性が含まれています。一般に、エレメントの属性はオプションです。ただし、<ulink> など一部のエレメントでは、属性が必須となっています。分からない場合は、DocBookの公式資料を参照して、使用するエレメントに適用される属性を調べてください (『参考文献』を参照)。

上に戻る

イメージの組み込み

文書にイメージを組み込むには、複数のエレメントのどれでも使用することができます。<graphic> エレメントは、<imageobject> エレメントが好まれているおかげであまり使われなくなっているので、ここでは <imageobject> エレメントの使用について述べます。

文書にイメージを組み込むには、3種類のエレメント (<mediaobject> エレメント、<imageobject> エレメント、および <imagedata> エレメント) を使用します。

<mediaobject>
	<imageobject>
	<imagedata fileref="images.d/fuzzy.eps" format="eps"> 
	</imageobject>
</mediaobject>
            

このコードは、SGML-tools Liteや他のDocBook変換ツールを使って文書を表示するときに、fuzzy.epsイメージを文書に組み込みます。epsは、文書の印刷やPDFへの変換に適した形式ですが、Webでの表示にはJPEG、GIF、またはPNGファイルを使用したいでしょう。DocBookレンダリング・ツールは、イメージ・ファイル形式を変換しないので、使用したい出力の種類に応じて、イメージ・ファイルを固有のフォーマットにしておく必要があります。

上に戻る

コードの組み込み

文書の作成時には、ソース・コードを文書内で引用すると便利です。<programlisting> エレメントは、ソース・コードをそのまま表示するときに使用します。これはHTMLの <pre> タグに似ていますが、<programlisting> エレメントには、解釈される他のDocBookエレメントを含めることができます。

<para>        <programlisting>
function F_pollList() {
  global $db,$G_URL;
  $sql  = "SELECT *,DATE_FORMAT(Birthstamp,'%c/%e/%y @ %h:%i %p') ";
  $sql  .= "AS Date FROM T_PollQuestions";
  $question = @mysql_query($sql,$db);
  $nquestion = mysql_num_rows($question);
  F_start("List of Polls");
  if ($nquestion > 0) {
 } else {
    print "There are no polls available at this time.";
  }
  F_end();
}
  </programlisting>
</para>
            

上記のコードでは < および > が使用されていますが、これはHTML文書では問題を起こす可能性があります。SGML-tools Liteは、HTMLへの変換時に、< および > を適当なエスケープ・コードに変換します。

上に戻る

リストの組み込み

読者が行いたいことの中にはおそらく、<itemizedlist> エレメントを使用したリスト (箇条書きリストまたは番号付きリスト) の作成があるでしょう。

<para>
This is how you create an non-numbered list.
</para>
<itemizedlist>
	<listitem> 
	<para>This is a list entry</para>
	</listitem>
	<listitem>
	<para>This is another list entry</para>
	</listitem>
</itemizedlist>
<para>
This is how you create a numbered list.
</para>
<orderedlist>
	<listitem> 
	<para>This is a list entry</para>
	</listitem>
	<listitem>
	<para>This is another list entry</para>
	</listitem>
</orderedlist>
            

<listitem> は、<orderedlist> または <itemizedlist> エレメントとともに使用することができます。ただし、単独では使用できません。

上に戻る

基本的なテンプレート

私がDocBookの学習を始めたときに、必要なエレメントをすべて覚えようとするよりも、基本的なテンプレートを作成するほうが簡単であることに気付きました。以下に示すのは、基本的な論文テンプレートです。これは、最初のDocBook文書を準備するのに役に立つかもしれません。このテンプレートを、ご使用のブラウザーからお気に入りのテキスト・エディターに切り貼りするだけで、作業を始めることができるはずです。ただし、ご使用のDocBookのバージョンが、テンプレートで宣言されているバージョンと同じであることを確認する必要があります。同じでない場合は、宣言されているバージョンを適当なバージョンに変更してください。

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
	<articleinfo>
	<title>Sample DocBook Template</title>
	<author>
		<firstname>firstname here</firstname>
		<surname>lastname here</surname>
	</author>
	</articleinfo>
<sect1>
	<title>Section 1 Title</title>
<para>
This is a paragraph.  
</para>
	<sect2>
		<title>Section 2 Title</title>
		<para>
This is another paragraph...
		</para>
	</sect2>
	<sect2>
	<title>Section 2 pt. 2</title>
		<para>
Yet another paragraph...
		</para>
	</sect2>
</sect1>
</article>
            

上に戻る

他のファイル形式への変換

文書作成者は、DocBookを使用しても、自分で文書を他の形式で表示する必要は実際にはまったくないことが多いでしょう。しかし、完成したDocBookファイルを持っていれば、必要な場合に、SGML-tools Liteを使ってそのファイルを他の複数の種類のファイルに変換することができます。Linuxディストリビューションを使用している場合は、SGML-tools LiteやSGML-toolsがすでにインストールされている可能性があります。これらのツールがすでにインストールされて機能しているかどうか、あるいはインストールCDに入っているかどうかを確認することができます。

DocBookファイルを構文解析しようとしてエラーが生じた場合は、文書の構文をチェックしてください。多くの場合は、「/」を入力し忘れているか、エレメントの配置が間違っているだけです。

これらのツールがまだインストールされていなくて、自分で文書を表示したい場合は、SGML-tools Liteホーム・ページからこれらのツールをダウンロードすることができます。最新バージョンを入手するには、SourceForge上のSGML-tools Liteホーム・ページ (『参考文献』を参照) にアクセスし、ソースあるいはRPMをダウンロードして、SGML-tools Liteホーム・ページ上の指示に従ってインストールしてください。

上に戻る

HTMLへのエクスポート

filename.sgmlという名前のDocBook文書をHTMLにエクスポートするには、単に以下のように入力します。

sgmltools -b html filename.sgml

文書に大きなエラーがなければ、SGML-tools Liteは「filename」ディレクトリーを作成して、エクスポートの結果 作成されたHTMLファイルを入れます。

上に戻る

プレーン・テキストへのエクスポート

DocBookは、プレーン・テキスト文書もサポートします。プレーンASCIIテキスト文書を表示するには、以下のコマンドを使用します。

sgmltools -b txt filename.sgml

これは「html」が「txt」に置き換えられたことを除いて、HTMLへの変換に使用するコマンドと同じです。-b引き数は、「txt」を「バックエンド」として使用するようにSGML-toolsに指示します。現在使用可能なバックエンドは、html、txt、rtf、ps、およびdviです。

上に戻る

PostScriptへのエクスポート

DocBookは、PostScriptによる商用印刷に適した出力を作成することができます。PostScriptに変換するコマンドの構文は、テキストやHTMLの場合と同じです。

sgmltools -b ps filename.sgml

ただし、文書にイメージを組み込む場合は、イメージをEPS形式で保管して、PostScript文書に組み込まれるようにしておく必要があるので注意してください。SGML-tools Liteは、GIFやJPEGを、最終文書に組み込めるようにPostScriptに変換することはしません。

上に戻る

この記事を読み終えたら

これはDocBookの使用に関する概要にすぎません。DocBookが備えているすべてのエレメントや可能性を包括的に扱ったものではありません。しかし、この記事によって、DocBookについてさらに学ぶ気になられることを願っています。この記事に従えば、基本的なDocBook文書を作成し、SGML-tools Liteを使ってDocBookファイルから使用可能な出力を作成できるはずです。DocBookについて詳しくは、DocBook.org (『参考文献』を参照) のオンライン・マニュアルを参照してください。

DocBookをもう少しいじくってみたいければ、Linux Documentation Projectから始めるのが良いでしょう。LDPにある文書のほとんどは、オンラインで使用可能なDocBookバージョンがあり、それを調べてDocBookの詳細な使用法を知ることができます。

参考文献

• 主なDocBookサイトDocBook.org にアクセスしてください。
  
  
• SGML-tools Lite のソースあるいはRPMをダウンロードして、指示に従ってインストールしてください。このサイトには、DocBook文書をHTML、PDF、PostScript、RTF、またはプレーン・テキストに変換するのに必要なツールがあります。
  
  
• OASIS DocBook Pages には、DocBook Technical Committeeのホーム・ページがあります。
  
  
• SGML DTDについては、W3C Overview of SGML Resources を参照してください。
  
  
• 詳しくは、OASISのSGML/XMLアプリケーション入門書General SGML/XML Applications を参照してください。
  
  

著者について

この記事を評価する

コメント

上に戻る

目次

• DocBookとは
• なぜDocBookを使うのか
• DocBookによる文書の作成
• イメージの組み込み
• コードの組み込み
• リストの組み込み
• 基本的なテンプレート
• 他のファイル形式への変換
• HTMLへのエクスポート
• プレーン・テキストへのエクスポート
• PostScriptへのエクスポート
• この記事を読み終えたら
• 参考文献
• 著者について
• コメント