給新貢獻人員的 FreeBSD 說明文件計畫入門書

`lang`

You have mail.
% date +"The time is %H:%M"
The time is 09:18
% svn checkout https://svn.FreeBSD.org/doc/head ~/doc
% svn up ~/doc
% igor -R filename.xml | less -RS
% cd ~/doc
% svn diff > bsdinstall.diff.txt
% svn checkout https://svn.FreeBSD.org/doc/head ~/doc
% svn checkout https://svn.FreeBSD.org/base/head ~/src
% svn update ~/doc
% svn revert chapter.xml
% cd ~/doc
% svn diff > doc-fix-spelling.diff
% cd ~/doc
% svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff
<chapter id="kernelconfig">
...
</chapter>
% cd ~/doc/en_US.ISO8859-1/books/handbook
% make -V KNOWN_FORMATS
% cd ~/doc/en_US.ISO8859-1/books/handbook
% make FORMATS=html
% cd ~/doc/en_US.ISO8859-1/books/handbook
% make FORMATS="html-split pdf"
SUBDIR =articles
SUBDIR+=books

COMPAT_SYMLINK = en

DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"
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"
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"
_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor
clean: _SUBDIRUSE
	rm -f ${CLEANFILES}
_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor
WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"
% cd ~/doc/en_US.ISO8859-1/htdocs/
% make all
% cd ~/doc/en_US.ISO8859-1/htdocs/
% env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install
% firefox /tmp/www/data/index.html
# httpd.conf for testing the FreeBSD website
Define TestRoot "/tmp/www/data"

# directory for configuration files
ServerRoot "/usr/local"

Listen 80

# minimum required modules
LoadModule authz_core_module libexec/apache24/mod_authz_core.so
LoadModule mime_module libexec/apache24/mod_mime.so
LoadModule unixd_module libexec/apache24/mod_unixd.so
LoadModule cgi_module libexec/apache24/mod_cgi.so
LoadModule dir_module libexec/apache24/mod_dir.so

# run the webserver as user and group
User www
Group www

ServerAdmin you@example.com
ServerName fbsdtest

# deny access to all files
<Directory />
    AllowOverride none
    Require all denied
</Directory>

# allow access to the website directory
DocumentRoot "${TestRoot}"
<Directory "${TestRoot}">
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

# prevent access to .htaccess and .htpasswd files
<Files ".ht*">
    Require all denied
</Files>

ErrorLog "/var/log/httpd-error.log"
LogLevel warn

# set up the CGI script directory
<Directory "${TestRoot}/cgi">
    AllowOverride None
    Options None
    Require all granted
    Options +ExecCGI
    AddHandler cgi-script .cgi
</Directory>

