# LDP Author Guide

v3.5 4 Dec, 2000
Mark
F.
Komarinski
VA Linux Systems

    markk@linuxdoc.org

Jorge
Godoy
&conectivasa;
Publishing Department

    godoy@conectiva.com

    godoy@metalab.unc.edu

David
C.
Merrill

    dcmerrill@mindspring.com

Yuji
Senda
translated into japanese 2000/12/24/

LDP 文書の作成者が快適に文書を作成するためのツールや手順、 およびヒントを、リストアップしました。

3.5
Dec 4, 2000
mfk
Changed mailing list pointers to new lists.
3.4
Dec 1, 2000
dcm
Added Crediting Translators and Converters
3.3
Nov 11, 2000
mfk
Added links to SGML GPL and FDL
3.1
Oct 10, 2000
mfk
Spelling changes, changed list of LDP policies to now accept DocBook XML. More information about how to use *jade with XML will follow.
3.0
Aug 24, 2000
gjf
Integrated David Merrill's style guide document. Further clean-up and additions.
2.0
Jul 13, 2000
mfk
Cleaned up using-docbook a bit. Moved some chapters
1.9
Jun 26, 2000
mfk
Integrated Jorge's using-docbook document.
1.5
Jun 14, 2000
mfk
Documented sgedit
1.4
Jun 12, 2000
mfk
Documented vim and sgedit. Spelling and other changes from ldp list. Also added LDP guidelines under style guide.

## この文書について

### この文書の目的と射程

この文書の作成は、1999年8月26日、Mark F. Komarinski が文書作成ツールを動かす のに 2 日もかかったことにイラついたのがきっかけでした。この文書がたとえ一人でも LDP 著者の役に立ったとしたら、わたしの務めは果たされます。

この文書の最新バージョンは、LDP のホームページ http://www.linuxdoc.org にあります。 オリジナルの DocBook SGML フォーマットや、その他 HTML 等のフォーマットも そこにあります。

実際にコードを書かずとも、Linux ムーブメントに貢献する方法はたくさんあります。 重要なもののひとつが、文書を書くことです。それによって個々人が世界中の無数の 人々と知識を共有することができます。この文書は、読者に LDP の活動内容を理解し てもらい、自分で HOWTO を書く際に必要なツールについて知ってもらうために作成され ています。

### LDP について

> LDP マニフェスト: http://www.linuxdoc.org/manifesto.html

> Linux Documentation Project は、GNU / Linux オペレーティングシステムについて の良質でフリーな文書を開発するために活動しています。LDP の最大の 目的は、Linux に関するすべての事柄の文書化を、共同で押し進めることです。 HOWTO や Guide の作成はこれにあたります。さらにわれわれは、簡単に利用と検索 ができる文書システムを構築したいと考えています。man ページや info 文書、HOWTO その他の統合はこれにあたります。

この後にはだいたい次のようなことが書いてあります。 「LDP ではボランティアが大勢集まって Linux OS 用の文書を作っている。一番目立つ のが HOWTO で、HOWTO は http://www.linuxdoc.org/ にある。」 この文書 (LDP Author Guide) の主な目的は、自分で HOWTO を書いて LDP に 寄稿する方法を説明することです。

### フィードバック

この文書へのコメントは、著者 (markk@linuxdoc.org) まで お願いします。

### 著作権と商標

Copyright 1999-2000 Mark F. Komarinski, David C. Merrill, Jorge Godoy

この文書は、以下の条件を守る限り、全部あるいは一部を無料で複製 できます。

- 全体もしくは部分を複製する場合、上記著作権表示とこの利用条件とが、 それらの複製上に完全な型で保持されること。

- 翻訳もしくは二次的著作物を作成した場合、配布に先立ち、著者に連絡して 承認を得ること。

- この文書の一部のみを配布する場合、その配布物には、文書全体の入手が可能 であることを明記し、文書全体の入手方法を表示すること。

- この文書の僅かな部分を、批評や説明の材料として他の著作物に転載する際 は、その引用が正当なものである場合に限り、この利用条件の記載を省略できる。 学術目的での利用については、この利用条件の適用例外となる場合があるので、 著者まで連絡して尋ねること。これらの制限は、著者としてのわれわれの権利を 守るためのものであって、教育者や学習者に制限を課すことを意図していない。 (この文書の作成フォーマットである SGML コードを除いた) この文書内のすべての ソースコードには、GNU General Public License が適用される。左記ライセンスは、 匿名 FTP 経由で、GNU アーカイブから入手可能である。

