Merge from chinsan's repo. (That's my 83th doc commit).
PR: docs/99751 Submitted by: chinsan.dot.tw@gmail.com
This commit is contained in:
Vanilla I. Shu
parent
ed5e278004
commit
e60c96d258
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=28195
3 changed files with 67 additions and 93 deletions
|
|
@ -41,7 +41,7 @@
|
|||
|
||||
<book>
|
||||
<bookinfo>
|
||||
<title>FreeBSD Documentation Project Primer for New Contributors</title>
|
||||
<title>FreeBSD 文件計畫上手書</title>
|
||||
|
||||
<corpauthor>FreeBSD 文件計劃</corpauthor>
|
||||
|
||||
|
|
@ -65,16 +65,12 @@
|
|||
&bookinfo.legalnotice;
|
||||
|
||||
<abstract>
|
||||
<para>感謝您參與 FreeBSD 文件計劃，您的點滴貢獻，都相當寶貴。</para>
|
||||
<para>感謝您參與 FreeBSD 文件計劃(簡稱：FDP, FreeBSD Documentation Project)，您的點滴貢獻，都相當寶貴。</para>
|
||||
|
||||
<para>This primer covers everything you will need to know in order
|
||||
to start contributing to the FreeBSD Documentation Project, from
|
||||
the tools and software you will be using (both mandatory and
|
||||
recommended) to the philosophy behind the Documentation
|
||||
Project.</para>
|
||||
<para>本入手書內容包括：如何開始著手翻譯的各項細節，以及會用到的一些好用工具(包括：必備工具、建議工具)
|
||||
，以及文件計畫的宗旨。</para>
|
||||
|
||||
<para>本文件還在草稿，尚未完稿。未完成的章節，我們會在章節名稱旁邊加註『
|
||||
<literal>*</literal> 』以作識別。</para>
|
||||
<para>本文件還在草稿，尚未完稿。未完成的章節，我們會在章節名稱旁邊加註『<literal>*</literal> 』以作識別。</para>
|
||||
</abstract>
|
||||
</bookinfo>
|
||||
|
||||
|
|
@ -127,52 +123,57 @@
|
|||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>The name of commands, files, and directories. On screen
|
||||
computer output.</entry>
|
||||
<entry><para>Edit your <filename>.login</filename>
|
||||
file.</para><para>Use <command>ls -a</command> to list all
|
||||
files.</para><para><screen>You have mail.</screen>
|
||||
</para></entry>
|
||||
<entry>指令</entry>
|
||||
<entry>使用 <command>ls -a</command> 來列出所有的檔案。</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>在輸入指令後，螢幕上會出現的對應內容：</entry>
|
||||
<entry>檔名</entry>
|
||||
<entry>修改 <filename>.login</filename> 檔。</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>螢幕上會出現的訊息</entry>
|
||||
<entry><screen>You have mail.</screen></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>輸入指令後，螢幕上會出現的對應內容：</entry>
|
||||
<entry><screen>&prompt.user; <userinput>su</userinput>
|
||||
Password:</screen></entry>
|
||||
Password:</screen></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>講到要參考的 Manual 時...</entry>
|
||||
<entry>要參考的線上手冊(manual)</entry>
|
||||
|
||||
<entry>Use <citerefentry>
|
||||
<entry>以 <citerefentry>
|
||||
<refentrytitle>su</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
</citerefentry> to change user names.</entry>
|
||||
</citerefentry> 來切換帳號。</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>在講到帳號(user)、群組(group)的名稱的時候...</entry>
|
||||
|
||||
<entry>Only <username>root</username> can do this.</entry>
|
||||
<entry>只有 <username>root</username> 才可以做這件事。</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>語氣的強調。</entry>
|
||||
<entry>語氣的強調</entry>
|
||||
|
||||
<entry>You <emphasis>must</emphasis> do this.</entry>
|
||||
<entry>你『必須』這麼做才行。</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>打指令時可替換的部份(可改為符合自己機器上的檔名、設備或其他類似部份)。</entry>
|
||||
<entry>打指令時，可替換的部份</entry>
|
||||
|
||||
<entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry>
|
||||
<entry>要刪除檔案的話，請打 <command>rm <filename><replaceable>要刪除的檔名</replaceable></filename></command></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>環境變數設定</entry>
|
||||
|
||||
<entry><envar>$HOME</envar> is your home directory.</entry>
|
||||
<entry><envar>$HOME</envar> 是指帳號的家目錄所在處。</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
|
|
@ -182,37 +183,29 @@ Password:</screen></entry>
|
|||
<sect1 id="preface-notes">
|
||||
<title>『Note、Tip、Important、Warning、Example』的運用</title>
|
||||
|
||||
<para>以下文字是『注意(Note)』、『技巧(Tip)』、『重要訊息(Important)』、『警告(Warning)』、『範例(Example)』的運用。</para>
|
||||
<para>以下文字是『注意』、『技巧』、『重要訊息』、『警告』、『範例』的運用。</para>
|
||||
|
||||
<note>
|
||||
<para>Notes are represented like this, and contain information that
|
||||
you should take note of, as it may affect what you do.</para>
|
||||
<para>表示需要注意的事項，其中包括您需要注意的事情，因為這些事情可能會影響到操作結果。</para>
|
||||
</note>
|
||||
|
||||
<tip>
|
||||
<para>Tips are represented like this, and contain information that you
|
||||
might find useful, or lead to an easier way to do something.</para>
|
||||
<para>提供可能對您有用或簡化操作方式的技巧說明。</para>
|
||||
</tip>
|
||||
|
||||
<important>
|
||||
<para>Important information is represented like this. Typically they
|
||||
flag extra steps you may need to carry out.</para>
|
||||
<para>表示要特別注意的事情。一般來說，它們會包括操作指令時需要加的額外參數。</para>
|
||||
</important>
|
||||
|
||||
<warning>
|
||||
<para>Warnings are represented like this, and contain information
|
||||
warning you about possible damage if you do not follow the
|
||||
instructions. This damage may be physical, to your hardware or to
|
||||
you, or it may be non-physical, such as the inadvertent deletion of
|
||||
important files.</para>
|
||||
<para>表示警告事項，比如如果您不注意則可能導致的損失。這些損失可能是對您或硬體造成實際傷害，
|
||||
也可能是無法估計的損害，例如一時疏忽而刪除重要檔案...。</para>
|
||||
</warning>
|
||||
|
||||
<example>
|
||||
<title>這是舉例說明</title>
|
||||
|
||||
<para>Examples are represented like this, and typically contain
|
||||
examples you should walk through, or show you what the results of a
|
||||
particular action should be.</para>
|
||||
<para>這是舉例說明而已，通常包含應遵循的指令範例，或顯示某些特定動作所可能發生的結果。</para>
|
||||
</example>
|
||||
</sect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -68,21 +68,19 @@
|
|||
</itemizedlist>
|
||||
|
||||
<sect1 id="overview-doc">
|
||||
<title>The FreeBSD Documentation Set</title>
|
||||
<title>FreeBSD 文件的組成部分：</title>
|
||||
|
||||
<para>FDP 總共負責 FreeBSD 的 4 種類別的文件：</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>Manual pages</term>
|
||||
<term>線上手冊(manual)</term>
|
||||
|
||||
<listitem>
|
||||
<para>英文版的系統 manual 並不是由 FDP 所撰寫的，因為它們是屬於 base system 的部份。
|
||||
然而，FDP 可以(也曾這麼做過)修改這些文件，來讓這些文件寫得更清楚，甚至是勘正錯誤的地方。</para>
|
||||
|
||||
<para>The translation teams are responsible for translating the
|
||||
system manual pages into different languages. These translations
|
||||
are kept within the FDP.</para>
|
||||
<para>翻譯團隊負責將系統的線上手冊翻譯為不同的語言。 這些譯本都由 FDP 維護。</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
|
@ -96,11 +94,10 @@
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Handbook</term>
|
||||
<term>使用手冊(Handbook)</term>
|
||||
|
||||
<listitem>
|
||||
<para>The Handbook aims to be the comprehensive on-line resource and
|
||||
reference for FreeBSD users.</para>
|
||||
<para>使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
|
@ -115,20 +112,13 @@
|
|||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>These four groups of documentation are all available in the
|
||||
FreeBSD CVS tree. This means that the logs of changes to these
|
||||
files are visible to anyone, and anyone can use a program such as
|
||||
<application>CVSup</application> or
|
||||
<application>CTM</application> to keep local copies of
|
||||
this documentation.</para>
|
||||
<para>這四個文件組成部分都可透過 FreeBSD CVS tree 來取得。也就是說，這些文件的修改記錄對於任何人都是公開的，
|
||||
而且無論是誰都可以用像是 <application>CSup</application>, <application>CVSup</application> 或
|
||||
<application>CTM</application> 將文件取出來(checkout)並放在自己機器上做備份或副本參考等用途。</para>
|
||||
|
||||
<para>In addition, many people have written tutorials or other web
|
||||
sites relating to FreeBSD. Some of these are stored in the CVS
|
||||
repository as well (where the author has agreed to this). In
|
||||
other cases the author has decided to keep his documentation
|
||||
separate from the main FreeBSD repository. The FDP endeavors to
|
||||
provide links to as much of this documentation as
|
||||
possible.</para>
|
||||
<para>此外，許多人會寫些教學文件或維護有關 FreeBSD 內容的網站。(若作者同意的話)其中有些資料會保存在 FreeBSD 正式
|
||||
CVS repository 內。而其他的文件，可能作者不希望被放在 FreeBSD repository 內而另存他處。
|
||||
總之，FDP 會盡力提供這些文件的連結。</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="overview-before">
|
||||
|
|
@ -138,8 +128,8 @@
|
|||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>如何從 FreeBSD CVS repository 更新自己電腦上的 FreeBSD 文件 部份(以 <application>CVS</application>
|
||||
或 <application>CVSup</application> 或是
|
||||
<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>
|
||||
|
|
@ -157,43 +147,39 @@
|
|||
|
||||
<procedure>
|
||||
<step>
|
||||
<para>安裝 <filename role="package">textproc/docproj</filename> 這個組合型 port(meta-port).</para>
|
||||
<para>安裝 <filename role="package">textproc/docproj</filename> 這個組合型 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>Get a local copy of the FreeBSD <filename>doc</filename> tree.
|
||||
Either use CVSup in <literal>checkout</literal> mode to do this, or
|
||||
get a full copy of the CVS repository locally.</para>
|
||||
<para>下載 FreeBSD <filename>doc</filename> tree 到本機上：
|
||||
無論是用 CSup 或 CVSup 的 <literal>checkout</literal> 模式，
|
||||
或是複製完整的 CVS repository 到本機上都可以。</para>
|
||||
|
||||
<para>If you have the CVS repository locally then as a minimum you
|
||||
will need to checkout the <filename>doc/share</filename>, and
|
||||
<filename>doc/en_US.ISO8859-1/share</filename>
|
||||
directories.</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>
|
||||
<para>若硬碟空間還算可以的話，那可以把所有語系的 doc 都 check out 出來：</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>cvs checkout doc</userinput></screen>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>If you are preparing a change to an existing book or article,
|
||||
check it out of the repository as necessary. If you are planning on
|
||||
contributing a new book or article then use an existing one as a
|
||||
guide.</para>
|
||||
<para>可依需要從 repository 中 checkout 出來你想修改某份現有的書籍或文章內容。
|
||||
若打算撰寫新書或新文章的話，可以參考現有的部分作為實例來做。</para>
|
||||
|
||||
<para>舉例來說，若想寫篇新文章，內容是有關在 FreeBSD 與 Windows 2000 之間建立 VPN 連線，
|
||||
那麼可以照類似下面這樣的作法：</para>
|
||||
|
||||
<procedure>
|
||||
<step>
|
||||
<para>Check out the <filename>articles</filename>
|
||||
directory.</para>
|
||||
<para>Check out <filename>articles</filename> 目錄：</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/articles</userinput></screen>
|
||||
</step>
|
||||
|
|
@ -223,19 +209,16 @@
|
|||
|
||||
<screen>&prompt.user; <userinput>make lint</userinput></screen>
|
||||
|
||||
<para>When you are ready to actually build the document, you
|
||||
may specify a single format or a list of formats in the
|
||||
<varname>FORMATS</varname> variable. 目前支援的格式共有：
|
||||
<para>當編書的一切都就緒時，這時你可以用 <varname>FORMATS</varname>
|
||||
變數來指定產生的格式為哪一種。 目前支援的格式共有：
|
||||
<literal>html</literal>, <literal>html-split</literal>,
|
||||
<literal>txt</literal>, <literal>ps</literal>,
|
||||
<literal>pdf</literal>, <literal>rtf</literal> 。
|
||||
The most up to date list of supported formats is
|
||||
listed at the top of the
|
||||
<filename>doc/share/mk/doc.docbook.mk</filename> file. Make
|
||||
sure to use quotes around the list of formats when you build
|
||||
more than one format with a single command.</para>
|
||||
所支援的格式列表最新版，可參考
|
||||
<filename>doc/share/mk/doc.docbook.mk</filename> 檔。 請記得：
|
||||
在單一指令中，若要同時產生多種格式的話，應使用引號(quotes)來將這些格式括起來。</para>
|
||||
|
||||
<para>舉例來說，若只要
|
||||
<para>舉例來說，若只要產生
|
||||
<literal>html</literal> 格式就好，那麼就打：</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@
|
|||
<title>工具</title>
|
||||
|
||||
<para>FDP 使用一堆工具來協助管理 FreeBSD 文件、轉換文件格式等等。
|
||||
因此，若要進行 FDP 工作的話，可能必須要學會這些工具才行。</para>
|
||||
因此，若要進行 FDP 工作的話，必須要學會這些工具才行。</para>
|
||||
|
||||
<para>這些工具都可以用 Ports 或 Packages 來安裝，以節省許多安裝的工夫。</para>
|
||||
|
||||
|
|
@ -47,10 +47,8 @@
|
|||
<para>裝了
|
||||
<filename role="package">textproc/docproj</filename> 可以更省時省力，它是個
|
||||
組合型的 port(meta-port)，本身並非軟體，只是將一些常用工具組合起來而已。
|
||||
Instead, it depends on various other ports being installed
|
||||
correctly. Installing this port <emphasis>should</emphasis>
|
||||
automatically download and install all of the packages listed in this
|
||||
chapter that you need.</para>
|
||||
裝了這個 port 之後，『應該』就會自動下載、安裝本章所會介紹到的工具了。
|
||||
若要處理中文的話，建議再裝 <filename role="package">chinese/docproj</filename> 會比較好。</para>
|
||||
|
||||
<para>One of the packages that you might need is the JadeTeX macro set.
|
||||
In turn, this macro set requires &tex; to be installed. &tex; is a large
|
||||
|
|
|
|||
Loading…
Reference in a new issue