ドキュメントの起草

PostgreSQL 8.0.0 文書
前のページ | 巻戻し | 付録 G. Documentation | 早送り | 次のページ

# G.4. ドキュメントの起草

SGMLとDocBookを起草する際にオープンソースとなっている数ある文章編集ツールの中からにどれを選んだらよいか悩むことはありません。 もっとも一般的なツールは相応の編集モードを備えたEmacs/XEmacsエディタです。 いくつかのシステムにおいては典型的なフルインストレーションを行った場合、使えるようになっています。

## G.4.1. Emacs/PSGML

PSGML は SGML ドキュメントを編集する上で最も一般的で最も強力なモードです。 正確に設定されていれば Emacs でタグを挿入したりマークアップの整合性をチェックできます。 HTML に対しても同じように使えます。 ダウンロード、インストール手順、そして詳しいドキュメントについては PSGML web サイト を参照してください。

PSGMLについてひとつ重要なことがあります。 ここで本書では、使用する環境としてSGML DTDのメインディレクトリは`/usr/local/lib/sgml`であると想定しています。 この章の例題のように`/usr/local/share/sgml`となっている場合には、`SGML_CATALOG_FILES`環境変数で設定するかもしくは（マニュアルでどのようにするかは説明しています）PSGMLのインストールをカスタマイズしなくてはなりません。

（パス名をシステムに合わせ）以下を `~/.emacs` ファイルに書いてください。

    ; ********** for SGML mode (psgml)

    (setq sgml-omittag t)
    (setq sgml-shorttag t)
    (setq sgml-minimize-attributes nil)
    (setq sgml-always-quote-attributes t)
    (setq sgml-indent-step 1)
    (setq sgml-indent-data t)
    (setq sgml-parent-document nil)
    (setq sgml-default-dtd-file "./reference.ced")
    (setq sgml-exposed-tags nil)
    (setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
    (setq sgml-ecat-files nil)

    (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )

そして同じファイルに（既に）ある`auto-mode-alist`にSGMLの項目を加えます。

    (setq
      auto-mode-alist
      '(("\\.sgml$" . sgml-mode)
       ))

現時点で全ての SGML ソースファイルはファイルの最後に次のようなかたまりが付いています。

    <!-- Keep this comment at the end of the file
    Local variables:
    mode: sgml
    sgml-omittag:t
    sgml-shorttag:t
    sgml-minimize-attributes:nil
    sgml-always-quote-attributes:t
    sgml-indent-step:1
    sgml-indent-data:t
    sgml-parent-document:nil
    sgml-default-dtd-file:"./reference.ced"
    sgml-exposed-tags:nil
    sgml-local-catalogs:("/usr/lib/sgml/catalog")
    sgml-local-ecat-files:nil
    End:
    -->

これにより`~/.emacs`ファイルを設定しない場合でも数多くの編集モードパラメータが設定されます。 とはいっても上記のインストレーションの指示に従う限りカタログパスが実際の場所と一致しなくなる不都合があります。 そうするとローカル変数を無効にしなければなりません。

    (setq inhibit-local-variables t)

PostgreSQL 配布物に中には構文解析済みDTD定義ファイル`reference.ced`があります。 PSGMLを使う場合、分冊に跨る独立したファイルを気軽に操作するにはファイルを編集しているとき適切な`DOCTYPE`宣言を挿入してください。 例えば、このソースを操作しているのであれば、付録の章ですので最初の行を以下のようにしてドキュメントを DocBook ドキュメントの "appendix" インスタンスとしてください。

    <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

これが意味するところは SGMLを読む全てのまたどんなものにでも正しく処理ができるようにすることで、`nsgmls -s docguide.sgml` コマンドでドキュメントを検証できます。 （とはいっても、全てのドキュメント一式を作成するときにこの行を削除しなければなりません。）

## G.4.2. そのほかの Emacs モード

GNU Emacs には異なるSGMLモードが含まれています。 これはPSGMLほど強力ではありませんが、より判り易く、かつ、軽快に動きます。 同時に構文を強調表示（フォントロック）させることができるのでとても便利です。

Norm Walsh がフォントロックと入力作業を軽減させるいくつかの機能をつけている主たるmode specifically for DocBook を提供しています。

前のページ | ホーム | 次のページ
ドキュメントのビルド | 上に戻る | スタイルガイド