#### 日本語訳について

JF Project `JF@linux.or.jp`

翻訳 千旦裕司 `ysenda@pop01.odn.ne.jp`

校正 境真太郎 `s_sakai@mxn.mesh.ne.jp`

この日本語訳も、上記に従って配布してください。

### 謝辞

この文書の作成にあたり、コメントをいただいたすべての人々、 David Lawyer, Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig, その 他の ldp-discuss@lists.linuxdoc.org メーリングリストの メンバーに感謝します。 HOWTO Index と sgmltools の文書からは、いくつかのセクションを抜粋 させていただきました。CVS へのネットワークアクセスに関するセクションの一部 は、Serek (ser@serek.arch.pwr.wror.pl)が書いています。 DocBook に関するセクションは、Jorge Godoy (godoy@conectiva.com) が書きました。二人の協力に大変感謝しています。

&conventions;

## LDP と SGML の紹介

### LDP

Linux Documentation Project (LDP) がスタートしたのは、初心者が、特定の 対象についての情報をすばやく見つけることができるようにするためでした。LDP に は、システム管理やネットワーク、プログラミングについての一連の文書だけで なく、個別の分野を対象として、それを使ったことがある人が書いたもっと細かい 事柄に関する文書も無数にあります。印刷について知りたいなら、Printing-HOWTO , ( 日本語訳) がありますし、手持ちのイーサネットカードが Linux で使えるか 知りたいときは、Ethernet HOWTO , ( 日本語訳) を見ればだいたい分かります。はじめの頃、こうした文書は、 テキストか HTML で書かれていましたが、そのうち、文書をもっと上手に管理する必要 が生じてきました。たとえば、 ウェブページ上で閲覧したり、CD-ROM 上からや、さらにはハンド・ヘルドの PDA 上 でテキストファイルとして読めるようにしたいといったことです。最終的に、この問題 を解決したのが、SGML でした。

### 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 フォーマットにしたい場合は、<title> タグを 14 ポイントのボールド体にするようレンダリングプログラムに指示し、 HTML にする 場合には、それを <h1> に変換するように指示します。最後に、文書の内容 であるコンテント (Content) があり、これは SGML 処理系によってレンダリングされ る対象物であり、最終的にユーザが目にする部分です。たとえば、このパラグラフは、 もちろんコンテントですが、画像や表、番号付きリストなんかもコンテントです。 コンテントは、タグ (tag) で囲まれて、個別のエレメントとして区別されます。

### なぜ HTML でなく、SGML なのか？

SGML は、文書のフォーマットを変換するだけではありません。索引や目次、 文書の内外へのリンクも自動的に生成できます。Jade や OpenJade パッケージ (以後は、レンダラーと呼びます) を使えば、SGML を LaTeX や info、テキスト、 HTML、RTF にも変換できます。こうした基本フォーマットから、MS Word や PostScript, PDF などのフォーマットの文書を作ることもできますし、LyX のようなプログラムを 使えば、TeX フォーマットで文書を書いて、その後で SGML に変換し、SGML から 好きなフォーマットにレンダリングできます。つまり、SGML は、文書の見た目には 関心がなく、もっぱらエレメントの機能に注目しています。この点から生じる大きな 違いは、パラグラフの位置やフォントサイズ、フォントタイプなどで悩まなくても いいので、文書を書くスピードが上がるということです。

### SGML は XML じゃない

最近は XML を使いたいという要望が多いので、DocBook では XML がサポート されています。DocBook は、一定の階層構造を持ったマークアップタグの集まりです。 XML DocBook v4.1.2 は、現在 LDP で正式にサポートされています。SGML については 既に知っていて、XML を使いたい場合は、次のことに注意してください。 (以下は、「DocBook: The Definitive Guide」から拝借しました。)

- すべての XML マークアップは、大文字小文字を区別する。あらゆるエレメント 名、アトリビュート名、エンティティ名は、小文字でなければならない。 この点で、SGML とは異なる。

