%includes; ]> &header;

ドキュメンテーションプロジェクトは 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' としてマークアップされ, ファイル名の表示については記述されません.

このマークアップのより表現に富む形式について多くの利点を挙げてみましょう.

もしそれらについてよく知っているなら, これは Microsoft Word の スタイルシートに少々似ているものではありますが, しかし非常により強力なものとなっています.

もちろん, この能力を生かすにはそれなりの労力が必要です.

いまのところは, このプロジェクトはまだ LinuxDoc をハンドブックや FAQ に使っています. それは変更中で, 特にドキュメントを DocBook へ 作り変えるプロジェクトを進めているところです.

もしあなたが LinuxDoc/DocBook について何も知らないとしても, 貢献できることはありますか?

はい. もちろんです. どんなドキュメントであってもなにもないよりは 良いものです. もしあなたが貢献すべきドキュメントを持っていて, それが LinuxDoc もしくは DocBook でマークアップされていないとしても, 何の問題もありません.

普通にそのドキュメントを 提出してください. プロジェクトのほかの誰かがあなたの提出されたドキュメントを見つけると, それにマークアップをして, そしてコミットしてくれます. 少々運がいいと そのときにあなたにマークアップされたテキストが戻ってきます. それは 役に立ちます. というのはあなたはドキュメントがマークアップされる "前と後の" 状態を持っているということになり, うまくいけばその過程から マークアップについていくらかでも学ぶことができるからです.

明らかに, あなたの提出したドキュメントは マークアップされる必要があるために, このことでコミットされるまでの過程は 長引いてしまうことになり, 何日も掛かるかもしれません. しかしそれはちゃんとコミットされることでしょう.

SGML や DocBook に関する他の情報は ?

http://www.sil.org/sgml/sgml.html

SGML/XML の web ページ. SGML について数え切れないほどの情報への ポインタがあります.

http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html

「やさしい SGML の紹介」です. 初心者の見方から SGML について もっと学びたいという方にお勧めです.

http://www.ora.com/davenport/

Davenport グループが DocBook DTD の設計と保守をしています. これらのページはすでに SGML について慣れているユーザや, DocBook を 学んでみたい方を目的としています.

http://fallout.campusview.indiana.edu/~jfieber/docbook/

John Fieber 氏のページで DocBook に関する資料やドキュメントの サンプルへのリンクがあります. FreeBSD のための マークアップのガイドの初歩についても含まれています.

http://www.nothing-going-on.demon.co.uk/FreeBSD/

Nik Clayton 氏のページで DocBook で書かれたドキュメントや それを HTML へ変換したものへのリンクがあります. 元の DocBook の ファイルもあり, どのように DocBook のさまざまな要素が使えるのかという 筋の通った例も書かれています.

DocBook のドキュメントが PDF フォーマットにて http://www.freebsd.org/~wosch/docbook/ から入手できます.

FreeBSD ドキュメンテーションプロジェクトのページ &footer