02b6548549
1.6 -> 1.8 docproj/doc-set.sgml 1.14 -> 1.15 docproj/sgml.sgml 1.36 -> 1.37 docproj/translations.sgml 1.12 -> 1.14 internal/developer.sgml 1.13 -> 1.14 internal/internal.sgml 1.18 -> 1.19 java/newsflash.sgml 1.12 -> 1.13 java/dists/12.sgml 1.5 -> 1.6 releases/2.2.5R/announce.sgml 1.5 -> 1.6 releases/2.2.6R/announce.sgml 1.8 -> 1.9 releases/2.2.7R/announce.sgml 1.4 -> 1.5 releases/2.2.8R/announce.sgml 1.5 -> 1.6 releases/3.0R/announce.sgml 1.5 -> 1.6 releases/3.1R/announce.sgml - Merge from the English version and add a line forgotten in the previous commit: 1.1 -> 1.2 releases/4.3R/notes.sgml Pointed out by: kogane@jp.FreeBSD.org Submitted by: hino@ccm.cl.nec.co.jp
195 lines
8.3 KiB
Text
195 lines
8.3 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD: www/ja/docproj/sgml.sgml,v 1.17 2000/10/31 19:32:43 kuriyama Exp $">
|
|
<!ENTITY title "FreeBSD Documentation Project: SGML">
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
<!-- The FreeBSD Japanese Documentation Project -->
|
|
<!-- $FreeBSD: www/ja/docproj/sgml.sgml,v 1.17 2000/10/31 19:32:43 kuriyama Exp $ -->
|
|
<!-- Original revision: 1.15 -->
|
|
|
|
<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;/tutorials/docproj-primer/index.html"><b>Documentation Project
|
|
入門</b></a>を読むべきでしょう. これは FreeBSD documentation の
|
|
作業をおこなうために知っておくべきすべてのことに関する包括的な
|
|
説明をねらったものです.</p>
|
|
|
|
<p>これは長編のドキュメントであり, たくさんの小さなファイルに
|
|
分割されています. また <a
|
|
href="&base;/tutorials/docproj-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-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html"><b>http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.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>
|
|
|
|
<dt><a
|
|
href="http://fallout.campusview.indiana.edu/~jfieber/docbook/"><b>http://fallout.campusview.indiana.edu/~jfieber/docbook/</b></a></dt>
|
|
|
|
<dd><p>John Fieber 氏のページで DocBook に関する資料やドキュメントの
|
|
サンプルへのリンクがあります. FreeBSD のための
|
|
マークアップのガイドの初歩についても含まれています.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www.nothing-going-on.demon.co.uk/FreeBSD/"><b>http://www.nothing-going-on.demon.co.uk/FreeBSD/</b></a></dt>
|
|
|
|
<dd><p>Nik Clayton 氏のページで DocBook で書かれたドキュメントや
|
|
それを HTML へ変換したものへのリンクがあります. 元の DocBook の
|
|
ファイルもあり, どのように DocBook のさまざまな要素が使えるのかという
|
|
筋の通った例も書かれています.</p>
|
|
</dd>
|
|
|
|
<dt><a
|
|
href="http://wolfram.schneider.org/papers/webbuild.html"><b>
|
|
http://wolfram.schneider.org/papers/webbuild.html</b></a></dt>
|
|
|
|
<dd> &webbuild; </dd>
|
|
</dl>
|
|
|
|
<p></p><a href="docproj.html">FreeBSD
|
|
ドキュメンテーションプロジェクトのページ</a>
|
|
&footer;
|
|
</body>
|
|
</html>
|