FreeBSD ドキュメンテーションプロジェクト: SGML
ドキュメンテーションプロジェクトは SGML をドキュメントを表現するための標準の手段として使用しています。
SGML とは Standard Generalized Markup Language のことです。
簡単に言えば (読者の中の SGML の純正主義者の方々にはお気にさわったらごめんなさい)、 SGML は他の言語を記述するための言語です。
あなたはおそらくすでに SGML を使ったことがあるでしょうが、 それには覚えがないでしょう。HTML (それは web ページを書くための言語ですが) には、正式の書き方があります。 その書き方が SGML で書かれているのです。あなたが HTML を書いているときには (それ自体は) SGML で書いているとは言いませんが、 SGML を使って定義された言語を使っているということになります。
SGML を使って定義されたマークアップ言語は非常にたくさんあります。 HTML もその一つです。ほかには "DocBook" というものがあります。 これは技術的なドキュメントを書くためことに特化して設計された言語なので、 後から書式を整えるように技術的なドキュメントを記述するためのタグ (<tag content> のもの) がたくさんあります。 FreeBSD ドキュメンテーションプロジェクトはこれを採用し、 より明確にするためにいくつかの新しい要素を定義しました。
例えば、これは HTML で短い段落を書いてみたものです。 (内容については気にせずに、タグだけを見て下さい)
<p>システムのパスワードは <tt>/etc/passwd</tt> に記録されます。 このファイルを編集したいときには <b><tt>vipw</tt></b> を使うべきです。 しかし、単に新しいユーザを加えたいだけのときには <b><tt>adduser</tt></b> も使うことができます。</p>
同じ段落を DocBook を使ってみるとこのようになります。
<para>システムのパスワードは <filename>/etc/passwd</filename>
に記録されます。このファイルを編集したいときには
<command>vipw</command> を使うべきです。しかし、
単に新しいユーザを加えたいだけのときには <command>adduser</command>
も使うことができます。</para>
見てわかるように、DocBook は HTML よりもずっと '表現が豊富' です。 HTML の例ではファイル名は 'typewriter' フォントで表示されるように マークアップされていますが、DocBook の例ではファイル名は 'filename' としてマークアップされ、ファイル名の表示については記述されません。
このマークアップのより表現に富む形式について多くの利点を挙げてみましょう。
曖昧だったり無節操だったりすることがありません。
「うーん、ファイル名を表示するのに、'tt'、'b'、'em' のどれを 使うべきなんだろう?」と考える無駄な時間は取りません。
その代わりに、タグを適材適所に使うだけのことです。
DocBook から他のフォーマット (HTML, PostScript® など) への変換過程では、すべての <filename> 要素は同じように表されます。
あなたはドキュメントの表示について考えることを止めて、 その代わりに内容に集中できるのです。
ドキュメントはどのそれぞれの出力形式には拘束されていないので、 同じドキュメントからさまざまな異なった形式のものを作ることができます。 — プレインテキスト、HTML, PostScript, RTF, PDF などです。
ドキュメントを作るということはとても '知的な' ことで、 そのためにより知的なことが行われています。 例えば、ドキュメントに含まれるそれぞれのコマンドのリストから自動的に索引を作るということもできます。
これは Microsoft® Word のスタイルシートに少々似ているものではありますが、 より強力なものとなっています。
もちろん、この能力を生かすにはそれなりの労力が必要です。
使えるタグが非常に多いために、 そのすべてを覚えたりそれらを効果的に使えるようになるためには、 より多くの時間が必要です。
SGML と DocBook を学ぶための最も良い方法は、 数多くの例のドキュメントのソースを読んで、 他の著者が同じ情報をどう書いているかを見ることです。
この方法に転向するのは簡単ではありません。
DocBook について何も知らないとしても、貢献できることがあるのでしょうか?
はい。もちろんです。 どんなドキュメントであっても何もないよりは良いものです。 もしあなたが貢献すべきドキュメントを持っていて、 それが DocBook でマークアップされていないとしても、 何の問題もありません。
普通にそのドキュメントを 提出してください。 プロジェクトのほかの誰かがあなたの提出されたドキュメントを見つけると、 それにマークアップをして、そしてコミットしてくれます。 少々運がいいとそのときにあなたにマークアップされたテキストが戻ってきます。 それは役に立ちます。というのはあなたはドキュメントがマークアップされる "前と後の" 状態を持っているということになり、 うまくいけばその過程からマークアップについていくらかでも学ぶことができるからです。
もちろん、 あなたの提出したドキュメントはマークアップしなければならないので、 数時間では済まず、数日に延びてしまうかもしれませんが、 いずれはコミットされることでしょう。
SGML や DocBook に関する他の情報は?
まず、ドキュメンテーションプロジェクト入門を読んでください。これは FreeBSD ドキュメンテーションプロジェクトの作業をおこなうために知っておくべきすべてのことに関する包括的な説明をねらったものです。 これは長編のドキュメントで、 たくさんの小さなページに分割されています。また ひとつの大きなページにまとめられているものもあります。
- http://www.oasis-open.org/cover/sgml-xml.html
SGML/XML の web ページ。SGML について数え切れないほどの情報へのリンクがあります。
- http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html
「やさしい SGML の紹介」です。初心者の見方から SGML についてもっと学びたいという方にお勧めです。
- http://www.oasis-open.org/docbook/
OASIS が DocBook DTD の保守をしています。 これらのページはすでに SGML について慣れているユーザや、 DocBook を学んでみたい方を目的としています。