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