LDP Author Guide Mark F. Komarinski VA Linux Systems markk@linuxdoc.org Jorge Godoy Conectiva S.A. Publishing Department godoy@conectiva.com godoy@metalab.unc.edu David C. Merrill dcmerrill@mindspring.com Revision History Revision 3.5 Dec 4, 2000 Revised by: mfk Changed mailing list pointers to new lists. Revision 3.4 Dec 1, 2000 Revised by: dcm Added Crediting Translators and Converters Revision 3.3 Nov 11, 2000 Revised by: mfk Added links to SGML GPL and FDL Revision 3.1 Oct 10, 2000 Revised by: mfk Spelling changes, changed list of LDP policies to now accept DocBook XML. More information about how to use *jade with XML will follow. Revision 3.0 Aug 24, 2000 Revised by: gjf Integrated David Merrill's style guide document. Further clean-up and additions. Revision 2.0 Jul 13, 2000 Revised by: mfk Cleaned up using-docbook a bit. Moved some chapters Revision 1.9 Jun 26, 2000 Revised by: mfk Integrated Jorge's using-docbook document. Revision 1.5 Jun 14, 2000 Revised by: mfk Documented sgedit Revision 1.4 Jun 12, 2000 Revised by: mfk Documented vim and sgedit. Spelling and other changes from ldp list. Also added LDP guidelines under style guide. LDP 文書の作成者が快適に文書を作成するためのツールや手順、およびヒント を、リストアップしました。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Table of Contents 1. この文書について 1.1. この文書の目的と射程 1.2. LDP について 1.3. フィードバック 1.4. 著作権と商標 1.4.1. 日本語訳について 1.5. 謝辞 1.6. この文書の表記法 2. LDP と SGML の紹介 2.1. LDP 2.2. SGML 2.3. なぜ HTML でなく、SGML なのか? 2.4. SGML は XML じゃない 2.5. 初めて寄稿する方へ 2.6. メーリングリスト 3. 文書作成ツール 3.1. DSSSL 3.1.1. Norman Walsh DSSSL 3.1.2. LDP DSSSL 3.2. DocBook DTD (version 4.1 か 3.1) 3.3. Jade 3.3.1. Jade 3.3.1.1. Jade を使う 3.3.1.2. XML モードの Jade 3.3.2. OpenJade 3.4. Jade wrappers 3.4.1. sgmltools-lite 3.4.2. Cygnus DocBook Tools 3.4.2.1. Cygnus Tools の使い方 3.5. 編集ツール 3.5.1. Emacs (PSGML) 3.5.1.1. PSGML を使って SGML を書く方法 3.5.2. VIM 3.5.2.1. はじめに 3.5.2.2. 新規文書のロードもしくは作成 3.5.3. WordPerfect 9 (Corel Office 2000) 3.5.4. sgedit 3.5.5. nedit 3.5.5.1. nedit の使い方 3.5.5.2. nedit の Tips とコツ 3.6. CVS 3.6.1. CVS アカウントの入手 3.6.2. それ以外の CVS リポジトリへのアクセス方法 3.6.2.1. 匿名 CVS アクセス 3.6.2.2. Web 経由での CVS ファイル 3.6.2.3. グラフィカルインターフェイスを使う 3.6.3. ファイルの更新と CVS 3.7. その他のツールとリファレンス 3.7.1. DocBook: The Definitive Guide 3.7.2. SGML テンプレート 3.7.3. Aspell 3.7.4. ispell 4. DocBook タグの使い方 4.1. はじめに 4.2. 必要な設定 4.3. カタログの作成と修正 4.3.1. 用語の説明 4.3.2. カタログ上での便利なコマンド 4.4. DocBook エレメントの使い方 4.4.1. 便利なコマンド 4.5. 索引をつくる 4.6. 画像の挿入 4.6.1. 上記以外の方法 4.7. 表組 4.8. プログラムコードとコメント 4.9. 翻訳者やコード変換者の氏名を表示する 4.9.1. タグ 4.9.2. "謝辞" (Acknowledgements) の章について 4.9.3. タグ 4.10. ツールとヒント 4.10.1. ソースのコンパイル 4.10.2. article の最初のページに要旨を挿入する 4.10.3. 索引を自動的に挿入する 4.10.4. 文書の中の下書き部分を隠す 4.10.5. 頻繁に利用する文書を外部から取り込む 4.11. 文書のサンプル 4.11.1. article の例 4.11.2. book の例 5. LDP スタイル・ガイド 5.1. 主題を決める 5.2. アウトラインを作成する 5.3. 文章を書く 5.4. テキストの推敲と校正 5.5. 作成した HOWTO の管理 5.6. リファレンス 6. スタイル関連事項の補足 6.1. 日付の書き方 6.2. 画像フォーマット 6.3. DocBook のバージョン 6.4. 利用禁止のタグ 6.5. タグの最小化 6.6. 文書内での表記法 7. DocBook のテクニックとコツ 7.1. 画像の挿入 7.2. HTML 出力ファイルのファイル名を指定する 7.3. ldp.dsl を使う 8. 文書の公開について 8.1. 文書公開のまえに 8.1.1. SGML コードの妥当性検査 8.2. 著作権とライセンスの問題 8.3. LDP への寄稿 8.4. 作成した文書の管理 9. LDP についての FAQ 用語集 Index List of Tables 4-1. 便利なコマンド 4-2. 表の例 List of Figures 3-1. sgedit のスクリーンショット 3-2. nedit のスクリーンショット 3-3. nedit へのシェルコマンドの追加 3-4. エラーがない場合の nsgml の出力 List of Examples 4-1. カタログの例 4-2. 索引生成のためのコード 4-3. 属性 zone の使い方 4-4. 属性 class で、値 startofrange と endofrange を使う方法 4-5. 画像の挿入 4-6. の使い方 4-7. 表の挿入 4-8. compiles-sgml スクリプト 4-9. article で、自動的に要旨を挿入するための stylesheet の設定 4-10. 索引を付けるために外部エンティティを設定する 4-11. パラメータ・エンティティを使う ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 1. この文書について 1.1. この文書の目的と射程 この文書の作成は、1999年8月26日、Mark F. Komarinski が文書作成ツールを 動かすのに 2 日もかかったことにイラついたのがきっかけでした。この文書が たとえ一人でも LDP 著者の役に立ったとしたら、わたしの務めは果たされます 。 この文書の最新バージョンは、LDP のホームページ http://www.linuxdoc.org にあります。オリジナルの DocBook SGML フォー マットや、その他 HTML 等のフォーマットもそこにあります。 実際にコードを書かずとも、Linux ムーブメントに貢献する方法はたくさんあ ります。重要なもののひとつが、文書を書くことです。それによって個々人が 世界中の無数の人々と知識を共有することができます。この文書は、読者に LDP の活動内容を理解してもらい、自分で HOWTO を書く際に必要なツールにつ いて知ってもらうために作成されています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.2. LDP について Linux Documentation Project は、GNU / Linux オペレーテ ィングシステムについての良質でフリーな文書を開発するた めに活動しています。LDP の最大の目的は、Linux に関する すべての事柄の文書化を、共同で押し進めることです。 HOWTO や Guide の作成はこれにあたります。さらにわれわれ は、簡単に利用と検索ができる文書システムを構築したいと 考えています。man ページや info 文書、HOWTO その他の統 合はこれにあたります。 --LDP マニフェスト: http://www.linuxdoc.org/manifesto.html この後にはだいたい次のようなことが書いてあります。「LDP ではボランティ アが大勢集まって Linux OS 用の文書を作っている。一番目立つのが HOWTO で 、HOWTO は http://www.linuxdoc.org/ にある。」この文書 (LDP Author Guide) の主な目的は、自分で HOWTO を書いて LDP に寄稿する方法を説明する ことです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.3. フィードバック この文書へのコメントは、著者 () までお願いします。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.4. 著作権と商標 Copyright 1999-2000 Mark F. Komarinski, David C. Merrill, Jorge Godoy この文書は、以下の条件を守る限り、全部あるいは一部を無料で複製できます 。 ・ 全体もしくは部分を複製する場合、上記著作権表示とこの利用条件とが、 それらの複製上に完全な型で保持されること。 ・ 翻訳もしくは二次的著作物を作成した場合、配布に先立ち、著者に連絡し て承認を得ること。 ・ この文書の一部のみを配布する場合、その配布物には、文書全体の入手が 可能であることを明記し、文書全体の入手方法を表示すること。 ・ この文書の僅かな部分を、批評や説明の材料として他の著作物に転載する 際は、その引用が正当なものである場合に限り、この利用条件の記載を省 略できる。学術目的での利用については、この利用条件の適用例外となる 場合があるので、著者まで連絡して尋ねること。これらの制限は、著者と してのわれわれの権利を守るためのものであって、教育者や学習者に制限 を課すことを意図していない。 (この文書の作成フォーマットである SGML コードを除いた) この文書内のすべてのソースコードには、GNU General Public License が適用される。左記ライセンスは、匿名 FTP 経由で、GNU アーカイブから入手可能である。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.4.1. 日本語訳について JF Project 翻訳千旦裕司 校正境真太郎 この日本語訳も、上記に従って配布してください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.5. 謝辞 この文書の作成にあたり、コメントをいただいたすべての人々、 David Lawyer, Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig, その 他の メーリングリストのメンバーに感謝 します。HOWTO Index と sgmltools の文 書からは、いくつかのセクションを抜粋させていただきました。CVS へのネッ トワークアクセスに関するセクションの一部は、Serek ()が書いています。 DocBook に関するセクショ ンは、Jorge Godoy () が書きました。二人の協力に大 変感謝しています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.6. この文書の表記法 この文書は、以下の表記法を使用しています。 [1] 説明 表記 警告 ┌──────────┐ │ Caution │ ├──────────┤ │警告文。 │ └──────────┘ ヒント Tip: ヒント。 注意 Note: 注意文。 特に注意すべき情報 ┌──────────┐ │ Warning │ ├──────────┤ │特に重要な警告文。 │ └──────────┘ ファイル名 file.extension ディレクトリ名 directory 入力コマンド command アプリケーション名 application bash でのユーザコマンドのプロンプト bash$ bash でのルートユーザコマンドのプロンプト bash# tcsh でのユーザコマンドのプロンプト tcsh$ 環境変数 VARIABLE 強調された単語 word サンプルコード パラグラフの最初と最後。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 2. LDP と SGML の紹介 2.1. LDP Linux Documentation Project (LDP) がスタートしたのは、初心者が、特定の 対象についての情報をすばやく見つけることができるようにするためでした。 LDP には、システム管理やネットワーク、プログラミングについての一連の文 書だけでなく、個別の分野を対象として、それを使ったことがある人が書いた もっと細かい事柄に関する文書も無数にあります。印刷について知りたいなら 、Printing-HOWTO , ( 日本語訳 ) があり ますし、手持ちのイーサネットカードが Linux で使えるか知りたいときは、 Ethernet HOWTO , (日 本語訳 ) を見れば だいたい分かります。はじめの頃、こうした文書は、テキストか HTML で書か れていましたが、そのうち、文書をもっと上手に管理する必要が生じてきまし た。たとえば、ウェブページ上で閲覧したり、CD-ROM 上からや、さらにはハン ド・ヘルドの PDA 上でテキストファイルとして読めるようにしたいといったこ とです。最終的に、この問題を解決したのが、SGML でした。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.2. SGML SGML (Standard General Markup Language) は、文書内にコードを埋め込むこ とで成り立っている言語です。その意味では、HTML と類似していますが、類似 点はそれだけです。SGML のパワーは、WYSIWYG (What You See Is What You Get) と違って、色やフォントサイズやある種の形式などを定義するわけではな いというところにあります。その代わり、(パラグラフやセクション、番号付き リストなどの) エレメント(element)を定義しておいて、SGML 処理系や後処理 用プログラムに版組や色、フォントなどを任せてしまいます。HTML でも同じこ とをしていますが、 HTML は実際のところ SGML のサブセットです。 SGML は、文書の生成のために、本質的に 3 つの部分から成り立っています。1 つ目は、構造 (Structure) で、これは、通常、DTD とか文書型定義 (Document Type Definition) とよばれています。 DTD では、個々のエレメント (element) (もしくはタグ(tag)) の関係が定義されています。この文書を書く のに使っている DocBook はそのひとつです。DTD は、文書の内容であるコンテ ント (content) が従うべきルールの箇条書きです。2 つ目は、DSSSL もしくは 、Document Style Semantics and Specification Language です。DSSSL は、 文書をレンダリングするプログラムに対して、SGML を人間が読める形式にする 際のやり方を指示します。たとえば、RTF フォーマットにしたい場合は、 タグを 14 ポイントのボールド体にするようレンダリングプログラム に指示し、 HTML にする場合には、それを <h1> に変換するように指示します 。最後に、文書の内容であるコンテント (Content) があり、これは SGML 処理 系によってレンダリングされる対象物であり、最終的にユーザが目にする部分 です。たとえば、このパラグラフは、もちろんコンテントですが、画像や表、 番号付きリストなんかもコンテントです。コンテントは、タグ (tag) で囲まれ て、個別のエレメントとして区別されます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.3. なぜ HTML でなく、SGML なのか? SGML は、文書のフォーマットを変換するだけではありません。索引や目次、文 書の内外へのリンクも自動的に生成できます。Jade や OpenJade パッケージ (以後は、レンダラーと呼びます) を使えば、SGML を LaTeX や info、テキス ト、 HTML、RTF にも変換できます。こうした基本フォーマットから、MS Word や PostScript, PDF などのフォーマットの文書を作ることもできますし、LyX のようなプログラムを使えば、TeX フォーマットで文書を書いて、その後で SGML に変換し、SGML から好きなフォーマットにレンダリングできます。つま り、SGML は、文書の見た目には関心がなく、もっぱらエレメントの機能に注目 しています。この点から生じる大きな違いは、パラグラフの位置やフォントサ イズ、フォントタイプなどで悩まなくてもいいので、文書を書くスピードが上 がるということです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.4. SGML は XML じゃない 最近は XML を使いたいという要望が多いので、DocBook では XML がサポート されています。DocBook は、一定の階層構造を持ったマークアップタグの集ま りです。 XML DocBook v4.1.2 は、現在 LDP で正式にサポートされています。 SGML については既に知っていて、XML を使いたい場合は、次のことに注意して ください。 (以下は、「DocBook: The Definitive Guide」から拝借しました 。) ・ すべての XML マークアップは、大文字小文字を区別する。あらゆるエレメ ント名、アトリビュート名、エンティティ名は、小文字でなければならな い。この点で、SGML とは異なる。 ・ すべてのアトリビュートは、シングルクオート (') か、ダブルクオート (") で囲まれなければならない。 ・ 空エレメント (たとえば、xref) は、/: <xref/> で終了しなければならな い。 ・ タグの短縮 (</>) はサポートしない。これは LDP においても、 SGML 内 で使用することは推奨されていない。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.5. 初めて寄稿する方へ もし、LDP は初めてで、更新されていない HOWTO の管理をしたり、新規に HOWTO を書いたりしようと思った場合は、<discuss@linuxdoc.org> の HOWTO コーディネータに連絡してください。これは、誰がどの文書を担当しているの か HOWTO コーディネータに分かるようにするためです。 これが終わると、好きなフォーマットで文書を書いて、そのドラフトを <submit@linuxdoc.org> に送っていただきます。 LDP のボランティアがそれを 校正して、数日中にボランティアから草稿とコメントが返ってきますので、そ れらのコメントを文書に反映させて、今度は LDP への最終稿として再度 ldp-submit メーリングリストに新バージョンを投稿します。 この時点で、別のボランティアが投稿された文書を DocBook 形式に変換して、 完成された DocBook 文書として手元に送られてきます。ここから先、LDP への 投稿はすべて DocBook 形式になります。マークアップについて疑問があれば、 変換を担当したボランティアに聞くか、LDP DocBook メーリングリストで質問 してください。 はじめから DocBook 形式で書き始める場合は、参考になるテンプレートがたく さんあります。 ・ http://www.linuxdoc.org/authors/template-ld/ big-howto-template-ld.sgml <http://www.linuxdoc.org/authors/ template-ld/big-howto-template-ld.sgml> - Stein Gojen が書いたこの テンプレートは、LinuxDoc 形式で書くときのものです。 ・ http://www.linuxdoc.org/authors/template/big-howto-template.sgml <http://www.linuxdoc.org/authors/template/big-howto-template.sgml> - このテンプレートも Stein が作ったものですが、上記よりもずっと大き くて複雑になっています。これは、DocBook の豊富な機能を活用したもの です。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.6. メーリングリスト メーリングリストがいくつかあるので、登録すれば LDP の活動に参加できます 。まず、<discuss@linuxdoc.org> は、LDP の中心的なメーリングリストで、登 録するには、subject 欄に "subscribe" と書いたメールを <discuss-subscribe@linuxdoc.org> にお送りください。登録を取り消す場合は 、subject 欄に "unsubscribe" と書いたメールを <discuss-unsubscribe@linuxdoc.org> まで送ってください。 他にも、<docbook@linuxdoc.org> メーリングリストは、マークアップや、 DocBook 自体に関する質問をするところです。特定のマークアップタグで困っ たときは、ここに質問を送って返事を待ってください。 DocBook メーリングリ ストに登録するには、"subscribe" と書いたメールを <docbook-subscribe@linuxdoc.org> にお送りください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 3. 文書作成ツール このセクションでは、LDP 文書を作成するのに必要なツールや便利なツールを いくつか紹介します。ここでは、インストール方法とツールの概要を説明して 、詳しい使い方は後で解説することにします。もしあなたがここにあるもの以 外のツールを使って LDP 文書をお書きの場合、このセクションで宣伝しますの で、是非そのツールをお知らせください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.1. DSSSL 通常の Walsh バージョンの DSSSL が必要で、そのオプションとして LDP の DSSSL があります。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.1.1. Norman Walsh DSSSL http://nwalsh.com/docbook/dsssl/ <http://nwalsh.com/docbook/dsssl/> DSSSL (Document Style Semantics and Specification Language) は、どうい う方法で SGML 文書を印刷やオンライン用の文書にするかを jade に指示する ものです。たとえば、DSSSL に従って、title タグが、HTML では <H1> タグに 変換され、RTF では 14 ポイントの Times Roman ボールド体に変換されます。 DSSSL に関する文書も上記にあります。DSSSL を修正することは、 DocBook 自 体を修正することにはならない点に注意してください。レンダリングされたテ キストの見栄えを変えているにすぎません。LDP では、次の修正された DSSSL を使っています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.1.2. LDP DSSSL http://www.linuxdoc.org/authors/tools/ldp.dsl <http://www.linuxdoc.org/ authors/tools/ldp.dsl> LDP DSSSL は、(上記の) Norman Walsh バージョンの DSSSL があることを前提 にして、目次などを生成するために若干の変更を加えたものです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.2. DocBook DTD (version 4.1 か 3.1) 必要なのは、 http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip <http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip> か、 http:// www.oasis-open.org/docbook/sgml/3.1/docbk31.zip <http:// www.oasis-open.org/docbook/sgml/3.1/docbk31.zip>。 XML DTD を使う場合は、 http://www.oasis-open.org/xml/4.1.2/ <http:// www.oasis-open.org/docbook/xml/4.1.2> です。 DocBook DTD は、DocBook SGML 文書のタグと文書構造とを定義しています。そ れゆえ、新規タグを加えたりして DTD を修正すると、DocBook ではなくなって しまいます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.3. Jade Jade と OpenJade は、ふたつとも、DTD と DSSSL に基づいてコードのレンダ リングや妥当性検査の大半を処理するプログラムです。どちらかが必要なので 、 DTD と DSSSL のインストールが終わってから、インストールしてください 。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.3.1. Jade ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz <ftp://ftp.jclark.com/ pub/jade/jade-1.2.1.tar.gz> Jade は、SGML のフロント・エンドプロセッサです。DocBook と DSSSL を使っ て、妥当性検査や、目的のフォーマットへの SGML ソースのレンダリングを行 います。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.3.1.1. Jade を使う ここでは、使っているディストリビューションを問わず、どのディストリビュ ーションでも、とにかくすぐに使えるようにする方法を紹介します。 1. いろんなファイルを入れるために、/usr/local/sgml/ といったベース・デ ィレクトリを作成します。以下では、そのディレクトリを $_toolroot と 呼びます。 2. Jade, DocBook DTD, DSSSL を、$_toolroot がそれぞれのベースディレク トリになるよう、次のようなディレクトリを作成して、インストールしま す。 □ $_toolroot/jade-1.2.1 □ $_toolroot/dtd □ $_toolroot/dsssl 3. 環境変数 SGML_CATALOG_FILES に $_toolroot にあるカタログファイル名 を設定する必要があります。それには次のコマンドを使ってください。 ┌───────────────────────────────────┐ │bash$ export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\ │ │$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog │ │ │ └───────────────────────────────────┘ 4. これで Jade を使う準備ができました。セクション別の HTML ファイルを 作成するには、次のコマンドを使います。 ┌────────────────────────────┐ │$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \ │ │-d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml │ │ │ └────────────────────────────┘ 5. 一枚の HTML ファイルにまとめるには、上記の Jade コマンドに -V nochunks を付けてください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.3.1.2. XML モードの Jade いったん XML 用の設定が済めば、Jade も OpenJade も SGML DocBook と同じ やり方で使えます。 XML DTD を解凍したら、jade/openjade のカタログファイルのデフォルトファ イル名として、docbook.cat ファイルから "catalog" にシンボリックリンクを 張ることもできます。次の $_xml_root の部分は、インストールした XML_DTD の場所に置き換えてください。 ┌───────────────────────────────────────┐ │bash$ cd $_xml_root │ │bash$ ln -s docbook.cat catalog │ │bash$ export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\ │ │$_toolroot/dtd/docbook/catalog (1) │ │bash$ jade -t sgml -i html -d style $_jade_path/pubtext/xml.dcl foo.xml (2) │ │ │ └───────────────────────────────────────┘ (1) XML, DSSSL, DocBook それぞれのカタログファイルが必要です。 $_toolroot は、先ほどの例と同じです。 (2) スタイルファイルは、好みのスタイルファイルに置き換えてください。 jade が動くには、xml.dcl へのポインタが必要で、これは、XML 文書名の 直前に指定される必要があります。 XML 文書を処理中に次のような警告が表示されるかもしれません。これは 出力には影響しませんが、原因は調査中です。 ┌────────────────────────────────┐ │/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name │ │/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name │ │ │ └────────────────────────────────┘ 既存の SGML DocBook 文書を XML 文書に変換したい場合は、(文書の冒頭の行 の)文書型宣言(declaration)のところで次のように書いてください。 ┌──────────────────────────────────┐ │ │ │ │ └──────────────────────────────────┘ LDP の文書規則に従っている場合、これ以外に文書に変更を加える必要はあり ません。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.3.2. OpenJade http://openjade.sourceforge.net/ <http://openjade.sourceforge.net/> DSSSL コミュニティーが作成した、Jade のエクステンションです。アプリケー ションのなかには jade を必要とするものもありますが、どちらもサポートで きるようにアップデートされつつあります。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.4. Jade wrappers オプションで以下のツールがあるので、Jade, DSSSL, DTD のインストール後に 、インストールできます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.4.1. sgmltools-lite http://sgmltools-lite.sourceforge.net/ <http:// sgmltools-lite.sourceforge.net/> これは、一年以上前に正式に解散した sgmltools プロジェクトを引き継いだも ので、それ以来、Cees de Groot が若干異なるプロジェクトを立ち上げて、 jade SGML 処理系へのラッパとしてツールを作っています。構文の汚さはかな り解消されました。作者は、古い sgmltools パッケージをインストールして、 そのあとに sgml-tools-lite を入れることで、この文書を非常に簡単にフォー マットできたそうです。構文を表示する sgmltools 用の man ページもありま す。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.4.2. Cygnus DocBook Tools Red Hat 専用ですが - http://www.redhat.com/ Red Hat では、6.2 リリースから、DocBook をサポートするツールその他を含 めた 3 つのパッケージを配布しています。これらのツールは、簡単にインスト ールできるので、ツールと格闘しなくても執筆に専念できます。TeTeX, Jade, JadeTeX をあらかじめインストールしておくことが必要です。パッケージは 3 つとも、インストール CD に入っています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.4.2.1. Cygnus Tools の使い方 これらのツールは、Red Hat 6.2 に付属しています。まず、次のパッケージが インストールされているか確認してください。 ・ sgml-common-0.1-8.noarch ・ docbook-3.1-4.noarch ・ stylesheets-1.54.13rh-1.noarch 最新バージョンは、Red Hat のウェブサイトにあります: http:// www.redhat.com/support/errata/RHBA-2000022-01.html <http:// www.redhat.com/support/errata/RHBA-2000022-01.html>. RPM ファイルをマシンにダウンロードするか、どこかから取ってくるかして、 いつも通りインストールしてください。(root になって、rpm -Uhv ファイル名 。) RPM がインストールされたら、次のコマンドを使って DocBook をレンダリ ングできます。 ┌──────────────────────────────────┐ │bash$ db2html filename │ └──────────────────────────────────┘ DocBook を HTML にレンダリングします。( .sgml 拡張子を除いた)ファイル名 と同じ名前でサブディレクトリが作成され、そこに HTML ファイルが置かれま す。 ┌──────────────────────────────────┐ │bash$ db2pdf filename │ └──────────────────────────────────┘ DocBook を PDF ファイルにレンダリングします。JadeTeX を使った db2pdf と pd2ps で、現在問題が生じているのに注意してください。これは、Red Hat に バグとして登録 <http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id= 9670>されています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5. 編集ツール 以下では、HOWTO の作成や編集、妥当性検査に使えるツールを紹介します。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.1. Emacs (PSGML) オプションです。 - http://www.lysator.liu.se/~lenst/about_psgml/ <http: //www.lysator.liu.se/~lenst/about_psgml/> Emacs には、SGML や XML 文書の編集のために作られたメジャーモードとして 、 SGML 文書作成用の psgml と呼ばれるモードがあります。これによる "構文 強調 (syntax highlighting)" や "きれいな表示 (pretty printing)" 機能を 使うと、SGML タグが強調されたり、手でタイプしなくてもタグを入れることが できたり、書きながら妥当性検査ができたりします。 Emacs ユーザにはうれしい機能ですし、他のどんな SGML 編集ツールよりも充 実した機能を備えていると、多くのユーザは思っています。DocBook や LinuxDoc、その他の DTD でも使えます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.1.1. PSGML を使って SGML を書く方法 3.5.1.1.1. はじめに 最近のディストリビューションをインストールしているなら、Emacs で使える ように既に PSGML がインストールされていると思います。確認のために、 Emacs を起動して、PSGML 文書を捜してみましょう。(C-himpsgml) ここからは、比較的新しいバージョンの Emacs に PSGML がインストールされ て使えるようになっているのを前提にします。話が早く進みすぎると思う方は 、Bob Ducharme の SGML CD book のフリーで公開されている次の章をご覧くだ さい。 http://www.snee.com/bob/sgmlfree/ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.1.1.2. .emacs をアップデートして PSGML を使う方法 .sgml ファイルを開いたときに GNU Emacs が PSGML モードに入って、SGML を 編集できる準備が整うようにしたい場合は、PSGML が DocBook DTD を見つけら れるようにしなければなりません。 GNU Emacs で PSGML が使えるようにディ ストリビューションで既に設定済みなら、何もしなくても多分うまく行くはず ですが、そうでない場合は、環境変数を設定して、SGML カタログ (つまり DTD のリスト) を捜すべき場所を PSGML に教える必要があります。 たとえば、まず ┌──────────────────────────────────┐ │bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog │ └──────────────────────────────────┘ と打って、次に、.emacs ファイルに次ぎのような内容の行を追加します。 ;; ******************************************************************* ;; set up psgml mode... ;; use psgml-mode instead of emacs native sgml-mode ;; (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) (setq auto-mode-alist (append (list '("\\.sgm$" . sgml-mode) '("\\.sgml$" . sgml-mode) ) auto-mode-alist)) ;; set some psgml variables (setq sgml-auto-activate-dtd t) (setq sgml-omittag-transparent t) (setq sgml-balanced-tag-edit t) (setq sgml-auto-insert-required-elements t) (setq sgml-live-element-indicator t) (setq sgml-indent-step nil) ;; create faces to assign to markup categories (make-face 'sgml-comment-face) (make-face 'sgml-start-tag-face) (make-face 'sgml-end-tag-face) (make-face 'sgml-entity-face) (make-face 'sgml-doctype-face) ; DOCTYPE data (make-face 'sgml-ignored-face) ; data ignored by PSGML (make-face 'sgml-ms-start-face) ; marked sections start (make-face 'sgml-ms-end-face) ; end of marked section (make-face 'sgml-pi-face) ; processing instructions (make-face 'sgml-sgml-face) ; the SGML declaration (make-face 'sgml-shortref-face) ; short references ;; view a list of available colors with the emacs-lisp command: ;; ;; list-colors-display ;; ;; please assign your own groovy colors, because these are pretty bad (set-face-foreground 'sgml-comment-face "coral") ;(set-face-background 'sgml-comment-face "cornflowerblue") (set-face-foreground 'sgml-start-tag-face "slateblue") ;(set-face-background 'sgml-start-tag-face "cornflowerblue") (set-face-foreground 'sgml-end-tag-face "slateblue") ;(set-face-background 'sgml-end-tag-face "cornflowerblue") (set-face-foreground 'sgml-entity-face "lavender") ;(set-face-background 'sgml-entity-face "cornflowerblue") (set-face-foreground 'sgml-doctype-face "lavender") ;(set-face-background 'sgml-doctype-face "cornflowerblue") (set-face-foreground 'sgml-ignored-face "cornflowerblue") ;(set-face-background 'sgml-ignored-face "cornflowerblue") (set-face-foreground 'sgml-ms-start-face "coral") ;(set-face-background 'sgml-ms-start-face "cornflowerblue") (set-face-foreground 'sgml-ms-end-face "coral") ;(set-face-background 'sgml-ms-end-face "cornflowerblue") (set-face-foreground 'sgml-pi-face "coral") ;(set-face-background 'sgml-pi-face "cornflowerblue") (set-face-foreground 'sgml-sgml-face "coral") ;(set-face-background 'sgml-sgml-face "cornflowerblue") (set-face-foreground 'sgml-shortref-face "coral") ;(set-face-background 'sgml-shortref-face "cornflowerblue") ;; assign faces to markup categories (setq sgml-markup-faces ' ( (comment . sgml-comment-face) (start-tag . sgml-start-tag-face) (end-tag . sgml-end-tag-face) (entity . sgml-entity-face) (doctype . sgml-doctype-face) (ignored . sgml-ignored-face) (ms-start . sgml-ms-start-face) (ms-end . sgml-ms-end-face) (pi . sgml-pi-face) (sgml . sgml-sgml-face) (shortref . sgml-shortref-face) )) ;; tell PSGML to pay attention to face settings (setq sgml-set-face t) ;; ...done setting up psgml-mode. ;; ******************************************************************* あとは、Emacs を再起動してください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.1.1.3. SGML のちょっとしたテスト ちょっとしたテストをしてみましょう。例として、新規ファイル /tmp/ test.sgml を開いて、次のように書き込みます。 ]> そして、C-cC-p と入力します。 Emacs が DTD を読み込もうとしているなら、 ミニバッファに Parsing prolog....done と表示されます。そしたら、C-c C-e RETURN と打って、<test> と入力してみましょう。正しく動いている場合は、 Emacs に次のように表示されます。 ]> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.1.1.4. DocBook 形式で新規に HOWTO を書く方法 HOWTO 用に新規ファイルを開いて、次のように入力します。 C-cC-p と打って、画面に注目。すべて予定通りなら、数秒間 Emacs が読み込 み処理をして、ミニバッファに Parsing prolog....done と表示されるのが分 かります。 ここで、C-cC-eRETURN と打ち、<article> エレメントを書き込んで、HOWTO の 執筆に取りかかりましょう。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.1.1.5. PSGML を使った Emacs のクイックリファレンス FreeBSD 文書にある Nik Clayton の入門書をご覧ください。 http:// www.freebsd.org/tutorials/docproj-primer/psgml-mode.html <http:// www.freebsd.org/tutorials/docproj-primer/psgml-mode.html> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.2. VIM http://www.vim.org Emacs についての話をしましたので、当然、次は vi のお話です。VIM (Vi IMproved) エディタは、vi の標準機能を持ちながら、タグの位置をスクリーン 上で色分けして教えてくれます SGML モードも持っています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.2.1. はじめに vim プログラムは実際に複数の部分から出来ています。まず、素の vim プログ ラムがあって、これは、vi プログラムやそのコマンドと互換性を持っています 。Red Hat ユーザなら、vim-common と vim-minimal パッケージが必要です。 次に、拡張機能を持った vim で、これは標準の vi に対して、構文強調などの 機能があります。Red Hat ユーザなら、vim-enhanced が必要です。最後の見逃 せない機能として、 X インターフェイスがあり、これは、グラフィカルインタ ーフェイスやメニュー、マウス操作などを提供しています。vim や vi からこ れを区別する場合、グラフィカル操作でのコマンドは、gvim と呼ばれています 。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.2.2. 新規文書のロードもしくは作成 vim と gvim モードでは、 .sgml ファイルは自動的に認識されて、"sgml モー ド" に入ります。あらかじめ分かっている一連の DocBook タグが vim に読み 込まれると、認識されたタグは茶色で強調されます。認識されない場合、ライ トブルーで表示されます。認識されたタグの属性(attribute)もライトブルーに なり、属性の値(value)は、ピンクになります。ここからは、通常の vi コマン ドを使って、カーソル移動と編集ができます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.3. WordPerfect 9 (Corel Office 2000) http://www.corel.com/ MS Windows プラットフォームの WordPerfect 9 は、SGML と DocBook 3.0 を サポートしています。Linux 用 WordPerfect 9 に SGML 機能はありません。 これは、SGML をサポートしている商用アプリケーションとしては一番安価なも のです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.4. sgedit http://www.tksgml.de/ sgedit は、SGML ファイルをビジュアルに編集できるプログラムです。このプ ログラムの長所は、あらかじめ Emacs や VI の使い方を知らなくてもよい点と 、クロスプラットフォームなので、Windows でも Linux でも動くという点です 。商用アプリケーションですが、値段は設定されていません。個人や教育機関 での利用については、フリーライセンス版が出るようです。 ビジュアル編集の他にも、sgedit は、ロード時や必要な時に、 Document-> Validate コマンドを使って、文書の妥当性検査ができます。 Figure 3-1. sgedit のスクリーンショット sgedit プログラムのスクリーンショット。左側には、階層を持った SGML 文書 のツリー構造が表示され、右側には、文書自体が表示されている。タグは、グ レーの背景で表示される。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.5. nedit http://nedit.org 率直に言って、nedit は、プログラマ向けで、新規ユーザや特にプログラマで ないユーザにとってはちょっときついかもしれません。それを除けば、タグの 色づけが自由にできたりして、かなりパワフルです。sgedit と異なり、nedit では、タグを自動で入れたり、文書の妥当性検査を自動的に行ったりはしませ ん。そのかわり、ウィンドウの内容に対してシェルコマンドが使えるようにな っています。(ファイルを保存した後で、チェックします。) わたしは、SGML の妥当性検査のために nsgmls を設定し、スペルチェックのために aspell を 設定しましたが、だいたい数分で終わりました。 Figure 3-2. nedit のスクリーンショット nedit では、画面の左端に行番号が表示されるので、nsgmls でエラーが出た場 合に便利です。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.5.1. nedit の使い方 新規文書を作るときは、LDP DocBook テンプレートをダウンロードして使うこ とが推奨されています。そのファイルがあれば、nedit を起動してすぐ編集に 取りかかれます。ファイルに .sgml 拡張子を付けて保存しておけば、nedit は 、 SGML/HTML タグ機能を有効にしてファイルをロードします。この機能は、 Preferences->Language Mode->SGML HTML コマンドを使って明示的に有効にす ることもできます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5.5.2. nedit の Tips とコツ nedit では、ウィンドウの内容を外部プログラムに出力することができるので 、この機能を使って、普段使っている関数を実行できます。ここで取り上げる 例題では、 nsgmls を使い、SGML の妥当性検査を行う方法を紹介します。 まず、 Preferences->Default Settings->Customize Menus->Shell Menu... を 選択します。すると、Shell メニューに登録されている全シェルコマンドを表 示するダイアログボックスが出てくるので、その Menu Entry の欄に "SGML validate" と書き込みます。このエントリーは、スクリーン上で見ることがで きます。次に、Accelerator の欄で、 Alt-S を押して、 SGML の妥当性検査が 自動で行われるようにします。Command Input の部分では、 window を選択し て、Command Output の部分では、dialog を選択します。 Command to Execute では、nsgmls -sv と入力しましょう。これがうまく動くためには、 PATH に nsgmls へのパスが設定されていないといけないので注意してください。 Figure 3-3. nedit へのシェルコマンドの追加 シェルコマンドを追加する時のダイアログボックス。 OK をクリックして、これで元のメインスクリーンに戻ります。SGML ファイル をロードして、Shell+SGML Validate を選択するか、Alt-S を押すと、nsgmls が起動されて、ウィンドウの内容をチェックします。-sv を使う理由は、-v を 指定すると、nsgmls はプログラムのバージョンを出力するので、その出力を見 れば nsgmls が実行されたことが必ず分かるようになるからです。バージョン 番号しか出力されない場合は、文書にエラーがなかったことになります。エラ ーがあれば、そのエラーが分かるように、別のウィンドウが開いて表示されま す。行番号機能を有効にしてあるなら (これには、 Preferences->Show Line Numbers を使います。)、nsgmls はエラーを行番号で表示するので、エラーを 見つけるのがずっと楽になります。 Figure 3-4. エラーがない場合の nsgml の出力 nsgmls がエラーを検出しなかった場合は、バージョン番号だけを報告します。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.6. CVS LDP では、文書の著者に CVS アカウントを発行しようとしています。それには 、次のような理由があります。 1. CVS なら、作成した文書のオフサイト・バックアップが持てる。他の著者 へ文書の引き継ぎをするときでも、CVS からその文書を取ってきて、直ぐ に作業に入れる。以前のバージョンの文書が必要になったときでも、問題 なく取り出すことができる。 2. 何人かで、ひとつの文書を作る際に非常に便利。CVS を使えば、自分が編 集中の時に、他人が加えた変更の内容を知ることができるし、そうした変 更をそのまま取り込むこともできる。 3. 変更箇所のログを保存できる。SGML 処理系が実際の処理に取りかかるより 先に、前もって処理されるような特別なタグを使えば、そうしたログ(や日 付スタンプ)を自動的に文書に埋め込むことができる。 4. 新規文書を作成して提出すると、LDP ウェブサイトも自動的に更新される ようなプログラムを作ることができる。これはまだ実現されてはいないけ れど是非やってみたいことです。今のところ、CVS の更新によって、HOWTO コーディネータに LDP ウェブページを更新するよう通知が行くようになっ ていますが、この仕組みを使うと SGML コードをメールで送る必要がなく なります。 CVS が全く初めてなら、いくつかウェブページがあるので、見ておくと役に立 つかもしれません。 ・ http://www.sourcegear.com/CVS/Docs/blandy <http:// www.sourcegear.com/CVS/Docs/blandy> ・ https://wroclaw.art.pl/~ser/docs/cvs.html <https://wroclaw.art.pl/ ~ser/docs/cvs.html> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.6.1. CVS アカウントの入手 まず、LDP にある CVS リポジトリのアカウントを入手する必要があります。こ れは、CVS が使うルートディレクトリそのもので、そのサブディレクトリとし て (HOWTO や mini HOWTO などの)いくつかのプロジェクト用のディレクトリが 作成されています。 アカウントを取るには、ハッシュ化されたパスワードとユーザ ID を作成しな ければなりません。ハッシュ化されたパスワードを使うと、CVS グループが送 信者のパスワードを知らずとも、暗号化されたパスワードを CVS グループに送 ることができます。それには、次のようなコマンドを bash (もしくは sh) か ら打ってください。 ┌────────────────────────────────────┐ │bash$ echo your_password | perl -e "print crypt(<>,\ │ │join '',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\"" │ └────────────────────────────────────┘ 上記コマンドの出力を、希望するユーザ ID と一緒に <cvsadmin@cvslist.linuxdoc.org> までお送りください。各自の CVSROOT ディ レクトリが作成されたあとで、その旨の返答メールが届くので、それが届いた 時点で、CVSROOT にログインして、すべてが適切に設定されてることを確認し てください。 ┌──────────────────────────────────┐ │bash$ export CVSROOT=:pserver:your_userid@cvs.linuxdoc.org:/cvsroot │ │bash$ cvs -d $CVSROOT login │ └──────────────────────────────────┘ (your_userid の部分は、受け取った返答メールにあるユーザ ID に置き換えま す。) パスワードを尋ねられて、そのあとで、CVS リポジトリに読み書きモードでの アクセス権が与えられます。cvs login コマンドは一度使うだけでシステムへ のアクセス権が得られ、.cvspass にパスワードが保存されるので、次からは cvs login を打つ必要はありません。 CVSROOT を設定して、作業を続けましょ う。次のコマンドで、LinuxDoc リポジトリ全体をコピーすることができます。 ┌──────────────────────────────────┐ │bash$ cvs get LDP │ └──────────────────────────────────┘ ほかにも、自分で作成した文書の SGML ソースが欲しいときは、次のコマンド を打ってください。 ┌──────────────────────────────────┐ │bash$ cvs get LDP/howto/docbook/YOUR-HOWTO.sgml │ │bash$ cvs get guide/docbook/YOURGUIDE │ └──────────────────────────────────┘ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.6.2. それ以外の CVS リポジトリへのアクセス方法 3.6.2.1. 匿名 CVS アクセス (LDP 文書の出版を希望する方など、)アカウントの不要な方でも、匿名 CVS ア クセスが利用できます。その場合、リポジトリは読み出し専用になります。 ┌──────────────────────────────────┐ │bash$ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login │ └──────────────────────────────────┘ パスワードには、"cvs" を使います。そうすれば、上記と同じように LinuxDoc モジュールが入手できます。匿名 CVS サイトの更新は、メインサイトより 30 分ほど遅れるので注意してください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.6.2.2. Web 経由での CVS ファイル CVS リポジトリには、Web 経由でもアクセスできます。 http:// cvsweb.linuxdoc.org/index.cgi/LDP <http://cvsweb.linuxdoc.org/index.cgi /LDP> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.6.2.3. グラフィカルインターフェイスを使う CVS にはグラフィカルインターフェイスがあります。 http://freshmeat.net/ appindex で CVS をキーワードに検索すれば、一覧が表示されます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.6.3. ファイルの更新と CVS CVS には、$Id$ という特別なタグがあり、これを使って文書に直接日付とバー ジョンを自動的に入れることができます。 commit した後で、CVS がこのタグ を $Id: cvs.sgml,v 1.3 2000/08/24 20:31:01 markk Exp $ のように変更しま す。このタグを文書内に書いておくと、ファイルを変更するたびに自動的にそ のタグが書き換えられ、変更するごとにリビジョン番号を上げることができま す。 更新した文書を CVS サーバにアップロードする準備が整ったら、 cvs ci -m "comment" 文書名.sgml とコマンドを打ってください。-m "comment" は必要で はありませんが、これを入れないと、(普通は vi か、環境変数 EDITOR に設定 された何らかの)エディタが立ち上がって、変更点についてのコメントを追加す るよう求められます。 ldp-discuss メーリングリスト上での議論からも詳しい情報が得られます。 文書の作成中に LDP CVS ツリーを使っている場合は、公開準備が整った時点で LDP に知らせる必要があります。<ldb-submit@lists.linuxdoc.org> にメール を送ってください。その際、文書のタイトルと、文書ファイルの LDP CVS ツリ ー内での相対パス名を本文に書いておいてください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.7. その他のツールとリファレンス このセクションでは、今のところ分類しきれていないリファレンス本やユーテ ィリティを紹介します。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.7.1. DocBook: The Definitive Guide http://www.docbook.org/ これは、1999年10月に O'Reilly から出版された、DocBook についてのすばら しいリファレンス本です。それほど実用的ではないように思われるし、 XML に 重点が置かれてはいますが、バージョン 3.1 の DocBook タグはすべて分かり やすく一覧表示されています。書店で買うこともできるし、本のすべての内容 を上記 URL からオンラインで (HTML と SGML フォーマットにおいて) 読むこ ともできます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.7.2. SGML テンプレート オプションです。- http://www.linuxdoc.org/authors/index.html#resources <http://www.linuxdoc.org/authors/index.html#resources> (日本語訳 <../.. /authors/index.html#resources>) SGML テンプレートと、変換した後の HTML 出力についてのリンクがあるので、 文書の体裁を理解する手助けになります。タグの多くは、作成する文書の内容 に合わせて置き換えることが必要です。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.7.3. Aspell オプションです。 - http://aspell.sourceforge.net/ <http:// aspell.sourceforge.net/> スペルチェック用のこのアプリケーションは、SGML タグを避けて、タグに挟ま れた内容だけをチェックすることができます。ispell のようなデフォルトのス ペルチェッカーだと、タグ自体もチェックしようとするので、新規タグがある と、いつもエラーになってしまいます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.7.4. ispell オプションです。 - http://www.cs.hmc.edu/~geoff/ispell.html <http:// www.cs.hmc.edu/~geoff/ispell.html> この ispell プログラムは、Red Hat (や、おそらく他のディストリビューショ ン )に同梱されているもので、マークアップタグを無視することができます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 4. DocBook タグの使い方 4.1. はじめに DocBook では、テキストをマークアップ(markup)する一連の便利なマークアッ プエレメント(element)を定義して、テキストをいろいろな異なるフォーマット に変換できるようにしています。 DocBook を使うと、HTML や XML, RTF, TeX その他の異なるフォーマットの文 書を生成できます。 これは、つまり、DocBook で文書を作成しておけば、可能な限り最大多数のひ とたちに情報を伝えることができるということです。 適切に保管されていないデジタル情報は、いざという時に見つからなかったり するものです。(バイナリフォーマットのような)通常とは異なる文字は含まれ ていないので、SGML ないし DocBook で書かれた文書なら、直接索引付けや検 索をすることができます。 SGML システムでは、マークアップ(markup)を使って、文書を記述しています。 DocBook には 300 以上のマークアップ・エレメント(element)があり、個々の エレメントにいくつかの属性があり、属性がいくつかの値を取ります。これら をどう活用するかは、作者が使う文書のスタイルによって決まります。 DocBook の定義ファイルである DTD に少しでも変更を加えると、それはもう DocBook ではなくなることを忘れないでください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.2. 必要な設定 SGML やある種のツールなどのように識別子(identifier)を使うシステムでは、 カタログ(catalogue)がベースになっていて、そのカタログが、そうした識別子 を読み取って、必要な定義が書かれたファイルを見つけだします。 カタログファイルの内容については、カタログの設定について書かれたセクシ ョン (Section 4.3 参照)で、もう少し詳しく説明します。 そうしたツールが必要なカタログを見つけられるように、環境変数 SGML_CATALOG_FILES の値を、次のように設定しなければなりません。 ┌──────────────────────────────────┐ │$ export SGML_CATALOG_FILES="/usr/lib/sgml/catalog" │ └──────────────────────────────────┘ DocBook やその他のツール類をコンピュータ上で正しく動かすのに必要な追加 設定は、これだけです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.3. カタログの作成と修正 カタログ(catalogue)は、公開識別子(public identifier)を解釈してシステム ファイルを見つけだす際のルールが記述されたテキストファイルです。 カタログファイルは、DocBook は使いやすくするためのものです。個々のユー ザは、カタログファイルを(たとえば、ホームディレクトリ、/usr/local/sgml 、その他の)どこにインストールしてもいいですし、インストールさえすれば、 それ以上処理したりコンパイルしたりする必要もありません。 Example 4-1. カタログの例 -- Catalogue for the Conectiva Styles -- (1) OVERRIDE YES PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN" (2) "/home/ldp/styles/books.dtd" DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd" DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd -- EOF -- (3) (1) コメント。コメントは、"--" で始まり、改行で終わります。 (2) 公開型宣言(public type declaration) "-//Connectiva SA//DTD books V1.0//EN" と /home/ldp/styles にある books.dtd ファイル。 (3) ファイルの終了を示すコメント。 上記の例では、識別子をファイルに対応させるために、次のような順序に従っ ています。 1. 識別子 PUBLIC をコピーする。 2. 識別するテキストを書き込む。 3. 対応するファイルへのパスを示す。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.3.1. 用語の説明 次の識別子に注目してください。 "-//Conectiva SA//DTD books V1.0//EN" この並び方は、ランダムではなく、あらかじめ決められた規則に従っています 。 " - " という語句は、使用される識別子が、登録済みのタイプではないことを 示しています。登録済み識別子はわずかしかなく、それらは通常、 ISO や IEEE といったエンティティ (entity)に属しています。 識別子の次の部分では、それを作成した組織名が定義されます。上記の例では 、Conectiva S.A. です。 最後からひとつ手前に部分では、コンテント(content) (本書の場合は、DTD [2] です。) と、識別されているテキスト名が定義されます。 最後のエレメントは、文書を記述した言語を示しています。DocBook は、英語 で書かれた DTD なので、言語は EN となります。 2 文字のコードが推奨され ているのは、ISO の言語識別基準に従っているからです。 詳しくは、OASIS Technical Resolution 9401:1997 (Amendment 2 to TR 9401) <http://www.oasis-open.org/html/a401.htm> をご覧ください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.3.2. カタログ上での便利なコマンド カタログ上で使われるコマンドのうち、代表的なものを以下で説明します。 PUBLIC キーワード PUBLIC は、公開識別子(public identifier) をシステム上の 識別子にマップします。 SYSTEM キーワード SYSTEM は、システム識別子(system identifier)をシステム上 のファイルにマップします。 SYSTEM "http://nexus.conectiva/utilidades/publicacoes/livros.dtd" "publicacoes/livros.dtd" SGMLDECL キーワード SGMLDECL は、使用されるべき SGML 文言 (SGML statement)の システム識別子を指示します。 SGMLDECL "publishings/books.dcl" DTDDECL SGMLDECL と同様、キーワード DTDDECL は、使用されるべき SGML 文言を 指示します。DTDDECL によって、SGML 文言は、DTD に対する公開識別子に 対応付けられます。残念ながら、この対応付けは、無料で入手できる既存 のツールではサポートされていません。この文言は、複数のカタログファ イルを使うときに効果があります。 DTDDECL "-//Conectiva SA//DTD livros V1.0//EN" "publicacoes/ livros.dcl" CATALOG キーワード CATALOG を使うと、あるカタログファイルを別のカタログファ イル内に含めることができます。それによって、カタログファイルそのも のを変更せずに、異なる複数のカタログを利用できるようになります。 OVERRIDE キーワード OVERRIDE は、公開識別子がシステム識別子に優先するかどう かを指示できます。大部分のシステムでの標準は、システム識別子が公開 識別子に優先しています。 DELEGATE キーワード DELEGATE を使うと、あるカタログを特定タイプの公開識別子 に対応付けることができます。DELEGATE コマンドは、CATALOG と非常に似 ていますが、特定のパターンが指定されない限り何もしない点で異なって います。 DOCTYPE 文書型が最初に書かれていても、公開識別子やシステム識別子が書かれて いない場合、DOCTYPE コマンドが、その文書を特定の DTD に対応付けます 。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.4. DocBook エレメントの使い方 DTD を解析して、それに基づいてエレメントを挿入する機能の付いたエディタ を利用すると、カーソル位置で特定のエレメントを使えるかどうかが分かるの でかなり便利です。これなら、文書のどこにも無効なエレメントを入れること がなくなります。 将来変更があってもなるべく簡単に移行できるように、文書の作成者は、 DocBook DTD の XML バージョンとの互換性をできるだけ保つように心がけたほ うがいいでしょう。つまり、エレメント名には大文字を使い、属性内ではダブ ルクオートでくくり、"短縮タグ"(下記参照)は使わないようにして、終了タグ も省略しないようにしましょう。(psgml + emacs のような)自動でタグを挿入 するツールの大部分は、こうしたルールに自動的に従っているか、ちょっと設 定するだけで従います。 タグの最小化(minimization)にはいくつかのやり方があります。空タグ(empty tag)もそれにあたります。タグの最小化の例としては、終了タグを入れるかわ りに、</> とだけ打つことです。以前にも述べましたが、他にも、タグの省略 (tag omission)というのがあります。次にその両方の例を挙げます。 強調タグを例にとると、まず、ここでは終了タグが省略され、 さらに、<>ここでは空タグも使われています。 個々の文書型には特定の構造があるので、そうした文書の例はのちほど紹介し ます。(Section 4.11参照) 上記の説明を考慮した上で、次に DocBook を使って文書を書く方法を説明して いきます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.4.1. 便利なコマンド Table 4-1では、一般的な文書を作成する際に便利なコマンドを一覧表示してい ます。ただ、いくつかのエレメントは、特定の文脈でのみ有効であることを忘 れないでください。 (訳注: 下記 Table 4-1 では、<to> </to> と書かれた部分がありましたが、そ のまま使うとエラーになり紛らわしいので、<para></para> に修正しています 。) Tip: 変換するフォーマットが変わると、特定のタグでの表示結果も変わる ことがときどきあります。DocBook で初めて文書を作成する場合は、公開 前に、いくつかのフォーマットで作成した文書がどういう体裁になるのか を確認したほうがよいでしょう。 Note: 変換結果は、変換の際に使ったスタイルシートに依存するので、マ ークアップはできるだけたくさん使うことをお薦めします。標準のスタイ ルシートでは出力結果にあまり違いが見えないときでも、そうしたタグを 目立たせる特定の出力フォーマットがあるかもしれないからです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Table 4-1. 便利なコマンド ┌─────┬─────────────────┬─────────┐ │用途 │コマンド │出力結果 │ ├─────┼─────────────────┼─────────┤ │メールアド│address@domain │ │ │レス │ │ │ ├─────┼─────────────────┼─────────┤ │著者につい│... │(下記の例を参照) │ │て │ │ │ ├─────┼─────────────────┼─────────┤ │著者名 │First_Name │First Name Middle │ │ │Middle_Name │Name Surname │ │ │Surname │ │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │キー名(キ │F1 │F1 │ │ーボード上│ │ │ │の表記) │ │ │ ├─────┼─────────────────┼─────────┤ │キーのシン│KEY_F1 │KEY_F1 │ │ボル名 │ │ │ ├─────┼─────────────────┼─────────┤ │キーのコー│0x3B │0x3B │ │ド │ │ │ ├─────┼─────────────────┼─────────┤ │キー入力 │ Ctrl │Ctrl-S │ │ │ S │ │ │ │ │ │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │プログラム│ファイル │ファイル │ │メニュー │ │ │ ├─────┼─────────────────┼─────────┤ │メニューア│保存 │保存 │ │イテム │ │ │ ├─────┼─────────────────┼─────────┤ │メニュー選│ │ファイル->保存 ( │ │択 │ │Ctrl-S) │ │ │ Ctrl │ │ │ │ S │ │ │ │ │ │ │ │ │ │ │ │ ファイル │ │ │ │ 保存 │ │ │ │ │ │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │マウスボタ│left │left │ │ン │ │ │ ├─────┼─────────────────┼─────────┤ │コマンド名│comando │command │ ├─────┼─────────────────┼─────────┤ │アプリケー│application │application │ │ション名 │ │ │ ├─────┼─────────────────┼─────────┤ │参考文献表│reference │[reference] │ │示 │ │ │ ├─────┼─────────────────┼─────────┤ │引用 │ 著者名 │ 引用文 │ │ │ 引用文 │ │ │ │ │ --著者名 │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │索引 │右記参照 │Section 4.5参照 │ ├─────┼─────────────────┼─────────┤ │ファイル名│file │file │ ├─────┼─────────────────┼─────────┤ │ディレクト│directory │directory/ │ │リ │ │ │ ├─────┼─────────────────┼─────────┤ │強調[a] │text │text │ ├─────┼─────────────────┼─────────┤ │脚注 │ 脚注文 │(この表組に最後を │ │ │ │参照) │ ├─────┼─────────────────┼─────────┤ │URL │ │Conectiva S.A. │ ├─────┼─────────────────┼─────────┤ │マーク付き│ │ ・ アイテム │ │箇条書き │ アイテム │ │ │ │ │ ・ アイテム │ │ │ │ │ │ │ アイテム │ │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │番号付き箇│ │ 1. アイテム │ │条書き │ アイテム │ │ │ │ │ 2. アイテム │ │ │ │ │ │ │ アイテム │ │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │書き分けた│ │2 進数から 10 進数│ │箇条書き │ 2 進数 │への変換表 │ │ │ 10 進数 │ │ │ │ 000 │2 進数: 00 │ │ │ │ │ │ │ 011 │10 進数: 0 │ │ │ │ │ │ │ 102 │2 進数: 01 │ │ │ │ │ │ │ │10 進数: 1 │ │ │ │ │ │ │ │2 進数: 10 │ │ │ │ │ │ │ │10 進数: 2 │ ├─────┼─────────────────┼─────────┤ │見出し付き│ │見出し 1 │ │箇条書き │ 見出し 1 │ │ │ │ │ 説明 │ │ │ 説明 │ │ │ │ │見出し 2 │ │ │ │ │ │ │ │ 説明 │ │ │ 見出し 2 │ │ │ │ │ │ │ │ 説明 │ │ │ │ │ │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │シンプルな│ 1 │1 2 3 │ │箇条書き │ 2 │4 5 6 │ │ │ 3 │ │ │ │ 4 │A, B, C, D, E, F │ │ │ 5 │ │ │ │ 6 │ │ │ │ │ │ │ │ │ │ │ │ A │ │ │ │ B │ │ │ │ C │ │ │ │ D │ │ │ │ E │ │ │ │ F │ │ ├─────┼─────────────────┼─────────┤ │画像 │右記参照 │Section 4.6参照 │ ├─────┼─────────────────┼─────────┤ │表組み │右記参照 │Section 4.7参照 │ ├─────┼─────────────────┼─────────┤ │プログラム│右記参照 │Section 4.8参照 │ │へのコメン│ │ │ │ト挿入 │ │ │ ├─────┼─────────────────┼─────────┤ │用語集 │ Term │この文書の巻末にあ│ │ │ │る用語集参照 │ │ │ Definition │ │ │ │ │ │ ├─────┼─────────────────┼─────────┤ │相互参照 │... │(画像等の出力結果 │ │ │ │欄参照) │ │ │ │ │ │ │... │ │ │ │Please, see for more information. │ │ ├─────┴─────────────────┴─────────┤ │Notes: │ │a. 強調表示にはいつくかの方法があります。斜体の太字が最も一般的で │ │すが、 DocBook では斜体しかサポートしていません。太字を使うには、 │ │利用しているスタイルシートに設定を追加する必要があります。 │ └─────────────────────────────────┘ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.5. 索引をつくる 文中にマークアップを挿入することで、索引を生成することができます。 そうしたマークアップは、あとで外部ツールによって処理されて、索引を生成 します。そうしたツールの一例に、collateindex.pl スクリプトがあります。 索引を生成するための処理は、Section 4.10.3で詳しく述べます。 索引には、入れ子レベル(nesting level)があります。索引のマークアップには 、次のコードを使います。Example 4-2 Example 4-2. 索引生成のためのコード Main level Second level Third level 属性 zone を使うことで、文書のチャプターやセクションおよびその他の部分 を参照することができます。 Example 4-3. 属性 zone の使い方 edition index 索引は、文中にマークアップを挿入することで生成されます。 Example 4-3 のコードは、索引上にこの edition というエントリーを生成する のに使われているものです。実際、属性 zone を使えば、文書内でも、文書外 の別ファイルにでもどこにでも索引ページを置くことができます。 ただ、簡単にメンテナンスができるように、索引のエントリーは、索引付けを した文書の最後のページにいつも置かれています。 Example 4-4. 属性 class で、値 startofrange と endofrange を使う方法 普段、文章を打ち込んでいると、ときどき examples index 長文をごっそりマークする必要が生じることがあります。 そういう場合でも、いつも通りに書き進めましょう。 そして、索引付けしたい部分の最後に来たら、次のように締めくくります。 . ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.6. 画像の挿入 画像の挿入は、どういうメディアで文書を公開する場合でも必要なものです。 TeX フォーマットを使うなら、PostScript ファイルのイメージが必要です。オ ンラインで公開するなら、JPG や GIF、 PNG といった一般的なイメージファイ ルが使えます。 画像を挿入する一番簡単な方法は、属性 fileref を使うことです。通常、画像 は、JPG や PostScript (PS もしくは EPS) で生成されます。 Example 4-5. 画像の挿入 <figure> を <informalfigure> に置き換えると、画像のタイトルを入れる必要 がなくなります。 さらに、属性 float があり、この値として 0 を指定すると、画像は、文の流 れに沿った正確な位置に置かれます。値として 1 を指定すると、より適切と考 えられるところに画像が動かされて、その位置に置かれます。 (この位置は、 スタイルシートに記述されている場合があるし、もしくは使用するアプリケー ションによって管理されている場合もあります。) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.6.1. 上記以外の方法 Example 4-5 以外の方法として、<figure> や <informalfigure> を使わない方 法もあります。 他にも、画像が使えないメディアで公開しようとする場合、興味深い代替措置 として、<imageobject> ラッパーを使う方法があります。 Example 4-6. <imageobject>の使い方 この部分には、この例での画像が置かれています。 画像による説明(オプション) 次のようなフォーマットのファイルが使えます。 BMP, CGM-BINARY, CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, GIF, GIF87A, GIF89A, IGES, JPEG, JPG, LINESPECIFIC, PCX, PIC, PS, SGML, TBL, TEX, TIFF, WMF, WPG. この方法には、より適切にアプリケーションを管理できるという利点がありま す。<imageobject> エレメントは、利用可能なフォーマットが見つかるまで順 番にテストされ、出力フォーマットとして画像をサポートしていない場合は、 <textobject> エレメントが使用されます。しかし、Example 4-6 形式を使う最 大の利点は、DocBook のリリース 5.0 では、 <graphic> エレメントは存在し なくなるという点です。 欠点としては、同じひとつの情報を表現するためにいくつものコードを必要と するという点です。文書内にイラストや写真を入れるのにどちらを使うかは文 書制作者しだいですが、将来のバージョンとの互換性からすると、僕としては 、画像の挿入方法としてこちらを推奨します。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.7. 表組 表にすると情報の意味が明瞭になるケースは数多くあります。 表を作成する簡単な方法は、<simplelist> を使った Table 4-1 でも既に紹介 しましたが、DocBook には、この種の情報を扱うもっと洗練された方法があり ます。 Example 4-7. 表の挿入 水平方向のスパンヘッダ 2 ヘッダ 3 ヘッダ 4 フッタ 1 フッタ 2 フッタ 3 フッタ 4 フッタ 5 データ 1-1 データ 1-2 データ 1-3 データ 1-4 データ 1-5 データ 2-1 データ 2-2 データ 2-3 データ 2-4 垂直方向のスパンデータ 3-1 ダブルスパンデータ 3-4 データ 4-1 データ 4-4 データ 4-5 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Table 4-2. 表の例 ┌───────────────┬───────┬──┬───────┐ │ 水平方向のスパン │ヘッダ 2 │ヘッ│ヘッダ 4 │ │ │ │ダ 3│ │ ├───────┬───────┼───────┼──┼───────┤ │データ 1-1 │データ 1-2 │データ 1-3 │デー│データ 1-5 │ │ │ │ │タ │ │ │ │ │ │1-4 │ │ ├───────┼───────┼───────┼──┼───────┤ │データ 2-1 │データ 2-2 │データ 2-3 │デー│ │ │ │ │ │タ │ │ │ │ │ │2-4 │垂直方向のスパ│ ├───────┼───────┴───────┼──┤ン │ │データ 3-1 │ │デー│ │ │ │ │タ │ │ │ │ │3-4 │ │ ├───────┤ ├──┼───────┤ │データ 4-1 │ │デー│データ 4-5 │ │ │ │タ │ │ │ │ ダブルスパン │4-4 │ │ ├───────┼───────┬───────┼──┼───────┤ │フッタ 1 │フッタ 2 │フッタ 3 │フッ│フッタ 5 │ │ │ │ │タ 4│ │ └───────┴───────┴───────┴──┴───────┘ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.8. プログラムコードとコメント 面白い機能として、コードの一部を指定して、それにコメントを付けるという のがあります。DocBook を使えば、プログラムコードを文書に挿入して、その コードの特定の行に「しるし(callout)」を付けることができます。 この機能は、例えば、カタログファイルの設定方法を説明した際に、使用して います。(Section 4.3 参照) その際に使ったコードを以下に示します。「しるし(callout)」機能の使用が望 ましくないケースでは、<areaspec> と <calloutlist> に挟まれた空間を消去 することもできます。 (訳注: Table 4-1同様、<to> </to> は <para> </para> に修正しました。) -- Catalogues for the Conectiva S.A. Style -- OVERRIDE YES PUBLIC "-//Conectiva SA//DTD books V1.0//EN" "/home/ldp/estilos/livros.dtd" DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd" DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd -- EOF -- Comment. Comments begin with -- and follows to the end of the line. The public type association "-//Conectiva SA//DTD books V1.0//EN" with the file books.dtd on the directory /home/ldp/estilos. Comment informing the end of the file. <example> や <para> エレメントを使わなくとも、コメント(listing)は、直接 本文内に書くことができます。 「しるし」の位置は、コメントが書かれたコード位置に合うように処理されま す。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.9. 翻訳者やコード変換者の氏名を表示する 誰かが LDP 文書作成の手助けをしてくれたときは、それを文書内で明らかにす べきですし、DocBook にもそのためのタグがあります。このセクションでは、 そうした何らかの形で貢献者の氏名 (credit) を表示すべき場合に使うタグに ついて紹介します。まず、編集者についてなら簡単です。DocBook にはあらか じめ <editor> というのがあります。しかし、氏名を表示すべきでも DocBook に該当するタグのない特別なケースが 2 つあります。翻訳者とコード変換者で す。 コード変換者とは、例えば HTML を DocBook SGML に変換するなど、ソースコ ードの変換を行う人のことです。ソースコードの変換が行われることで、LDP アーカイブは、メタデータの作成というこれからの目標の達成により適したも のになりますし、文書を多様な出力フォーマットで提供することができるよう になります。 翻訳者は、オリジナル文書を、例えば英語から日本語、ドイツ語から英語とい った別の地域の言語へと移し換えます。個々の翻訳文書によって、世界中のよ り多くの人々があなたの文書を利用できるようになりますし、Linux アーカイ ブの究極の野望である、「全世界制覇 "Total World Dominion (tm)" 」にまた 一歩近づくことができます。 以下のセクションに示すような方法で、そうした人たちや、あなたの文書作成 に貢献したそれ以外の人たちに対して、その支援内容を明らかにすることがで きます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.9.1. <othercredit> タグ 翻訳者やコード変換者の氏名を表示する場合には、<othercredit> というタグ ・エントリーを使ってください。翻訳やコード変換といったそれぞれの役割を 明示するには、<othercredit> タグの <role> 属性に、"converter" (コード変 換者) や "translator" (翻訳者) といった値を設定します。これは、例えば、 次のようになります。 David Merrill Conversion from HTML to DocBook v3.1 (SGML). ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.9.2. "謝辞" (Acknowledgements) の章について 文書内には、"謝辞" (Acknowledgements) と題したセクションを作って、そこ で、その文書に意味のある貢献をしたすべての人のことを書くようにしましょ う。翻訳者やコード変換者だけでなく、多くの有意義なフィードバックを送っ てくれた人や、あなたが知ろうとしていた知識を教えてくれた人、あるいは、 現在の文書が出来上がるまでに手足となって手伝ってくれた人たちなどがそれ に含まれます。大部分の著者が、文書の最後にこのセクションを置いています 。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.9.3. <revremark> タグ <revision> タグには階層があり、その中に、<revremark> というタグがありま す。このタグで囲んだ領域には、文書を改訂した際の簡単な覚え書きを書き込 んでおくことができます。新しいフォーマットでリリースした最初のバージョ ンのコメントとしてコード変換者に対する謝辞を書いておいたり、翻訳者の氏 名を翻訳したバージョンごとに書いておいたりすることをお薦めしたいと思い ます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.10. ツールとヒント 出力結果を見たり索引を作ったりする処理は、文書作成中に何度も繰り返され ますし、エラーが出ることも多いはずです。こうした処理を楽に行うために、 いくつかのスクリプトを用意しました。よろしければカスタマイズして使って ください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.10.1. ソースのコンパイル compiles-sgml スクリプトは、一連のコマンドをグループ化したものです。パ ラメータとして、SGML の文書名と出力したいフォーマット名を渡す必要があり ます。 下記のバージョンのスクリプトでは、 XML, HTML, TeX, RTF, PS, DVI および 写像 PS (mirrored PS) フォーマットをサポートしているので、フォトリトグ ラフを生成する場合には理想的です。 索引の生成は、collateindex.pl[3] スクリプトが自動的に行うので、左記スク リプトをあらかじめシステムにインストールしておいてください。 様々なフォーマットで出力を生成する下記のコマンドとは別に、他にも直接変 換を行うツールが Cygnus™ から提供されています。そのツールは、ここ <http://sourceware.cygnus.com/docbook-tools/>から入手することができます 。 以下のスクリプトは、ここ <http://www.linuxdoc.org/LDP/LDP-Author-Guide/ compile-sgml> から手に入れることもできます。 上記の場所には、 collateindex.pl <http://www.linuxdoc.org/LDP/ LDP-Author-Guide/collateindex.pl> もあります。 Example 4-8. compiles-sgml スクリプト #!/bin/bash # # Compile DocBook documents into several output formats. # # Godoy. # 19991230 - Initial release. # 20000117 - Placed the options using "case" and parameters passed # via command line. The pages on the Zope are already updated. # --- Removed to public version (/home/ldp). # 20000120 - Placed the call to use the books.dtd. # 20000126 - Placed the commands for the index generation. # # If the jade is already installed, disconsider the line bellow. JADE=/usr/bin/jade # If the jade package is already installed, disconsider the line bellow. # JADE=/usr/bin/openjade DOCUMENT=$1 shift 1 TYPE=$1 . ~/.bash_profile . ~/.bashrc case $TYPE in html) rm -f *.htm rm -f *.html perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o index.sgml HTML.index $JADE -t sgml -i html -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#html $DOCUMENT.sgml ;; rtf) rm -f $DOCUMENT.rtf perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index $JADE -t rtf -V rtf-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/books.dsl#print $DOCUMENT.sgml ;; xml) rm -f $DOCUMENT.xml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index $JADE -t sgml -i xml -d /home/ldp/SGML/style/xsl/docbook/html/docbook.xsl $DOCUMENT.sgml ;; tex) rm -f $DOCUMENT.tex perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml ;; dvi) rm -f $DOCUMENT.tex rm -f $DOCUMENT.dvi perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml jadetex $DOCUMENT.tex ;; mirror) rm -f $DOCUMENT.tex rm -f $DOCUMENT.dvi rm -f $DOCUMENT.mirror.ps perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml jadetex $DOCUMENT.tex dvips -h /home/ldp/estilos/skel/mirr.hd -O 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.mirror.ps ;; ps) rm -f $DOCUMENT.tex rm -f $DOCUMENT.dvi rm -f $DOCUMENT.ps perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml jadetex $DOCUMENT.tex dvips -The 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.ps ;; *) echo "How to use: $0 file {html|tex|rtf|xml|ps|dvi|mirror}" exit 1 esac exit 0 こうしたスクリプトは、Makefile を作って、関数のいくつかを最適化すること で、修正できるのがお分かりになると思います。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.10.2. article の最初のページに要旨を挿入する article の最初のページに要旨を表示できる機能が欲しいと思う場合があるか もしれません。ただ、DocBook の article は、標準では、この機能を持ってい ません。 (訳注: DocBook の book を使う場合は、問題ありません。) これを有効にするには、利用しているスタイルシートに修正を加える必要があ ります。 以下の例は、その場合の処理について述べています。使い方は、 Example 4-8 をご覧ください。 Example 4-9. article で、自動的に要旨を挿入するための stylesheet の設定 ]> ; Includes a summary at the beginning of an item. (define %generate-article-toc% #t) ; Includes a summary at the beginning of an item. (define %generate-article-toc% #t) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.10.3. 索引を自動的に挿入する DocBook には索引付けをするためのマークアップがありますが、それらは自動 的には生成されません。しかし、collateindex.pl <http://www.linuxdoc.org/ LDP/LDP-Author-Guide/collateindex.pl> ツールを使えば、索引生成は自動化 できます。 次にこのスクリプトの使い方を説明します。実際の例は、この文書で先ほどご 覧になったと思います。(Example 4-8参照) 1. HTML スタイルシートと、オプション -V html-index を使って、jade で文 書を処理します。 ┌───────────────────────────────┐ │$ jade -t sgml -d html/docbook.dsl -V html-index document.sgml│ └───────────────────────────────┘ 2. collateindex.pl <http://www.linuxdoc.org/LDP/LDP-Author-Guide/ collateindex.pl> を使って、index.sgml 文書を生成します。 ┌────────────────────────────┐ │$ perl collateindex.pl -o index.sgml HTML.index │ └────────────────────────────┘ 上記の例が機能するには、外部エンティティ(external entity) を定義して index.sgml ファイルを取り込む必要があります。 Example 4-10. 索引を付けるために外部エンティティを設定する ]> 文中に必要な情報を取り込む方法については、Section 4.5 もご覧ください。 Note: PS か PDF での出力の際に目次や索引を取り込もうとしている場合 は、 jadetex か pdfjadetex を最低 3 回は実行する必要があることに注 意してください。これは、TeX が必要とする処理であり、DocBook もしく はそれに関連したアプリケーションの問題ではありません。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.10.4. 文書の中の下書き部分を隠す 面白い機能として、文書の作成中に、その作成部分を最終稿として公開するか どうかを簡単なチェックだけで決めることができる機能があります。既存の文 書を更新しようとしている場合などには特に、文書内に草稿として位置づけら れている部分がいくつも存在する場合がよくあります。 DocBook では、パラメータ・エンティティ(parameter entity)を使って、文書 内に散らばった特定部分の文章を、状況に応じて隠したり表示したりすること ができます。文書を更新している場合には、文書がどう見えるのかを確認した り、新しい章や編のおおまかな出来具合を確認したりする必要がありますが、 その草稿部分を最終稿には表示したくないということがよくあります。 パラメータ・エンティティを使うと、文書の冒頭の一行を変更するだけで、そ うした草稿部分を文書内に含めたり、文書から削除したりすることができます 。 Example 4-11. パラメータ・エンティティを使う ... この段落は、上記エンティティ "review" の値が "INCLUDE" と 定義されたときに、文書中の一部となります。 ]]> 上記エンティティ review は、文書内のいろいろな箇所に書き込むことができ ます。その部分への変更が終了したら、上記の例ならば、 3 行目と 6 行目を 削除するだけです。 草稿のままで保持して、最終稿には含めないようにするには、エンティティの 値を INCLUDE から IGNORE に書き換えるだけで済みます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.10.5. 頻繁に利用する文書を外部から取り込む 外部エンティティ(external entity)の重要な特性は、よく使われるメモや文書 を取り扱う際に発揮されます。 この特性を活かして、(例えば、ライセンスや社則などの)頻繁に利用される文 章をファイルにして、そうしたファイルを文書の適切な位置に取り込むことが できます。 この特性を応用した例に、先ほどの Example 4-10 があります。また、この HOWTO 文書自体の SGML コードもその一例です。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.11. 文書のサンプル 繰り返しになりますが、個々の文書型には、その文書型特有のヘッダと有効な コマンドの階層があります。以下のサブセクションでは、article と book に ついてのヘッダと有効なコマンド階層を紹介します。 ここでの例は、あらゆる利用方法をカバーしているわけではないので、以下で は、使い方の一般例を提供する意味で紹介します。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.11.1. article の例 Jorge Luiz Godoy Filho Conectiva S.A. Publishing Departmentt;/orgdiv> godoy@conectiva.com 1.0 27 de janeiro de 2000 godoy Verso inicial. This document can be freely translated and distributed. It's released under the LDP License. SGML DocBook DTD XML catalogs documents Publishingdlt;/keyword> Conectiva configuration use tools HOWTO ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.11.2. book の例 作成中 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 5. LDP スタイル・ガイド 5.1. 主題を決める HOWTO を書き始める前に、カバーしようとする主題の範囲を明確にすることが 先決です。主題の範囲は、以下の条件に合致することがベストです。 1. 広すぎず、狭すぎず. 広範な情報をカバーしようとすると、深さが犠牲に なります。広い主題を貧弱にカバーするよりも、狭い主題を充分にカバー するほうがベターです。 Linux のツール類は、ひとつの仕事しかしません が、それを的確にこなすことで有名です。同様に、HOWTO でもひとつの主 題を的確にカバーするようにしてください。 主題となる事柄が非常に狭い場合は、他の HOWTO の一部として作成するほ うがいいかもしれません。そうすれば、読者は必要とする HOWTO を見つけ やすくなります。関連するトピックの HOWTO を LDP リポジトリで検索し て、既存の HOWTO のなかにこれから書こうとする情報を追加できる場所が ないか確認してください。 どの程度だと書きすぎか、どの程度だと書き足りないかは、選んだ主題に もよりますし、その主題にどれだけ習熟しているかなどにもよります。そ のことを念頭に置いて、適切な判断を下してください。 2. 主題は明確に. 書き始める前に、主題となる領域の境界をどこに据えるか を正確に意識するようにしてください。他の HOWTO と同じ領域をカバーす るべきではありませんし、作成する HOWTO と関連する既存の HOWTO との 間になるべくギャップを作らないようにしてください。 3. 新しい主題であること. 特定の主題について書く前に、LDP で他の HOWTO をチェックして、おなじトピックが既に文書化されていないか確認してく ださい。もし既にあるなら、同じ文書をふたつ作るよりも、既存の文書を 活用するようにしてください。 もし既存の HOWTO では不十分な場合や、更新が必要な場合は、その著者に 連絡して、協力を申し出るようにしてください。LDP の著者は、たいてい いいヤツです。結局、彼らは、知りもしないひとを助けるために貴重な時 間を割いたわけです。ですので、申し出は快く受け入れてくれるでしょう 。ただ、どうか作業結果は一本化してください。でないと、皆が混乱しま す。 4. LDP で事前に承認されること. HOWTO 作成に入る前に、ldp-discuss メー リングリストにその旨連絡して、 LDP ボランティアからのフィードバック を取るようにしてください。事前にメーリングリストをチェックしておく と、後で悩まずにすみます。経験者の談です。 ポストしなくとも、ldp-discuss メーリングリストに参加して、定期的に フォローしておくのは、とてもいいことです。LDP の活動やニーズ、ポリ シーの現状を知るのに役立ちます。LDP ボランティアはむろん援助は惜し みませんが、 LDP のポリシーを学び、それに従うかどうかは、最終的にあ なたがお決めになることです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.2. アウトラインを作成する 実際に書き始めるにあたり、事前にアウトラインを作成してください。アウト ラインを準備しておくと、主題についての明確なイメージを持つことができる ようになりますし、その時々で、HOWTO の細かな部分に集中できます。 極端に短い HOWTO でない限り、アウトラインはおそらく何段階かのレベルにわ かれるはずです。階層を持ったアウトラインを作成する場合は、主題に関する 一般的な事柄が最上位に含まれ、サブセクションに特定の詳しい事柄が来るよ うにしてください。個々のアウトラインのレベルを個別に眺めて、主題につい ての主要領域がすべてカバーされているかどうかを確認してください。サブセ クション全体で、セクションに含まれるべきすべての主要領域がカバーされる ようにしてください。 アウトラインの個々の項目は、前の項目を受け、後の項目を導くような論理関 係になるようにしてください。たとえば、特定のプログラムに関する HOWTO の 場合、あらかじめインストールのセクションを書かずに、いきなり設定のセク ションを作らないようにしてください。 アウトラインができたら、今度は、それを批判的な目でもう一度眺めてくださ い。すべての関連トピックを適当な詳しさでカバーしているでしょうか? HOWTO の射程外のことが書かれていませんか?それを誰かに見せて、意見を求 めるといいかもしれません。書き始めた後よりも、アウトラインの段階の方が 自分の HOWTO の全体像を掴みやすいものです。多くのフィードバックが欲しい ときは、アウトラインを ldp-discuss メーリングリストに投稿することも考え てください。 Note: ここで述べようとしているテーマにもう気付いた方もいらっしゃる でしょう。フリーソフトウェアと同様に、フリードキュメントも、"はやめ のリリース、しょっちゅうリリース (release early, release often) <http://cruel.org/freeware/cathedral.html#4>" がベストです。 ldp-discuss メーリングリストには、LDP 文書作成の経験者が大勢います から、 HOWTO 作成時に迷うことがあったら、アドバイスを求めるといいか もしれません。 Linus の法則を思い出しましょう。 "目玉の数さえ充分あれば、どんな typo も深刻ではない。 [4] " --Eric S. Raymond (Mr. Raymond ごめんなさい。) FIXME: クレジットやライセンス、コピーライトなどなどのトピックに関する " 標準的" なレイアウトを提示すること。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.3. 文章を書く この時点で、HOWTO の枠組が決まり、未加工の断片的な情報が集められ、文書 化され、アウトラインに組み込まれていると思います。よいニュースです。こ れで中間地点を過ぎました。あとは下り坂です。 次にチャレンジするのは、これまで集めた生のままのデータ全部にマッサージ を施しながら、読んで、楽しんで、理解できるような完成品に仕上げることで す。 実際に文章を書き始めることができる地点までたどり着くには、大変な作業が 必要だったと思います。しかし、そのハードワークが報われる時が来ました。 この段階では、あなた独自の方法で無味乾燥な大量の情報を吟味して、イマジ ネーションと独創性を発揮できます。 効率よく文章を書く方法全般を解説することは、この文書の範疇を越えるので 、基本的なことだけを説明しようと思います。"リファレンス" のセクションで 、この文書などよりも的確にこれを扱った文献を紹介しています。それらの文 献をあたって、アドバイスに従ってください。 まずは、Politics and the English Language <http://www.resort.com/ ~prime8/Orwell/patee.html> からいくつかアドバイスを紹介します。 注意深いライターは、文章を一行書くたびに、少なくとも次 の 4 つのことを自問する。 1. 自分は何を言おうとしているんだろう? 2. どんな言葉でそれを表現できるだろう? 3. どういうイメージや言い回しを使うともっとはっきりす るだろうか? 4. このイメージは、新鮮な効果を発揮するだろうか? おそらくは、次のふたつも自問するだろう。 1. もっと端的に表現できないだろうか? 2. 陳腐で余計なことを言っていないだろうか? ...言葉の効果を計りかねるのはよくあることです。それゆえ 、直観をあてにできないときに、頼れるルールが必要になる 。たいていのケースは次のルールでカバーできると、わたし は思う。 1. 普段目にすることが多い隠喩や直喩、その他の比喩的表 現は使わないこと。 2. 簡単な単語を使えるときは、難しい単語を使わないこと 。 3. 使わなくてもいい単語は、決して使わないこと。 4. 能動態が使える場合に、受動態を使わないこと。 5. 外国語のフレーズ、科学用語、専門用語の類は、日常英 語のなかで該当する語句が思い浮かぶ場合は使わないこ と。 6. 以上のルールをひとつでも破ると、そのとたんに、言葉 は野暮なものになる。 --George Orwell それから、純粋にスタイルの観点から言うと、多くの HOWTO が使っている一人 称での書き方は、わたしには魅力があるように思えます。この魅力は、そうで ない大部分の文書からは得難いものです。自分自身として話すことを恐れずに 、 " I " を使い、体験談や自分の意見を書いてください。 これ以上くどいと思うかたがいらっしゃるとは思いますが、これらすべての提 案の基調となっている原則は、シンプルであることです。読者はすでにあたら しく登場する概念と日々格闘しているのですから、あなたの言葉が理解できず に格闘するといったことにならないようにしてください。KISS の原則を忘れな いようお願いします: Keep It Simple, Stupid! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.4. テキストの推敲と校正 HOWTO の文章を書き終わったら、次は、それを推敲して磨きをかけます。推敲 の善し悪しで、まずまずの HOWTO か、すばらしい HOWTO かが決まります。 推敲の目的は、文書に忍び込んだ余計な事柄を削除することです。HOWTO を注 意深く読み返して、その主題についての読者の理解に役立たないものは、バッ サリと削ってください。文章を書いているうちに脱線するのは、著者として自 然なことです。今は、それを訂正するときです。 推敲と校正の際は、スペルミスや typo といった明らかなミスをチェックしな くてはなりません。しかし、その際、もっと深くて、見つけにくい、必要な情 報の "欠落" も同時にチェックすべきです。セクションの内容がそのセクショ ンのタイトルと正確に合致しているかどうか確認してください。 文書の質と正確さについて完全に満足のいくものができたら、次にそれを誰か に渡して、第三者として校正してもらってください。自分では作品に近すぎて 、根本的な欠点を理解できないことがあるからです。 こうした校訂は、ある意味で、ソフトウェア開発のコード・レビューのような ものです。プログラマが自分たちで作ったコードをレビューしてもあまり意味 がないでしょう?作者が自分たちで作った文書を校訂しても、それ以上意味の ある結果を得られるでしょうか?そうしたわけで、友人をリクルートするか、 ldp-discuss メーリングリストに投稿してボランティアを捜し、寄稿する前に HOWTO を校正するようにしてください。 Note: もし自分では精通していない言語で文書を書いている場合は、その 言語に精通した校正者を捜すことを強くお薦めします。技術文書では、他 のどんなタイプの文書よりも、特段に正確な文法と語彙を使わなければな りません。言葉の誤用は、それがどれほど致し方のない意図せざる誤用で あったとしても、あなたの HOWTO の価値を低下させてしまいます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.5. 作成した HOWTO の管理 作成した HOWTO 文書が公開されたからといって、仕事がすべて終わったわけで はありません。HOWTO の情報を更新し、読者のアイデアや提案に応えて HOWTO を確実に改善していくためには、定期的なメンテナンスが必要です。 HOWTO に は、活発に成長する生きた知識が詰まっているので、公開してそれで終わりと いう固定的なものではありません。 HOWTO に自分のメールアドレスを書いて、読者からのフィードバックを丁寧に お願いしたでしょうか?一旦正式に公開されると、提案のメールをいくつも受 け取るようになります。そのなかにはとても貴重なものがありますが、それ以 外は個人的な問題の解決を求めるものだったりします。時間がなければ、個人 的な問題に応える必要は全くありません。LDP で HOWTO を書いたからといって 、ネット上のあらゆる人にフリーサポートを生涯続ける義務を負うわけではな いからです。ただ、もしできるなら、そうした人に別の情報源を教えてあげる と、親切ではあります。また、受け取った質問のパターンが見えてくれば、 HOWTO に追加すべきトピックが分かるかもしれません。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.6. リファレンス 文章の書き方に関する文献がオンライン上にもたくさんあります。特にすぐれ たもののいくつかを簡単に紹介します。 ・ Politics and the English Language <http://www.resort.com/~prime8/ Orwell/patee.html>. ・ Elements of Style <http://bartleby.com/141> ・ FIXME: テクニカル・ライティングに関する良い文献がありましたら、 URL をお教えください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 6. スタイル関連事項の補足 このセクションでは、文書の作成にあたり、スタイルに関連するトピックのい くつかを補足しています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.1. 日付の書き方 <pubdate> タグを文書で使う際には、次の書式で日付を記入してください。 v1.0, 21 April 2000 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.2. 画像フォーマット 文書に画像を付けて LDP に送る際は、まず .eps のセットと、次に .gif もし くは .jpg のどちらか一方のセットとを送ってください。.gif の特許の問題は 意識しておくべきですが、.gif のほうが、.jpg よりすこしだけ良い画像が作 れるようです。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.3. DocBook のバージョン LDP では、以下のフォーマットでの文書をサポートし、受け入れています。 ・ SGML DocBook versions 4.x と 3.1 ・ SGML LinuxDoc ・ XML DocBook version 4.1.2 DocBook のヘッダを書くときは、次のように書いてください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.4. 利用禁止のタグ 非推奨タグとして DocBook: The Definitive Guide のリストに挙がっているタ グは、LDP 文書内でも使用しないようにしてください。新しいタグの使い方に ついては、テクニックとコツのセクションで紹介しています。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.5. タグの最小化 タグの最小化(tag minimization)とは、(たとえば、</para> のような)完全な 終了タグのかわりに、</> を使うことです。これを使うと、その文書に将来関 わる作者や LDP メンバーにとっては文書構造が分かりにくくなりますし、XML DocBook では認められていない使い方なので、そうした習慣は止めるようにし てください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.6. 文書内での表記法 様々な文書間で守るべき表記法に、次のようなものがあります。 コマンドの使い方を示そうとする場合、ユーザコマンドラインとしての表示に なるよう、コマンド行を書いてください。プロンプトには、まず、シェルの種 類 (bash, tcsh, zsh, など) が表示され、次に、(root でない)通常のユーザ として実行される場合には $ を、root ユーザとして実行される場合は # を表 示してください。 それゆえ、コマンドは、次のように表示されます。 ┌──────────────────────────────────┐ │bash$ command "run as a normal user" │ │bash# command "run as a root user" │ │tcsh# setenv DISPLAY :0.0 │ └──────────────────────────────────┘ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 7. DocBook のテクニックとコツ このセクションでは、文書を書く際の DocBook のちょっとひねった使い方をい くつか紹介します。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.1. 画像の挿入 HOWTO に画像を入れようと思っている場合、LinuxDoc では画像のサポートはあ りませんでしたが、DocBook なら可能です。次に、HOWTO に画像を入れる方法 の一例を紹介します。 Screen shot of the LyX document processing program 上記は、<graphic> を使うよりも、ふたつの理由ですぐれています。第一に、 DocBook 5.0 では、<mediaobject> に移行するため、<graphic> は削除されま す。それゆえ、今から正しい方法で使い始めるほうがよいと思われます。第二 に、<mediaobject> なら、出力形式に従って異なる複数のフォーマットの画像 を扱うことができます。上記の例で言うと、最初の <imageobject> は、DVI, PS, PDF といった TeX から生成されるフォーマットに利用される EPS (Encapsulated PostScript) 画像で、ふたつ目の <imageobject> は、ディスプ レイ画面用、大部分は HTML 用の出力で利用される JPEG 画像です。 <textobject> の部分は、出力が画像をサポートしていない場合に表示されるも のです(TXT)。<alt> タグのようなものとお考えください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.2. HTML 出力ファイルのファイル名を指定する 個別の HTML ファイルを出力する場合、SGML 処理系は、デフォルトで、恣意的 なファイル名しか付けません。これでは、読者がページをブックマークしてお いてもすぐに変更されてしまいますし、あなたもどれがどのファイルなのか分 からなくなって、紛らわしいでしょう。理由はどうであれ、ここでは、個別の 出力ファイルに好きな名前を付ける方法を紹介します。 <article> タグを最初に置く場合( これはひとつだけのはずです。)、そこに id パラメータを書き込んで、その値を index とします。そうすると、タグは 次のようになります。 最初に <chapter> タグを置く場合、このタグ内の内容は通常イントロダクショ ンとなるでしょうし、これは文書内の最初に置きたいと思うでしょうから、修 正しないでください [5]。それ以外の個々の <section> タグについては、 id パラメータとその名前を書き込んでください。名前には、アルファベットと数 字だけを使うようにし、内容が理解できる程度の短い名前にしてください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.3. ldp.dsl を使う LDP では、独自の DSSSL を使っていて、それによって、背景部分や HOWTO の 最初のページにある目次の自動生成機能を付け加えています。その最新バージ ョンは、 http://www.linuxdoc.org/authors/tools/ldp.dsl にあります。 ファイルが手に入ったら、DocBook DSSSL ファイルの置き場所に基づいて先頭 の数行を修正する必要があるかもしれません。わたしの例では、Cygnus ツール セットを使っています。 ldp.dsl ファイルを /usr/lib/sgml/stylesheets に置いて、それを好きなエデ ィタで開いてください。次のようになっているのがわかると思います。 ┌──────────────────────────────────┐ │ │ │(1) " CDATA dsssl> │ │]]> │ │ │ │(2) " CDATA dsssl> │ │]]> │ │]> │ └──────────────────────────────────┘ (1) 最初の "docbook.dsl" が、/usr/lib/sgml/stylesheets/nwalsh-modular/ html/docbook.dsl を読むようにしてください。 (2) 二つ目の "docbook.dsl" が /usr/lib/sgml/stylesheets/nwalsh-modular/ print/docbook.dsl を読むようにしてください。 もし違う DSSSL を使っているなら、上記ふたつのファイルのところが HTML 用 とプリント用の DSSSL ファイルを指すように変更してください。通常、それら は html や print と呼ばれるディレクトリに入っています。 以上が済めば、HTML ファイルの出力ができるようになります。 ┌─────────────────────────────────────────────┐ │bash$ mkdir HOWTO-HOWTO ; cd HOWTO-HOWTO │ │bash$ jade -t sgml -i html -d /usr/lib/sgml/stylesheets/ldp.dsl\#html ../HOWTO-HOWTO.sgml│ └─────────────────────────────────────────────┘ 最初のコマンドでは、出力ファイルを入れるディレクトリを作成しています。 次のコマンド(jade を使っている方です)では、文書のセクションごとの個別の HTML ファイルを生成しています。RTF などを出力したい場合は、次のようにし てください。 ┌─────────────────────────────────────┐ │bash$ jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl ../HOWTO-HOWTO.sgml│ └─────────────────────────────────────┘ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 8. 文書の公開について 8.1. 文書公開のまえに 将来の無数の読者に文書を公開するまえに、やるべきことがいくつかあります 。 第一に、必ずスペルチェックをすることです。SGML を書くのに使われるユーテ ィリティには、たいていスペルチェック用のプラグインが付いています。付い ていない場合でも、aspell があります。 第二に、他の人に査読してもらい、コメントをもらったり、事実に間違いがな いか確認してもらってください。LDP が出す文書は、無数の Linux ユーザが読 むことになるので、事実の誤りは極力減らす必要があります。執筆対象に関し て大勢の人が参加するメーリングリストに登録しているなら、そこで他の人に 尋ねて、助けてもらいましょう。 第三に、作成した文書を公開するウェブサイトを作ってください。これは必須 ではありませんが、その文書がどこで作成されたのかを知る手がかりになりま す。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.1.1. SGML コードの妥当性検査 jade や実際の nsgmls コマンドを使って、作成した .sgml コードが DTD に照 らして妥当かどうか検査し、エラーのないことを確かめることができます。 ┌──────────────────────────────────┐ │bash$ nsgmls -s HOWTO-HOWTO.sgml │ └──────────────────────────────────┘ これで問題がなければ、何事もなくコマンドプロンプトが返ってきます。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.2. 著作権とライセンスの問題 LDP で LDP 文書として認められるには、http://www.linuxdoc.org/ manifesto.html にある LDP マニフェストの " ライセンス上の必要事項 " に 従ったライセンスが付いていなければなりません。文書の作成者として、著作 権を保持することができますし、ライセンスに他の制限 (たとえば、翻訳や二 次文書を作成したときは、著者の承認を得なければならない、とか) を付け加 えることもできます。 われわれとしては、GNU Free Documentation License (GFDL) <http:// www.gnu.org/copyleft/fdl.html> か、オプション A と B なしの Open Publication License (OPL) <http://opencontent.org/openpub/> を使うこと をお薦めします。 DocBook 用にマークアップされた GNU GPL と GNU FDL が GNOME Documentation Project <http://developer.gnome.org/projects/gdp/ licenses.html> にあるので、それを使うこともできます。その場合、ライセン ス全文を文書内に入れるだけです。ただ、全文は長いので、ライセンスへのリ ンクを書き込んでおくだけでも結構です。 著作権の「鋳型」を使おうとする場合は、" 著作権とライセンス "といったセ クションを立てて、そこに文面をそのままコピーしてください。御自分の名前 で著作権の表示も入れてください。(ライセンスのために著作権が奪われるわけ ではありません。) 既存の文書の新しい管理者になった場合は、その文書を管 理していた以前の著者名と日付についての著作権も書かなければなりません。 この LDP Author Guide のライセンスでは、二次文書や翻訳を作成する場合に 著者への報告を求めていることに、お気付きかもしれません。また、わたしは 、(この文書を書いた SGML のソースコードを除く) すべてのソースコードを明 示的に GPL の基に置きました。作成した HOWTO にソースコードが含まれてい て、それを他の人にも使ってもらおうと思うときは、同じようにするといいと 思います。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.3. LDP への寄稿 LDP 文書のきめ細かい査読が済むと、その文書は LDP でリリースできます。 SGML ソースコードを添付して、(<submit@linuxdoc.org> にメールを送ってく ださい。( gzip で圧縮しても結構です。) メールの subject 欄には HOWTO の文書名を入れて、本文にはその HOWTO の変 更点や書き足した点の概要を書いておくのを忘れないでください。これがある と文書管理の作業時間が短縮できますし、送った HOWTO が LDP のウェブサイ ト上で更新されるのを待たなくて済みます。5 日間何の知らせもないときは、 もう一度メールを送って、まだ作業中なのかどうか確認してください。 HOWTO にテキスト以外の画像や特別なカタログが含まれる場合、.sgml ソース コードを含む全ファイルを .tar.gz ファイルに固めて、メールに添付して submit メーリングリストまで送ってください。 文書の作成中に LDP CVS ツリーを使っている場合は、文書を公開する準備が整 ったときに再度 LDP へ報告する必要があります。その際は、 <submit@linuxdoc.org> にメールをお送りください。タイトルに文書名を入れ て、本文に LDP CVS ツリー内での相対パスを書いておいてください。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.4. 作成した文書の管理 作成した HOWTO が公開されたからといって、仕事が全部終わったわけではあり ません。HOWTO の情報を更新し、読者のアイデアや提案に応えて HOWTO を確実 に改善していくためには、定期的なメインテナンスが不可欠です。HOWTO には 、活発に成長する生きた知識が詰まっているので、公開したらそれで終わりと いう固定的なものではありません。 HOWTO に自分のメールアドレスを書いて、読者からのフィードバックを丁寧に お願いしたでしょうか?一旦正式に公開されると、提案のメールをいくつも受 け取るようになります。そのなかにはとても貴重なものがありますが、それ以 外は個人的な問題の解決を求めるものだったりします。時間がなければ、個人 的な問題に応える必要は全くありません。LDP で HOWTO を書いたからといって 、ネット上のあらゆる人にフリーサポートを生涯続ける義務を負うわけではな いからです。ただ、もしできるなら、そうした人に別の情報源を教えてあげる と、親切ではあります。また、受け取った質問のパターンが見えてくれば、 HOWTO に追加すべきトピックが分かるかもしれません。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Chapter 9. LDP についての FAQ Q: LDP のお手伝いをしたいのですが、どうしたらいいでしょう? Q: LDP 文書をまとめて、書籍として出版したいのですが、LDP 文書のライセン スはどういったものになりますか? Q: LDP 文書の中に誤りを見つけたのですが、修正できますか? Q: SGML が分かりません。/ ツールが動きません。/ SGML が嫌いです。 Q: LDP のお手伝いをしたいのですが、どうしたらいいでしょう? A: 一番簡単な方法は、何か主題を捜して、それを文書化することです。もしく は、管理者がいない HOWTO をチェックして、自分がよく知っている分野で文書 化し続けられるものがないか確認することです。 Q: LDP 文書をまとめて、書籍として出版したいのですが、LDP 文書のライセン スはどういったものになりますか? A: http://www.linuxdoc.org/COPYRIGHT.html" <http://www.linuxdoc.org/ COPYRIGHT.html> をご覧ください。ただ、これは個々の著者に対するガイドラ インでしかないことに注意してください。とはいえ、この URL に挙がっている ものより厳しい条件を付けることはできません。 Q: LDP 文書の中に誤りを見つけたのですが、修正できますか? A: 文書の著者か、LDP コーディネータ <discuss@linuxdoc.org> 宛に連絡して 、問題の部分と、どういう修正が必要が必要かを報告してください。 Q: SGML が分かりません。/ ツールが動きません。/ SGML が嫌いです。 A: 問題ありません。最初の草稿は、お好きなフォーマットで書いていただいて 結構ですので、それを LDP までお送りください。LDP ボランティアが査読して 、その後で DocBook に変換します。それさえ済めば、HOWTO の管理自体は難し くないでしょう。疑問があれば、いつでも LDP ボランティアに連絡するか、 LDP DocBook メーリングリスト <docbook@linuxdoc.org> まで連絡してくださ い。 用語集 属性 (attribute) 属性とは、それが置かれたエレメントに追加情報を持たせることを可能に するものです。属性は、必ず「属性名と値」のペアが初期化ポインタで結 ばれた形で現れます。id="identification" は属性の一例ですが、ここで は id が属性で、identification が値です。 文書型定義 (DTD, Document Type Definition) 組み合わせと順序についてのルールを指定して、エレメント名とその属性 とを定義した文言の集合。カーソル位置のコンテキスト上で、あるエレメ ントを挿入できるか否かを定義しているのが、DTD です。 DSSSL DSSSL は、Document Style Semantics and Specification Language の略 です。 ISO 標準 (ISO/IEC 10179:1996) となっています。DSSSL 規格は、 SGML の文書スタイルシートページのための言語として国際的に使用されて います。 エレメント (element) エレメントは、文書の階層構造を定義するものです。ほとんどのエレメン トは、開始タグと終了タグから成ります。そのタグの間に、文章の一部や 、あるいは文書全体が入ります。開始タグだけしかなく、コンテントを持 たない空エレメント (empty element)というのもあります。 エンティティ (entity) エンティティとは、ある名前によって(SGML 文書内で)参照できるようにさ れた一部のデータについて、そのデータを指示する名称です。この指示は 、文書中に文言として書き込むことで有効になります。指示対象となるデ ータは、単純な文字列や複数の編となる文章群でもよく、DTD の一連の文 言でも構いません。 SGML 上でのエンティティには、パラメータエンティ ティ (parameter entity)、一般エンティティ(generic entity)、外部エン ティティ (external entity)、内部エンティティ(internal entity)、デー タエンティティ (data entity)があります。 外部エンティティ (external entity) 外部エンティティは、外部文書をポイントするものです。外部エンティテ ィは、 SGML 文書の任意の位置にテキストを取り込みたい場合に使用しま す。使い方としては、サンプルプログラムや法律上の注意書き、文書の一 編などを取り込むことが考えられます。 一般エンティティ (generic entity) "&" で始まりセミコロンで終わる名前で参照されるエンティティは、一般 エンティティです。ほとんどの場合、このタイプのエンティティは、文書 上で使用され、DTD 上では使用されません。一般エンティティには、外部 エンティティと内部エンティティの二種類があります。どちらも、特殊文 字や、もしくは、繰り返し利用されるセンテンス、名前、文書の一編など を参照するものです。 内部エンティティ (internal entity) 内部エンティティは、テキストの一部を参照するためのもので、しばしば 、頻繁に利用されるテキストの一部のショートカットとして使われます。 パラメータエンティティ (parameter entity) DTD 上でよく使用されるエンティティ。このエンティティ名は、パーセン ト記号 (%) で始まり、セミコロンで終わります。 フロート (float) サイドバーや画像、表組、チャートなどのオブジェクトで、テキスト上に おいて決まった位置を持たない場合に、フロートと呼ばれます。印刷テキ ストの場合、チャートは、ページの一番上か一番下に置かれます。大きす ぎる際は、次のページに渡って置かれます。 処理命令 (processing instruction) 処理命令とは、文書成形ツールに渡されるコマンドのことです。処理命令 は、 "<?" で始まります。この文書上で、HTML ファイルへの変換の際に出 力ファイル名を指定するために使用されているコマンドの一例として、次 のようなものがあります。 <?dbhtml filename="file.html"> SGML 汎用マークアップ言語規約(Standard Generalized Markup Language)。こ れは、使用されるプラットフォームに依存しない、マークアップシステム を使った電子文書作成のためのルールを規定する国際標準 (ISO8879) でも あります。 タグ (tag) "<" と ">" マークに挟まれた SGML エレメントのこと。タグは、文書の意 味や構造をマークするために使用されます。タグの一例としては、タイト ルの開始をマークするための <title> があります。 XML eXtensible Markup Language. インターネットでの利用のために特別に作 成された SGML のサブ・プロダクト。 XSL XML Style Language. XSL と XML 文書との関係は、DSSSL と SGML 文書の 関係と同じです。実際、このスタイルは、文書としての XML そのものです 。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Index C catalogue creating example, Creating and modifying catalogues <making-catalogues.html> terminology, Explaining the terminology system <making-catalogues.html#CATALOGUE-EXPLAINING-TERMINOLOGY> modifying, Creating and modifying catalogues <making-catalogues.html> sample, Creating and modifying catalogues <making-catalogues.html> terminology, Explaining the terminology system <making-catalogues.html#CATALOGUE-EXPLAINING-TERMINOLOGY> catalogues creating, Creating and modifying catalogues <making-catalogues.html> configurations, Configuration needed <configurations.html> variables SGML_CATALOG_FILES, Configuration needed <configurations.html> conventions, Documents <conventions.html> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ D documents re-use, Re-using parts of documents <tools-hints.html#TOOLS-REUSE> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ E edition examples, Document samples <examples-documents.html> article, Article example <examples-documents.html# EXAMPLES-DOCUMENTS-ARTICLE> book, Book Example <examples-documents.html# EXAMPLES-DOCUMENTS-BOOK> index, Encoding Indexes <encoding-index.html> using DocBook, Writing with DocBook elements <writing-docbook.html> commands, Useful commands <writing-docbook.html# WRITING-DOCBOOK-COMMANDS> entities parameters exemple, Making notes on the text while it's being written <tools-hints.html#TOOLS-WRITING> usage, Making notes on the text while it's being written <tools-hints.html#TOOLS-WRITING> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ F figures inserting figure, Inserting Pictures <inserting-pictures.html> mediaobject, Alternative Methods <inserting-pictures.html# INSERTING-FIGURES-MEDIAOBJECT> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ G graphics inserting graphic, Inserting Pictures <inserting-pictures.html> mediaobject, Alternative Methods <inserting-pictures.html# INSERTING-FIGURES-MEDIAOBJECT> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ L listings inserting, Listings and program codes <listings.html> example, Listings and program codes <listings.html> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ N nedit, nedit <editing.html#NEDIT> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ T tables inserting, Tables <tables.html> example, Tables <tables.html> tools articles summary, Inserting a summary on the initial articles page <tools-hints.html#TOC-ARTICLES> compiling sources compile-sgml, Compiling the sources <tools-hints.html# TOOLS-COMPILE> compiling the sources, Compiling the sources <tools-hints.html# TOOLS-COMPILE> indexes automatic generation See also edition, index Notes [1] あなたの文書上で本書と同じ表記を作りたい場合は、この文書のソースを ご覧ください。ただ、現在ご覧いただいている表記は、あなたがどのフォ ーマットでこの文書をお読みになっているかに依存します。オンライン文 書の表記は、PostScript や PDF でのそれとは少し異なります。 [2] 有効コンテントは、DTD, DOCUMENT, ELEMENTS, ENTITIES, NONSGML です。 [3] 索引の詳細は、Norman Walsh のサイトにある索引関係のページをご覧くだ さい。 [4] 上記 2 つの quotation は、山形浩生さんの翻訳からお借りしました。 [5] (訳注: この文書(原文)の SGML ソースでは、最初にタグを無修正で置き、 その中での最初のをとしています。トップレベル・エレメント( LDP では 、比較的短い文書にはが、長めの文書にはが使われることが多いようです 。) に応じて適宜読み替えてください。)