diff --git a/ja/docproj/sgml.sgml b/ja/docproj/sgml.sgml index 6bd55206a4..1affe0711a 100644 --- a/ja/docproj/sgml.sgml +++ b/ja/docproj/sgml.sgml @@ -1,174 +1,168 @@ - - + + ]> - + &header;

ドキュメンテーションプロジェクトは SGML - をドキュメントを表現するための標準の手段としようとしています。

+ をドキュメントを表現するための標準の手段として使用しています。

-

SGML とは Standard Generalised Markup - Language のことです。

+

SGML とは Standard Generalized Markup + Language のことです。

-

簡単に言えば (読者の中の SGML の純正主義者の方々にはお気にさわったら - ごめんなさい) SGML は他の言語を記述するための言語です。

+

簡単に言えば (読者の中の SGML + の純正主義者の方々にはお気にさわったらごめんなさい)、 + SGML は他の言語を記述するための言語です。

あなたはおそらくすでに SGML を使ったことがあるでしょうが、 - それには覚えがないでしょう。HTMLには、それは web - ページを書くための言語ですが、正式の書き方があります。 - その書き方が SGML で書かれているのです。あなたが HTML - を書いているときには SGML で書いているとは言いませんが - (per se)、SGML を使って定義された言語を使っている - ということになります。

+ それには覚えがないでしょう。HTML (それは web + ページを書くための言語ですが) には、正式の書き方があります。 + その書き方が SGML で書かれているのです。あなたが HTML + を書いているときには (それ自体は) SGML で書いているとは言いませんが、 + SGML を使って定義された言語を使っているということになります。

SGML を使って定義されたマークアップ言語は非常にたくさんあります。 - HTMLもその中の一つです。ほかには "LinuxDoc" - と呼ばれるものもあります。おそらくあなたが想像しているように、 - それはもともとは Linux のドキュメンテーショングループが - 彼らのドキュメントを書くために作ったもので、 - FreeBSDドキュメンテーションプロジェクトでも同様にそれを採用しました。

- -

もう一つの SGML で定義されたマークアップ言語として "DocBook" - というものがあります。これは技術的なドキュメントを書くために特別に - 設計された言語で、それなりにたくさんのタグがあって (<...> - の中のもの) そのものに関連する技術的なドキュメントを記述しています。

- + HTML もその一つです。ほかには "DocBook" + というものがあります。 + これは技術的なドキュメントを書くためことに特化して設計された言語なので、 + 後から書式を整えるように技術的なドキュメントを記述するためのタグ + (<tag content> のもの) がたくさんあります。 + FreeBSD ドキュメンテーションプロジェクトはこれを採用し、 + より明確にするためにいくつかの新しい要素を定義しました。

+

例えば、これは HTML で短い段落を書いてみたものです。 - (内容については気にせずに、タグだけを見て下さい)

+ (内容については気にせずに、タグだけを見て下さい)

システムのパスワードは /etc/passwd に記録されます。
 	このファイルを編集したいときには vipw を使うべきです。
 	しかし、単に新しいユーザを加えたいだけのときには adduser
 	も使うことができます。

 ]]>

同じ段落を DocBook を使ってみるとこのようになります。

システムのパスワードは /etc/passwd
       に記録されます。このファイルを編集したいときには
       vipw を使うべきです。しかし、
       単に新しいユーザを加えたいだけのときには adduser
       も使うことができます。
 ]]>

見てわかるように、DocBook は HTML よりもずっと '表現が豊富' です。 HTML の例ではファイル名は 'typewriter' フォントで表示されるように マークアップされていますが、DocBook の例ではファイル名は 'filename' としてマークアップされ、ファイル名の表示については記述されません。

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

-

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

+

これは Microsoft® Word + のスタイルシートに少々似ているものではありますが、 + より強力なものとなっています。

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

-

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

+

もしあなたが DocBook について何も知らないとしても、 + 貢献できることがあるのでしょうか?

-

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

- -

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

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

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

+ "前と後の" 状態を持っているということになり、 + うまくいけばその過程からマークアップについていくらかでも学ぶことができるからです。

-

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

+

もちろん、 + あなたの提出したドキュメントはマークアップしなければならないので、 + 数時間では済まず、数日に延びてしまうかもしれませんが、 + いずれはコミットされることでしょう。

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

まず、Documentation Project - 入門を読むべきでしょう。 これは FreeBSD documentation の + 入門を読んでください。 これは FreeBSD documentation の 作業をおこなうために知っておくべきすべてのことに関する包括的な - 説明をねらったものです。

- -

これは長編のドキュメントであり、たくさんの小さなファイルに - 分割されています。また - ひとつの大きなファイルとしてまとめられているものもあります。

+ ひとつの大きなページにまとめられているものもあります。

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 を学んでみたい方を目的としています。

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