os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Clean up. Remove directories not needed for the PO translation and

Browse source 
remove chapters.ent from the Makefile.
This commit is contained in:
Warren Block 2016-06-21 22:15:35 +00:00
parent 04101aed1a
commit 61d406f4ae
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=48979
15 changed files with 0 additions and 7227 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
zh_TW.UTF-8/books/fdp-primer/Makefile
View file

@ -28,9 +28,6 @@ IMAGES_LIB+= callouts/3.png
IMAGES_LIB+= callouts/4.png
IMAGES_LIB+= callouts/5.png
# Entities
SRCS+= chapters.ent
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..

27
zh_TW.UTF-8/books/fdp-primer/chapters.ent
View file

@ -1,27 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
Creates entities for each chapter in the Documentation Project Primer.
Each entity is named chap.foo, where foo is the value of the id
attribute on that chapter, and corresponds to the name of the
directory in which that chapter's .xml file is stored.
Chapters should be listed in the order in which they are referenced.
$FreeBSD$
Original revision: 1.6
-->
<!ENTITY chap.overview SYSTEM "overview/chapter.xml">
<!ENTITY chap.xml-primer SYSTEM "sgml-primer/chapter.xml">
<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
<!ENTITY chap.xml-markup SYSTEM "sgml-markup/chapter.xml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
<!ENTITY chap.translations SYSTEM "translations/chapter.xml">
<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml">
<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.xml">
<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml">
<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml">
<!ENTITY app.examples SYSTEM "examples/appendix.xml">

486
zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml
View file

@ -1,486 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 1999 Neil Blakey-Milner, 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 THE AUTHOR "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.16
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="doc-build">
<title>The Documentation Build Process</title>
<para>This chapter's main purpose is to clearly explain <emphasis>how
the documentation build process is organized</emphasis>, and
<emphasis>how to affect modifications to this process</emphasis>.
</para>
<para>After you have finished reading this chapter you should:</para>
<itemizedlist>
<listitem>
<para>Know what you need to build the FDP documentation, in
addition to those mentioned in the <link linkend="tools">SGML tools chapter</link>.</para>
</listitem>
<listitem>
<para>Be able to read and understand the
<application>make</application> instructions that are present in
each document's <filename>Makefile</filename>s, as well as an
overview of the <filename>doc.project.mk</filename> includes.</para>
</listitem>
<listitem>
<para>Be able to customize the build process by using
<application>make</application> variables and
<application>make</application> targets.</para>
</listitem>
</itemizedlist>
<sect1 xml:id="doc-build-toolset">
<title>The FreeBSD Documentation Build Toolset</title>
<para>Here are your tools. Use them every way you can.</para>
<itemizedlist>
<listitem>
<para>The primary build tool you will need is
<application>make</application>, but specifically
<application>Berkeley Make</application>.</para>
</listitem>
<listitem>
<para>Package building is handled by FreeBSD's
<application>pkg_create</application>. If you are not using
FreeBSD, you will either have to live without packages, or
compile the source yourself.</para>
</listitem>
<listitem>
<para><application>gzip</application> is needed to create
compressed versions of the document.
<application>bzip2</application> compression and
<application>zip</application> archives are also supported.
<application>tar</application> is supported, but package
building demands it.</para>
</listitem>
<listitem>
<para><application>install</application> is the default method
to install the documentation. There are alternatives,
however.</para>
</listitem>
</itemizedlist>
<note>
<para>It is unlikely you will have any trouble finding these last two, they
are mentioned for completeness only.</para>
</note>
</sect1>
<sect1 xml:id="doc-build-makefiles">
<title>Understanding Makefiles in the Documentation tree</title>
<para>There are three main types of <filename>Makefile</filename>s
in the FreeBSD Documentation Project tree.</para>
<itemizedlist>
<listitem>
<para><link linkend="sub-make">Subdirectory
<filename>Makefile</filename>s</link> simply pass
commands to those directories below them.</para>
</listitem>
<listitem>
<para><link linkend="doc-make">Documentation
<filename>Makefile</filename>s</link> describe the
document(s) that should be produced from this directory.</para>
</listitem>
<listitem>
<para><link linkend="make-includes"><application>Make</application>
includes</link> are the glue that perform the document production,
and are usually of the form
<filename>doc.xxx.mk</filename>.</para>
</listitem>
</itemizedlist>
<sect2 xml:id="sub-make">
<title>Subdirectory Makefiles</title>
<para>These <filename>Makefile</filename>s usually take the form of:</para>
<programlisting>SUBDIR =articles
SUBDIR+=books
COMPAT_SYMLINK = en
DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
<para>In quick summary, the first four non-empty lines define the
<application>make</application> variables,
<varname>SUBDIR</varname>, <varname>COMPAT_SYMLINK</varname>,
and <varname>DOC_PREFIX</varname>.</para>
<para>The first <varname>SUBDIR</varname> statement, as well as
the <varname>COMPAT_SYMLINK</varname> statement, shows how to
assign a value to a variable, overriding any previous
value.</para>
<para>The second <varname>SUBDIR</varname> statement shows how a
value is appended to the current value of a variable. The
<varname>SUBDIR</varname> variable is now <literal>articles
books</literal>.</para>
<para>The <varname>DOC_PREFIX</varname> assignment shows how a
value is assigned to the variable, but only if it is not already
defined. This is useful if <varname>DOC_PREFIX</varname> is not
where this <filename>Makefile</filename> thinks it is - the user
can override this and provide the correct value.</para>
<para>Now what does it all mean? <varname>SUBDIR</varname>
mentions which subdirectories below this one the build process
should pass any work on to.</para>
<para><varname>COMPAT_SYMLINK</varname> is specific to
compatibility symlinks (amazingly enough) for languages to their
official encoding (<filename>doc/en</filename> would point to
<filename>en_US.ISO-8859-1</filename>).</para>
<para><varname>DOC_PREFIX</varname> is the path to the root of the
FreeBSD Document Project tree. This is not always that easy to
find, and is also easily overridden, to allow for flexibility.
<varname>.CURDIR</varname> is a <application>make</application>
builtin variable with the path to the current directory.</para>
<para>The final line includes the FreeBSD Documentation Project's
project-wide <application>make</application> system file
<filename>doc.project.mk</filename> which is the glue which
converts these variables into build instructions.</para>
</sect2>
<sect2 xml:id="doc-make">
<title>Documentation Makefiles</title>
<para>These <filename>Makefile</filename>s set a bunch of
<application>make</application> variables that describe how to
build the documentation contained in that directory.</para>
<para>Here is an example:</para>
<programlisting>MAINTAINER=nik@FreeBSD.org
DOC?= book
FORMATS?= html-split html
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
# SGML content
SRCS= book.xml
DOC_PREFIX?= ${.CURDIR}/../../..
.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
<para>The <varname>MAINTAINER</varname> variable is a very
important one. This variable provides the ability to claim
ownership over a document in the FreeBSD Documentation
Project, whereby you gain the responsibility for maintaining
it.</para>
<para><varname>DOC</varname> is the name (sans the
<filename>.xml</filename> extension) of the main document
created by this directory. <varname>SRCS</varname> lists all
the individual files that make up the document. This should
also include important files in which a change should result
in a rebuild.</para>
<para><varname>FORMATS</varname> indicates the default formats
that should be built for this document.
<varname>INSTALL_COMPRESSED</varname> is the default list of
compression techniques that should be used in the document
build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by
default, should be non-empty if only compressed documents are
desired in the build.</para>
<note>
<para>We covered optional variable assignments in the
<link linkend="sub-make">previous section</link>.</para>
</note>
<para>The <varname>DOC_PREFIX</varname> and include statements
should be familiar already.</para>
</sect2>
</sect1>
<sect1 xml:id="make-includes">
<title>FreeBSD Documentation Project make includes</title>
<para>This is best explained by inspection of the code. Here are
the system include files:</para>
<itemizedlist>
<listitem>
<para><filename>doc.project.mk</filename> is the main project
include file, which includes all the following include files, as
necessary.</para>
</listitem>
<listitem>
<para><filename>doc.subdir.mk</filename> handles traversing of
the document tree during the build and install processes.</para>
</listitem>
<listitem>
<para><filename>doc.install.mk</filename> provides variables
that affect ownership and installation of documents.</para>
</listitem>
<listitem>
<para><filename>doc.docbook.mk</filename> is included if
<varname>DOCFORMAT</varname> is <literal>docbook</literal>
and <varname>DOC</varname> is set.</para>
</listitem>
</itemizedlist>
<sect2>
<title>doc.project.mk</title>
<para>By inspection:</para>
<programlisting>DOCFORMAT?= docbook
MAINTAINER?= doc@FreeBSD.org
PREFIX?= /usr/local
PRI_LANG?= en_US.ISO8859-1
.if defined(DOC)
.if ${DOCFORMAT} == "docbook"
.include "doc.docbook.mk"
.endif
.endif
.include "doc.subdir.mk"
.include "doc.install.mk"</programlisting>
<sect3>
<title>Variables</title>
<para><varname>DOCFORMAT</varname> and <varname>MAINTAINER</varname>
are assigned default values, if these are not set by the
document make file.</para>
<para><varname>PREFIX</varname> is the prefix under which the
<link linkend="tools">documentation building tools</link> are
installed. For normal package and port installation, this is
<filename>/usr/local</filename>.</para>
<para><varname>PRI_LANG</varname> should be set to whatever
language and encoding is natural amongst users these documents are
being built for. US English is the default.</para>
<note>
<para><varname>PRI_LANG</varname> in no way affects what documents
can, or even will, be built. Its main use is creating links to
commonly referenced documents into the FreeBSD documentation
install root.</para>
</note>
</sect3>
<sect3>
<title>Conditionals</title>
<para>The <literal>.if defined(DOC)</literal> line is an example of
a <application>make</application> conditional which, like in
other programs, defines behavior if some condition is true or
if it is false. <literal>defined</literal> is a function which
returns whether the variable given is defined or not.</para>
<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
tests whether the <varname>DOCFORMAT</varname> variable is
<literal>"docbook"</literal>, and in this case, includes
<filename>doc.docbook.mk</filename>.</para>
<para>The two <literal>.endif</literal>s close the two above
conditionals, marking the end of their application.</para>
</sect3>
</sect2>
<sect2>
<title>doc.subdir.mk</title>
<para>This is too long to explain by inspection, you should be
able to work it out with the knowledge gained from the previous
chapters, and a little help given here.</para>
<sect3>
<title>Variables</title>
<itemizedlist>
<listitem>
<para><varname>SUBDIR</varname> is a list of subdirectories
that the build process should go further down
into.</para>
</listitem>
<listitem>
<para><varname>ROOT_SYMLINKS</varname> is the name of
directories that should be linked to the document
install root from their actual locations, if the current
language is the primary language (specified by
<varname>PRI_LANG</varname>).</para>
</listitem>
<listitem>
<para><varname>COMPAT_SYMLINK</varname> is described in the
<link linkend="sub-make">Subdirectory Makefile</link>
section.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Targets and macros</title>
<para>Dependencies are described by
<literal>target:
dependency1 dependency2 ...</literal>
tuples, where to build <literal>target</literal>, you need to build
the given dependencies first.</para>
<para>After that descriptive tuple, instructions on how to build
the target may be given, if the conversion process between the
target and its dependencies are not previously defined, or if
this particular conversion is not the same as the default
conversion method.</para>
<para>A special dependency <literal>.USE</literal> defines
the equivalent of a macro.</para>
<programlisting>_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===&gt; ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} &amp;&amp; \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>
<para>In the above, <buildtarget>_SUBDIRUSE</buildtarget> is now a
macro which will execute the given commands when it is listed
as a dependency.</para>
<para>What sets this macro apart from other targets? Basically,
it is executed <emphasis>after</emphasis> the instructions
given in the build procedure it is listed as a dependency to,
and it does not adjust <varname>.TARGET</varname>, which is the
variable which contains the name of the target currently
being built.</para>
<programlisting>clean: _SUBDIRUSE
rm -f ${CLEANFILES}</programlisting>
<para>In the above, <buildtarget>clean</buildtarget> will use the
<buildtarget>_SUBDIRUSE</buildtarget> macro after it has
executed the instruction
<command>rm -f ${CLEANFILES}</command>. In effect, this causes
<buildtarget>clean</buildtarget> to go further and further down
the directory tree, deleting built files as it goes
<emphasis>down</emphasis>, not on the way back up.</para>
<sect4>
<title>Provided targets</title>
<itemizedlist>
<listitem>
<para><buildtarget>install</buildtarget> and
<buildtarget>package</buildtarget> both go down the
directory tree calling the real versions of themselves
in the subdirectories
(<buildtarget>realinstall</buildtarget> and
<buildtarget>realpackage</buildtarget>
respectively).</para>
</listitem>
<listitem>
<para><buildtarget>clean</buildtarget> removes files created
by the build process (and goes down the directory tree
too). <buildtarget>cleandir</buildtarget> does the same,
and also removes the object directory, if any.</para>
</listitem>
</itemizedlist>
</sect4>
</sect3>
<sect3>
<title>More on conditionals</title>
<itemizedlist>
<listitem>
<para><literal>exists</literal> is another condition
function which returns true if the given file exists.</para>
</listitem>
<listitem>
<para><literal>empty</literal> returns true if the given
variable is empty.</para>
</listitem>
<listitem>
<para><literal>target</literal> returns true if the given
target does not already exist.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Looping constructs in make (.for)</title>
<para><literal>.for</literal> provides a way to repeat a set of
instructions for each space-separated element in a variable.
It does this by assigning a variable to contain the current
element in the list being examined.</para>
<programlisting>_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===&gt; ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} &amp;&amp; \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>
<para>In the above, if <varname>SUBDIR</varname> is empty, no
action is taken; if it has one or more elements, the
instructions between <literal>.for</literal> and
<literal>.endfor</literal> would repeat for every element,
with <varname>entry</varname> being replaced with the value of
the current element.</para>
</sect3>
</sect2>
</sect1>
</chapter>