Include etc/apache24/Includes/*.conf
# service apache24 onestart
% cd ~/doc/en_US.ISO8859-1/htdocs
% make all
% su -
Password:
# cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs
# make install
# find /usr/local/www -ctime 3 -delete
% rm /tmp/foo
<para>To remove <filename>/tmp/foo</filename>, use &man.rm.1;.</para>

<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
This is a paragraph. It starts with the start tag for
 the 'p' element, and it will end with the end tag for the 'p'
 element.

This is another paragraph. But this one is much shorter.
One paragraph.
<hr></hr>

This is another paragraph. A horizontal rule separates this
 from the previous paragraph.
One paragraph.
<hr/>

This is another paragraph. A horizontal rule separates this
 from the previous paragraph.
This is a simple paragraph where some
 of the words have been emphasized.
The inclusion of the align attribute
 on this paragraph was superfluous, since the default is left.

<p align="center">This may appear in the center.</p>
<p align='right'>I am on the right!</p>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <body>
    <p>This is a paragraph containing some text.</p>

    <p>This paragraph contains some more text.</p>

    <p align="right">This paragraph might be right-justified.</p>
  </body>
</html>
% xmllint --valid --noout example.xml
% xmllint --valid --noout example.xml
example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
"Owner//Keyword Description//Language"
PUBLIC  "-//W3C//DTD XHTML 1.0 Transitional//EN"             "1.0/transitional.dtd"
<!DOCTYPE html SYSTEM "/path/to/file.dtd">
<!-- This is inside the comment -->

<!--This is another comment-->

<!-- This is how you
     write multiline comments -->

<p>A simple <!-- Comment inside an element's content --> paragraph.</p>
<!-- This comment--is wrong -->
<para>The current version of our product is
  &current.version;.</para>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % param.some "some">
<!ENTITY % param.text "text">
<!ENTITY % param.new  "%param.some more %param.text">

<!-- %param.new now contains "some more text" -->
]>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <!-- There may be some comments in here as well -->

  <body>
    <p>This is a paragraph containing some text.</p>

    <p>This paragraph contains some more text.</p>

    <p align="right">This paragraph might be right-justified.</p>

    <p>The current version of this document is: &version;</p>
  </body>
</html>
% xmllint --noent --dropdtd example.xml > example.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!-- And so forth -->
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <!-- Use the entities to load in the chapters -->

  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>
<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!-- Define a parameter entity to load in the chapter general entities -->
<!ENTITY % chapters SYSTEM "chapters.ent">

<!-- Now use the parameter entity to load in this file -->
%chapters;
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>
<p>This is the first paragraph.</p>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <body>
    <p>The current version of this document is: &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>
% xmllint --dropdtd --noent example.xml > example.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % entities SYSTEM "entities.ent"> %entities;
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <body>
    <p>The current version of this document is: &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
% xmllint --dropdtd --noent example.xml > example.html
<![KEYWORD[
  Contents of marked section
]]>
<para>Here is an example of how to include some text that contains
  many <literal>&lt;</literal> and <literal>&amp;</literal>
  symbols.  The sample text is a fragment of
  <acronym>XHTML</acronym>.  The surrounding text (<para> and
  <programlisting>) are from DocBook.</para>

<programlisting><![CDATA[This is a sample that shows some of the
 elements within <acronym>XHTML</acronym>. Since the angle
 brackets are used so many times, it is simpler to say the whole
 example is a CDATA marked section than to use the entity names for
 the left and right angle brackets throughout.

    <ul>
      <li>This is a listitem</li>
      <li>This is a second listitem</li>
      <li>This is a third listitem</li>
    </ul>

    <p>This is the end of the example.</p>]]></programlisting>
<![INCLUDE[
  This text will be processed and included.
]]>

<![IGNORE[
 This text will not be processed or included.
]]>
<!ENTITY % electronic.copy "INCLUDE">

<![%electronic.copy;[
<!ENTITY chap.preface	SYSTEM "preface.xml">
]]>

<!ENTITY chap.preface "">
<!ENTITY % electronic.copy "IGNORE">
<!ENTITY version "1.1">
<!ENTITY % conditional.text "IGNORE">

<![%conditional.text;[
<!ENTITY para1 SYSTEM "para1.xml">
]]>

<!ENTITY para1 "">

<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
	  <title>The Document's Title</title>
  </head>

  <body>

    …

  </body>
</html>
<h1>First section</h1>

<!-- Document introduction goes here -->

<h2>This is the heading for the first section</h2>

<!-- Content for the first section goes here -->

<h3>This is the heading for the first sub-section</h3>

<!-- Content for the first sub-section goes here -->

<h2>This is the heading for the second section</h2>

This is a paragraph. It can contain just about any
 other element.
A small excerpt from the US Constitution:

<blockquote>We the People of the United States, in Order to form
 a more perfect Union, establish Justice, insure domestic
 Tranquility, provide for the common defence, promote the general
 Welfare, and secure the Blessings of Liberty to ourselves and our
 Posterity, do ordain and establish this Constitution for the
 United States of America.</blockquote>
An unordered list. Listitems will probably be
 preceded by bullets.

<ul>
  <li>First item</li>

  <li>Second item</li>

  <li>Third item</li>
</ul>

An ordered list, with list items consisting of multiple
 paragraphs. Each item (note: not each paragraph) will be
 numbered.

<ol>
 <li>This is the first item. It only has one paragraph.</li>

  <li><p>This is the first paragraph of the second item.</p>

    <p>This is the second paragraph of the second item.</p></li>

  <li><p>This is the first and only paragraph of the third
    item.</p></li>
</ol>
<dl>
  <dt>Term 1</dt>

  <dd><p>Paragraph 1 of definition 1.</p>

    <p>Paragraph 2 of definition 1.</p></dd>

  <dt>Term 2</dt>

  <dd><p>Paragraph 1 of definition 2.</p></dd>

  <dt>Term 3</dt>

  <dd><p>Paragraph 1 of definition 3.</p></dd>
</dl>
<pre>  From: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: New documentation available

  There is a new copy of my primer for contributors to the FreeBSD
  Documentation Project available at

    &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;

  Comments appreciated.

  N</pre>
<p>This is a simple 2x2 table.</p>

<table>
  <tr>
    <td>Top left cell</td>

    <td>Top right cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>
<p>One tall thin cell on the left, two short cells next to
  it on the right.</p>

<table>
  <tr>
    <td rowspan="2">Long and thin</td>
  </tr>

  <tr>
    <td>Top cell</td>

    <td>Bottom cell</td>
  </tr>
</table>
<p>One long cell on top, two short cells below it.</p>

<table>
  <tr>
    <td colspan="2">Top cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>
<p>On a 3x3 grid, the top left block is a 2x2 set of
  cells merged into one.  The other cells are normal.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Top left large cell</td>

    <td>Top right cell</td>
  </tr>

  <tr>
    <!-- Because the large cell on the left merges into
         this row, the first <td> will occur on its
         right -->

    <td>Middle right cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom middle cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>
<p><em>This</em> has been emphasized, while
  <strong>this</strong> has been strongly emphasized.</p>
<p>Many system settings are stored in
  <tt>/etc</tt>.</p>
<p>More information is available at the
  <a href="http://www.&os;.org/">&os; web site</a>.</p>
<p id="samplepara">This paragraph can be referenced
  in other links with the name <tt>samplepara</tt>.</p>
<p>More information can be found in the
  <a href="foo.html#samplepara">sample paragraph</a> of
  <tt>foo.html</tt>.</p>
<p>More information can be found in the
  <a href="#samplepara">sample paragraph</a> of this
  document.</p>
PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"
<book>
  <info>
    <title>Your Title Here</title>

    <author>
      <personname>
        <firstname>Your first name</firstname>
        <surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
          <email>Your email address</email>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $</releaseinfo>

    <abstract>
      <para>Include an abstract of the book's contents here.</para>
    </abstract>
  </info>

  …

</book>
<article>
  <info>
    <title>Your title here</title>

    <author>
      <personname>
	<firstname>Your first name</firstname>
	<surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
	  <email>Your email address</email></address>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $</releaseinfo>

    <abstract>
      <para>Include an abstract of the article's contents here.</para>
    </abstract>
  </info>

  …

</article>
<chapter>
  <title>The Chapter's Title</title>

...
</chapter>
<chapter>
 <title>This is An Empty Chapter</title>

  <para></para>
</chapter>
<chapter>
  <title>A Sample Chapter</title>

  <para>Some text in the chapter.</para>

  <sect1>
    <title>First Section</title>

    …
  </sect1>

  <sect1>
    <title>Second Section</title>

    <sect2>
      <title>First Sub-Section</title>

      <sect3>
	<title>First Sub-Sub-Section</title>

	…
      </sect3>
    </sect2>

    <sect2>
      <title>Second Sub-Section (1.2.2)</title>

      …
    </sect2>
  </sect1>
</chapter>
<part>
  <title>Introduction</title>

  <chapter>
    <title>Overview</title>

    ...
  </chapter>

  <chapter>
    <title>What is FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>History</title>

    ...
  </chapter>
</part>
<para>This is a paragraph.  It can contain just about any
  other element.</para>
<para>A small excerpt from the US Constitution:</para>

<blockquote>
  <title>Preamble to the Constitution of the United States</title>

  <attribution>Copied from a web site somewhere</attribution>

  <para>We the People of the United States, in Order to form a more
    perfect Union, establish Justice, insure domestic Tranquility,
    provide for the common defence, promote the general Welfare, and
    secure the Blessings of Liberty to ourselves and our Posterity, do
    ordain and establish this Constitution for the United States of
    America.</para>
</blockquote>
<tip>
  <para>&os; may reduce stress.</para>
</tip>

<important>
  <para>Please use admonitions sparingly.  Too many admonitions
    are visually jarring and can have the opposite of the
    intended effect.</para>
</important>
<example>
  <para>Empty files can be created easily:</para>

  <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen>
</example>
% touch file1 file2 file3
<itemizedlist>
  <listitem>
    <para>This is the first itemized item.</para>
  </listitem>

  <listitem>
    <para>This is the second itemized item.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>This is the first ordered item.</para>
  </listitem>

  <listitem>
    <para>This is the second ordered item.</para>
  </listitem>
</orderedlist>
<variablelist>
  <varlistentry>
    <term>Parallel</term>

    <listitem>
      <para>In parallel communications, groups of bits arrive
	at the same time over multiple communications
	channels.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>Serial</term>

    <listitem>
      <para>In serial communications, bits arrive one at a
	time over a single communications
	channel.</para>
    </listitem>
  </varlistentry>
</variablelist>
<procedure>
  <step>
    <para>Do this.</para>
  </step>

  <step>
    <para>Then do this.</para>
  </step>

  <step>
    <para>And now do this.</para>
  </step>

  <step>
    <para>Finally, do one of these.</para>

    <stepalternatives>
      <step>
	<para>Go left.</para>
      </step>

      <step>
	<para>Go right.</para>
      </step>
    </stepalternatives>
  </step>
</procedure>
<para>When finished, the program will look like
  this:</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("hello, world\n");
}</programlisting>
#include <stdio.h>

int
main(void)
{
    printf("hello, world\n");
}
<para>When finished, the program will look like
  this:</para>

<programlisting>#include &lt;stdio.h&gt; <co xml:id="co-ex-include"/>

int <co xml:id="co-ex-return"/>
main(void)
{
    printf("hello, world\n"); <co xml:id="co-ex-printf"/>
}</programlisting>

<calloutlist>
  <callout arearefs="co-ex-include">
    <para>Includes the standard IO header file.</para>
  </callout>

  <callout arearefs="co-ex-return">
    <para>Specifies that <function>main()</function> returns an
      int.</para>
  </callout>

  <callout arearefs="co-ex-printf">
    <para>The <function>printf()</function> call that writes
      <literal>hello, world</literal> to standard output.</para>
  </callout>
</calloutlist>
#include <stdio.h> 

int 
main(void)
{
    printf("hello, world\n"); 
}
<informaltable pgwide="1">
  <tgroup cols="2">
    <thead>
      <row>
        <entry>This is Column Head 1</entry>
        <entry>This is Column Head 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
	<entry>Row 1, column 1</entry>
	<entry>Row 1, column 2</entry>
      </row>

      <row>
	<entry>Row 2, column 1</entry>
	<entry>Row 2, column 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>
% ls -1
foo1
foo2
foo3
% ls -1 | grep foo2
foo2
% su
Password: 
# cat foo2
This is the file called 'foo2'
<para>&os; is without doubt <emphasis>the</emphasis>
  premiere &unix;-like operating system for the Intel
  architecture.</para>
<para>Request For Comments (<acronym>RFC</acronym>) 1149
  defined the use of avian carriers for transmission of
  Internet Protocol (<acronym>IP</acronym>) data.  The
  quantity of <acronym>IP</acronym> data currently
  transmitted in that manner is unknown.</para>
<para>However, make sure that the search does not go beyond the
  <quote>boundary between local and public administration</quote>,
  as <acronym>RFC</acronym> 1535 calls it.</para>
<para>To switch to the second virtual terminal, press
  <keycombo action="simul"><keycap>Alt</keycap>
    <keycap>F1</keycap></keycombo>.</para>

<para>To exit <command>vi</command> without saving changes, type
  <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
    <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

<para>My window manager is configured so that
  <keycombo action="simul"><keycap>Alt</keycap>
    <mousebutton>right</mousebutton>
  </keycombo> mouse button is used to move windows.</para>
PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

…

]>
<para><application>Sendmail</application> is the most
  widely used Unix mail application.<para>

<para><application>Sendmail</application> includes the
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
  programs.</para>

<para>One of the command line parameters to <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, will display the current
  status of messages in the mail queue.  Check this on the command
  line by running <command>sendmail -bp</command>.</para>
<para>The source for the Handbook in English is found in
  <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
  The main file is called <filename>book.xml</filename>.
  There is also a <filename>Makefile</filename> and a
  number of files with a <filename>.ent</filename> extension.</para>

<para><filename>kbd0</filename> is the first keyboard detected
  by the system, and appears in
  <filename>/dev</filename>.</para>
<para>Install the <package>net/wireshark</package> binary
  package to view network traffic.</para>

<para><package role="port">net/wireshark</package> can also be
  built and installed from the Ports Collection.</para>
<para>The local machine can always be referred to by the
  name <systemitem class="systemname">localhost</systemitem>, which will have the IP
  address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>

<para>The <systemitem class="domainname">FreeBSD.org</systemitem>
  domain contains a number of different hosts, including
  <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
  <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>

<para>When adding an <acronym>IP</acronym> alias to an
  interface (using <command>ifconfig</command>)
  <emphasis>always</emphasis> use a netmask of
  <systemitem class="netmask">255.255.255.255</systemitem> (which can
  also be expressed as
  <systemitem class="netmask">0xffffffff</systemitem>).</para>

<para>The <acronym>MAC</acronym> address uniquely identifies
 every network card in existence. A typical
 <acronym>MAC</acronym> address looks like
 <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>

<para>To carry out most system administration functions
 requires logging in as <systemitem class="username">root</systemitem>.</para>
<para>This URL shows only as text:
 <uri>https://www.FreeBSD.org</uri>. It does not
 create a link.</para>
<para>An email address that does not actually exist, like
 <email>notreal@example.com</email>, can be used as an
 example.</para>
<para>Sometimes a link to an email address like
 <email role="nolink">notreal@example.com</email> is not
 desired.</para>
<para>Two common targets in a <filename>Makefile</filename>
 are <buildtarget>all</buildtarget> and
 <buildtarget>clean</buildtarget>.</para>

<para>Typically, invoking <buildtarget>all</buildtarget> will
  rebuild the application, and invoking
  <buildtarget>clean</buildtarget> will remove the temporary
  files (<filename>.o</filename> for example) created by the
  build process.</para>

<para><buildtarget>clean</buildtarget> may be controlled by a
  number of variables, including <varname>CLOBBER</varname>
  and <varname>RECURSE</varname>.</para>
<para>The <literal>maxusers 10</literal> line in the kernel
  configuration file determines the size of many system tables, and is
  a rough guide to how many simultaneous logins the system will
  support.</para>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
% man command
<para>The <literal>maxusers <replaceable>n</replaceable></literal>
  line in the kernel configuration file determines the size of many system
  tables, and is a rough guide to how many simultaneous logins the system will
  support.</para>

<para>For a desktop workstation, <literal>32</literal> is a good value
  for <replaceable>n</replaceable>.</para>
<para>Edit the file, then click
  <guibutton>[&nbsp;Save&nbsp;]</guibutton> to save the
  changes.</para>
<screen><errorname>Panic: cannot mount root</errorname></screen>
Panic: cannot mount root
# vidcontrol -p < /dev/ttyv0 > shot.scr
<mediaobject>
  <imageobject>
    <imagedata fileref="fig1"/> 
  </imageobject>

  <textobject>
    <literallayout class="monospaced">+---------------+ 
|       A       |
+---------------+</literallayout>
  </textobject>

  <textobject>
    <phrase>A picture</phrase> 
  </textobject>
</mediaobject>
…
IMAGES= fig1.eps fig2.png fig3.png
…
…
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
…
<mediaobject>
  <imageobject>
    <imagedata fileref="chapter1/fig1"/> 
  </imageobject>

  …

</mediaobject>
…
IMAGES=  chapter1/fig1.png
…
<chapter xml:id="introduction">
  <title>Introduction</title>

  <para>This is the introduction.  It contains a subsection,
    which is identified as well.</para>

  <sect1 xml:id="introduction-moredetails">
    <title>More Details</title>

    <para>This is a subsection.</para>
  </sect1>
</chapter>
<para>More information can be found
  in <xref linkend="introduction"/>.</para>

<para>More specific information can be found
  in <xref linkend="introduction-moredetails"/>.</para>
<para>Read the <link
    xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
    introduction</link>, then pick the nearest mirror from
  the list of <link
    xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
    mirror sites</link>.</para>
<para>Read this
  <link xlink:href="&url.articles.bsdl-gpl;">article
    about the BSD license</link>, or just the
  <link xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para>
<para>Of course, you could stop reading this document and go to the
  <link xlink:href="&url.base;/index.html">FreeBSD home page</link> instead.</para>
<para>Wikipedia has an excellent reference on
  <link
    xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
    Partition Tables</link>.</para>
<para>Wikipedia has an excellent reference on
  GUID Partition Tables: <link
    xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"></link>.</para>
<para>Wikipedia has an excellent reference on
  GUID Partition Tables: <link
    xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"/>.</para>
% svn checkout https://svn.FreeBSD.org/doc/head/ head
% svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml
head/
    sv_SE.ISO8859-1/
                     Makefile
                     htdocs/
                           docproj/
                     books/
                           faq/
                               Makefile
                               book.xml
% cd doc
% tar cf swedish-docs.tar sv_SE.ISO8859-1
% gzip -9 swedish-docs.tar
<!--
     The FreeBSD Documentation Project

     $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $
-->
<!--
     The FreeBSD Spanish Documentation Project

     $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $
     Original revision: r38674
-->
# cd /usr/ports/textproc/docproj
# make config
# make clean deinstall install clean
# cd /usr/ports/editors/poedit
# make install clean
% svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
% svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
    ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
% cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
% make po
% poedit es_ES.po
% cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
% make tran
% make FORMATS=html
% firefox article.html
% cd ~/doc/es_ES.ISO8859-1/books/
% svn mkdir porters-handbook
A         porters-handbook
% cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
% svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .
A         Makefile
#
# $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $
#
# Build the FreeBSD Porter's Handbook.
#

MAINTAINER=doc@FreeBSD.org

DOC?= book

FORMATS?= html-split

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

# XML content
SRCS=  book.xml

# Images from the cross-document image library
IMAGES_LIB+=    callouts/1.png
IMAGES_LIB+=    callouts/2.png
IMAGES_LIB+=    callouts/3.png
IMAGES_LIB+=    callouts/4.png
IMAGES_LIB+=    callouts/5.png
IMAGES_LIB+=    callouts/6.png
IMAGES_LIB+=    callouts/7.png
IMAGES_LIB+=    callouts/8.png
IMAGES_LIB+=    callouts/9.png
IMAGES_LIB+=    callouts/10.png
IMAGES_LIB+=    callouts/11.png
IMAGES_LIB+=    callouts/12.png
IMAGES_LIB+=    callouts/13.png
IMAGES_LIB+=    callouts/14.png
IMAGES_LIB+=    callouts/15.png
IMAGES_LIB+=    callouts/16.png
IMAGES_LIB+=    callouts/17.png
IMAGES_LIB+=    callouts/18.png
IMAGES_LIB+=    callouts/19.png
IMAGES_LIB+=    callouts/20.png
IMAGES_LIB+=    callouts/21.png

URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..

.include "${DOC_PREFIX}/share/mk/doc.project.mk"
% cd ~/doc/fr_FR.ISO8859-1/articles/
% svn mkdir pgpkeys
A         pgpkeys
% cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys
% svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .
A         Makefile
#
# $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $
#
# Article: PGP Keys

DOC?= article

FORMATS?= html
WITH_ARTICLE_TOC?= YES

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

SRCS=   article.xml

# To build with just key fingerprints, set FINGERPRINTS_ONLY.

URL_RELPREFIX?= ../../../..
DOC_PREFIX?=    ${.CURDIR}/../../..

.include "${DOC_PREFIX}/share/mk/doc.project.mk"
% cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
% make po
% poedit es_ES.po
If <acronym>NTP</acronym> is not being used
Si <acronym>NTP</acronym> no se utiliza
&dollar;FreeBSD&dollar;
&dollar;FreeBSD&dollar;
% cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
% make tran
% make FORMATS=html
% firefox book.html
#$FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $
% cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/
% ls
Makefile	article.xml	es_ES.po
% svn add Makefile article.xml es_ES.po
A         Makefile
A         article.xml
A         es_ES.po
% svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po
property 'svn:keywords' set on 'Makefile'
property 'svn:keywords' set on 'article.xml'
property 'svn:keywords' set on 'es_ES.po'
% svn propset svn:mime-type text/x-gettext-translation es_ES.po
property 'svn:mime-type' set on 'es_ES.po'
% svn propset svn:mime-type text/xml article.xml
property 'svn:mime-type' set on 'article.xml'
% cd ~/doc
svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff
#$FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $
% cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/
% ls
Makefile	article.xml	ko_KR.po
% svn add Makefile article.xml ko_KR.po
A         Makefile
A         article.xml
A         ko_KR.po
% svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po
property 'svn:keywords' set on 'Makefile'
property 'svn:keywords' set on 'article.xml'
property 'svn:keywords' set on 'ko_KR.po'
% svn propset svn:mime-type 'text/x-gettext-translation；charset=UTF-8' ko_KR.po
property 'svn:mime-type' set on 'ko_KR.po'
% svn propset fbsd:notbinary yes ko_KR.po
property 'fbsd:notbinary' set on 'ko_KR.po'
% svn propset svn:mime-type 'text/xml；charset=UTF-8' article.xml
property 'svn:mime-type' set on 'article.xml'
% svn propset fbsd:notbinary yes article.xml
property 'fbsd:notbinary' set on 'article.xml'
% cd ~/doc
svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff
<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Indentation</title>

      <para>The first line in each file starts with no indentation,
	<emphasis>regardless</emphasis> of the indentation level of
	the file which might contain the current file.</para>

      ...
    </sect2>
  </sect1>
</chapter>
<para>See the <link
    linkend="gmirror-troubleshooting">Troubleshooting</link>
  section if there are problems booting.  Powering down and
  disconnecting the original <filename>ada0</filename> disk
  will allow it to be kept as an offline backup.</para>

<para>It is also possible to journal the boot disk of a &os;
  system.  Refer to the article <link
    xlink:href="&url.articles.gjournal-desktop;">Implementing UFS
    Journaling on a Desktop PC</link> for detailed
  instructions.</para>
<para>With file flags, even
  <systemitem class="username">root</systemitem> can be
  prevented from removing or altering files.</para>
<article lang='en'>
  <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>
Data capacity ranges from 40 MB to 15
GB.  Hardware compression …
57600&nbsp;bps
&os;&nbsp;9.2
Sun&nbsp;Microsystems
if has("autocmd")
    au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
    au BufNewFile,BufRead *.[1-9] call ShowSpecial()
endif " has(autocmd)

function Set_Highlights()
    "match ExtraWhitespace /^\s* \s*\|\s\+$/
    highlight default link OverLength ErrorMsg
    match OverLength /\%71v.\+/
    return 0
endfunction

function ShowSpecial()
    setlocal list listchars=tab:>>,trail:*,eol:$
    hi def link nontext ErrorMsg
    return 0
endfunction " ShowSpecial()

function Set_SGML()
    setlocal number
    syn match sgmlSpecial "&[^;]*;"
    setlocal syntax=sgml
    setlocal filetype=xml
    setlocal shiftwidth=2
    setlocal textwidth=70
    setlocal tabstop=8
    setlocal softtabstop=2
    setlocal formatprg="fmt -p"
    setlocal autoindent
    setlocal smartindent
    " Rewrap paragraphs
    noremap P gqj
    " Replace spaces with tabs
    noremap T :s/        /\t/<CR>
    call ShowSpecial()
    call Set_Highlights()
    return 0
endfunction " Set_SGML()
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
  <documentElement localName="section" typeId="DocBook">
  <documentElement localName="chapter" typeId="DocBook">
  <documentElement localName="article" typeId="DocBook">
  <documentElement localName="book" typeId="DocBook">
  <typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc">
</locatingRules>
(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)
(package-install 'flycheck)
(flycheck-define-checker igor
  "FreeBSD Documentation Project sanity checker.

See URLs http://www.freebsd.org/docproj/ and
http://www.freshports.org/textproc/igor/."
  :command ("igor" "-X" source-inplace)
  :error-parser flycheck-parse-checkstyle
  :modes (nxml-mode)
  :standard-input t)

  (add-to-list 'flycheck-checkers 'igor 'append)
;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")

((nxml-mode
  (eval . (turn-on-auto-fill))
  (fill-column . 70)
  (eval . (require 'flycheck))
  (eval . (flycheck-mode 1))
  (flycheck-checker . igor)
  (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))
% cp /usr/local/share/nano/xml.nanorc ~/.nanorc
syntax "xml" "\.([jrs]html?|xml|xslt?)$"
# trailing whitespace
color ,blue "[[:space:]]+$"
# multiples of eight spaces at the start a line
# (after zero or more tabs) should be a tab
color ,blue "^([TAB]*[ ]{8})+"
# tabs after spaces
color ,yellow "( )+TAB"
# highlight indents that have an odd number of spaces
color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"
# lines longer than 70 characters
color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"
% perl -i'' -pe 's/TAB/\t/g' ~/.nanorc
% nano -AKipwz -r 70 -T8 chapter.xml
alias nano "nano -AKipwz -r 70 -T8"
% nano chapter.xml
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

<book xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:lang="en">

  <info>
    <title>An Example Book</title>

    <author>
      <personname>
        <firstname>Your first name</firstname>
        <surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
	  <email>foo@example.com</email>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>2000</year>
      <holder>Copyright string here</holder>
    </copyright>

    <abstract>
      <para>If your book has an abstract then it should go here.</para>
    </abstract>
  </info>

  <preface>
    <title>Preface</title>

    <para>Your book may have a preface, in which case it should be placed
      here.</para>
  </preface>

  <chapter>
    <title>My First Chapter</title>

    <para>This is the first chapter in my book.</para>

    <sect1>
      <title>My First Section</title>

      <para>This is the first section in my book.</para>
    </sect1>
  </chapter>
</book>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

<article xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:lang="en">

  <info>
    <title>An Example Article</title>

    <author>
      <personname>
        <firstname>Your first name</firstname>
        <surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
	  <email>foo@example.com</email>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>2000</year>
      <holder>Copyright string here</holder>
    </copyright>

    <abstract>
      <para>If your article has an abstract then it should go here.</para>
    </abstract>
  </info>

  <sect1>
    <title>My First Section</title>

    <para>This is the first section in my article.</para>

    <sect2>
      <title>My First Sub-Section</title>

      <para>This is the first sub-section in my article.</para>
    </sect2>
  </sect1>
</article>

帳號	提示符號
一般使用者	`%`
`root`	`#`

代表意義	範例
指令	使用 `ls -l` 來列出所有的檔案。
檔名	編輯 `.login` 。
螢幕上會出現的訊息	You have mail.
輸入指令後，螢幕上會出現的對應內容。	`%` `date +"The time is %H:%M"` The time is 09:18
要參考的線上手冊	使用 su(1) 來切換帳號。
使用者名稱和群組名稱	只有 `root` 才可以做這件事。
語氣的強調。	使用者必須這樣做
打指令時，可替換的部份	要搜尋線上手冊的關鍵字，請輸入 `man -k 關鍵字`
環境變數。	`$HOME` 是指帳號的家目錄所在處。

目錄	用途
`share`	含有未特定用於各說明文件翻譯與編碼的檔案。其子目錄更進一步將不同資訊的分類，例如，構成 make(1) 基礎設施的檔案放置於 `share/mk`，而額外的 XML 支援檔 (如 FreeBSD 延伸的 DocBook DTD) 則放在 `share/xml`。
`lang.encoding`	每一個目錄代表可用的說明文件翻譯與編碼，例如 `en_US.ISO8859-1/` 及 `zh_TW.UTF-8/`。名稱雖然長，但完整表達語言與編碼可以避免未來當一個翻譯團隊要以不同編碼提供同一個語言的說明文件造成的問題，這也同時避免往後要切換成萬國碼 (Unicode) 可能造成的問題。

目錄	用途
`articles`	以 DocBook `article` (或同等級) 標記的說明文件。非常短，且會分成幾個小節，通常取得時只會有一個 XHTML 檔案。
`books`	以 DocBook `book` (或同等級) 標記的說明文件。有跟書籍一樣的長度，會分成數個章。通常取得時會包含一個大型的 XHTML 檔 (供有較快連線速度的人使用，或者那些想直接在瀏覽器列印的人) 與數個連結的較小的檔案。
`man`	供系統操作手冊 (Manual page) 翻譯使用。這個目錄會包含一個或多個 `mann` 目錄來對應已經翻譯的章節。

`FORMATS` 值	檔案類型	說明
`html`	HTML，單檔	單一 `book.html` 或 `article.html`。
`html-split`	HTML，多檔	多個 HTML 檔案，每個章或節一個檔案，供一般網站使用。
`pdf`	PDF	可攜的文件格式


FreeBSD Name Entities
`&os;`	`FreeBSD`
`&os.stable;`	`FreeBSD-STABLE`
`&os.current;`	`FreeBSD-CURRENT`

Manual Page Entities
`&man.ls.1;`	ls(1)	Usage: `&man.ls.1; is the manual page for <command>ls</command>.`
`&man.cp.1;`	cp(1)	Usage: `The manual page for <command>cp</command> is &man.cp.1;.`
`&man.command.sectionnumber;`	link to `command` manual page in section `sectionnumber`	Entities are defined for all the FreeBSD manual pages.

FreeBSD Mailing List Entities
`&a.doc;`	`FreeBSD documentation project mailing list`	Usage: `A link to the &a.doc;.`
`&a.questions;`	`FreeBSD general questions mailing list`	Usage: `A link to the &a.questions;.`
`&a.listname;`	link to `listname`	Entities are defined for all the FreeBSD mailing lists.

FreeBSD Document Link Entities
`&url.books.handbook;`	`../../../../doc/en_US.ISO8859-1/books/handbook`	Usage: `A link to the <link xlink:href="&url.books.handbook;/advanced-networking.html">Advanced Networking</link> chapter of the Handbook.`
`&url.books.bookname;`	relative path to `bookname`	Entities are defined for all the FreeBSD books.
`&url.articles.committers-guide;`	`../../../../doc/en_US.ISO8859-1/articles/committers-guide`	Usage: `A link to the <link xlink:href="&url.articles.committers-guide;">Committer's Guide</link> article.`
`&url.articles.articlename;`	relative path to `articlename`	Entities are defined for all the FreeBSD articles.

Other Operating System Name Entities
`&linux;`	Linux®	The Linux® operating system.
`&unix;`	UNIX®	The UNIX® operating system.
`&windows;`	Windows®	The Windows® operating system.

Miscellaneous Entities
`&prompt.root;`	`#`	The `root` user prompt.
`&prompt.user;`	`%`	A prompt for an unprivileged user.
`&postscript;`	PostScript®	The PostScript® programming language.
`&tex;`	TeX	The TeX typesetting language.
`&xorg;`	Xorg	The Xorg open source X Window System.

	Preamble to the Constitution of the United States We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
	--Copied from a web site somewhere

	Includes the standard IO header file.
	Specifies that `main()` returns an int.
	The `printf()` call that writes `hello, world` to standard output.

This is Column Head 1	This is Column Head 2
Row 1, column 1	Row 1, column 2
Row 2, column 1	Row 2, column 2

11.1.	i18n 與 l10n 代表的是什麼意思？
	i18n 指的是國際化 (Internationalization) 而 l10n 指的是在地化 (Localization)。這些都是為了書寫方便而用的簡寫。 i18n 就是開頭為 “i” 後面有 18 個字母，最後接 “n”。同樣地，l10n 是開頭為 “l” 後面有 10 個字母，最後接 “n”。
11.2.	有給翻譯人員參與討論的郵遞論壇 (Mailing list) 嗎？
	有的，不同的語系翻譯人員都各自有自屬的郵遞論壇。這份翻譯計劃清單有列出各翻譯計劃的詳細 mailing lists 及相關網站。此外，有一般翻譯討論的`<freebsd-translators@freebsd.org>`郵件論壇。
11.3.	需要更多人一起參與翻譯嗎？
	當然囉，越多人參與翻譯，那麼就能夠越快翻完，而且英文版說明文件若有增減、更新的話，各翻譯版也可以儘快同步囉。不一定得是專業譯者，才能參與翻譯的。
11.4.	有要求哪些語言能力呢
	理論上，必須要對英文非常熟稔，而且很明顯地，對想翻譯的語言必須要能運用自如。英文也並非一定要會的。比如說，可以把西班牙文 (Spanish) 的 FAQ 翻譯為匈牙利文 (Hungarian)。
11.5.	該學會哪些程式的使用呢？
	強烈建議在自己機器上也建立 FreeBSD Subversion 檔案庫的備份 (至少要有說明文件的部分)，這可以執行： `%` `svn checkout https://svn.FreeBSD.org/doc/head/ head` svn.FreeBSD.org 是公共的 `SVN` 伺服器。可以從 Subversion 鏡像站清單檢查認證的伺服器。注意: 這需要安裝 devel/subversion 套件。你可以很自在地使用 svn。他可以讓你察看說明文件檔案不同版本之間的修改差異。例如你要看 `en_US.ISO8859-1/books/fdp-primer/book.xml` 版本`r33733` 和 `r33734` 的差異，請執行： `%` `svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml`
11.6.	要怎麼找出來還有誰要跟我一起翻譯的呢？
	說明文件計劃翻譯頁列了目前已知的各翻譯者成果，如果已經有其他人也在做跟你一樣的翻譯工作，那麼請不要重複浪費人力，請與他們聯繫看看還有哪些地方可以幫上忙的。若上面並未列出你母語的翻譯，或是也有人要翻譯但還未公開宣布的話，那麼就寄信到 FreeBSD 說明文件計劃郵遞論壇。
11.7.	都沒人翻譯為我所使用的語言，該怎麼辦？
	恭喜啊，你剛好踏上 “FreeBSD `您的語言` 說明文件翻譯計劃”的啟程之路，歡迎登船。首先呢，先判斷是否有妥善規劃時間，因為你只有一個人在翻而已，因此，相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。寫信到文件計劃郵遞論壇 (Documentation Project mailing list) 向大家宣布你正準備要翻譯，然後文件計劃的翻譯部分就會更新相關資料。若你的國家已經有人提供 FreeBSD 的鏡像站 (Mirror) 服務的話，那麼就先跟他們聯繫，並詢問你是否在上面可以有網頁空間來放相關計劃資料，以及是否可以有提供電子郵件帳號或郵遞論壇服務。然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些 —— 像是 FAQ 啦，或是如何上手之類的說明文章。
11.8.	已經翻好一些說明文件了，該寄到哪呢？
	這要看情況而定。若你是在翻譯團隊內做的話 (像是日本團隊、德國團隊)，他們會有自己內部流程來決定翻譯文件怎麼送，這些大致流程會在他們網頁上面有寫。若你是某語系的唯一翻譯者 (或你是負責某翻譯計劃，並想把成果回饋給 FreeBSD 計劃)，那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)
11.9.	我是該語系的唯一翻譯者，該怎麼把翻譯成果寄出去呢？ or 我們是翻譯團隊，該怎麼把我們成員翻譯成果寄出去呢？
	首先，請先確定你的翻譯成果組織條理分明，並可正確編譯，也就是說：把它擺到現有說明文件樹內是可以正確編譯成功的。目前，FreeBSD 說明文件都是放在最上層的 `head/` 目錄內。而該目錄下的則根據其 ISO639 所定義的語系代碼來做分類命名的 (在 1999/1/20 之後的 FreeBSD 版本中的 `/usr/share/misc/iso639`)。若你這個語系可能會有不同編碼方式 (像是：中文) 那麼就應該會像下面這樣，來依你所使用的編碼方式細分。最後，你應該建立好各文件的目錄了。舉例來說，假設有瑞典文 (Swedish) 版的翻譯，那麼應該會長像： head/ sv_SE.ISO8859-1/ Makefile htdocs/ docproj/ books/ faq/ Makefile book.xml `sv_SE.ISO8859-1`是依照 `語系 (Lang).編碼 (Encoding)` 的規則來建立的譯名。請注意：其中有兩個 Makefile 檔，它們是用來建置說明文件的。然後請用 tar(1) 與 gzip(1) 來把你的說明文件壓縮起來，並寄到本計劃來。 `%` `cd doc` `%` `tar cf swedish-docs.tar sv_SE.ISO8859-1` `%` `gzip -9 swedish-docs.tar` 接著，把 `swedish-docs.tar.gz` 放到網頁空間上，若你沒有自己網頁空間的話 (ISP 不提供)，那麼可以該檔寄到文件工程團隊 Documentation Engineering Team `<doceng@FreeBSD.org>` 來。還有，記得用 Bugzilla 提交一個回報來通知大家你已經提交說明文件了，還有，若有人可以幫忙檢閱、複審文件的話，對翻譯品質較好，因為這也有助於提升翻譯品質的流暢度。最後，會有人 (可能是文件計劃管理者，或是文件工程團隊 Documentation Engineering Team `<doceng@FreeBSD.org>` 成員) 會檢閱你的翻譯文件，並確認是否可正常編譯。此外，他們會特別注意下列幾點：你的檔案是否都有用 RCS tag (像是 "ID" 之類的)？ `sv_SE.ISO8859-1` 是否可以順利`make all` 編譯呢？ `make install` 是否結果有正確若有問題的話，那麼檢閱者會叮嚀你，來讓這些翻譯成果可以正確使用。若沒問題的話，那麼就會很快把你的翻譯成果提交。
11.10.	可以加入某語系或某國家才有的東西到翻譯內容內嗎？
	我們希望不要這麼做。舉例來說，假設你正準備把使用手冊 (Handbook) 翻譯為韓文版，並希望把韓國零售商也加到你翻譯的韓文版使用手冊內。我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 …) 因為，有可能英語讀者跑去韓國時，會想買 FreeBSD 相關產品。此外，這也可以提升 FreeBSD 的可見度，很顯然的，這並不是件壞事啊。若你有某國才有的資料，請提供給英文版使用手冊以作為修訂 (用 Bugzilla)，然後再把英文版的修訂部分翻為你要翻譯的使用手冊吧。謝謝。
11.11.	要怎麼把該語系特有的字元寫進去翻譯內容呢？
	說明文件內所有的非 ASCII (Non-ASCII) 的字元，都要使用 SGML entities 才能寫進去。簡單來說，長相一開頭會是 and 符號 (&)，然後是該 Entity 名稱，最後接上分號 (;)。這些 Entity 名稱都是 ISO8879 所制訂的，其在 Port 樹內的 textproc/iso8879。以下舉一些例子： Entity 名稱: é 外觀: é 說明: 小 “e”，並帶尖、重音 (Acute accent) Entity 名稱: É 外觀: É 說明: 大 “E”，並帶尖、重音 (Acute accent) Entity 名稱: ü 外觀: ü 說明: 小 “u”，並帶日耳曼語系中的母音變化 (Umlaut) 在裝了 iso8879 這個 Port 之後，就可以在 `/usr/local/share/xml/iso8879` 找到這些的詳細列表。
11.12.	如何稱呼讀者呢？
	在英文文件內，讀者都是以 “you” 來稱呼，而有些語言並沒有正式/非正式的區隔。若你所要翻的語言可以區別這些差異，那麼請用該語系在一般技術說明文件上所使用的稱呼吧。如果容易造成困惑的話，那麼請改用較中性的稱呼來取代。
11.13.	翻譯成果內要不要附上一些其他訊息呢？
	要。每份英文版原稿的開頭，通常會有像下面的內容： <!-- The FreeBSD Documentation Project $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $ --> 實際上的內容可能稍有不同，但每份原稿都會附上 $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $ 這一行以及 `The FreeBSD Documentation Project` 宣告。請注意：$FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $ 開頭的這行是會由 Subversion 隨著每次異動而自動更改的，所以新檔案的話請保持原狀 (也就是只要寫 $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $ 就好了)。翻譯文件中，必須都要有 $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $ 這行，並且把 `FreeBSD Documentation Project` 這行改為 `The FreeBSD language Documentation Project`。此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。因此呢，西班牙文版 (Spanish) 的檔案開頭應該是長像這樣： <!-- The FreeBSD Spanish Documentation Project $FreeBSD: head/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $ Original revision: r38674 -->

語言	地區	翻譯目錄名稱	PO 檔名稱	字元集
英文	美國	`en_US.ISO8859-1`	`en_US.po`	ISO 8859-1
孟加拉文	孟加拉	`bn_BD.UTF-8`	`bn_BD.po`	UTF-8
丹麥文	丹麥	`da_DK.ISO8859-1`	`da_DK.po`	ISO 8859-1
德文	德國	`de_DE.ISO8859-1`	`de_DE.po`	ISO 8859-1
希臘文	希臘	`el_GR.ISO8859-7`	`el_GR.po`	ISO 8859-7
西班牙文	西班牙	`es_ES.ISO8859-1`	`es_ES.po`	ISO 8859-1
法文	法國	`fr_FR.ISO8859-1`	`fr_FR.po`	ISO 8859-1
匈牙利文	匈牙利	`hu_HU.ISO8859-2`	`hu_HU.po`	ISO 8859-2
義大利文	義大利	`it_IT.ISO8859-15`	`it_IT.po`	ISO 8859-15
日文	日本	`ja_JP.eucJP`	`ja_JP.po`	EUC JP
韓文	韓國	`ko_KR.UTF-8`	`ko_KR.po`	UTF-8
蒙古文	蒙古	`mn_MN.UTF-8`	`mn_MN.po`	UTF-8
荷蘭文	荷蘭	`nl_NL.ISO8859-1`	`nl_NL.po`	ISO 8859-1
挪威文	挪威	`no_NO.ISO8859-1`	`no_NO.po`	ISO 8859-1
波蘭文	波蘭	`pl_PL.ISO8859-2`	`pl_PL.po`	ISO 8859-2
葡萄牙文	巴西	`pt_BR.ISO8859-1`	`pt_BR.po`	ISO 8859-1
俄文	俄羅斯	`ru_RU.KOI8-R`	`ru_RU.po`	KOI8-R
賽爾維亞	賽爾維亞文	`sr_YU.ISO8859-2`	`sr_YU.po`	ISO 8859-2
土耳其文	土耳其	`tr_TR.ISO8859-9`	`tr_TR.po`	ISO 8859-9
中文	中國	`zh_CN.UTF-8`	`zh_CN.po`	UTF-8
中文	台灣	`zh_TW.UTF-8`	`zh_TW.po`	UTF-8

字詞	XML 程式碼	備註
CD-ROM	`<acronym>CD-ROM</acronym>`
DoS (Denial of Service)	`<acronym>DoS</acronym>`
email
file system
IPsec
Internet
manual page
mail server
name server
Ports Collection
read-only
Soft Updates
stdin	`<varname>`stdin`</varname>`
stdout	`<varname>`stdout`</varname>`
stderr	`<varname>`stderr`</varname>`
Subversion	`<application>Subversion</application>`	不要用大寫 `SVN` 來表示 Subversion 應用程式。若要表示指令，請使用 `<command>svn</command>`。
UNIX®	`&unix;`
userland		指那些要會用在使用者空間 (User space) 而非核心的東西。
web server

給新貢獻人員的 FreeBSD 說明文件計畫入門書

FreeBSD 說明文件計劃

重要:

序

1. Shell 提示符號

2. 書中所用的編排風格

3. 注意、提示、重要、警告與範例

注意:

提示:

重要:

警告:

4. 感謝

章 1. 概論

1.1. 快速上手

1.2. FreeBSD 說明文件集

章 2. 工具

2.1. 必備工具

2.1.1. DTDs 與 Entities

2.2. 選用工具

2.2.1. 軟體

章 3. 工作副本

3.1. 說明文件與操作手冊

3.2. 選擇一個目錄

3.3. 取出一份副本

3.4. 更新工作副本

3.5. 還原變更

3.6. 比對差異

3.7. Subversion 參考文獻

章 4. 說明文件目錄結構

4.1. 最上層，doc/

4.2. lang.encoding/ 目錄

4.3. 文件特定資訊

4.3.1. 使用手冊 (Handbook)

books/handbook/

4.3.1.1. 實體組織結構

注意:

4.3.1.1.1. Makefile

4.3.1.1.2. book.xml

4.3.1.1.3. directory/chapter.xml

重要:

章 5. 說明文件建置流程

5.1. 繪製 Docbook 為其他格式

5.2. FreeBSD 說明文件建置工具集

5.3. 了解在說明文件樹中的 Makefile

5.3.1. 子目錄的 Makefile

5.3.2. 說明文件的 Makefile

5.4. FreeBSD 說明文件計劃 Make 引用檔

5.4.1. doc.project.mk

5.4.1.1. 變數

注意:

5.4.1.2. 條件

5.4.2. doc.subdir.mk

5.4.2.1. 變數

5.4.2.2. 目標與巨集

5.4.2.2.1. 已提供的目標

5.4.2.3. 更多條件

5.4.2.4. 在 make (.for) 中的迴圈結構

章 6. 網站

6.1. 環境變數

提示:

6.2. 建置並安裝網頁

提示:

章 7. XML 入門

7.1. 概論

注意:

7.2. 元素、標籤與屬性

重要:

7.2.1. 待辦事項...

7.3. DOCTYPE 宣告

7.3.1. 正式公用識別碼 (FPI)

注意:

7.3.1.1. catalog 檔案

7.3.2. FPI 的替代方案

7.4. 跳脫回 XML

7.5. 註解

7.5.1. 待辦事項...

7.6. Entities

7.6.1. 一般 Entities

7.6.2. 參數 Entities

7.6.3. 待辦事項...

4.1. 最上層，`doc/`

4.2. `lang.encoding/` 目錄

`books/handbook/`

4.3.1.1.1. `Makefile`

4.3.1.1.2. `book.xml`

4.3.1.1.3. `directory/chapter.xml`

5.3. 了解在說明文件樹中的 `Makefile`

5.3.1. 子目錄的 `Makefile`

5.3.2. 說明文件的 `Makefile`

5.4.1. `doc.project.mk`

5.4.2. `doc.subdir.mk`

5.4.2.4. 在 `make (.for)` 中的迴圈結構

7.3.1.1. `catalog` 檔案

7.8.1.1. `CDATA`

7.8.1.2. `INCLUDE` 與 `IGNORE`

9.4.5. 使用 `part` 元素來分部