blob: e85b5c64805e65379c17bb5ab390c01985f7c675 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
<?xml version="1.0" encoding="euc-jp"?>
<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
"http://www.FreeBSD.org/XML/doc/share/sgml/xhtml10-freebsd.dtd" [
<!ENTITY title "FreeBSD ドキュメンテーションプロジェクト: SGML">
]>
<!-- The FreeBSD Japanese Documentation Project -->
<!-- Original revision: 1.28 -->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>&title;</title>
<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
</head>
<body class="navinclude.docs">
<p>ドキュメンテーションプロジェクトは SGML
をドキュメントを表現するための標準の手段として使用しています。</p>
<p>SGML とは <b>S</b>tandard <b>G</b>eneralized <b>M</b>arkup
<b>L</b>anguage のことです。</p>
<p>簡単に言えば (読者の中の SGML
の純正主義者の方々にはお気にさわったらごめんなさい)、
SGML は他の言語を記述するための言語です。</p>
<p>あなたはおそらくすでに SGML を使ったことがあるでしょうが、
それには覚えがないでしょう。HTML (それは web
ページを書くための言語ですが) には、正式の書き方があります。
その書き方が SGML で書かれているのです。あなたが HTML
を書いているときには (それ自体は) SGML で書いているとは<b>言いません</b>が、
SGML を使って定義された言語を使っているということになります。</p>
<p>SGML を使って定義されたマークアップ言語は非常にたくさんあります。
HTML もその一つです。ほかには "DocBook"
というものがあります。
これは技術的なドキュメントを書くためことに特化して設計された言語なので、
後から書式を整えるように技術的なドキュメントを記述するためのタグ
(<tt><tag content></tt> のもの) がたくさんあります。
FreeBSD ドキュメンテーションプロジェクトはこれを採用し、
より明確にするためにいくつかの新しい要素を定義しました。</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>このマークアップのより表現に富む形式について多くの利点を挙げてみましょう。</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>SGML と DocBook を学ぶための最も良い方法は、
数多くの例のドキュメントのソースを読んで、
他の著者が同じ情報をどう書いているかを見ることです。</p></li>
<li><p>この方法に転向するのは簡単ではありません。</p></li>
</ul>
<h2>DocBook について何も知らないとしても、貢献できることがあるのでしょうか?</h2>
<p>はい。もちろんです。
どんなドキュメントであっても何もないよりは良いものです。
もしあなたが貢献すべきドキュメントを持っていて、
それが 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>ドキュメンテーションプロジェクト入門</b></a>を読んでください。これは FreeBSD
ドキュメンテーションプロジェクトの作業をおこなうために知っておくべきすべてのことに関する包括的な説明をねらったものです。
これは長編のドキュメントで、
たくさんの小さなページに分割されています。また<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>
</body>
</html>
|