336
zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml
View file

@ -1,336 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2000 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.17
-->
<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="examples">
<title>範例</title>
<para>本附錄收錄一些 SGML 檔範例，以及用來轉換格式的相關指令。
若已成功安裝文件計畫工具包的話，那麼就可以直接照下面範例來使用。</para>
<para>這些例子並不是很詳細 &mdash; 並未包括你可能想用的元件，
尤其像是你文件的前頁(正文前的書頁，包括扉頁、序言、目錄等)
若需參考更多 DocBook 標記語言文件的話，那麼可以透過 <application>CSup</application>、<application>CVSup</application>
程式來抓 <literal>doc</literal> tree 部分，以察看本文件或其他文件的 SGML 原稿。
或者，也可以線上瀏覽
<uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/">http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/</uri>。</para>
<para>為了避免不必要的困擾，這些例子採用標準的 DocBook 4.1 DTD 而非 FreeBSD 額外的 DTD。
同時並採用 Norm Walsh 氏的樣式表(stylesheets)，而非 FreeBSD 文件計劃有自行改過的樣式表。
在一般使用 DocBook 的例子，這樣子會比較簡化環境，而不會造成額外困擾。</para>
<sect1 xml:id="examples-docbook-book">
<title>DocBook <tag>book</tag></title>
<example>
<title>DocBook <tag>book</tag></title>
<programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book lang='zh_tw'>
<bookinfo>
<title>樣本書的例子</title>
<author>
<firstname>名(first name)</firstname>
<surname>姓(surname)</surname>
<affiliation>
<address><email>foo@example.com</email></address>
</affiliation>
</author>
<copyright>
<year>2000</year>
<holder>相關版權字樣</holder>
</copyright>
<abstract>
<para>該書若有摘要，就寫在這邊。</para>
</abstract>
</bookinfo>
<preface>
<title>序言</title>
<para>該書若有序言，就放在這邊。</para>
</preface>
<chapter>
<title>第一章</title>
<para>這是這本書的第一章。</para>
<sect1>
<title>第一節</title>
<para>這本書的第一節。</para>
</sect1>
</chapter>
</book>]]></programlisting>
</example>
</sect1>
<sect1 xml:id="examples-docbook-article">
<title>DocBook <tag>article</tag></title>
<example>
<title>DocBook <tag>article</tag></title>
<programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article lang='zh_tw'>
<articleinfo>
<title>文章樣本</title>
<author>
<firstname>名(first name)</firstname>
<surname>姓(surname)</surname>
<affiliation>
<address><email>foo@example.com</email></address>
</affiliation>
</author>
<copyright>
<year>2000</year>
<holder>相關版權字樣</holder>
</copyright>
<abstract>
<para>該文章若有摘要，就寫在這邊。</para>
</abstract>
</articleinfo>
<sect1>
<title>第一節</title>
<para>該文章的第一節。</para>
<sect2>
<title>第一小節(sub-section)</title>
<para>該文章的第一小節(sub-section)</para>
</sect2>
</sect1>
</article>]]></programlisting>
</example>
</sect1>
<sect1 xml:id="examples-formatted">
<title>Producing formatted output</title>
<para>本節有些前提，假設：已經有裝 <package>textproc/docproj</package>
上面所安裝各軟體，無論它們是用 port 方式安裝或是手動安裝。
此外，假設所裝的軟體都放在 <filename>/usr/local/</filename> 下的子目錄，
並且所安裝的相關執行檔，都有裝在你的 <envar>PATH</envar> 環境變數內的目錄。
如有必要的話，請依你的系統環境而調整相關路徑。</para>
<sect2>
<title>使用 Jade</title>
<example>
<title>轉換 DocBook 為 HTML (完整模式)</title>
<screen>&prompt.user; <userinput>jade -V nochunks \ <co xml:id="examples-co-jade-1-nochunks"/>
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-1-catalog"/>
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-1-dsssl"/>
-t sgml <co xml:id="examples-co-jade-1-transform"/> file.xml &gt; file.html <co xml:id="examples-co-jade-1-filename"/></userinput></screen>
<calloutlist>
<callout arearefs="examples-co-jade-1-nochunks">
<para>Specifies the <literal>nochunks</literal> parameter to the
stylesheets, forcing all output to be written to
<abbrev>STDOUT</abbrev> (using Norm Walsh's stylesheets).</para>
</callout>
<callout arearefs="examples-co-jade-1-catalog">
<para>Specifies the catalogs that Jade will need to process.
Three catalogs are required. The first is a catalog that
contains information about the DSSSL stylesheets. The second
contains information about the DocBook DTD. The third contains
information specific to Jade.</para>
</callout>
<callout arearefs="examples-co-jade-1-dsssl">
<para>Specifies the full path to the DSSSL stylesheet that Jade
will use when processing the document.</para>
</callout>
<callout arearefs="examples-co-jade-1-transform">
<para>Instructs Jade to perform a
<emphasis>transformation</emphasis> from one DTD to another. In
this case, the input is being transformed from the DocBook DTD
to the HTML DTD.</para>
</callout>
<callout arearefs="examples-co-jade-1-filename">
<para>Specifies the file that Jade should process, and redirects
output to the specified <filename>.html</filename> file.</para>
</callout>
</calloutlist>
</example>
<example>
<title>轉換 DocBook 為 HTML (章節模式)</title>
<screen>&prompt.user; <userinput>jade \
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-2-catalog"/>
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-2-dsssl"/>
-t sgml <co xml:id="examples-co-jade-2-transform"/> file.xml <co xml:id="examples-co-jade-2-filename"/></userinput></screen>
<calloutlist>
<callout arearefs="examples-co-jade-2-catalog">
<para>Specifies the catalogs that Jade will need to process.
Three catalogs are required. The first is a catalog that
contains information about the DSSSL stylesheets. The second
contains information about the DocBook DTD. The third contains
information specific to Jade.</para>
</callout>
<callout arearefs="examples-co-jade-2-dsssl">
<para>Specifies the full path to the DSSSL stylesheet that Jade
will use when processing the document.</para>
</callout>
<callout arearefs="examples-co-jade-2-transform">
<para>Instructs Jade to perform a
<emphasis>transformation</emphasis> from one DTD to another. In
this case, the input is being transformed from the DocBook DTD
to the HTML DTD.</para>
</callout>
<callout arearefs="examples-co-jade-2-filename">
<para>Specifies the file that Jade should process. The
stylesheets determine how the individual HTML files will be
named, and the name of the <quote>root</quote> file (i.e., the
one that contains the start of the document.</para>
</callout>
</calloutlist>
<para>This example may still only generate one HTML file, depending on
the structure of the document you are processing, and the
stylesheet's rules for splitting output.</para>
</example>
<example xml:id="examples-docbook-postscript">
<title>轉換 DocBook 為 Postscript(PS) 格式</title>
<para>The source SGML file must be converted to a &tex; file.</para>
<screen>&prompt.user; <userinput>jade -Vtex-backend \ <co xml:id="examples-co-jade-3-tex-backend"/>
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-3-catalog"/>
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \<co xml:id="examples-co-jade-3-dsssl"/>
-t tex <co xml:id="examples-co-jade-3-tex"/> file.xml</userinput></screen>
<calloutlist>
<callout arearefs="examples-co-jade-3-tex-backend">
<para>Customizes the stylesheets to use various options
specific to producing output for &tex;.</para>
</callout>
<callout arearefs="examples-co-jade-3-catalog">
<para>Specifies the catalogs that Jade will need to process. Three
catalogs are required. The first is a catalog that contains
information about the DSSSL stylesheets. The second contains
information about the DocBook DTD. The third contains
information specific to Jade.</para>
</callout>
<callout arearefs="examples-co-jade-3-dsssl">
<para>Specifies the full path to the DSSSL stylesheet that
Jade will use when processing the document.</para>
</callout>
<callout arearefs="examples-co-jade-3-tex">
<para>Instructs Jade to convert the output to &tex;.</para>
</callout>
</calloutlist>
<para>The generated <filename>.tex</filename> file must now be run
through <command>tex</command>, specifying the
<literal>&amp;jadetex</literal> macro package.</para>
<screen>&prompt.user; <userinput>tex "&amp;jadetex" file.tex</userinput></screen>
<para>You have to run <command>tex</command> <emphasis>at
least</emphasis> three times. The first run processes the
document, and determines areas of the document which are referenced
from other parts of the document, for use in indexing, and so
on.</para>
<para>Do not be alarmed if you see warning messages such as
<literal>LaTeX Warning: Reference `136' on page 5 undefined on input
line 728.</literal> at this point.</para>
<para>The second run reprocesses the document now that certain pieces
of information are known (such as the document's page length). This
allows index entries and other cross-references to be fixed
up.</para>
<para>The third pass performs any final cleanup necessary.</para>
<para>The output from this stage will be
<filename>file.dvi</filename>.</para>
<para>Finally, run <command>dvips</command> to convert the
<filename>.dvi</filename> file to Postscript.</para>
<screen>&prompt.user; <userinput>dvips -o file.ps file.dvi</userinput></screen>
</example>
<example>
<title>轉換 DocBook 為 PDF 格式</title>
<para>The first part of this process is identical to that when
converting DocBook to Postscript, using the same
<command>jade</command> command line (<xref linkend="examples-docbook-postscript"/>).</para>
<para>When the <filename>.tex</filename> file has been generated you
run pdfTeX. However, use the &amp;pdfjadetex macro package
instead.</para>
<screen>&prompt.user; <userinput>pdftex "&amp;pdfjadetex" file.tex</userinput></screen>
<para>Again, run this command three times.</para>
<para>This will generate
<filename>file.pdf</filename>, which does
not need to be processed any further.</para>
</example>
</sect2>
</sect1>
</appendix>

241
zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml
View file

@ -1,241 +0,0 @@
<?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>

165
zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml
View file

@ -1,165 +0,0 @@
<?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.10
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="psgml-mode">
<title>Using <literal>sgml-mode</literal> with
<application>Emacs</application></title>
<para>Recent versions of <application>Emacs</application> or <application>XEmacs</application> (available from the ports
collection) contain a very useful package called PSGML. Automatically
invoked when a file with the <filename>.xml</filename> extension is loaded,
or by typing <command>M-x sgml-mode</command>, it is a major mode for
dealing with SGML files, elements and attributes.</para>
<para>An understanding of some of the commands provided by this mode can
make working with SGML documents such as the Handbook much easier.</para>
<variablelist>
<varlistentry>
<term><command>C-c C-e</command></term>
<listitem>
<para>Runs <literal>sgml-insert-element</literal>. You will be
prompted for the name of the element to insert at the current point.
You can use the TAB key to complete the element. Elements that are
not valid at the current point will be disallowed.</para>
<para>The start and end tags for the element will be inserted. If the
element contains other, mandatory, elements then these will be
inserted as well.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c =</command></term>
<listitem>
<para>Runs <literal>sgml-change-element-name</literal>. Place the
point within an element and run this command. You will be prompted
for the name of the element to change to. Both the start and end
tags of the current element will be changed to the new
element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-r</command></term>
<listitem>
<para>Runs <literal>sgml-tag-region</literal>. Select some text (move
to start of text, C-space, move to end of text, C-space) and then
run this command. You will be prompted for the element to use. This
element will then be inserted immediately before and after your
marked region.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c -</command></term>
<listitem>
<para>Runs <literal>sgml-untag-element</literal>. Place the point
within the start or end tag of an element you want to remove, and
run this command. The element's start and end tags will be
removed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-q</command></term>
<listitem>
<para>Runs <literal>sgml-fill-element</literal>. Will recursively fill
(i.e., reformat) content from the current element in. The filling
<emphasis>will</emphasis> affect content in which whitespace is
significant, such as within <tag>programlisting</tag>
elements, so run this command with care.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-a</command></term>
<listitem>
<para>Runs <literal>sgml-edit-attributes</literal>. Opens a second
buffer containing a list of all the attributes for the closest
enclosing element, and their current values. Use TAB to navigate
between attributes, <command>C-k</command> to remove an existing
value and replace it with a new one, <command>C-c C-c</command>
to close this buffer and return to the main document.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-v</command></term>
<listitem>
<para>Runs <literal>sgml-validate</literal>. Prompts you to save the
current document (if necessary) and then runs an SGML validator. The
output from the validator is captured into a new buffer, and you can
then navigate from one troublespot to the next, fixing markup errors
as you go.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c /</command></term>
<listitem>
<para>Runs <literal>sgml-insert-end-tag</literal>. Inserts the
end tag for the current open element.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Doubtless there are other useful functions of this mode, but those are
the ones I use most often.</para>
<para>You can also use the following entries in
<filename>.emacs</filename> to set proper spacing, indentation,
and column width for working with the Documentation Project.</para>
<programlisting>
(defun local-sgml-mode-hook
(setq fill-column 70
indent-tabs-mode nil
next-line-add-newlines nil
standard-indent 4
sgml-indent-data t)
(auto-fill-mode t)
(setq sgml-catalog-files '("/usr/local/share/xml/catalog")))
(add-hook 'psgml-mode-hook
'(lambda () (local-psgml-mode-hook)))
</programlisting>
</chapter>

122
zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml
View file

@ -1,122 +0,0 @@
<?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.13
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="see-also">
<title>他山之石</title>
<para>This document is deliberately not an exhaustive discussion of SGML,
the DTDs listed, and the FreeBSD Documentation Project. For more
information about these, you are encouraged to see the following web
sites.</para>
<sect1 xml:id="see-also-fdp">
<title>The FreeBSD Documentation Project</title>
<itemizedlist>
<listitem>
<para><link xlink:href="&url.base;/docproj/index.html">The FreeBSD
Documentation Project web pages</link></para>
</listitem>
<listitem>
<para><link xlink:href="&url.books.handbook;/index.html">The FreeBSD Handbook</link></para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="see-also-sgml">
<title>SGML</title>
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.oasis-open.org/cover/">The SGML/XML web
page</link>, a comprehensive SGML resource</para>
</listitem>
<listitem>
<para><link xlink:href="http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;id=SG">Gentle introduction to SGML</link></para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="see-also-html">
<title>HTML</title>
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.w3.org/">The World Wide Web
Consortium</link></para>
</listitem>
<listitem>
<para><link xlink:href="http://www.w3.org/TR/REC-html40/">The HTML 4.0
specification</link></para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="see-also-docbook">
<title>DocBook</title>
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.oasis-open.org/docbook/">The DocBook
Technical Committee</link>, maintainers of the DocBook DTD</para>
</listitem>
<listitem>
<para><link xlink:href="http://www.docbook.org/">DocBook: The Definitive
Guide</link>, the online documentation for the DocBook
DTD.</para>
</listitem>
<listitem>
<para><link xlink:href="http://docbook.sourceforge.net/">The DocBook Open
Repository</link> contains DSSSL stylesheets and other resources
for people using DocBook.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="see-also-linuxdoc">
<title>The Linux Documentation Project</title>
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.linuxdoc.org/">The Linux Documentation
Project web pages</link></para>
</listitem>
</itemizedlist>
</sect1>
</chapter>

2682
zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml
View file

File diff suppressed because it is too large Load diff

1543
zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml
View file

File diff suppressed because it is too large Load diff

281
zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml
View file

@ -1,281 +0,0 @@
<?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.17
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">
<title>Structuring documents under <filename>doc/</filename></title>
<para>The <filename>doc/</filename> tree is organized in a particular
fashion, and the documents that are part of the FDP are in turn organized
in a particular fashion. The aim is to make it simple to add new
documentation into the tree and:</para>
<orderedlist>
<listitem>
<para>make it easy to automate converting the document to other formats;</para>
</listitem>
<listitem>
<para>promote consistency between the different documentation
organizations, to make it easier to switch between working on
different documents;</para>
</listitem>
<listitem>
<para>make it easy to decide where in the tree new documentation should
be placed.</para>
</listitem>
</orderedlist>
<para>In addition, the documentation tree has to accommodate documentation
that could be in many different languages and in many different
encodings. It is important that the structure of the documentation tree
does not enforce any particular defaults or cultural preferences.</para>
<sect1 xml:id="structure-top">
<title>The top level, <filename>doc/</filename></title>
<para>There are two types of directory under <filename>doc/</filename>,
each with very specific directory names and meanings.</para>
<segmentedlist>
<segtitle>Directory</segtitle>
<segtitle>Meaning</segtitle>
<seglistitem>
<seg><filename>share/</filename></seg>
<seg>Contains files that are not specific to the various translations
and encodings of the documentation. Contains subdirectories to
further categorize the information. For example, the files that
comprise the &man.make.1; infrastructure are in
<filename>share/mk</filename>, while the additional SGML support
files (such as the FreeBSD extended DocBook DTD) are in
<filename>share/xml</filename>.</seg>
</seglistitem>
<seglistitem>
<seg><filename>lang.encoding/</filename></seg>
<seg>One directory exists for each available translation and encoding
of the documentation, for example
<filename>en_US.ISO8859-1/</filename> and
<filename>zh_TW.UTF-8/</filename>. The names are long, but by fully
specifying the language and encoding we prevent any future headaches
should a translation team want to provide the documentation in the
same language but in more than one encoding. This also completely
isolates us from any problems that might be caused by a switch to
Unicode.</seg>
</seglistitem>
</segmentedlist>
</sect1>
<sect1 xml:id="structure-locale">
<title>The
<filename>lang.encoding/</filename> directories</title>
<para>These directories contain the documents themselves. The
documentation is split into up to three more categories at this
level, indicated by the different directory names.</para>
<segmentedlist>
<segtitle>Directory</segtitle>
<segtitle>Contents</segtitle>
<seglistitem>
<seg><filename>articles</filename></seg>
<seg>Documentation marked up as a DocBook <tag>article</tag>
(or equivalent). Reasonably short, and broken up into sections.
Normally only available as one HTML file.</seg>
</seglistitem>
<seglistitem>
<seg><filename>books</filename></seg>
<seg>Documentation marked up as a DocBook <tag>book</tag> (or
equivalent). Book length, and broken up into chapters. Normally
available as both one large HTML file (for people with fast
connections, or who want to print it easily from a browser) and
as a collection of linked, smaller files.</seg>
</seglistitem>
<seglistitem>
<seg><filename>man</filename></seg>
<seg>For translations of the system manual pages. This directory will
contain one or more
<filename>mann</filename> directories,
corresponding to the sections that have been translated.</seg>
</seglistitem>
</segmentedlist>
<para>Not every
<filename>lang.encoding</filename> directory will contain all of these directories. It depends
on how much translation has been accomplished by that translation
team.</para>
</sect1>
<sect1 xml:id="structure-document">
<title>Document specific information</title>
<para>This section contains specific notes about particular documents
managed by the FDP.</para>
<sect2>
<title>The Handbook</title>
<subtitle><filename>books/handbook/</filename></subtitle>
<para>The Handbook is written to comply with the FreeBSD DocBook
extended DTD.</para>
<para>The Handbook is organized as a DocBook <tag>book</tag>.
It is then divided into <tag>part</tag>s, each of which may
contain several <tag>chapter</tag>s.
<tag>chapter</tag>s are further subdivided into sections
(<tag>sect1</tag>) and subsections (<tag>sect2</tag>,
<tag>sect3</tag>) and so on.</para>
<sect3>
<title>Physical organization</title>
<para>There are a number of files and directories within the
<filename>handbook</filename> directory.</para>
<note>
<para>The Handbook's organization may change over time, and this
document may lag in detailing the organizational changes. If you
have any questions about how the Handbook is organized, please
contact the &a.doc;.</para>
</note>
<sect4>
<title><filename>Makefile</filename></title>
<para>The <filename>Makefile</filename> defines some variables that
affect how the SGML source is converted to other formats, and
lists the various source files that make up the Handbook. It then
includes the standard <filename>doc.project.mk</filename> file, to
bring in the rest of the code that handles converting documents
from one format to another.</para>
</sect4>
<sect4>
<title><filename>book.xml</filename></title>
<para>This is the top level document in the Handbook. It contains
the Handbook's <link linkend="sgml-primer-doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that describe the
Handbook's structure.</para>
<para><filename>book.xml</filename> uses <link linkend="sgml-primer-parameter-entities">parameter
entities</link> to load in the files with the
<filename>.ent</filename> extension. These files (described later)
then define <link linkend="sgml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
</sect4>
<sect4>
<title><filename>directory/chapter.xml</filename></title>
<para>Each chapter in the Handbook is stored in a file called
<filename>chapter.xml</filename> in a separate directory from the
other chapters. Each directory is named after the value of the
<literal>id</literal> attribute on the <tag>chapter</tag>
element.</para>
<para>For example, if one of the chapter files contains:</para>
<programlisting><![CDATA[
<chapter id="kernelconfiguration">
...
</chapter>]]></programlisting>
<para>then it will be called <filename>chapter.xml</filename> in
the <filename>kernelconfiguration</filename> directory. In
general, the entire contents of the chapter will be held in this
file.</para>
<para>When the HTML version of the Handbook is produced, this will
yield <filename>kernelconfiguration.html</filename>. This is
because of the <literal>id</literal> value, and is not related to
the name of the directory.</para>
<para>In earlier versions of the Handbook the files were stored in
the same directory as <filename>book.xml</filename>, and named
after the value of the <literal>id</literal> attribute on the
file's <tag>chapter</tag> element. Moving them into
separate directories prepares for future plans for the Handbook.
Specifically, it will soon be possible to include images in each
chapter. It makes more sense for each image to be stored in a
directory with the text for the chapter than to try to keep the
text for all the chapters, and all the images, in one large
directory. Namespace collisions would be inevitable, and it is
easier to work with several directories with a few files in them
than it is to work with one directory that has many files in
it.</para>
<para>A brief look will show that there are many directories with
individual <filename>chapter.xml</filename> files, including
<filename>basics/chapter.xml</filename>,
<filename>introduction/chapter.xml</filename>, and
<filename>printing/chapter.xml</filename>.</para>
<important>
<para>Chapters and/or directories should not be named in a fashion
that reflects their ordering within the Handbook. This ordering
might change as the content within the Handbook is reorganized;
this sort of reorganization should not (generally) include the
need to rename files (unless entire chapters are being promoted
or demoted within the hierarchy).</para>
</important>
<para>Each <filename>chapter.xml</filename> file will not be a
complete SGML document. In particular, they will not have their
own DOCTYPE lines at the start of the files.</para>
<para>This is unfortunate as
it makes it impossible to treat these as generic SGML
files and simply convert them to HTML, RTF, PS, and other
formats in the same way the main Handbook is generated. This
<emphasis>would</emphasis> force you to rebuild the Handbook
every time you want to see the effect a change has had on just
one chapter.</para>
</sect4>
</sect3>
</sect2>
</sect1>
</chapter>

92
zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml
View file

@ -1,92 +0,0 @@
<?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.12
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="stylesheets">
<title>* Stylesheets</title>
<para>SGML says nothing about how a document should be displayed to the
user, or rendered on paper. To do that, various languages have been
developed to describe stylesheets, including DynaText, Panorama, SPICE,
JSSS, FOSI, CSS, and DSSSL.</para>
<para>For DocBook, we are using stylesheets written in DSSSL. For HTML we
are using CSS.</para>
<sect1 xml:id="stylesheets-dsssl">
<title>* DSSSL</title>
<para>The Documentation Project uses a slightly customized version of
Norm Walsh's modular DocBook stylesheets.</para>
<para>These can be found in
<package>textproc/dsssl-docbook-modular</package>.</para>
<para>The modified stylesheets are not in the ports system. Instead they
are part of the Documentation Project source repository, and can be
found in <filename>doc/share/xml/freebsd.dsl</filename>. It is well
commented, and pending completion of this section you are encouraged to
examine that file to see how some of the available options in the
standard stylesheets have been configured in order to customize the
output for the FreeBSD Documentation Project. That file also contains
examples showing how to extend the elements that the stylesheet
understands, which is how the FreeBSD specific elements have been
formatted.</para>
</sect1>
<sect1 xml:id="stylesheets-css">
<title>CSS</title>
<para>Cascading Stylesheets (CSS) are a mechanism for attaching style
information (font, weight, size, color, and so forth) to elements in an
HTML document without abusing HTML to do so.</para>
<sect2>
<title>The Web site (HTML documents)</title>
<para>The FreeBSD web site does not currently use CSS. Unfortunately,
the look and feel is constructed using abuses of HTML of varying
degrees. This should be fixed, and would be a good project for
someone looking to contribute to the documentation project.</para>
</sect2>
<sect2>
<title>The DocBook documents</title>
<para>The FreeBSD DSSSL stylesheets include a reference to a stylesheet,
<filename>docbook.css</filename>, which is expected to appear in the
same directory as the HTML files. The project-wide CSS file is copied
from <filename>doc/share/misc/docbook.css</filename> when documents
are converted to HTML, and is installed automatically.</para>
</sect2>
</sect1>
</chapter>

191
zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml
View file

@ -1,191 +0,0 @@
<?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.22
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
<title>建構 Website</title>
<sect1 xml:id="the-website-prep">
<title>事前準備</title>
<para>請先準備約 200MB 空間，這些是要用來放 SGML 工具程式、CVS tree、
臨時編譯用的空間，以及編譯好的網頁存放空間。若事先已有裝 SGML 工具程式、
CVS tree 的話，那麼只需頂多約 100MB 空間即可。</para>
<note>
<para>請確認一下你的相關文件製作所會用到的 ports 都是最新版！
若不清楚所裝的版本為何，那麼就先以 &man.pkg.delete.1; 指令來移除舊版，
接著才去裝 port。 舉例來說，若已裝的是 jade-1.1，
但是我們目前需要的卻是 jade-1.2，那麼先用下列方式來移除舊版：</para>
<screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen>
</note>
<para>接著，就是設定 CVS repository。需要至少 www, doc, ports 這三樣
CVS tree(當然還要加上 CVSROOT)。 請參閱
<link xlink:href="&url.books.handbook;/synching.html#CVSUP">CVSup 簡介</link>
以瞭解如何來 mirror a CVS tree 或部分 CVS tree。</para>
<para>最低需求的 cvsup collections 為：<literal>www</literal>,
<literal>doc-all</literal>, <literal>cvs-base</literal> 以及
<literal>ports-base</literal>。</para>
<para>剛講的這些需要約 105MB 空間。</para>
<para>而完整的 CVS tree - 包括 <literal>src</literal>,
<literal>doc</literal>, <literal>www</literal> 以及
<literal>ports</literal> - 目前約為 940MB。</para>
</sect1>
<sect1 xml:id="the-website-build">
<title>Build the web pages from scratch</title>
<procedure>
<step>
<para>先建立要編譯的目錄(至少要有 60MB 空間)，並切換到該目錄。</para>
<screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput>
&prompt.root; <userinput>cd /var/tmp/webbuild</userinput></screen>
</step>
<step>
<para>從 CVS tree 內 checkout 相關的 SGML 檔。</para>
<screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen>
</step>
<step>
<para>切到 <filename>www/en</filename> 目錄，然後打
&man.make.1; <buildtarget>all</buildtarget> 來產生網頁。</para>
<screen>&prompt.root; <userinput>cd en</userinput>
&prompt.root; <userinput>make all</userinput></screen>
</step>
</procedure>
</sect1>
<sect1 xml:id="the-website-install">
<title>在你的網頁伺服器上安裝網頁</title>
<procedure>
<step>
<para>如果你已經離開 <filename>en</filename>
這個目錄，請切換回這個目錄中。</para>
<screen>&prompt.root; <userinput>cd path/www/en</userinput></screen>
</step>
<step>
<para>執行 &man.make.1; <buildtarget>install</buildtarget> ，
並將 <varname>DESTDIR</varname> 設定為你想安裝檔案的目錄名稱。</para>
<screen>&prompt.root; <userinput>make DESTDIR=/usr/local/www install</userinput></screen>
</step>
<step>
<para>如果你之前已經在相同的目錄中安裝了這些網頁，
安裝過程並不會刪除任何既有或過期的網頁。
舉例來說，如果你每日建構和安裝新的網頁副本，
這個指令將會搜尋並刪除在三天內沒有更新的檔案。</para>
<screen>&prompt.root; <userinput>find /usr/local/www -ctime 3 -print0 | xargs -0 rm</userinput></screen>
</step>
</procedure>
</sect1>
<sect1 xml:id="the-website-env">
<title>環境變數</title>
<variablelist>
<varlistentry>
<term><envar>CVSROOT</envar></term>
<listitem>
<para>設定 CVS tree 的位置，此為必備條件。</para>
<screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ENGLISH_ONLY</varname></term>
<listitem>
<para>如果設定這個環境變數，而且值不為空白，
makefiles 將只會建構和安裝英文文件。
所以將會略過其他的各國翻譯。例如：</para>
<screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen>
<para>如果你想要取消變數 <varname>ENGLISH_ONLY</varname>
以及建構所有的頁面並包括翻譯，只要將變數 <varname>ENGLISH_ONLY</varname>
的值設定成空白即可。</para>
<screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>WEB_ONLY</varname></term>
<listitem>
<para>如果有設定這個變數的話，
makefiles 將只會從 www 目錄建構及安裝 HTML 頁面。
所有從 doc 目錄下的文件全部都會被忽略 (Handbook, FAQ, Tutorials)。
例如：</para>
<screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>NOPORTSCVS</varname></term>
<listitem>
<para>如果設了這個變數，makefiles 就不會從 ports cvs repository
取出檔案。 取而代之會從
<filename>/usr/ports</filename> (或是 <envar>PORTSBASE</envar>
所設定的值) 內複製檔案。</para>
</listitem>
</varlistentry>
</variablelist>
<para><envar>CVSROOT</envar> 是環境變數。
你必須直接使用指令或是在 dot files (如： ~/.profile) 中
設定這個環境變數。</para>
<para><varname>WEB_ONLY</varname>、<varname>ENGLISH_ONLY</varname> 及
<varname>NOPORTSCVS</varname> 都是 makefile 變數。
你可以在 <filename>/etc/make.conf</filename>、<filename>Makefile.inc</filename>
中設定這些變數，作法就像是用命令列或使用 dot files 來設定環境變數一般。</para>
</sect1>
</chapter>

235
zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml
View file

@ -1,235 +0,0 @@
<?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.32
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools">
<title>工具</title>
<para>FDP 使用一堆工具來協助管理 FreeBSD 文件、轉換文件格式等等。
因此，若要進行 FDP 工作的話，必須要學會這些工具才行。</para>
<para>這些工具都可以用 Ports 或 Packages 來安裝，以節省許多安裝的工夫。</para>
<para>您必須安裝這些工具，才能使用接下來各章節會介紹到的例子。 這些工具的用法，會在後續相關章節談到。 </para>
<tip>
<title>建議安裝 <package>textproc/docproj</package></title>
<para>裝了
<package>textproc/docproj</package> 可以更省時省力，它是個
組合型的 port(meta-port)，本身並非軟體，只是將一些常用工具組合起來而已。
裝了這個 port 之後，『應該』就會自動下載、安裝本章所會介紹到的工具了。
若要處理中文的話，建議再裝 <package>chinese/docproj</package> 會比較好。</para>
<para>在這些 packages 當中，你可能會需要使用 JadeTeX 這個 macro 設定，
一旦選擇使用該 macro 的話，它會接著去裝 &tex;。由於 &tex; 算是個蠻大的套件，
除非你需要輸出 Postscript 或 PDF 格式，否則就不必裝了。</para>
<para>所以請考慮是否要節省編譯時間、硬碟空間，以判定要不要裝 JadeTeX (以及 &tex;)
了。若要一併裝起來的話：</para>
<screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
<para>或是，不裝的話：</para>
<screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
<para>或者，也可以選擇 <package>textproc/docproj-jadetex</package> 或是 <package>textproc/docproj-nojadetex</package> 這兩個之一來裝，
它們都是已事先設定 <varname>JADETEX</varname> 變數的 slave ports，
都一樣會裝 docproj 差別僅在於有沒有 JadeTeX 而已。
請注意：若只要輸出 HTML 或 ASCII 格式文件，那就不用裝 <application>JadeTeX</application>，
而若要輸出 PostScript、PDF 格式，就需要裝 &tex; 才行。</para>
</tip>
<sect1 xml:id="tools-mandatory">
<title>必備工具</title>
<sect2>
<title>軟體</title>
<para>這些都是在進行 FreeeBSD 文件計劃時所會需要用上的工具程式，
而且可以用來轉換文件為 HTML、plain text以及 RTF 格式。這些相關套件在
<package>textproc/docproj</package> 都已經全部收錄了。</para>
<variablelist>
<varlistentry>
<term><application>Jade</application>
(<package>textproc/jade</package>)</term>
<listitem>
<para>DSSSL 規格的實作程式，可用來把標記語言的文件(marked up)轉換為其他格式，像是：HTML 及 &tex;。</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Tidy</application>
(<package>www/tidy</package>)</term>
<listitem>
<para>HTML <quote>pretty printer</quote>，可用來把自動產生的 HTML 內容整理得更易閱讀、以便日後維護。</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Links</application>
(<package>www/links</package>)</term>
<listitem>
<para>文字操作模式的 WWW 瀏覽器(browser)可以把 HTML 檔轉為 plain text 格式。</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>peps</application>
(<package>graphics/peps</package>)</term>
<listitem>
<para>文件中有些圖是存成 EPS 格式的，這些必須要轉為 PNG 格式，
才能讓一般瀏覽器可以正常觀看。</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>DTD 及 Entity</title>
<para>由於 FDP 有用到許多 DTD 跟 Entity，因此在開工前，要裝上這些才行。</para>
<variablelist>
<varlistentry>
<term>HTML DTD (<package>textproc/html</package>)</term>
<listitem>
<para>HTML 是用於 WWW 的標記語言，且也是 FreeBSD 網頁所使用的格式。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DocBook DTD (<package>textproc/docbook</package>)</term>
<listitem>
<para>DocBook 是專門用來製作技術文件的標示語言版本，
FreeBSD 全部文件都是以 DocBook 所寫成的。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ISO 8879 entities
(<package>textproc/iso8879</package>)</term>
<listitem>
<para>在 ISO 8879:1986 之中有 19 個 entity 被許多 DTD 所大量使用，
包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>樣式表(Stylesheets)</title>
<para>這些樣式表都是用來轉換、重排文件的螢幕顯示、列印等效果處理</para>
<variablelist>
<varlistentry>
<term>Modular DocBook 樣式表
(<package>textproc/dsssl-docbook-modular</package>)</term>
<listitem>
<para>Modular DocBook 樣式表，是用來把 DocBook 的標記語言文件轉換為其他格式，像是：
HTML 或 RTF。</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 xml:id="tools-optional">
<title>輔助工具</title>
<para>不一定得裝下列的工具才行，但是，裝了之後會更容易進行各項工作，
而且可輸出的格式也更具彈性。</para>
<sect2>
<title>軟體</title>
<variablelist>
<varlistentry>
<term><application>JadeTeX</application> 及
<application>teTeX</application>
(<package>print/jadetex</package> 及
<package>print/teTeX</package>)</term>
<listitem>
<para><application>Jade</application> 與
<application>teTeX</application> 可用來把 DocBook 格式文件轉為
DVI, Postscript 及 PDF 格式。安裝時請記得加上
<application>JadeTeX</application> 這個 macro，這樣才會順便裝上這兩個套件。</para>
<para>若無意把文件轉換更多格式的話(舉例：只要 HTML, plain text, RTF 這些格式就夠的話)
，那麼就不用裝
<application>JadeTeX</application> 與
<application>teTeX</application>。 如此一來可省下一些的編譯時間、安裝空間，
因為 <application>teTeX</application> 大約要至少 30MB 空間。</para>
<important>
<para>若決定要裝
<application>JadeTeX</application> 以及
<application>teTeX</application> 的話，那麼在裝完 <application>JadeTeX</application> 之後，
要記得設定 <application>teTeX</application> 才行。
<filename>print/jadetex/pkg-message</filename> 內有詳細介紹相關步驟。</para>
</important>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Emacs</application> 或
<application>XEmacs</application>
(<package>editors/emacs</package> 或
<package>editors/xemacs</package>)</term>
<listitem>
<para>這兩者編輯器都具有處理 SGML DTD 標記文件的特殊模式。
該模式提供一些指令，來簡化所需的打字次數，而且可以減少可能發生的錯誤。</para>
<para>不過，這些編輯器並不是必備的；任何文字編輯器都可以用來編輯標記語言文件。
不過，你可以透過類似上述這樣的編輯器，來讓這些繁瑣作業更輕鬆有效率些。</para>
</listitem>
</varlistentry>
</variablelist>
<para>若有推薦其他好用的處理 SGML 文件程式，請來信讓 &a.doceng; 知道，
如此一來，該軟體就會列入這裡介紹了。</para>
</sect2>
</sect1>
</chapter>

383
zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml
View file

@ -1,383 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 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.29
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="translations">
<title>翻譯時的常見問題</title>
<para>本章是翻譯 FreeBSD 文件(包含：FAQ, Handbook, tutorials, manual pages等)的常見問題(FAQ)。</para>
<para>本文件 <emphasis>主要</emphasis> 是以 FreeBSD 德文翻譯計劃的翻譯 FAQ 為母本而來的，
原始撰稿者為 Frank Gr&uuml;nder <email>elwood@mc5sys.in-berlin.de</email> ，並由
Bernd Warken <email>bwarken@mayn.de</email> 再翻譯回英文版。</para>
<para>The FAQ is maintained by the &a.doceng;.</para>
<qandaset>
<qandaentry>
<question>
<para>FAQ 的目的是?</para>
</question>
<answer>
<para>隨著越來越多人參與 freebsd-doc 郵遞論壇，而且希望將 FreeBSD 文件翻譯為各種語言版本。
我們希望這份 FAQ 能儘可能為這些參與翻譯者提供快速的解惑。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para><phrase>i18n</phrase> 跟 <phrase>l10n</phrase> 是什麼呢？</para>
</question>
<answer>
<para><phrase>i18n</phrase> 是
<phrase>internationalization</phrase> 的簡寫，而 <phrase>l10n</phrase>
則是 <phrase>localization</phrase> 的簡寫。這些都是為了書寫方便而用的簡寫。</para>
<para><phrase>i18n</phrase> 就是開頭為 <quote>i</quote> 後面有 18 個字母，最後接 <quote>n</quote>。
同理，
<phrase>l10n</phrase> 則是開頭為 <quote>l</quote> 後面有 10 個字母，最後接 <quote>n</quote>。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>有專門給譯者參與討論的 mailing list 嗎？</para>
</question>
<answer>
<para>有啊，不同的語系翻譯者都各自有自屬的 mailing lists。這份 <link xlink:href="http://www.freebsd.org/docproj/translations.html">翻譯計劃清單</link>
有列出各翻譯計劃的詳細 mailing lists 及相關網站。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>需要更多人一起參與翻譯嗎？</para>
</question>
<answer>
<para>當然囉，越多人參與翻譯，那麼就能夠越快翻完，而且英文版文件若有增減、更新的話，
各翻譯版也可以儘快同步囉。</para>
<para>不一定得是專業譯者，才能參與翻譯的。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>有要求哪些語言能力呢？</para>
</question>
<answer>
<para>理論上，必須要對英文非常熟稔，而且很明顯地，對想翻譯的語言必須要能運用自如。</para>
<para>英文並非一定要會的。比如說，可以把西班牙文(Spanish)的 FAQ 翻譯為匈牙利文(Hungarian)。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>該學會哪些程式的使用呢？</para>
</question>
<answer>
<para>強烈建議在自己機器上也建立 FreeBSD CVS repository 的備份(至少文件部分)，可以用
<application>CTM</application> 或
<application>CVSup</application> 都可以。Handbook 中的 "更新、升級 FreeBSD"
一章內有提到如何使用這些程式。</para>
<para>此外，需要熟悉 <application>CVS</application> 用法。
如此一來，你可以查閱不同版本之間的差異處。</para>
<para>[XXX To Do(尚未撰稿，仍待補充) -- 寫份上手說明(tutorial)來介紹如何以 CVSup
取得文件部分，以及察看不同版本之間的差異。]</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>要怎麼找出來還有誰要跟我一起翻譯的呢？</para>
</question>
<answer>
<para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">文件計劃的翻譯</link> 這列了目前已知的各翻譯者成果
，如果已經有其他人也在做跟你一樣的翻譯工作，那麼請不要重複浪費人力，
請與他們聯繫看看還有哪些地方可以幫上忙的。</para>
<para>若上面並未列出你母語的翻譯，或是也有人要翻譯但還未公開宣布的話，那麼就寄信到 &a.doc; 吧。
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>都沒人翻譯為我所使用的語言，該怎麼辦？</para>
</question>
<answer>
<para>恭喜啊，你剛好踏上 <quote>FreeBSD
<replaceable>你的母語</replaceable> 文件翻譯計劃</quote> 的啟程之路，歡迎上船。</para>
<para>首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已，
因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。</para>
<para>寫信到 &a.doc; 向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料</para>
<para>若你的國家已經有人提供 FreeBSD 的 mirror(映設) 服務的話，那麼就先跟他們聯繫，
並詢問你是否在上面可以有網頁空間來放相關計劃資料，
以及是否可以有提供 email 帳號或 mailing list 服務。</para>
<para>然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些
&mdash; 像是 FAQ 啦，或是如何上手之類的說明文章。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>已經翻好一些文件了，該寄到哪呢？</para>
</question>
<answer>
<para>這要看情況而定。 若你是在翻譯團隊內做的話(像是日本、德國)，
他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。</para>
<para>若你是某語系的唯一翻譯者(或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃)
，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？</para>
<para>或者</para>
<para>我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？</para>
</question>
<answer>
<para>首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說：
把它擺到現有文件架構內是可以正確編譯成功的。</para>
<para>目前，FreeBSD 文件都是放在最上層的 <filename>doc/</filename> 目錄內。
而該目錄下的則依其語系來做分類命名的，依照 ISO639 定義(<filename>/usr/share/misc/iso639</filename>
的這個 FreeBSD 版本比 1999/01/20 還新)。</para>
<para>若你這個語系可能會有不同編碼方式(像是：中文)
那麼就應該會像下面這樣，來依你所使用的編碼方式細分。</para>
<para>最後，你應該建立好各文件的目錄了。</para>
<para>舉例來說，假設有瑞典文(Swedish)版的翻譯，那麼應該會長像：</para>
<programlisting>doc/
sv_SE.ISO8859-1/
Makefile
books/
faq/
Makefile
book.xml</programlisting>
<para><literal>sv_SE.ISO8859-1</literal> 是依照
<filename>語系(lang).編碼(encoding)</filename>
的規則來建立的譯名。
請注意：其中有兩個 <filename>Makefiles</filename> 檔，它們是用來編書的。</para>
<para>然後請用 &man.tar.1; 與 &man.gzip.1; 來把你的翻譯文件壓縮起來，並寄到本計劃來。</para>
<screen>&prompt.user; <userinput>cd doc</userinput>
&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen>
<para>接著，把 <filename>swedish-docs.tar.gz</filename> 放到網頁空間上，若你沒有自己網頁空間的話(ISP不提供)
，那麼可以該檔寄到 &a.doceng; 來。</para>
<para>還有，記得用 &man.send-pr.1; 以正式通知大家；你已經寄出翻譯文件了，
還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好，
因為這也有助於提升翻譯品質的流暢度。</para>
<para>最後，會有人(可能是文件計劃總管，或是 &a.doceng; 成員)
會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點：</para>
<orderedlist>
<listitem>
<para>你的檔案是否都有用 RCS tag (像是 "ID" 之類的)？</para>
</listitem>
<listitem>
<para><filename>sv_SE.ISO8859-1</filename> 是否可以順利 <command>make all</command> 編譯呢？</para>
</listitem>
<listitem>
<para><command>make install</command> 是否結果有正確？</para>
</listitem>
</orderedlist>
<para>若有問題的話，那麼檢閱者會叮嚀你，來讓這些翻譯成果可以正確使用。</para>
<para>若沒問題的話，那麼就會很快把你的翻譯成果 commit 進去了。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>可以加入某語系或某國家才有的東西到翻譯內容內嗎？</para>
</question>
<answer>
<para>我們希望不要這麼做。</para>
<para>舉例來說，假設你正準備把 Handbook 翻譯為韓文版，
並希望把韓國零售處也加到你翻譯的 Handbook 韓文版內。</para>
<para>我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 &hellip;)
因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。
此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。</para>
<para>若你有某國才有的資料，請(用 &man.send-pr.1; )提供給英文版 Handbook 以作為修訂
，然後再把英文版的修訂部分，翻為你要翻譯的 Handbook 吧。</para>
<para>感恩，謝謝。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>要怎麼把該語系特有的字元寫進去翻譯內容呢？</para>
</question>
<answer>
<para>文件內所有的非 ASCII(Non-ASCII) 字元，都要使用 SGML entities 才能寫進去。</para>
<para>簡單來說，長相一開頭會是 &amp; 符號(&amp;)，然後是該 entity 名稱，最後接上分號(;)。</para>
<para>這些 entity 名稱都是 ISO8879 所制訂的，而 port tree 內則在
<package>textproc/iso8879</package>。</para>
<para>以下舉一些例子：</para>
<segmentedlist>
<segtitle>Entity名稱</segtitle>
<segtitle>實際樣子</segtitle>
<segtitle>介紹</segtitle>
<seglistitem>
<seg>&amp;eacute;</seg>
<seg>&eacute;</seg>
<seg>小 <quote>e</quote>，並帶尖、重音(acute accent)</seg>
</seglistitem>
<seglistitem>
<seg>&amp;Eacute;</seg>
<seg>&Eacute;</seg>
<seg>大 <quote>E</quote>，並帶尖、重音(acute accent)</seg>
</seglistitem>
<seglistitem>
<seg>&amp;uuml;</seg>
<seg>&uuml;</seg>
<seg>小 <quote>u</quote>，並帶日耳曼語系中的母音變化(umlaut)</seg>
</seglistitem>
</segmentedlist>
<para>在裝了 iso8879 這個 port 之後，就可以在
<filename>/usr/local/share/xml/iso8879</filename> 找到這些的詳細列表。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>如何稱呼讀者呢？</para>
</question>
<answer>
<para>在英文文件內，讀者都是以 <quote>you</quote> 來稱呼，而有些語言並沒有正式/非正式的區隔。</para>
<para>若你所要翻的語言可以區別這些差異，那麼請用該語系在一般技術文件上所使用的稱呼吧。
如果容易造成困惑的話，那麼請改用較中性的稱呼來取代。</para>
<!--
摘自 http://fatpipi.cirx.org/~vanilla/rules.txt
如非必要，翻譯文章內盡量少用直接稱呼你我他的用字。
如果真的得用，就採用第三人稱(用【他】而非【你】)，還有就是用複數(用【你們】而非【你】)，
當然這還是得配合原文的上下語意。如果他是寫 "I" 而翻譯成 "我"，則無可厚非。
但是對於文內絕大多數的"You..... you ...etc"
其實都可以把【你】簡化或是避免掉，這對閱讀時候的順暢感應該有幫助。
-->
</answer>
</qandaentry>
<qandaentry>
<question>
<para>翻譯成果內要不要附上一些其他訊息呢？</para>
</question>
<answer>
<para>當然要。</para>
<para>每份英文版原稿的開頭，通常會有像下面的內容：</para>
<programlisting>&lt;!--
The FreeBSD Documentation Project
&dollar;FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.5 2000/07/07 18:38:38 dannyboy Exp &dollar;
--&gt;</programlisting>
<para>實際上的內容可能稍有不同，但每份原稿都會附上 &dollar;FreeBSD&dollar; 這一行以及
<literal>The FreeBSD Documentation Project</literal> 宣告。
請注意：&dollar;FreeBSD 開頭的這行是會由 CVS 隨著每次異動而自動更改的，
所以，新檔案的話請保持原狀(也就是只要寫 <literal>&dollar;FreeBSD&dollar;</literal> 就好了)。</para>
<para>翻譯文件中，必須都要有 &dollar;FreeBSD&dollar; 這行，並且把
<literal>FreeBSD Documentation Project</literal> 這行改為
<literal>The FreeBSD 你的語系
Documentation Project</literal>。</para>
<para>此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。</para>
<para>因此呢，西班牙文版(Spanish)的檔案開頭應該是長像這樣：</para>
<programlisting>&lt;!--
The FreeBSD Spanish Documentation Project
&dollar;FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.3 1999/06/24 19:12:32 jesusr Exp &dollar;
Original revision: 1.11
--&gt;</programlisting>
</answer>
</qandaentry>
</qandaset>
</chapter>

440
zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml
View file

@ -1,440 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 1998 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.48
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style">
<title>文件的撰寫風格</title>
<para>由於 FreeBSD 文件是由眾多作者所維護的，為了保持寫作風格的一貫性，
於是就產生較有共識的寫作規則，請各位記得要遵守。</para>
<variablelist>
<varlistentry>
<term>使用美式英語</term>
<listitem>
<para>同一個字在不同種類的英語會有著不同的拼法。
遇到拼字不同的情況，請採用美式英語拼法。 像是：
請改用 <quote>color</quote>，而非 <quote>colour</quote>。
請改用 <quote>rationalize</quote>，而非 <quote>rationalise</quote>
等等類似字彙。</para>
<note>
<para>若文章採用英式英語也可以接受，但必須全篇文章都採用同一拼法才行
。 而文件的其他部份，像是書、網頁、 manual
說明等則必須採用美式英語。</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>不要用簡寫</term>
<listitem>
<para>請不要簡寫(contraction)。 請務必將完整的字寫出來。 比如：
<quote>Don't use contractions</quote> 這句有用到簡寫，就要避免。</para>
<para>正式書面寫法避免簡寫的原因，乃是因為如此一來字句意思較精準，
且對譯者會比較輕鬆些。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>正確使用 serial comma 以及頓號</term>
<listitem>
<para>英文段落通常會逗號(,)作為該句所提到的各項目的語氣區隔。
並且會在最後一個提到的項目時，先加上逗號再接上 <quote>and</quote>，
最後才是最後的項目。</para>
<para>舉個例子，看看下面這句：</para>
<blockquote>
<para>This is a list of one, two and three items.</para>
</blockquote>
<para>那麼這一句到底是有三個項目(<quote>one</quote>、<quote>two</quote>
、<quote>three</quote>)呢？或者是只有兩個項目(<quote>one</quote>、
<quote>two and three</quote>)呢？</para>
<para>因此較妥的方式是以 serial comma 的方式，才能正確表達語意：</para>
<blockquote>
<para>This is a list of one, two, and three items.</para>
</blockquote>
<para>然而，在翻譯過程中，建議把逗號(,)部份改為頓號(、)，並且
<quote>and</quote> 的部份可略而不翻，以免語意頓塞。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>避免使用贅詞</term>
<listitem>
<para>請試著避免使用贅詞(redundant phrase)。 尤其是
<quote>這個指令</quote>、<quote>這個檔案</quote>、<quote>man
指令</quote> 這幾個通常都是不必要的贅詞。</para>
<para>以指令(command)方面舉例，比較妥當的用法是第二句的例子：</para>
<informalexample>
<para>使用 <command>cvsup</command> 指令來更新原始碼。</para>
</informalexample>
<informalexample>
<para>使用 <command>cvsup</command> 來更新原始碼。</para>
</informalexample>
<para>以檔案(filename)方面舉例，比較妥當的用法是第二句的例子：</para>
<informalexample>
<para>&hellip; 在這個
<filename>/etc/rc.local</filename> 檔案 &hellip;</para>
</informalexample>
<informalexample>
<para>&hellip; 在
<filename>/etc/rc.local</filename> 檔 &hellip;</para>
</informalexample>
<para>以 man(manual)方面舉例，比較妥當的用法是第二句(有用到 SGML
<tag>citerefentry</tag> 標籤)：</para>
<informalexample>
<para>請打 <command>man csh</command> 指令以參閱詳情說明。</para>
</informalexample>
<informalexample>
<para>詳情請參閱 &man.csh.1;。</para>
</informalexample>
</listitem>
</varlistentry>
<varlistentry>
<term>每句後面加上兩個空白</term>
<listitem>
<para>為了使文章更易閱讀，以及讓 <application>Emacs</application>
之類的工具容易運用，請在每一完整句子後面加上兩個空白。</para>
<para>不過，句號(.)後面有接大寫字母，
並不一定表示前一個句點所在處就是完整句子，
尤其是名字部份常常會有這現象。 像是 <quote>Jordan K. Hubbard</quote>
這人名就是很好的例證：句號後面接空白，然後是大寫的
<literal>H</literal>，然而這肯定並不是兩段句子。</para>
</listitem>
</varlistentry>
</variablelist>
<para>撰寫風格的相關細節，可參閱 William Strunk 所寫的 <link xlink:href="http://www.bartleby.com/141/">Elements of Style</link>。</para>
<sect1 xml:id="writing-style-guide">
<title>Style guide</title>
<para>由於 Handbook 是由眾多作者所維護，為了保持寫作風格的一貫性，
請遵守下列撰寫風格。</para>
<sect2>
<title>大小寫</title>
<para>Tag 的部份都是用小寫字母，譬如是用 <literal>&lt;para&gt;</literal>
，<emphasis>而非</emphasis> <literal>&lt;PARA&gt;</literal>。</para>
<para>而 SGML 內文則是用大寫字母表示，像是：
<literal>&lt;!ENTITY&hellip;&gt;</literal> 及
<literal>&lt;!DOCTYPE&hellip;&gt;</literal>，
<emphasis>而不是</emphasis>
<literal>&lt;!entity&hellip;&gt;</literal> 及
<literal>&lt;!doctype&hellip;&gt;</literal>。</para>
</sect2>
<sect2>
<title>縮寫字</title>
<para>縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法，
比如："Network Time Protocol (<acronym role="Network Time Protocol">NTP</acronym>)"。
定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙，
除非使用完整詞彙可以更能表達語意)來表達即可。
通常每本書只會第一次提到時，才會列出完整詞彙，
但若您高興也可以在每章第一次提到時又列出完整詞彙。</para>
<para>此外，同一縮寫字在前三次使用時，須使用 &lt;acronym&gt; 標籤，
並把完整詞彙附在 <literal>role</literal> 屬性內做說明。
如此一來就會建立詞彙表，並且當滑鼠移至該縮寫字上方時，
就會顯示完整詞彙。</para>
</sect2>
<sect2>
<title>縮排</title>
<para><emphasis>無論</emphasis> 檔案縮排設定為何，
每個檔案一開始的縮排(indentation)都是從 0 縱列開始</para>
<para>未完的標籤會以多兩個空白來增加縮排，
結尾的標籤則少兩個空白來縮減縮排。 若已達 8 個空白，則以 tab 取代之。
此外，在 tab 前面不要再用空白，也不要在每行後面加上空白。
每個 tag 的內文若超過一行的話，則接下來的就多兩個空白以做縮排。</para>
<para>舉個例子，這節所用的寫法大致是下面這樣：</para>
<programlisting><![CDATA[+--- 這是 0 縱列
V
<chapter>
<title>...</title>
<sect1>
<title>...</title>
<sect2>
<title>縮排</title>
<para><emphasis>無論</emphasis> 檔案縮排設定為何，
每個檔案一開始的縮排(indentation)都是從 0 縱列開始。</para>
...
</sect2>
</sect1>
</chapter>]]></programlisting>
<para>若用 <application>Emacs</application> 或
<application>XEmacs</application> 來編輯這檔，那麼會自動進入
<literal>sgml-mode</literal> 模式，
然後就會強制使用每個檔案最下方的環境設定。</para>
<para><application>Vim</application> 愛用者也可以用下列設定來調整：</para>
<programlisting>augroup sgmledit
autocmd FileType sgml set formatoptions=cq2l " 特殊格式選項
autocmd FileType sgml set textwidth=70 " 在 70 縱列處即自動換行
autocmd FileType sgml set shiftwidth=2 " 自動縮排 2 個空白
autocmd FileType sgml set softtabstop=2 " 按 Tab 會自動轉為兩個空白縮排
autocmd FileType sgml set tabstop=8 " 把 8 個空白轉為 tab
autocmd FileType sgml set autoindent " 自動縮排
augroup END</programlisting>
</sect2>
<sect2>
<title>Tag 風格</title>
<sect3>
<title>Tag 空行</title>
<para>同一縮排等級的標籤要以空一行來做區隔，而不同縮排等級的則不必。
比如：</para>
<informalexample>
<programlisting><![CDATA[<article lang='zh_tw'>
<articleinfo>
<title>NIS</title>
<pubdate>October 1999</pubdate>
<abstract>
<para>...
...
...</para>
</abstract>
</articleinfo>
<sect1>
<title>...</title>
<para>...</para>
</sect1>
<sect1>
<title>...</title>
<para>...</para>
</sect1>
</article>]]></programlisting>
</informalexample>
</sect3>
<sect3>
<title>標籤的分行</title>
<para>像是 <tag>itemizedlist</tag>
這類的標籤事實上本身不含任何文字資料，必須得由其他標籤來補充內文。
這類的標籤會獨用一整行。</para>
<para>另外，像是 <tag>para</tag> 及
<tag>term</tag> 這類的標籤並不需搭配其他標籤，
就可附上文字資料，並且在標籤後面的<emphasis>同一行</emphasis>
內即可立即寫上這些內文。</para>
<para>當然，這兩類的標籤結尾時也是跟上面道理相同。</para>
<para>不過，當上述這兩種標籤混用時，會有很明顯的困擾。</para>
<para>當第一類標籤的後面接上第二類標籤的話，
那麼要把這兩類標籤各自分行來寫。 後者標籤的段落，
也是需要做適當縮排調整。</para>
<para>而第二類標籤結尾時，可以與第一類標籤的結尾放在同一行。</para>
</sect3>
</sect2>
<sect2>
<title>空白的更改</title>
<para>在 commit 修改時，<emphasis>請別在修改內容的同時，
也一起更改編排格式</emphasis>。</para>
<para>如此一來，像是 Handbook 翻譯團隊才能迅速找出你改了哪些內容，
而不用費心思去判斷該行的改變，是由於格式重排或者內容異動。</para>
<para>舉例說明，若要在某段加上兩個句子，如此一來該段落的某行勢必會超出 80
縱列，這時請先 commmit 修改。 接著，再修飾過長行落的換行，然後再次
commit 之。 而第二次的 commit 紀錄，請明確說明這只是 whitespace-only
(修改空白而已) 的更改，如此一來，翻譯團隊就可以忽略第二次 commit 了
。</para>
</sect2>
<sect2>
<title>Nonbreaking space</title>
<para>請避免一些情況下的斷行：造成版面醜醜的、或是須連貫表達的同一句子。
斷行的情況會隨所閱讀的工具不同而有所不同。 尤其是透過純文字瀏覽器來看
HTML 時會更明顯看到類似下面這樣不好的編排段落：</para>
<literallayout class="monospaced">Data capacity ranges from 40 MB to 15
GB. Hardware compression &hellip;</literallayout>
<para>請使用 <literal>&amp;nbsp;</literal> 以避免同句子之間的斷行，
以下示範如何使用 nonbreaking spaces：</para>
<itemizedlist>
<listitem>
<para>在數字與單位之間：</para>
<programlisting><![CDATA[57600&nbsp;bps]]></programlisting>
</listitem>
<listitem>
<para>在程式名稱與版號之間：</para>
<programlisting><![CDATA[FreeBSD&nbsp;4.7]]></programlisting>
</listitem>
<listitem>
<para>multiword 之間 (使用時請小心，像是 <quote>The FreeBSD Brazilian
Portuguese Documentation Project</quote> 這類由三到四個字所組成的，
則不用加。)：</para>
<programlisting><![CDATA[Sun&nbsp;Microsystems]]></programlisting>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 xml:id="writing-style-word-list">
<title>詞彙表</title>
<para>以下為 FreeBSD 文件計劃編排時所採用的小型詞彙表。
若找不到要找的詞彙，請參閱 <link xlink:href="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly
word list</link>。</para>
<itemizedlist>
<listitem>
<para>2.2.X</para>
</listitem>
<listitem>
<para>4.X-STABLE</para>
</listitem>
<listitem>
<para>CD-ROM</para>
</listitem>
<listitem>
<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
</listitem>
<listitem>
<para>Ports Collection</para>
</listitem>
<listitem>
<para>IPsec</para>
</listitem>
<listitem>
<para>Internet</para>
</listitem>
<listitem>
<para>MHz</para>
</listitem>
<listitem>
<para>Soft Updates</para>
</listitem>
<listitem>
<para>Unix</para>
</listitem>
<listitem>
<para>disk label</para>
</listitem>
<listitem>
<para>email</para>
</listitem>
<listitem>
<para>file system</para>
</listitem>
<listitem>
<para>manual page</para>
</listitem>
<listitem>
<para>mail server</para>
</listitem>
<listitem>
<para>name server</para>
</listitem>
<listitem>
<para>null-modem</para>
</listitem>
<listitem>
<para>web server</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>