DocBookの概要

移植可能文書作成プログラムの使い方

この記事では、DocBookについてと、DocBookを使用した単純な文書の作成方法について説明します。Joe Brockmeierが、文書を構文解析して、HTML、PostScript、プレーン・テキスト、およびPDFバージョンを作成するための、文書の作成おおよびSGML-tools Liteの使用方法を示します。また、DocBookに関するその他の参考資料と、SGML-tools Liteおよび他のDocBookツールを見つけるヒントも記載されています。

Joe Brockmeier (jbrockmeier@earthlink.net), freelance writer

Joe "Zonker" Brockmeierは、Linux Magazine の補助編集者で、Install, Configure and Customize Slackware Linux (Prima Publishing発行) の著者でもあります。Joeは、皆様からの質問、ご意見、およびDocBookについての今後の記事に関するアイデアを歓迎しています。メール・アドレスはjbrockmeier@earthlink.net です。



2000年 9月 01日

オープン・ソース・プロジェクトの文書作成について考えたり、あるいは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 を参照してください。

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Linux
ArticleID=228100
ArticleTitle=DocBookの概要
publish-date=09012000