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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
Original revision: 1.23
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">
<title>概論</title>
<para>歡迎參與 FreeBSD 文件計劃。維持優秀質量的文件對 FreeBSD 的成功來說十分重要，
而 FreeBSD 文件計劃(以下皆以 FDP 來代表 FreeBSD Documentation Project
的縮寫) 則與這些文件撰寫、更新息息相關，因此您的點滴貢獻都是十分寶貴的。</para>
<para>本文件最主要的目的，就是清楚告訴您：『FDP 的架構有哪些』、『如何撰寫並提交文件給 FDP』、
『如何有效運用工具來協助撰稿』。</para>
<para><indexterm>
<primary>Membership</primary>
</indexterm>
我們歡迎每個熱心的志士來加入 FDP 行列。FDP 並不限定每月必須交出多少稿量，才能加入。
您唯一須要作的就是訂閱 &a.doc; 。</para>
<para>讀完本份文件，您將會：</para>
<itemizedlist>
<listitem>
<para>瞭解有哪些文件是由 FDP 所維護的。</para>
</listitem>
<listitem>
<para>可以看懂 FDP 所維護的 SGML 原始文件。</para>
</listitem>
<listitem>
<para>知道如何來對文件作修改。</para>
</listitem>
<listitem>
<para>知道如何投稿自己的修改部份，並最後正式進入 FreeBSD 文件內。</para>
</listitem>
</itemizedlist>
<sect1 xml:id="overview-doc">
<title>FreeBSD 文件的組成部分</title>
<para>FDP 總共負責 FreeBSD 的 4 種類別的文件：</para>
<variablelist>
<varlistentry>
<term>線上手冊(manual)</term>
<listitem>
<para>英文版的系統 manual 並不是由 FDP 所撰寫的，因為它們是屬於 base system 的部份。
然而，FDP 可以(也曾這麼做過)修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。</para>
<para>翻譯團隊負責將系統的線上手冊翻譯為不同的語言。 這些譯本都由 FDP 維護。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FAQ</term>
<listitem>
<para>FAQ 主要是收集在各論壇或 newsgroup 會常問到或有可能會問到的 FreeBSD 相關問題與答案 。
(簡單講，就是『問答集』格式) 通常會擺在這裡面的問答格式，不會放太長的詳細內容。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>使用手冊(Handbook)</term>
<listitem>
<para>使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Web site</term>
<listitem>
<para>FreeBSD 主要各項介紹方面的 WWW 部份，歡迎逛逛 <link xlink:href="&url.base;/index.html">http://www.FreeBSD.org/</link>
以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方。</para>
</listitem>
</varlistentry>
</variablelist>
<para>這四個文件組成部分都可透過 FreeBSD CVS tree 來取得。也就是說，這些文件的修改記錄對於任何人都是公開的，
而且無論是誰都可以用像是 <application>CSup</application>, <application>CVSup</application> 或
<application>CTM</application> 將文件取出來(checkout)並放在自己機器上做備份或副本參考等用途。</para>
<para>此外，許多人會寫些教學文件或維護有關 FreeBSD 內容的網站。(若作者同意的話)其中有些資料會保存在 FreeBSD 正式
CVS repository 內。而其他的文件，可能作者不希望被放在 FreeBSD repository 內而另存他處。
總之，FDP 會盡力提供這些文件的連結。</para>
</sect1>
<sect1 xml:id="overview-before">
<title>在開工之前...</title>
<para>本文假設您已經瞭解：</para>
<itemizedlist>
<listitem>
<para>如何從 FreeBSD CVS repository 更新自己電腦上的 FreeBSD 文件部份(以 <application>CVS</application>
或 <application>CSup</application> 或 <application>CVSup</application> 或是
<application>CTM</application>) 或是用
<application>CVSup</application> 來下載 <emphasis>checked-out</emphasis> 的副本</para>
</listitem>
<listitem>
<para>如何用 FreeBSD Ports 套件管理機制或 &man.pkg.add.1; 來下載、安裝軟體。</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="overview-quick-start">
<title>快速上手篇</title>
<para>若想先自行試試看，並有信心可以作得到，那麼就照下面步驟吧。</para>
<procedure>
<step>
<para>安裝 <package>textproc/docproj</package> 這個組合型 port(meta-port)。</para>
<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
</step>
<step>
<para>下載 FreeBSD <filename>doc</filename> tree 到本機上：
無論是用 CSup 或 CVSup 的 <literal>checkout</literal> 模式，
或是複製完整的 CVS repository 到本機上都可以。</para>
<para>若想在本機上只跑最低限度的 CVS repository 就好，那麼必須要
checkout 出 <filename>doc/share</filename> 以及 <filename>doc/en_US.ISO8859-1/share</filename>
這兩個目錄才行。</para>
<screen>&prompt.user; <userinput>cvs checkout doc/share</userinput>
&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/share</userinput></screen>
<para>若硬碟空間還算可以的話，那可以把所有語系的 doc 都 check out 出來：</para>
<screen>&prompt.user; <userinput>cvs checkout doc</userinput></screen>
</step>
<step>
<para>可依需要從 repository 中 checkout 出來你想修改某份現有的書籍或文章內容。
若打算撰寫新書或新文章的話，可以參考現有的部分作為實例來做。</para>
<para>舉例來說，若想寫篇新文章，內容是有關在 FreeBSD 與 Windows 2000 之間建立 VPN 連線，
那麼可以照類似下面這樣的作法：</para>
<procedure>
<step>
<para>Check out <filename>articles</filename> 目錄：</para>
<screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/articles</userinput></screen>
</step>
<step>
<para>複製現有的文章作為範本。在這個例子中，您打算決定把新文章放在
<filename>vpn-w2k</filename> 的目錄下。</para>
<screen>&prompt.user; <userinput>cd doc/en_US.ISO8859-1/articles</userinput>
&prompt.user; <userinput>cp -R committers-guide vpn-w2k</userinput></screen>
</step>
</procedure>
<para>若是要修改現有文章，像是 FAQ(擺在 <filename>doc/en_US.ISO8859-1/books/faq</filename>)
，那麼要從 repository 中取出來(check out)：</para>
<screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/books/faq</userinput></screen>
</step>
<step>
<para>以編輯器來編寫 <filename>.xml</filename> 檔。</para>
</step>
<step>
<para>以 <buildtarget>lint</buildtarget> 當輔助參數，來快速檢測文件結構及連結有無錯誤，
以下這個指令，實際上不會進行耗時的編書過程，只是先測試文件有無錯誤。</para>
<screen>&prompt.user; <userinput>make lint</userinput></screen>
<para>當編書的一切都就緒時，這時你可以用 <varname>FORMATS</varname>
變數來指定產生的格式為哪一種。 目前支援的格式共有：
<literal>html</literal>, <literal>html-split</literal>,
<literal>txt</literal>, <literal>ps</literal>,
<literal>pdf</literal>, <literal>rtf</literal> 。
所支援的格式列表最新版，可參考
<filename>doc/share/mk/doc.docbook.mk</filename> 檔。 請記得：
在單一指令中，若要同時產生多種格式的話，應使用引號(quotes)來將這些格式括起來。</para>
<para>舉例來說，若只要產生
<literal>html</literal> 格式就好，那麼就打：</para>
<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
<para>但若希望有 <literal>html</literal> 及 <literal>txt</literal> 格式的話，
你可能要打兩次 &man.make.1; 指令才能完成：</para>
<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
&prompt.user; <userinput>make FORMATS=txt</userinput></screen>
<para>其實，也可以用單一指令來完成：</para>
<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
</step>
<step>
<para>最後，以 &man.send-pr.1; 來提交修改的部份。</para>
</step>
</procedure>
</sect1>
</chapter>
|