- すべてのアトリビュートは、シングルクオート (') か、ダブルクオート (") で 囲まれなければならない。

- 空エレメント (たとえば、xref) は、/: <xref/> で終了しなければ ならない。

- タグの短縮 (</>) はサポートしない。これは LDP においても、 SGML 内で使用することは推奨されていない。

### 初めて寄稿する方へ

もし、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 - Stein Gojen が書いたこのテンプレートは、LinuxDoc 形式で書くときのものです。

- http://www.linuxdoc.org/authors/template/big-howto-template.sgml - このテンプレートも Stein が作ったものですが、上記よりもずっと大きくて 複雑になっています。これは、DocBook の豊富な機能を活用したものです。

### メーリングリスト

メーリングリストがいくつかあるので、登録すれば 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 にお送りください。

## 文書作成ツール

このセクションでは、LDP 文書を作成するのに必要なツールや便利なツール をいくつか紹介します。ここでは、インストール方法とツールの概要を説明して、 詳しい使い方は後で解説することにします。もしあなたがここにあるもの以外のツール を使って LDP 文書をお書きの場合、このセクションで宣伝しますので、是非その ツールをお知らせください。

### DSSSL

通常の Walsh バージョンの DSSSL が必要で、そのオプションとして LDP の DSSSL があります。

#### Norman Walsh 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 を 使っています。

#### LDP DSSSL

http://www.linuxdoc.org/authors/tools/ldp.dsl

LDP DSSSL は、(上記の) Norman Walsh バージョンの DSSSL があることを前提 にして、目次などを生成するために若干の変更を加えたものです。

### 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/3.1/docbk31.zip。

XML DTD を使う場合は、 http://www.oasis-open.org/xml/4.1.2/ です。

DocBook DTD は、DocBook SGML 文書のタグと文書構造とを定義しています。 それゆえ、新規タグを加えたりして DTD を修正すると、DocBook ではなくなって しまいます。

### Jade

Jade と OpenJade は、ふたつとも、DTD と DSSSL に基づいてコードの レンダリングや妥当性検査の大半を処理するプログラムです。どちらかが必要なので、 DTD と DSSSL のインストールが終わってから、インストールしてください。

#### Jade

ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz

Jade は、SGML のフロント・エンドプロセッサです。DocBook と DSSSL を 使って、妥当性検査や、目的のフォーマットへの SGML ソースのレンダリングを行い ます。

##### 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 を付けてください。

##### 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
    bash$
    jade -t sgml -i html -d style $_jade_path/pubtext/xml.dcl foo.xml

XML, DSSSL, DocBook それぞれのカタログファイルが必要です。 $_toolroot は、先ほどの例と同じです。

スタイルファイルは、好みのスタイルファイルに置き換えてください。jade が動くには、xml.dcl へのポインタが必要で、これは、XML 文書名の直前に指定され る必要があります。

XML 文書を処理中に次のような警告が表示されるかもしれません。これは出力 には影響しませんが、原因は調査中です。

    <xml_dtd_pth>/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
    <xml_dtd_pth>/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name

既存の SGML DocBook 文書を XML 文書に変換したい場合は、(文書の冒頭の 行の)文書型宣言(declaration)のところで次のように書いてください。

    <?xml version='1.0' encoding='ISO-8859-1'?>
    <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'>

LDP の文書規則に従っている場合、これ以外に文書に変更を加える必要は ありません。

#### OpenJade

http://openjade.sourceforge.net/

DSSSL コミュニティーが作成した、Jade のエクステンションです。 アプリケーションのなかには jade を必要とするものもありますが、どちらも サポートできるようにアップデートされつつあります。

### Jade wrappers

オプションで以下のツールがあるので、Jade, DSSSL, DTD のインストール 後に、インストールできます。

#### sgmltools-lite

http://sgmltools-lite.sourceforge.net/

これは、一年以上前に正式に解散した sgmltools プロジェクトを引き継いだ もので、それ以来、Cees de Groot が若干異なるプロジェクトを立ち上げて、 jade SGML 処理系へのラッパとしてツールを作っています。構文の汚さはかなり解消 されました。作者は、古い sgmltools パッケージをインストールして、そのあとに sgml-tools-lite を入れることで、この文書を非常に簡単にフォーマットできた そうです。 構文を表示する sgmltools 用の man ページもあります。

#### Cygnus DocBook Tools

Red Hat 専用ですが - http://www.redhat.com/

Red Hat では、6.2 リリースから、DocBook をサポートするツールその他を 含めた 3 つのパッケージを配布しています。これらのツールは、簡単にインストールで きるので、ツールと格闘しなくても執筆に専念できます。TeTeX, Jade, JadeTeX をあら かじめインストールしておくことが必要です。パッケージは 3 つとも、インストール CD に入っています。

##### 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.

RPM ファイルをマシンにダウンロードするか、どこかから取ってくるかして、 いつも通りインストールしてください。(root になって、`rpm -Uhv ファイル名`。) RPM がインストールされたら、次のコマンドを 使って DocBook をレンダリングできます。

    bash$ db2html filename

DocBook を HTML にレンダリングします。( .sgml 拡張子を除いた)ファイル名 と同じ名前でサブディレクトリが作成され、そこに HTML ファイルが置かれます。

    bash$ db2pdf filename

DocBook を PDF ファイルにレンダリングします。JadeTeX を使った db2pdf と pd2ps で、現在問題が生じているのに注意してください。これは、Red Hat にバグと して 登録されています。

### 編集ツール

以下では、HOWTO の作成や編集、妥当性検査に使えるツールを紹介します。

#### Emacs (PSGML)

オプションです。 - http://www.lysator.liu.se/~lenst/about_psgml/

Emacs には、SGML や XML 文書の編集のために作られたメジャーモードとして、 SGML 文書作成用の psgml と呼ばれるモードがあります。これによる 構文強調 (syntax highlighting) や きれいな表示 (pretty printing) 機能を使うと、SGML タグが強調されたり、手でタイプしなくてもタグを入れることが できたり、書きながら妥当性検査ができたりします。

Emacs ユーザにはうれしい機能ですし、他のどんな SGML 編集ツールよりも充実 した機能を備えていると、多くのユーザは思っています。DocBook や LinuxDoc、その他 の DTD でも使えます。

##### PSGML を使って SGML を書く方法

###### はじめに

最近のディストリビューションをインストールしているなら、Emacs で 使えるように既に PSGML がインストールされていると思います。確認のために、 Emacs を起動して、PSGML 文書を捜してみましょう。(Ch impsgml)

ここからは、比較的新しいバージョンの Emacs に PSGML がインストール されて使えるように なっているのを前提にします。話が早く進みすぎると思う方は、Bob Ducharme の SGML CD book のフリーで公開されている次の章をご覧ください。 http://www.snee.com/bob/sgmlfree/

###### .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 を再起動してください。

###### SGML のちょっとしたテスト

ちょっとしたテストをしてみましょう。例として、新規ファイル `/tmp/test.sgml` を開いて、次のように 書き込みます。

    !DOCTYPE test [
    <!ELEMENT test - - (#PCDATA)>
    ]

そして、C cC p と入力します。 Emacs が DTD を読み込もうとしているなら、ミニバッファに Parsing prolog....done と表示されます。そしたら、 C-c C-e RETURN と打って、`test` と入力してみましょう。正しく動いている場合は、 Emacs に次のように表示されます。

    !DOCTYPE test [
    <!ELEMENT test - - (#PCDATA)>
    ]
    testtest

###### DocBook 形式で新規に HOWTO を書く方法

HOWTO 用に新規ファイルを開いて、次のように入力します。

    !DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN"

CcC p と打って、画面に注目。すべて予定通りなら、数秒間 Emacs が読み込み処理をして、 ミニバッファに Parsing prolog....done と表示されるのが 分かります。

ここで、C cCe RETURN と打ち、`article` エレメントを書き込んで、HOWTO の執筆に取りかかりましょう。

###### PSGML を使った Emacs のクイックリファレンス

FreeBSD 文書にある Nik Clayton の入門書をご覧ください。 http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html

#### VIM

http://www.vim.org

Emacs についての話をしましたので、当然、次は vi のお話です。VIM (Vi IMproved) エディタは、vi の標準機能を持ちながら、タグの位置をスクリーン上で色分けして 教えてくれます SGML モードも持っています。

##### はじめに

vim プログラムは実際に複数の部分から出来ています。まず、素の vim プログラム があって、これは、vi プログラムやそのコマンドと互換性を持っています。Red Hat ユーザなら、vim-common と vim-minimal パッケージが必要です。次に、拡張機能を 持った `vim` で、これは標準の vi に対して、構文強調などの 機能があります。Red Hat ユーザなら、vim-enhanced が必要です。最後の見逃せない 機能 として、 X インターフェイスがあり、これは、グラフィカルインターフェイスや メニュー、マウス操作などを提供しています。vim や vi からこれを区別する場合、 グラフィカル操作でのコマンドは、`gvim` と呼ばれています。

##### 新規文書のロードもしくは作成

`vim` と `gvim` モードでは、 `.sgml` ファイルは自動的に認識されて、sgml モード に入ります。あらかじめ分かっている一連の DocBook タグが `vim` に読み込まれると、認識されたタグは茶色で強調されます。認識されない 場合、ライトブルーで表示されます。認識されたタグの属性(attribute)もライトブルー になり、属性の値(value)は、ピンクになります。ここからは、通常の `vi` コマンドを使って、カーソル移動と編集ができます。

#### WordPerfect 9 (Corel Office 2000)

http://www.corel.com/

MS Windows プラットフォームの WordPerfect 9 は、SGML と DocBook 3.0 を サポートしています。Linux 用 WordPerfect 9 に SGML 機能はありません。

これは、SGML をサポートしている商用アプリケーションとしては一番安価な ものです。

#### sgedit

http://www.tksgml.de/

sgedit は、SGML ファイルをビジュアルに編集できるプログラムです。 このプログラムの長所は、あらかじめ Emacs や VI の使い方を知らなくても よい点と、クロスプラットフォームなので、Windows でも Linux でも動くという 点です。商用アプリケーションですが、値段は設定されていません。個人や教育 機関での利用については、フリーライセンス版が出るようです。

ビジュアル編集の他にも、sgedit は、ロード時や必要な時に、 Document Validate コマンド を使って、文書の妥当性検査ができます。

##### sgedit のスクリーンショット

sgedit プログラムのスクリーンショット。左側には、階層を持った SGML 文書のツリー構造が表示され、右側には、文書自体が表示されている。 タグは、グレーの背景で表示される。

#### nedit

http://nedit.org

率直に言って、nedit は、プログラマ向けで、新規ユーザや特にプログラマで ないユーザにとってはちょっときついかもしれません。それを除けば、タグの色づけ が自由にできたりして、かなりパワフルです。sgedit と異なり、nedit では、タグを 自動で入れたり、文書の妥当性検査を自動的に行ったりはしません。そのかわり、 ウィンドウ の内容に対してシェルコマンドが使えるようになっています。(ファイルを保存した後 で、チェックします。) わたしは、SGML の妥当性検査のために `nsgmls` を設定し、スペルチェックのために `aspell` を 設定しましたが、だいたい数分で終わりました。

##### nedit のスクリーンショット

nedit では、画面の左端に行番号が表示されるので、`nsgmls` でエラーが出た場合に便利です。

##### nedit の使い方

新規文書を作るときは、LDP DocBook テンプレートをダウンロードして使う ことが推奨されています。そのファイルがあれば、nedit を起動してすぐ編集に 取りかかれます。ファイルに .sgml 拡張子を付けて保存しておけば、nedit は、 SGML/HTML タグ機能を有効にしてファイルをロードします。この機能は、 Preferences Language ModeSGML HTML コマンドを使って明示的に有効にすることもできます。

##### nedit の Tips とコツ

nedit では、ウィンドウの内容を外部プログラムに出力することができるので、 この機能を使って、普段使っている関数を実行できます。ここで取り上げる例題では、 `nsgmls` を使い、SGML の妥当性検査を行う方法を紹介します。

まず、 Preferences Default SettingsCustomize MenusShell Menu... を選択します。すると、Shell メニュー に登録されている全シェルコマンドを表示するダイアログボックスが出てくるので、 その Menu Entry の欄に "SGML validate" と書き込みます。このエントリーは、 スクリーン上で見ることができます。次に、Accelerator の欄で、 AltS を押して、 SGML の妥当性検査が自動で行われるようにします。Command Input の部分では、 window を選択して、Command Output の部分では、dialog を選択します。 Command to Execute では、nsgmls -sv と入力しましょう。これがうまく動くため には、 `PATH` に `nsgmls` へのパスが設定されていないと いけないので注意してください。

###### nedit へのシェルコマンドの追加

シェルコマンドを追加する時のダイアログボックス。

OK をクリックして、これで元のメインスクリーン に戻ります。SGML ファイルをロードして、Shell SGML Validate を選択するか、 AltS を押すと、`nsgmls` が起動されて、ウィンドウの内容をチェックします。-sv を使う 理由は、-v を指定すると、`nsgmls` はプログラムのバージョン を出力するので、その出力を見れば `nsgmls` が実行されたこと が必ず分かるようになるからです。バージョン番号しか出力されない場合は、 文書にエラーがなかったことになります。エラーがあれば、そのエラーが分かる ように、 別のウィンドウが開いて表示されます。行番号機能を有効にしてあるなら (これには、 Preferences Show Line Numbers を使います。)、`nsgmls` はエラーを 行番号で表示するので、エラーを見つけるのがずっと楽になります。

###### エラーがない場合の nsgml の出力

nsgmls がエラーを検出しなかった場合は、バージョン番号だけを報告します。

&cvs;

### その他のツールとリファレンス

このセクションでは、今のところ分類しきれていないリファレンス本や ユーティリティを紹介します。

#### DocBook: The Definitive Guide

http://www.docbook.org/

これは、1999年10月に O'Reilly から出版された、DocBook についての すばらしいリファレンス本です。それほど実用的ではないように思われるし、 XML に重点が置かれてはいますが、バージョン 3.1 の DocBook タグはすべて 分かりやすく一覧表示されています。書店で買うこともできるし、本のすべての内容を 上記 URL からオンラインで (HTML と SGML フォーマットにおいて) 読むことも できます。

#### SGML テンプレート

オプションです。- http://www.linuxdoc.org/authors/index.html#resources (日本語訳)

SGML テンプレートと、変換した後の HTML 出力についてのリンクがある ので、文書の体裁を理解する手助けになります。タグの多くは、作成する文書の内容に 合わせて置き換えることが必要です。

#### Aspell

オプションです。 - http://aspell.sourceforge.net/

スペルチェック用のこのアプリケーションは、SGML タグを避けて、 タグに挟まれた内容だけをチェックすることができます。ispell のような デフォルトのスペルチェッカーだと、タグ自体もチェックしようとする ので、新規タグがあると、いつもエラーになってしまいます。

#### ispell

オプションです。 - http://www.cs.hmc.edu/~geoff/ispell.html

この ispell プログラムは、Red Hat (や、おそらく他のディストリビューション )に同梱されているもので、マークアップタグを無視することができます。

&using-docbook;

&style-guide;

## スタイル関連事項の補足

このセクションでは、文書の作成にあたり、スタイルに関連するトピックの いくつかを補足しています。

### 日付の書き方

`pubdate` タグを文書で使う際には、 次の書式で日付を記入してください。

    v1.0, 21 April 2000

### 画像フォーマット

文書に画像を付けて LDP に送る際は、まず `.eps` の セットと、次に `.gif` もしくは `.jpg` のどちらか一方のセットとを送ってください。`.gif` の特許の問題は意識しておくべきですが、`.gif` のほうが、`.jpg` よりすこしだけ良い画像が作れるようです。

### DocBook のバージョン

LDP では、以下のフォーマットでの文書をサポートし、受け入れています。

- SGML DocBook versions 4.x と 3.1

- SGML LinuxDoc

- XML DocBook version 4.1.2

DocBook のヘッダを書くときは、次のように書いてください。

    !doctype article public "-//OASIS//DTD DocBook V4.1//EN"

### 利用禁止のタグ

非推奨タグとして DocBook: The Definitive Guide のリストに挙がっているタグは、LDP 文書内でも使用しないようにしてください。 新しいタグの使い方については、テクニックとコツのセクションで紹介しています。

### タグの最小化

タグの最小化(tag minimization)とは、(たとえば、`para` のような)完全な終了タグのかわりに、`` を使うことです。これを使うと、その文書に将来関わる作者や LDP メンバーにとっては文書構造が分かりにくくなりますし、XML DocBook では 認められていない使い方なので、そうした習慣は止めるようにしてください。

### 文書内での表記法

様々な文書間で守るべき表記法に、次のようなものがあります。

コマンドの使い方を示そうとする場合、ユーザコマンドラインとしての 表示になるよう、コマンド行を書いてください。プロンプトには、まず、シェルの 種類 (bash, tcsh, zsh, など) が表示され、次に、(root でない)通常のユーザ として実行される場合には $ を、root ユーザとして実行される場合は # を表示 してください。

それゆえ、コマンドは、次のように表示されます。

    bash$ command "run as a normal user"
    bash# command "run as a root user"
    tcsh# setenv DISPLAY :0.0

## DocBook のテクニックとコツ

このセクションでは、文書を書く際の DocBook のちょっとひねった使い方を いくつか紹介します。

### 画像の挿入

HOWTO に画像を入れようと思っている場合、LinuxDoc では画像のサポートは ありませんでしたが、DocBook なら可能です。次に、HOWTO に画像を入れる方法の 一例を紹介します。

    figure
       titleLyX screen shottitle
       mediaobject
          imageobject
             imagedata fileref="lyx_screenshot.eps" format="eps"
          imageobject
          imageobject
             imagedata fileref="lyx_screenshot.jpg" format="jpg"
          imageobject
          textobject
             phraseScreen shot of the LyX document processing programphrase
          textobject
       mediaobject
    figure

上記は、`graphic` を使うよりも、 ふたつの理由ですぐれています。第一に、DocBook 5.0 では、`mediaobject` に移行するため、`graphic` は削除されます。それゆえ、今から 正しい方法で使い始めるほうがよいと思われます。第二に、`mediaobject` なら、出力形式に従って異なる複数のフォーマットの 画像を扱うことができます。上記の例で言うと、最初の `imageobject` は、DVI, PS, PDF といった TeX から生成されるフォーマット に利用される EPS (Encapsulated PostScript) 画像で、ふたつ目の `imageobject` は、ディスプレイ画面用、大部分は HTML 用の出力で利用される JPEG 画像です。`textobject` の部分は、出力が画像をサポートしていない場合 に表示されるものです(TXT)。`alt` タグの ようなものとお考えください。

### HTML 出力ファイルのファイル名を指定する

個別の HTML ファイルを出力する場合、SGML 処理系は、デフォルトで、 恣意的なファイル名しか付けません。これでは、読者がページをブックマーク しておいてもすぐに変更されてしまいますし、あなたもどれがどのファイルなの か分からなくなって、紛らわしいでしょう。理由はどうであれ、ここでは、 個別の出力ファイルに好きな名前を付ける方法を紹介します。

`article` タグを最初に置く場合( これはひとつだけのはずです。)、そこに id パラメータを書き込んで、その値を index とします。そうすると、タグは次のようになります。

    article id="index"

最初に `chapter` タグを置く場合、 このタグ内の内容は通常イントロダクションとなるでしょうし、これは文書内の最初 に置きたいと思うでしょうから、修正しないでください (訳注: この文書(原文)の SGML ソースでは、最初に `book` タグを無修正で置き、その中での最初の `chapter` を `chapter id="aboutthisguide"` としています。トップレベル・エレメント( LDP では、比較的短い文書 には `article` が、長めの文書には `book` が使われることが多いようです。) に応じて適宜読み替えてください。) 。それ以外の 個々の `section` タグについては、 id パラメータとその名前を書き込んでください。名前には、アルファベットと 数字だけを使うようにし、内容が理解できる程度の短い名前にしてください。

    chapter id="tips"

### ldp.dsl を使う

LDP では、独自の DSSSL を使っていて、それによって、背景部分や HOWTO の 最初のページにある目次の自動生成機能を付け加えています。その最新バージョンは、 http://www.linuxdoc.org/authors/tools/ldp.dsl にあります。

ファイルが手に入ったら、DocBook DSSSL ファイルの置き場所に基づいて 先頭の数行を修正する必要があるかもしれません。わたしの例では、Cygnus ツール セットを使っています。

`ldp.dsl` ファイルを `/usr/lib/sgml/stylesheets` に置いて、それを好きなエディタで開いてください。次のように なっているのがわかると思います。

    <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
    <!ENTITY % html "IGNORE">
    <![%html;[
    <!ENTITY % print "IGNORE">
    <!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
    ]]>
    <!ENTITY % print "INCLUDE">
    <![%print;[
    <!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
    ]]>
    ]>

最初の "docbook.dsl" が、`/usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl` を読むようにしてください。

二つ目の "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

## 文書の公開について

### 文書公開のまえに

将来の無数の読者に文書を公開するまえに、やるべきことがいくつかあります。

第一に、必ずスペルチェックをすることです。SGML を書くのに使われる ユーティリティには、たいていスペルチェック用のプラグインが付いています。 付いていない場合でも、aspell があります。

第二に、他の人に査読してもらい、コメントをもらったり、事実に間違いが ないか確認してもらってください。LDP が出す文書は、無数の Linux ユーザが 読むことになるので、事実の誤りは極力減らす必要があります。執筆対象に関して 大勢の人が参加するメーリングリストに登録しているなら、そこで他の人に 尋ねて、助けてもらいましょう。

第三に、作成した文書を公開するウェブサイトを作ってください。これは必須 ではありませんが、その文書がどこで作成されたのかを知る手がかりになります。

#### SGML コードの妥当性検査

jade や実際の nsgmls コマンドを使って、作成した .sgml コードが DTD に照らして妥当かどうか検査し、エラーのないことを確かめることができます。

    bash$ nsgmls -s HOWTO-HOWTO.sgml

これで問題がなければ、何事もなくコマンドプロンプトが返ってきます。

### 著作権とライセンスの問題

LDP で LDP 文書として認められるには、 http://www.linuxdoc.org/manifesto.html にある LDP マニフェスト の " ライセンス上の必要事項 " に従ったライセンスが付いていなければなりません。 文書の作成者として、著作権を保持することができますし、ライセンスに他の 制限 (たとえば、翻訳や二次文書を作成したときは、著者の承認を得なければなら ない、とか) を付け加えることもできます。

われわれとしては、 GNU Free Documentation License (GFDL) か、オプション A と B なしの Open Publication License (OPL) を使うことをお薦めします。 DocBook 用にマークアップされた GNU GPL と GNU FDL が GNOME Documentation Project にあるので、それを使うこともできます。 その場合、ライセンス全文を文書内に入れるだけです。ただ、全文は長いので、 ライセンスへのリンクを書き込んでおくだけでも結構です。

著作権の「鋳型」を使おうとする場合は、 著作権とライセンス といったセクションを立てて、そこに文面をそのままコピーしてください。 御自分の名前で著作権の表示も入れてください。(ライセンスのために 著作権が奪われるわけではありません。) 既存の文書の新しい管理者になった 場合は、その文書を管理していた以前の著者名と日付についての著作権も 書かなければなりません。

この LDP Author Guide のライセンスでは、二次文書や翻訳を作成する場合に 著者への報告を求めていることに、お気付きかもしれません。また、わたしは、(この 文書を書いた SGML のソースコードを除く) すべてのソースコードを明示的に GPL の 基に置きました。作成した HOWTO にソースコードが含まれていて、それを他の人 にも使ってもらおうと思うときは、同じようにするといいと思います。

### 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 ツリー内での相対パスを書いておいてください。

### 作成した文書の管理

作成した HOWTO が公開されたからといって、仕事が全部終わったわけでは ありません。HOWTO の情報を更新し、読者のアイデアや提案に応えて HOWTO を確実に 改善していくためには、定期的なメインテナンスが不可欠です。HOWTO には、 活発に成長する生きた知識が詰まっているので、公開したらそれで終わりという 固定的なものではありません。

HOWTO に自分のメールアドレスを書いて、読者からのフィードバックを 丁寧にお願いしたでしょうか？ 一旦正式に公開されると、提案のメールをいくつも 受け取るようになります。そのなかにはとても貴重なものがありますが、それ以外は 個人的な問題の解決を求めるものだったりします。時間がなければ、個人的な問題に 応える必要は全くありません。LDP で HOWTO を書いたからといって、ネット上の あらゆる人にフリーサポートを生涯続ける義務を負うわけではないからです。ただ、 もしできるなら、そうした人に別の情報源を教えてあげると、親切ではあります。 また、受け取った質問のパターンが見えてくれば、HOWTO に追加すべきトピックが 分かるかもしれません。

## LDP についての FAQ

LDP のお手伝いをしたいのですが、どうしたらいいでしょう？

一番簡単な方法は、何か主題を捜して、それを文書化することです。 もしくは、管理者がいない HOWTO をチェックして、自分がよく知っている 分野で文書化し続けられるものがないか確認することです。

LDP 文書をまとめて、書籍として出版したいのですが、LDP 文書のライセンスは どういったものになりますか？

http://www.linuxdoc.org/COPYRIGHT.html" をご覧ください。 ただ、これは個々の著者に対するガイドラインでしかないことに注意してください。 とはいえ、この URL に挙がっているものより厳しい条件を付けることはできません。

LDP 文書の中に誤りを見つけたのですが、修正できますか？

文書の著者か、LDP コーディネータ discuss@linuxdoc.org 宛に連絡して、問題の部分と、どういう修正が必要が必要かを報告して ください。

SGML が分かりません。/ ツールが動きません。/ SGML が嫌いです。

問題ありません。最初の草稿は、お好きなフォーマットで書いていただいて 結構ですので、それを LDP までお送りください。LDP ボランティアが査読して、 その後で DocBook に変換します。それさえ済めば、HOWTO の管理自体は難しく ないでしょう。疑問があれば、いつでも LDP ボランティアに連絡するか、 LDP DocBook メーリングリスト docbook@linuxdoc.org まで連絡してください。

&glossary;

&doc-index;