eb0a534139
Submitted by: Emily Boyd (emilyboyd at emilyboyd dot com) Sponsored by: Google Summer of Code 2005
175 lines
7.3 KiB
Text
175 lines
7.3 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD: www/ja/docproj/sgml.sgml,v 1.26 2004/02/21 11:35:24 rushani Exp $">
|
|
<!ENTITY title "FreeBSD Documentation Project: SGML">
|
|
<!ENTITY % navincludes SYSTEM "../includes.navdocs.sgml"> %navincludes;
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
<!-- The FreeBSD Japanese Documentation Project -->
|
|
<!-- Original revision: 1.22 -->
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<p>ドキュメンテーションプロジェクトは SGML
|
|
をドキュメントを表現するための標準の手段としようとしています。</p>
|
|
|
|
<p>SGML とは <b>S</b>tandard <b>G</b>eneralised <b>M</b>arkup
|
|
<b>L</b>anguage のことです。</p>
|
|
|
|
<p>簡単に言えば (読者の中の SGML の純正主義者の方々にはお気にさわったら
|
|
ごめんなさい) SGML は他の言語を記述するための言語です。</p>
|
|
|
|
<p>あなたはおそらくすでに SGML を使ったことがあるでしょうが、
|
|
それには覚えがないでしょう。HTMLには、それは web
|
|
ページを書くための言語ですが、正式の書き方があります。
|
|
その書き方が SGML で書かれているのです。あなたが HTML
|
|
を書いているときには SGML で書いているとは<b>言いません</b>が
|
|
(per se)、SGML を使って定義された言語を使っている
|
|
ということになります。</p>
|
|
|
|
<p>SGML を使って定義されたマークアップ言語は非常にたくさんあります。
|
|
HTMLもその中の一つです。ほかには "LinuxDoc"
|
|
と呼ばれるものもあります。おそらくあなたが想像しているように、
|
|
それはもともとは Linux のドキュメンテーショングループが
|
|
彼らのドキュメントを書くために作ったもので、
|
|
FreeBSDドキュメンテーションプロジェクトでも同様にそれを採用しました。</p>
|
|
|
|
<p>もう一つの SGML で定義されたマークアップ言語として "DocBook"
|
|
というものがあります。これは技術的なドキュメントを書くために特別に
|
|
設計された言語で、それなりにたくさんのタグがあって (<...>
|
|
の中のもの) そのものに関連する技術的なドキュメントを記述しています。</p>
|
|
|
|
<p>例えば、これは HTML で短い段落を書いてみたものです。
|
|
(内容については気にせずに、タグだけを見て下さい)</p>
|
|
|
|
<pre><![ CDATA [
|
|
<p>システムのパスワードは <tt>/etc/passwd</tt> に記録されます。
|
|
このファイルを編集したいときには <b><tt>vipw</tt></b> を使うべきです。
|
|
しかし、単に新しいユーザを加えたいだけのときには <b><tt>adduser</tt></b>
|
|
も使うことができます。</p>
|
|
]]></pre>
|
|
|
|
<p>同じ段落を DocBook を使ってみるとこのようになります。</p>
|
|
|
|
<pre><![ CDATA [
|
|
<para>システムのパスワードは <filename>/etc/passwd</filename>
|
|
に記録されます。このファイルを編集したいときには
|
|
<command>vipw</command> を使うべきです。しかし、
|
|
単に新しいユーザを加えたいだけのときには <command>adduser</command>
|
|
も使うことができます。</para>
|
|
]]></pre>
|
|
|
|
<p>見てわかるように、DocBook は HTML よりもずっと '表現が豊富' です。
|
|
HTML の例ではファイル名は 'typewriter' フォントで表示されるように
|
|
マークアップされていますが、DocBook の例ではファイル名は 'filename'
|
|
としてマークアップされ、ファイル名の表示については記述されません。</p>
|
|
|
|
<p>このマークアップのより表現に富む形式について多くの利点を挙げてみましょう。
|
|
|
|
<ul>
|
|
<li><p>曖昧だったり無節操だったりすることがありません。</p>
|
|
<p>「うーん、ファイル名を表示するのに、'tt'、'b'、'em' のどれを
|
|
使うべきなんだろう?」と考える無駄な時間は取りません。</p>
|
|
<p>その代わりに、タグを適材適所に使うだけのことです。</p>
|
|
|
|
<p>DocBook から他のフォーマット (HTML、PostScript® など) への変換方法は
|
|
すべての <filename> が同じように表されるということを
|
|
確かめるということです。</p>
|
|
</li>
|
|
|
|
<li><p>あなたはドキュメントの表示について考えることを止めて、
|
|
その代わりに内容に集中できるのです。</p>
|
|
</li>
|
|
|
|
<li><p>ドキュメントはどのそれぞれの出力形式には拘束されていないので、
|
|
同じドキュメントからさまざまな異なった形式のものを作ることができます。
|
|
- プレインテキスト、HTML、PostScript、RTF、PDF などです。</p></li>
|
|
|
|
<li><p>ドキュメントを作るということはとても '知的な' ことで、
|
|
そのためにより知的なことが行われています。例えば、
|
|
ドキュメントに含まれるそれぞれのコマンドのリストから
|
|
自動的に索引を作るということもできます。</p></li>
|
|
</ul>
|
|
|
|
<p>もしそれらについてよく知っているなら、これは Microsoft® Word
|
|
のスタイルシートに少々似ているものではありますが、
|
|
しかし非常により強力なものとなっています。</p>
|
|
|
|
<p>もちろん、この能力を生かすにはそれなりの労力が必要です。</p>
|
|
|
|
<ul>
|
|
<li><p>使えるタグが非常に多いために、そのすべてを覚えたりそれらを
|
|
効果的に使えるようになるためには、より多くの時間が必要です。</p>
|
|
|
|
<p>覚えるための最も良い方法は、数多くの例のドキュメントのソースを
|
|
読んで、他の著者が同じ情報をどう書いているかを見ることです。</p></li>
|
|
|
|
<li><p>この方法に転向するにはそれほど簡単ではありません。</p></li>
|
|
</ul>
|
|
|
|
<p>いまのところは、このプロジェクトはまだ LinuxDoc をハンドブックや
|
|
FAQ に使っています。それは変更中で、特にドキュメントを DocBook
|
|
へ作り変えるプロジェクトを進めているところです。</p>
|
|
|
|
<h2>もしあなたが LinuxDoc/DocBook について何も知らないとしても、
|
|
貢献できることはありますか?</h2>
|
|
|
|
<p>はい。もちろんです。どんなドキュメントであってもなにもないよりは
|
|
良いものです。もしあなたが貢献すべきドキュメントを持っていて、
|
|
それが LinuxDoc もしくは DocBook でマークアップされていないとしても、
|
|
何の問題もありません。</p>
|
|
|
|
<p>普通にそのドキュメントを <a href="submitting.html">提出してください</a>。
|
|
プロジェクトのほかの誰かがあなたの提出されたドキュメントを見つけると、
|
|
それにマークアップをして、そしてコミットしてくれます。
|
|
少々運がいいとそのときにあなたにマークアップされたテキストが戻ってきます。
|
|
それは役に立ちます。というのはあなたはドキュメントがマークアップされる
|
|
"前と後の" 状態を持っているということになり、うまくいけばその過程から
|
|
マークアップについていくらかでも学ぶことができるからです。</p>
|
|
|
|
<p>明らかに、あなたの提出したドキュメントは
|
|
マークアップされる必要があるために、このことでコミットされるまでの過程は
|
|
長引いてしまうことになり、何日も掛かるかもしれません。
|
|
しかしそれはちゃんとコミットされることでしょう。</p>
|
|
|
|
<h2>SGML や DocBook に関する他の情報は ?</h2>
|
|
|
|
<p>まず、<a
|
|
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/index.html"><b>Documentation Project
|
|
入門</b></a>を読むべきでしょう。 これは FreeBSD documentation の
|
|
作業をおこなうために知っておくべきすべてのことに関する包括的な
|
|
説明をねらったものです。</p>
|
|
|
|
<p>これは長編のドキュメントであり、たくさんの小さなファイルに
|
|
分割されています。また <a
|
|
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/book.html"><b>
|
|
ひとつの大きなファイル</b></a>としてまとめられているものもあります。</p>
|
|
|
|
<dl>
|
|
<dt><a
|
|
href="http://www.oasis-open.org/cover/sgml-xml.html"><b>http://www.oasis-open.org/cover/sgml-xml.html</b></a></dt>
|
|
|
|
<dd><p>SGML/XML の web ページ。SGML
|
|
について数え切れないほどの情報へのポインタがあります。</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"><b>http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</b></a></dt>
|
|
|
|
<dd><p>「やさしい SGML の紹介」です。初心者の見方から SGML
|
|
についてもっと学びたいという方にお勧めです。</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www.oasis-open.org/docbook/"><b>http://www.oasis-open.org/docbook/</b></a></dt>
|
|
|
|
<dd><p>OASIS が DocBook DTD の保守をしています。
|
|
これらのページはすでに SGML について慣れているユーザや、
|
|
DocBook を学んでみたい方を目的としています。</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p></p><a href="docproj.html">FreeBSD
|
|
ドキュメンテーションプロジェクトのページ</a>
|
|
&footer;
|
|
</body>
|
|
</html>
|