diff options
| author | Warren Block <wblock@FreeBSD.org> | 2016-06-21 22:15:35 +0000 |
|---|---|---|
| committer | Warren Block <wblock@FreeBSD.org> | 2016-06-21 22:15:35 +0000 |
| commit | 61d406f4ae70935b42dfd199565c2ea7002fe445 (patch) | |
| tree | 5683a8801abf25ac50f6e8b1b6e901ed74cb4c4c /zh_TW.UTF-8/books/fdp-primer | |
| parent | 04101aed1a9da257ee6c8dea5042a874e832e02e (diff) | |
| download | doc-61d406f4ae70935b42dfd199565c2ea7002fe445.tar.gz doc-61d406f4ae70935b42dfd199565c2ea7002fe445.zip | |
Clean up. Remove directories not needed for the PO translation and
remove chapters.ent from the Makefile.
Notes
Notes:
svn path=/head/; revision=48979
Diffstat (limited to 'zh_TW.UTF-8/books/fdp-primer')
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/Makefile | 3 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/chapters.ent | 27 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml | 486 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml | 336 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml | 241 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml | 165 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml | 122 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml | 2682 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml | 1543 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml | 281 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml | 92 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml | 191 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml | 235 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml | 383 | ||||
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml | 440 |
15 files changed, 0 insertions, 7227 deletions
diff --git a/zh_TW.UTF-8/books/fdp-primer/Makefile b/zh_TW.UTF-8/books/fdp-primer/Makefile index e53528b90e..594aaefe3d 100644 --- a/zh_TW.UTF-8/books/fdp-primer/Makefile +++ b/zh_TW.UTF-8/books/fdp-primer/Makefile @@ -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}/../../.. diff --git a/zh_TW.UTF-8/books/fdp-primer/chapters.ent b/zh_TW.UTF-8/books/fdp-primer/chapters.ent deleted file mode 100644 index a3d22b4c72..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/chapters.ent +++ /dev/null @@ -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"> diff --git a/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml deleted file mode 100644 index 9932157881..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml +++ /dev/null @@ -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} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${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} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${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> diff --git a/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml b/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml deleted file mode 100644 index 5fc6839c92..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml +++ /dev/null @@ -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>這些例子並不是很詳細 — 並未包括你可能想用的元件， - 尤其像是你文件的前頁(正文前的書頁，包括扉頁、序言、目錄等) - 若需參考更多 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 > 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>&jadetex</literal> macro package.</para> - - <screen>&prompt.user; <userinput>tex "&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 &pdfjadetex macro package - instead.</para> - - <screen>&prompt.user; <userinput>pdftex "&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> diff --git a/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml deleted file mode 100644 index d3f24e60ef..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml +++ /dev/null @@ -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> diff --git a/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml deleted file mode 100644 index 6edba25352..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml +++ /dev/null @@ -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> diff --git a/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml deleted file mode 100644 index 89f409164e..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml +++ /dev/null @@ -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&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> diff --git a/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml deleted file mode 100644 index 6b0907ff57..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml +++ /dev/null @@ -1,2682 +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.73 ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sgml-markup"> - <title>SGML Markup</title> - - <para>This chapter describes the two markup languages you will encounter - when you contribute to the FreeBSD documentation project. Each section - describes the markup language, and details the markup that you are likely - to want to use, or that is already in use.</para> - - <para>These markup languages contain a large number of elements, and it can - be confusing sometimes to know which element to use for a particular - situation. This section goes through the elements you are most likely to - need, and gives examples of how you would use them.</para> - - <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since - that would just reiterate the documentation for each language. The aim of - this section is to list those elements more likely to be useful to you. - If you have a question about how best to markup a particular piece of - content, please post it to the &a.doc;.</para> - - <note> - <title>Inline vs. block</title> - - <para>In the remainder of this document, when describing elements, - <emphasis>inline</emphasis> means that the element can occur within a - block element, and does not cause a line break. A - <emphasis>block</emphasis> element, by comparison, will cause a line - break (and other processing) when it is encountered.</para> - </note> - - <sect1 xml:id="sgml-markup-html"> - <title>HTML</title> - - <para>HTML, the HyperText Markup Language, is the markup language of - choice on the World Wide Web. More information can be found at - <URL:<uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>>.</para> - - <para>HTML is used to markup pages on the FreeBSD web site. It should not - (generally) be used to mark up other documentation, - since DocBook offers a - far richer set of elements to choose from. Consequently, you will - normally only encounter HTML pages if you are writing for the web - site.</para> - - <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the - latest, 4.0 (available in both <emphasis>strict</emphasis> and - <emphasis>loose</emphasis> variants).</para> - - <para>The HTML DTDs are available from the ports collection in the - <package>textproc/html</package> port. They are automatically - installed as part of the <package>textproc/docproj</package> - port.</para> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>There are a number of HTML FPIs, depending upon the version (also - known as the level) of HTML that you want to declare your document to - be compliant with.</para> - - <para>The majority of HTML documents on the FreeBSD web site comply with - the loose version of HTML 4.0.</para> - - <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Sectional elements</title> - - <para>An HTML document is normally split into two sections. The first - section, called the <emphasis>head</emphasis>, contains - meta-information about the document, such as its title, the name of - the author, the parent document, and so on. The second section, the - <emphasis>body</emphasis>, contains the content that will be displayed - to the user.</para> - - <para>These sections are indicated with <tag>head</tag> and - <tag>body</tag> elements respectively. These elements are - contained within the top-level <tag>html</tag> element.</para> - - <example> - <title>Normal HTML document structure</title> - - <programlisting><html> - <head> - <title><replaceable>The document's title</replaceable></title> - </head> - - <body> - - … - - </body> -</html></programlisting> - </example> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Headings</title> - - <para>HTML allows you to denote headings in your document, at up to - six different levels.</para> - - <para>The largest and most prominent heading is <tag>h1</tag>, - then <tag>h2</tag>, continuing down to - <tag>h6</tag>.</para> - - <para>The element's content is the text of the heading.</para> - - <example> - <title><tag>h1</tag>, <tag>h2</tag>, etc.</title> - - <para>Use:</para> - - <programlisting><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> - -<!‐- Content for the second section goes here -‐></programlisting> - </example> - - <para>Generally, an HTML page should have one first level heading - (<tag>h1</tag>). This can contain many second level - headings (<tag>h2</tag>), which can in turn contain many - third level headings. Each - <tag>h<replaceable>n</replaceable></tag> element should have - the same element, but one further up the hierarchy, preceding it. - Leaving gaps in the numbering is to be avoided.</para> - - <example> - <title>Bad ordering of - <tag>h<replaceable>n</replaceable></tag> elements</title> - - <para>Use:</para> - - <programlisting><h1>First section</h1> - -<!‐- Document introduction -‐> - -<h3>Sub-section</h3> - -<!‐- This is bad, <h2> has been left out -‐></programlisting> - </example> - </sect3> - - <sect3> - <title>Paragraphs</title> - - <para>HTML supports a single paragraph element, - <tag>p</tag>.</para> - - <example> - <title><tag>p</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any - other element.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph.</para> - - <example> - <title><tag>blockquote</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>A small excerpt from the US Constitution:</p> - -<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>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Lists</title> - - <para>You can present the user with three types of lists, ordered, - unordered, and definition.</para> - - <para>Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be preceded by a bullet point. - Definition lists are composed of two sections for each entry. The - first section is the term being defined, and the second section is - the definition of the term.</para> - - <para>Ordered lists are indicated by the <tag>ol</tag> - element, unordered lists by the <tag>ul</tag> element, and - definition lists by the <tag>dl</tag> element.</para> - - <para>Ordered and unordered lists contain listitems, indicated by the - <tag>li</tag> element. A listitem can contain textual - content, or it may be further wrapped in one or more - <tag>p</tag> elements.</para> - - <para>Definition lists contain definition terms - (<tag>dt</tag>) and definition descriptions - (<tag>dd</tag>). A definition term can only contain inline - elements. A definition description can contain other block - elements.</para> - - <example> - <title><tag>ul</tag> and <tag>ol</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>An unordered list. Listitems will probably be - preceded by bullets.</p> - -<ul> - <li>First item</li> - - <li>Second item</li> - - <li>Third item</li> -</ul> - -<p>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be - numbered.</p> - -<ol> - <li><p>This is the first item. It only has one paragraph.</p></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>]]></programlisting> - </example> - - <example> - <title>Definition lists with <tag>dl</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Pre-formatted text</title> - - <para>You can indicate that text should be shown to the user exactly - as it is in the file. Typically, this means that the text is shown - in a fixed font, multiple spaces are not merged into one, and line - breaks in the text are significant.</para> - - <para>In order to do this, wrap the content in the - <tag>pre</tag> element.</para> - - <example> - <title><tag>pre</tag></title> - - <para>You could use <tag>pre</tag> to mark up an email - message:</para> - - <programlisting><![CDATA[<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 - - <URL:http://people.FreeBSD.org/~nik/primer/index.html> - - Comments appreciated. - - N</pre>]]></programlisting> - - <para>Keep in mind that <literal><</literal> and - <literal>&</literal> still are recognized as special - characters in pre-formatted text. This is why the example - shown had to use <literal>&lt;</literal> instead of - <literal><</literal>. For consistency, - <literal>&gt;</literal> was used in place of - <literal>></literal>, too. Watch out for the special characters - that may appear in text copied from a plain-text source, - e.g., an email message or program code.</para> - - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <note> - <para>Most text-mode browsers (such as Lynx) do not render tables - particularly effectively. If you are relying on the tabular - display of your content, you should consider using alternative - markup to prevent confusion.</para> - </note> - - <para>Mark up tabular information using the <tag>table</tag> - element. A table consists of one or more table rows - (<tag>tr</tag>), each containing one or more cells of table - data (<tag>td</tag>). Each cell can contain other block - elements, such as paragraphs or lists. It can also contain another - table (this nesting can repeat indefinitely). If the cell only - contains one paragraph then you do not need to include the - <tag>p</tag> element.</para> - - <example> - <title>Simple use of <tag>table</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting></example> - - <para>A cell can span multiple rows and columns. To indicate this, - add the <literal>rowspan</literal> and/or <literal>colspan</literal> - attributes, with values indicating the number of rows of columns - that should be spanned.</para> - - <example> - <title>Using <literal>rowspan</literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting> - </example> - - <example> - <title>Using <literal>colspan</literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting> - </example> - - <example> - <title>Using <literal>rowspan</literal> and - <literal>colspan</literal> together</title> - - <para>Use:</para> - - <programlisting><![CDATA[<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> - <td>Middle right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom middle cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasizing information</title> - - <para>You have two levels of emphasis available in HTML, - <tag>em</tag> and <tag>strong</tag>. - <tag>em</tag> is for a normal level of emphasis and - <tag>strong</tag> indicates stronger emphasis.</para> - - <para>Typically, <tag>em</tag> is rendered in italic and - <tag>strong</tag> is rendered in bold. This is not always - the case, however, and you should not rely on it.</para> - - <example> - <title><tag>em</tag> and <tag>strong</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p><em>This</em> has been emphasized, while - <strong>this</strong> has been strongly emphasized.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Bold and italics</title> - - <para>Because HTML includes presentational markup, you can also - indicate that particular content should be rendered in bold or - italic. The elements are <tag>b</tag> and - <tag>i</tag> respectively.</para> - - <example> - <title><tag>b</tag> and <tag>i</tag></title> - - <programlisting><![CDATA[<p><b>This</b> is in bold, while <i>this</i> is - in italics.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Indicating fixed pitch text</title> - - <para>If you have content that should be rendered in a fixed pitch - (typewriter) typeface, use <tag>tt</tag> (for - <quote>teletype</quote>).</para> - - <example> - <title><tag>tt</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>This document was originally written by - Nik Clayton, who can be reached by email as - <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Content size</title> - - <para>You can indicate that content should be shown in a larger or - smaller font. There are three ways of doing this.</para> - - <orderedlist> - <listitem> - <para>Use <tag>big</tag> and <tag>small</tag> - around the content you wish to change size. These tags can be - nested, so <literal><big><big>This is much - bigger</big></big></literal> is possible.</para> - </listitem> - - <listitem> - <para>Use <tag>font</tag> with the <literal>size</literal> - attribute set to <literal>+1</literal> or <literal>-1</literal> - respectively. This has the same effect as using - <tag>big</tag> or <tag>small</tag>. However, - the use of this approach is deprecated.</para> - </listitem> - - <listitem> - <para>Use <tag>font</tag> with the <literal>size</literal> - attribute set to a number between 1 and 7. The default font size - is <literal>3</literal>. This approach is deprecated.</para> - </listitem> - </orderedlist> - - <example> - <title><tag>big</tag>, <tag>small</tag>, and - <tag>font</tag></title> - - <para>The following fragments all do the same thing.</para> - - <programlisting><![CDATA[<p>This text is <small>slightly smaller</small>. But - this text is <big>slightly bigger</big>.</p> - -<p>This text is <font size="-1">slightly smaller</font>. But - this text is <font size="+1">slightly bigger</font.</p> - -<p>This text is <font size="2">slightly smaller</font>. But - this text is <font size="4">slightly bigger</font>.</p>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other documents on the WWW</title> - - <para>In order to include a link to another document on the WWW you - must know the URL of the document you want to link to.</para> - - <para>The link is indicated with <tag>a</tag>, and the - <literal>href</literal> attribute contains the URL of the target - document. The content of the element becomes the link, and is - normally indicated to the user in some way (underlining, change of - color, different mouse cursor when over the link, and so - on).</para> - - <example> - <title>Using <literal><a href="..."></literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>More information is available at the - <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> - </example> - - <para>These links will take the user to the top of the chosen - document.</para> - </sect3> - - <sect3> - <title>Linking to other parts of documents</title> - - <para>Linking to a point within another document (or within the same - document) requires that the document author include anchors that you - can link to.</para> - - <para>Anchors are indicated with <tag>a</tag> and the - <literal>name</literal> attribute instead of - <literal>href</literal>.</para> - - <example> - <title>Using <literal><a name="..."></literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p><a name="para1">This</a> paragraph can be referenced - in other links with the name <tt>para1</tt>.</p>]]></programlisting> - </example> - - <para>To link to a named part of a document, write a normal link to - that document, but include the name of the anchor after a - <literal>#</literal> symbol.</para> - - <example> - <title>Linking to a named part of another document</title> - - <para>Assume that the <literal>para1</literal> example resides in a - document called <filename>foo.html</filename>.</para> - - <programlisting><![CDATA[<p>More information can be found in the - <a href="foo.html#para1">first paragraph</a> of - <tt>foo.html</tt>.</p>]]></programlisting> - </example> - - <para>If you are linking to a named anchor within the same document - then you can omit the document's URL, and just include the name of - the anchor (with the preceding <literal>#</literal>).</para> - - <example> - <title>Linking to a named part of the same document</title> - - <para>Assume that the <literal>para1</literal> example resides in - this document:</para> - - <programlisting><![CDATA[<p>More information can be found in the - <a href="#para1">first paragraph</a> of this - document.</p>]]></programlisting> - </example> - </sect3> - </sect2> - </sect1> - - <sect1 xml:id="sgml-markup-docbook"> - <title>DocBook</title> - - <para>DocBook was originally developed by HaL Computer Systems and O'Reilly - & Associates to be a DTD for writing technical documentation - <footnote><para>A short history can be found under <link xlink:href="http://www.oasis-open.org/committees/docbook/intro.shtml"> - http://www.oasis-open.org/committees/docbook/intro.shtml</link>. - </para></footnote>. Since 1998 it is maintained by the <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> - DocBook Technical Committee</link>. As such, and unlike LinuxDoc - and HTML, DocBook is very heavily oriented towards markup that - describes <emphasis>what</emphasis> something is, rather than describing - <emphasis>how</emphasis> it should be presented.</para> - - <note> - <title><literal>formal</literal> vs. <literal>informal</literal></title> - - <para>Some elements may exist in two forms, <emphasis>formal</emphasis> - and <emphasis>informal</emphasis>. Typically, the formal version of - the element will consist of a title followed by the informal - version of the element. The informal version will not have a - title.</para> - </note> - - <para>The DocBook DTD is available from the ports collection in the - <package>textproc/docbook</package> port. It is automatically - installed as part of the <package>textproc/docproj</package> - port.</para> - - <sect2> - <title>FreeBSD extensions</title> - - <para>The FreeBSD Documentation Project has extended the DocBook DTD by - adding some new elements. These elements serve to make some of the - markup more precise.</para> - - <para>Where a FreeBSD specific element is listed below it is clearly - marked.</para> - - <para>Throughout the rest of this document, the term - <quote>DocBook</quote> is used to mean the FreeBSD extended DocBook - DTD.</para> - - <note> - <para>There is nothing about these extensions that is FreeBSD - specific, it was just felt that they were useful enhancements for - this particular project. Should anyone from any of the other *nix - camps (NetBSD, OpenBSD, Linux, …) be interested in - collaborating on a standard DocBook extension set, please get in - touch with &a.doceng;.</para> - </note> - - <para>The FreeBSD extensions are not (currently) in the ports - collection. They are stored in the FreeBSD CVS tree, as <link xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/xml/freebsd.dtd">doc/share/xml/freebsd.dtd</link>.</para> - </sect2> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>In compliance with the DocBook guidelines for writing FPIs for - DocBook customizations, the FPI for the FreeBSD extended DocBook DTD - is:</para> - - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting> - </sect2> - - <sect2> - <title>Document structure</title> - - <para>DocBook allows you to structure your documentation in several - ways. In the FreeBSD Documentation Project we are using two primary - types of DocBook document: the book and the article.</para> - - <para>A book is organized into <tag>chapter</tag>s. This is a - mandatory requirement. There may be <tag>part</tag>s between - the book and the chapter to provide another layer of organization. - The Handbook is arranged in this way.</para> - - <para>A chapter may (or may not) contain one or more sections. These - are indicated with the <tag>sect1</tag> element. If a section - contains another section then use the <tag>sect2</tag> - element, and so on, up to <tag>sect5</tag>.</para> - - <para>Chapters and sections contain the remainder of the content.</para> - - <para>An article is simpler than a book, and does not use chapters. - Instead, the content of an article is organized into one or more - sections, using the same <tag>sect1</tag> (and - <tag>sect2</tag> and so on) elements that are used in - books.</para> - - <para>Obviously, you should consider the nature of the documentation you - are writing in order to decide whether it is best marked up as a book - or an article. Articles are well suited to information that does not - need to be broken down into several chapters, and that is, relatively - speaking, quite short, at up to 20-25 pages of content. Books are - best suited to information that can be broken up into several - chapters, possibly with appendices and similar content as well.</para> - - <para>The <link xlink:href="&url.base;/docs.html">FreeBSD - tutorials</link> are all marked up as articles, while this - document, the <link xlink:href="&url.books.faq;/index.html">FreeBSD - FAQ</link>, and the <link xlink:href="&url.books.handbook;/index.html">FreeBSD Handbook</link> are - all marked up as books.</para> - - <sect3> - <title>Starting a book</title> - - <para>The content of the book is contained within the - <tag>book</tag> element. As well as containing structural - markup, this element can contain elements that include additional - information about the book. This is either meta-information, used - for reference purposes, or additional content used to produce a - title page.</para> - - <para>This additional information should be contained within - <tag>bookinfo</tag>.</para> - - <example> - <title>Boilerplate <tag>book</tag> with - <tag>bookinfo</tag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><book> - <bookinfo> - <title><replaceable>Your title here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your email address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> - </abstract> - </bookinfo> - - … - -</book></programlisting> - </example> - </sect3> - - <sect3> - <title>Starting an article</title> - - <para>The content of the article is contained within the - <tag>article</tag> element. As well as containing - structural markup, this element can contain elements that include - additional information about the article. This is either - meta-information, used for reference purposes, or additional content - used to produce a title page.</para> - - <para>This additional information should be contained within - <tag>articleinfo</tag>.</para> - - <example> - <title>Boilerplate <tag>article</tag> with - <tag>articleinfo</tag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><article> - <articleinfo> - <title><replaceable>Your title here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your email address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> - </abstract> - </articleinfo> - - … - -</article></programlisting> - </example> - </sect3> - <sect3> - <title>Indicating chapters</title> - - <para>Use <tag>chapter</tag> to mark up your chapters. Each - chapter has a mandatory <tag>title</tag>. Articles do not - contain chapters, they are reserved for books.</para> - - <example> - <title>A simple chapter</title> - - <programlisting><![CDATA[<chapter> - <title>The chapter's title</title> - - ... -</chapter>]]></programlisting> - </example> - - <para>A chapter cannot be empty; it must contain elements in addition - to <tag>title</tag>. If you need to include an empty - chapter then just use an empty paragraph.</para> - - <example> - <title>Empty chapters</title> - - <programlisting><![CDATA[<chapter> - <title>This is an empty chapter</title> - - <para></para> -</chapter>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Sections below chapters</title> - - <para>In books, chapters may (but do not need to) be broken up into - sections, subsections, and so on. In articles, sections are the - main structural element, and each article must contain at least one - section. Use the - <tag>sect<replaceable>n</replaceable></tag> element. The - <replaceable>n</replaceable> indicates the section number, which - identifies the section level.</para> - - <para>The first <tag>sect<replaceable>n</replaceable></tag> is - <tag>sect1</tag>. You can have one or more of these in a - chapter. They can contain one or more <tag>sect2</tag> - elements, and so on, down to <tag>sect5</tag>.</para> - - <example> - <title>Sections in chapters</title> - - <programlisting><![CDATA[<chapter> - <title>A sample chapter</title> - - <para>Some text in the chapter.</para> - - <sect1> - <title>First section (1.1)</title> - - … - </sect1> - - <sect1> - <title>Second section (1.2)</title> - - <sect2> - <title>First sub-section (1.2.1)</title> - - <sect3> - <title>First sub-sub-section (1.2.1.1)</title> - - … - </sect3> - </sect2> - - <sect2> - <title>Second sub-section (1.2.2)</title> - - … - </sect2> - </sect1> -</chapter>]]></programlisting> - </example> - - <note> - <para>This example includes section numbers in the section titles. - You should not do this in your documents. Adding the section - numbers is carried out by the stylesheets (of which more - later), and you do not need to manage them yourself.</para> - </note> - </sect3> - - <sect3> - <title>Subdividing using <tag>part</tag>s</title> - - <para>You can introduce another layer of organization between - <tag>book</tag> and <tag>chapter</tag> with one or - more <tag>part</tag>s. This cannot be done in an - <tag>article</tag>.</para> - - <programlisting><![CDATA[<part> - <title>Introduction</title> - - <chapter> - <title>Overview</title> - - ... - </chapter> - - <chapter> - <title>What is FreeBSD?</title> - - ... - </chapter> - - <chapter> - <title>History</title> - - ... - </chapter> -</part>]]></programlisting> - </sect3> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Paragraphs</title> - - <para>DocBook supports three types of paragraphs: - <tag>formalpara</tag>, <tag>para</tag>, and - <tag>simpara</tag>.</para> - - <para>Most of the time you will only need to use - <tag>para</tag>. <tag>formalpara</tag> includes a - <tag>title</tag> element, and <tag>simpara</tag> - disallows some elements from within <tag>para</tag>. Stick - with <tag>para</tag>.</para> - - <example> - <title><tag>para</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>This is a paragraph. It can contain just about any - other element.</para> ]]></programlisting> - - <para>Appearance:</para> - - <para>This is a paragraph. It can contain just about any other - element.</para> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph. You will - probably only need it infrequently.</para> - - <para>Blockquotes can optionally contain a title and an attribution - (or they can be left untitled and unattributed).</para> - - <example> - <title><tag>blockquote</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting> - - <para>Appearance:</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> - </example> - </sect3> - - <sect3> - <title>Tips, notes, warnings, cautions, important information and - sidebars.</title> - - <para>You may need to include extra information separate from the - main body of the text. Typically this is <quote>meta</quote> - information that the user should be aware of.</para> - - <para>Depending on the nature of the information, one of - <tag>tip</tag>, <tag>note</tag>, - <tag>warning</tag>, <tag>caution</tag>, and - <tag>important</tag> should be used. Alternatively, if the - information is related to the main text but is not one of the above, - use <tag>sidebar</tag>.</para> - - <para>The circumstances in which to choose one of these elements over - another is unclear. The DocBook documentation suggests:</para> - - <itemizedlist> - <listitem> - <para>A Note is for information that should be heeded by all - readers.</para> - </listitem> - - <listitem> - <para>An Important element is a variation on Note.</para> - </listitem> - - <listitem> - <para>A Caution is for information regarding possible data loss - or software damage.</para> - </listitem> - - <listitem> - <para>A Warning is for information regarding possible hardware - damage or injury to life or limb.</para> - </listitem> - </itemizedlist> - - <example> - <title><tag>warning</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<warning> - <para>Installing FreeBSD may make you want to delete Windows from your - hard disk.</para> -</warning>]]></programlisting> - </example> - - <!-- Need to do this outside of the example --> - <warning> - <para>Installing FreeBSD may make you want to delete Windows from - your hard disk.</para> - </warning> - </sect3> - - <sect3> - <title>Lists and procedures</title> - - <para>You will often need to list pieces of information to the user, - or present them with a number of steps that must be carried out in - order to accomplish a particular goal.</para> - - <para>In order to do this, use <tag>itemizedlist</tag>, - <tag>orderedlist</tag>, or - <tag>procedure</tag><footnote><para>There are other types of - list element in DocBook, but we are not concerned with those at - the moment.</para> - </footnote> - </para> - - <para><tag>itemizedlist</tag> and - <tag>orderedlist</tag> are similar to their counterparts in - HTML, <tag>ul</tag> and <tag>ol</tag>. Each one - consists of one or more <tag>listitem</tag> elements, and - each <tag>listitem</tag> contains one or more block - elements. The <tag>listitem</tag> elements are analogous to - HTML's <tag>li</tag> tags. However, unlike HTML, they are - required.</para> - - <para><tag>procedure</tag> is slightly different. It consists - of <tag>step</tag>s, which may in turn consists of more - <tag>step</tag>s or <tag>substep</tag>s. Each - <tag>step</tag> contains block elements.</para> - - <example> - <title><tag>itemizedlist</tag>, - <tag>orderedlist</tag>, and - <tag>procedure</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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> - -<procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <para>And now do this.</para> - </step> -</procedure>]]></programlisting> - - <para>Appearance:</para> - - <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> - </example> - - <!-- Can't have <procedure> inside <example>, so this is a cheat --> - - <procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <para>And now do this.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Showing file samples</title> - - <para>If you want to show a fragment of a file (or perhaps a complete - file) to the user, wrap it in the <tag>programlisting</tag> - element.</para> - - <para>White space and line breaks within - <tag>programlisting</tag> <emphasis>are</emphasis> - significant. In particular, this means that the opening tag should - appear on the same line as the first line of the output, and the - closing tag should appear on the same line as the last line of the - output, otherwise spurious blank lines may be included.</para> - - <example> - <title><tag>programlisting</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>When you have finished, your program should look like - this:</para> - -<programlisting>#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting>]]></programlisting> - - <para>Notice how the angle brackets in the - <literal>#include</literal> line need to be referenced by their - entities instead of being included literally.</para> - - <para>Appearance:</para> - - <para>When you have finished, your program should look like - this:</para> - - <programlisting>#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting> - </example> - </sect3> - - <sect3> - <title>Callouts</title> - - <para>A callout is a mechanism for referring back to an earlier piece - of text or specific position within an earlier example without - linking to it within the text.</para> - - <para>To do this, mark areas of interest in your example - (<tag>programlisting</tag>, - <tag>literallayout</tag>, or whatever) with the - <tag>co</tag> element. Each element must have a unique - <literal>id</literal> assigned to it. After the example include a - <tag>calloutlist</tag> that refers back to the example and - provides additional commentary.</para> - - <example> - <title><tag>co</tag> and - <tag>calloutlist</tag></title> - - <programlisting><![CDATA[<para>When you have finished, your program should look like - this:</para> - -<programlisting>#include <stdio.h> <co id="co-ex-include"/> - -int <co id="co-ex-return"/> -main(void) -{ - printf("hello, world\n"); <co 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>]]></programlisting> - - <para>Appearance:</para> - - <para>When you have finished, your program should look like - this:</para> - - <programlisting>#include <stdio.h> <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> - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <para>Unlike HTML, you do not need to use tables for layout purposes, - as the stylesheet handles those issues for you. Instead, just use - tables for marking up tabular data.</para> - - <para>In general terms (and see the DocBook documentation for more - detail) a table (which can be either formal or informal) consists of - a <tag>table</tag> element. This contains at least one - <tag>tgroup</tag> element, which specifies (as an attribute) - the number of columns in this table group. Within the tablegroup - you can then have one <tag>thead</tag> element, which - contains elements for the table headings (column headings), and one - <tag>tbody</tag> which contains the body of the - table.</para> - - <para>Both <tag>tgroup</tag> and <tag>thead</tag> - contain <tag>row</tag> elements, which in turn contain - <tag>entry</tag> elements. Each <tag>entry</tag> - element specifies one cell in the table.</para> - - <example> - <title><tag>informaltable</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<informaltable frame="none" 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>]]></programlisting> - - <para>Appearance:</para> - - <informaltable frame="none" 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> - </example> - - <para>Always use the <literal>pgwide</literal> attribute with - a value of <literal>1</literal> with the - <tag>informaltable</tag> element. A bug in Internet - Explorer can cause the table to render incorrectly if this - is omitted.</para> - - <para>If you do not want a border around the table the - <literal>frame</literal> attribute can be added to the - <tag>informaltable</tag> element with a value of - <literal>none</literal> (i.e., <literal><informaltable - frame="none"></literal>).</para> - - <example> - <title>Tables where <literal>frame="none"</literal></title> - - <para>Appearance:</para> - - <informaltable frame="none" 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> - </example> - </sect3> - - <sect3> - <title>Examples for the user to follow</title> - - <para>A lot of the time you need to show examples for the user to - follow. Typically, these will consist of dialogs with the computer; - the user types in a command, the user gets a response back, they - type in another command, and so on.</para> - - <para>A number of distinct elements and entities come into play - here.</para> - - <variablelist> - <varlistentry> - <term><tag>screen</tag></term> - - <listitem> - <para>Everything the user sees in this example will be on the - computer screen, so the next element is - <tag>screen</tag>.</para> - - <para>Within <tag>screen</tag>, white space is - significant.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><tag>prompt</tag>, - <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal></term> - - <listitem> - <para>Some of the things the user will be seeing on the screen - are prompts from the computer (either from the operating system, command - shell, or application). These should be marked up using - <tag>prompt</tag>.</para> - - <para>As a special case, the two shell prompts for the normal - user and the root user have been provided as entities. Every - time you want to indicate the user is at a shell prompt, use - one of <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> as necessary. They do - not need to be inside <tag>prompt</tag>.</para> - - <note> - <para><literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> are FreeBSD - extensions to DocBook, and are not part of the original - DTD.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><tag>userinput</tag></term> - - <listitem> - <para>When displaying text that the user should type in, wrap it - in <tag>userinput</tag> tags. It will probably be - displayed differently to the user.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><tag>screen</tag>, <tag>prompt</tag>, and - <tag>userinput</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting> - - <para>Appearance:</para> - - <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> - </example> - - <note> - <para>Even though we are displaying the contents of the file - <filename>foo2</filename>, it is <emphasis>not</emphasis> marked - up as <tag>programlisting</tag>. Reserve - <tag>programlisting</tag> for showing fragments of files - outside the context of user actions.</para> - </note> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasizing information</title> - - <para>When you want to emphasize a particular word or phrase, use - <tag>emphasis</tag>. This may be presented as italic, or - bold, or might be spoken differently with a text-to-speech - system.</para> - - <para>There is no way to change the presentation of the emphasis - within your document, no equivalent of HTML's <tag>b</tag> - and <tag>i</tag>. If the information you are presenting is - important then consider presenting it in - <tag>important</tag> rather than - <tag>emphasis</tag>.</para> - - <example> - <title><tag>emphasis</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>FreeBSD is without doubt <emphasis>the</emphasis> - premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix - like operating system for the Intel architecture.</para> - </example> - </sect3> - - <sect3> - <title>Quotations</title> - - <para>To quote text from another document or source, or to denote - a phrase that is used figuratively, use <tag>quote</tag>. - Within a <tag>quote</tag> tag, you may use most of the - markup tags available for normal text.</para> - - <example> - <title>Quotations</title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the - <quote>boundary between local and public administration</quote>, - as RFC 1535 calls it.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>However, make sure that the search does not go beyond the - <quote>boundary between local and public administration</quote>, - as RFC 1535 calls it.</para> - </example> - </sect3> - - <sect3> - <title>Keys, mouse buttons, and combinations</title> - - <para>To refer to a specific key on the keyboard, use - <tag>keycap</tag>. To refer to a mouse button, use - <tag>mousebutton</tag>. And to refer to combinations of key - presses or mouse clicks, wrap them all in - <tag>keycombo</tag>.</para> - - <para><tag>keycombo</tag> has an attribute called - <literal>action</literal>, which may be one of - <literal>click</literal>, <literal>double-click</literal>, - <literal>other</literal>, <literal>press</literal>, - <literal>seq</literal>, or <literal>simul</literal>. The last two - values denote whether the keys or buttons should be pressed in - sequence, or simultaneously.</para> - - <para>The stylesheets automatically add any connecting symbols, such - as <literal>+</literal>, between the key names, when wrapped in - <tag>keycombo</tag>.</para> - - <example> - <title>Keys, mouse buttons, and combinations</title> - - <para>Use:</para> - - <programlisting><![CDATA[<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 your work, 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>]]></programlisting> - - <para>Appearance:</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 your work, 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> - </example> - </sect3> - - <sect3> - <title>Applications, commands, options, and cites</title> - - <para>You will frequently want to refer to both applications and - commands when writing for the Handbook. The distinction between - them is simple: an application is the name for a suite (or possibly - just 1) of programs that fulfil a particular task. A command is the - name of a program that the user can run.</para> - - <para>In addition, you will occasionally need to list one or more of - the options that a command might take.</para> - - <para>Finally, you will often want to list a command with its manual - section number, in the <quote>command(number)</quote> format so - common in Unix manuals.</para> - - <para>Mark up application names with - <tag>application</tag>.</para> - - <para>When you want to list a command with its manual section number - (which should be most of the time) the DocBook element is - <tag>citerefentry</tag>. This will contain a further two - elements, <tag>refentrytitle</tag> and - <tag>manvolnum</tag>. The content of - <tag>refentrytitle</tag> is the name of the command, and the - content of <tag>manvolnum</tag> is the manual page - section.</para> - - <para>This can be cumbersome to write, and so a series of <link linkend="sgml-primer-general-entities">general entities</link> - have been created to make this easier. Each entity takes the form - <literal>&man.manual-page.manual-section;</literal>.</para> - - <para>The file that contains these entities is in - <filename>doc/share/xml/man-refs.ent</filename>, and can be - referred to using this FPI:</para> - - <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> - - <para>Therefore, the introduction to your documentation will probably - look like this:</para> - - <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]></programlisting> - - <para>Use <tag>command</tag> when you want to include a - command name <quote>in-line</quote> but present it as something the - user should type in.</para> - - <para>Use <tag>option</tag> to mark up the options - which will be passed to a command.</para> - - <para>When referring to the same command multiple times in - close proximity it is preferred to use the - <literal>&man.command.section;</literal> - notation to markup the first reference and use - <tag>command</tag> to markup subsequent references. - This makes the generated output, especially HTML, appear - visually better.</para> - - <para>This can be confusing, and sometimes the choice is not always - clear. Hopefully this example makes it clearer.</para> - - <example> - <title>Applications, commands, and options.</title> - - <para>Use:</para> - - <programlisting><![CDATA[<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.8;, and &man.newaliases.8; - 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>]]></programlisting> - - <para>Appearance:</para> - - <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>, <citerefentry> - <refentrytitle>mailq</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, and <citerefentry> - <refentrytitle>newaliases</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry> 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> - </example> - - <note> - <para>Notice how the - <literal>&man.command.section;</literal> notation is easier to follow.</para> - </note> - </sect3> - - <sect3> - <title>Files, directories, extensions</title> - - <para>Whenever you wish to refer to the name of a file, a directory, - or a file extension, use <tag>filename</tag>.</para> - - <example> - <title><tag>filename</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>The SGML source for the Handbook in English can be - found in <filename>/usr/doc/en/handbook/</filename>. The first - file is called <filename>handbook.xml</filename> in that - directory. You should also see a <filename>Makefile</filename> - and a number of files with a <filename>.ent</filename> - extension.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The SGML source for the Handbook in English can be found in - <filename>/usr/doc/en/handbook/</filename>. The first file is - called <filename>handbook.xml</filename> in that directory. You - should also see a <filename>Makefile</filename> and a number of - files with a <filename>.ent</filename> extension.</para> - </example> - </sect3> - - <sect3> - <title>The name of ports</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>You might need to include the name of a program from the - FreeBSD Ports Collection in the documentation. Use the - <tag>filename</tag> tag with the <literal>role</literal> - attribute set to <literal>package</literal> to identify these. - Since ports - can be installed in any number of locations, only include - the category and the port name; do not include - <filename>/usr/ports</filename>.</para> - - <example> - <title><tag>filename</tag> tag with - <literal>package</literal> role</title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Install the <package>net/ethereal</package> - port to view network traffic.</para> - </example> - </sect3> - - <sect3> - <title>Devices</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When referring to devices you have two choices. You can either - refer to the device as it appears in <filename>/dev</filename>, or - you can use the name of the device as it appears in the kernel. For - this latter course, use <tag>devicename</tag>.</para> - - <para>Sometimes you will not have a choice. Some devices, such as - networking cards, do not have entries in <filename>/dev</filename>, - or the entries are markedly different from those entries.</para> - - <example> - <title><tag>devicename</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para><devicename>sio</devicename> is used for serial - communication in FreeBSD. <devicename>sio</devicename> manifests - through a number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> - -<para>By contrast, the networking devices, such as - <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para> - -<para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para><filename>sio</filename> is used for serial communication - in FreeBSD. <filename>sio</filename> manifests through a - number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and - <filename>/dev/cuaa0</filename>.</para> - - <para>By contrast, the networking devices, such as - <filename>ed0</filename> do not appear in - <filename>/dev</filename>.</para> - - <para>In MS-DOS, the first floppy drive is referred to as - <filename>a:</filename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para> - </example> - </sect3> - - <sect3> - <title>Hosts, domains, IP addresses, and so forth</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>You can markup identification information for networked - computers (hosts) in several ways, depending on the nature of the - information. All of them use <tag>hostid</tag> as the - element, with the <literal>role</literal> attribute selecting the - type of the marked up information.</para> - - <variablelist> - <varlistentry> - <term>No role attribute, or - <literal>role="hostname"</literal></term> - - <listitem> - <para>With no role attribute (i.e., - <tag>hostid</tag>...<tag>/hostid</tag>) the - marked up information is the simple hostname, such as - <literal>freefall</literal> or <literal>wcarchive</literal>. - You can explicitly specify this with - <literal>role="hostname"</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="domainname"</literal></term> - - <listitem> - <para>The text is a domain name, such as - <literal>FreeBSD.org</literal> or - <literal>ngo.org.uk</literal>. There is no hostname - component.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="fqdn"</literal></term> - - <listitem> - <para>The text is a Fully Qualified Domain Name, with both - hostname and domain name parts.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="ipaddr"</literal></term> - - <listitem> - <para>The text is an IP address, probably expressed as a dotted - quad.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="ip6addr"</literal></term> - - <listitem> - <para>The text is an IPv6 address.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="netmask"</literal></term> - - <listitem> - <para>The text is a network mask, which might be expressed as a - dotted quad, a hexadecimal string, or as a - <literal>/</literal> followed by a number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="mac"</literal></term> - - <listitem> - <para>The text is an Ethernet MAC address, expressed as a series - of 2 digit hexadecimal numbers separated by colons.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><tag>hostid</tag> and roles</title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>The local machine can always be referred to by the - name <hostid>localhost</hostid>, which will have the IP address - <hostid role="ipaddr">127.0.0.1</hostid>.</para> - -<para>The <hostid role="domainname">FreeBSD.org</hostid> domain - contains a number of different hosts, including - <hostid role="fqdn">freefall.FreeBSD.org</hostid> and - <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para> - -<para>When adding an IP alias to an interface (using - <command>ifconfig</command>) <emphasis>always</emphasis> use a - netmask of <hostid role="netmask">255.255.255.255</hostid> - (which can also be expressed as <hostid - role="netmask">0xffffffff</hostid>.</para> - -<para>The MAC address uniquely identifies every network card - in existence. A typical MAC address looks like <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The local machine can always be referred to by the name - <systemitem>localhost</systemitem>, which will have the IP address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> - - <para>The <systemitem class="fqdomainname">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 IP 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 MAC address uniquely identifies every network card in - existence. A typical MAC address looks like <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> - </example> - </sect3> - - <sect3> - <title>Usernames</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When you need to refer to a specific username, such as - <literal>root</literal> or <literal>bin</literal>, use - <tag>username</tag>.</para> - - <example> - <title><tag>username</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>To carry out most system administration functions you - will need to be <username>root</username>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>To carry out most system administration functions you will - need to be <systemitem class="username">root</systemitem>.</para> - </example> - </sect3> - - <sect3> - <title>Describing <filename>Makefile</filename>s</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>Two elements exist to describe parts of - <filename>Makefile</filename>s, <tag>maketarget</tag> and - <tag>makevar</tag>.</para> - - <para><tag>maketarget</tag> identifies a build target exported - by a <filename>Makefile</filename> that can be given as a parameter - to <command>make</command>. <tag>makevar</tag> identifies a - variable that can be set (in the environment, on the - <command>make</command> command line, or within the - <filename>Makefile</filename>) to influence the process.</para> - - <example> - <title><tag>maketarget</tag> and - <tag>makevar</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>Two common targets in a <filename>Makefile</filename> - are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> - -<para>Typically, invoking <maketarget>all</maketarget> will rebuild the - application, and invoking <maketarget>clean</maketarget> will remove - the temporary files (<filename>.o</filename> for example) created by - the build process.</para> - -<para><maketarget>clean</maketarget> may be controlled by a number of - variables, including <makevar>CLOBBER</makevar> and - <makevar>RECURSE</makevar>.</para>]]></programlisting> - - <para>Appearance:</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> - </example> - </sect3> - - <sect3> - <title>Literal text</title> - - <para>You will often need to include <quote>literal</quote> text in the - Handbook. This is text that is excerpted from another file, or - which should be copied from the Handbook into another file - verbatim.</para> - - <para>Some of the time, <tag>programlisting</tag> will be - sufficient to denote this text. <tag>programlisting</tag> - is not always appropriate, particularly when you want to include a - portion of a file <quote>in-line</quote> with the rest of the - paragraph.</para> - - <para>On these occasions, use <tag>literal</tag>.</para> - - <example> - <title><tag>literal</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting> - - <para>Appearance:</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> - </example> - </sect3> - - <sect3> - <title>Showing items that the user <emphasis>must</emphasis> fill - in</title> - - <para>There will often be times when you want to show the user what to - do, or refer to a file, or command line, or similar, where the user - cannot simply copy the examples that you provide, but must instead - include some information themselves.</para> - - <para><tag>replaceable</tag> is designed for this eventuality. - Use it <emphasis>inside</emphasis> other elements to indicate parts - of that element's content that the user must replace.</para> - - <example> - <title><tag>replaceable</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> -</informalexample>]]></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen>&prompt.user; <userinput>man command</userinput></screen> - </informalexample> - - <para><tag>replaceable</tag> can be used in many different - elements, including <tag>literal</tag>. This example also - shows that <tag>replaceable</tag> should only be wrapped - around the content that the user <emphasis>is</emphasis> meant to - provide. The other content should be left alone.</para> - - <para>Use:</para> - - <programlisting><![CDATA[<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>]]></programlisting> - - <para>Appearance:</para> - - <para>The <literal>maxusers n</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> - </example> - </sect3> - - <sect3> - <title>Quoting system errors</title> - - <para>You might want to show errors generated by FreeBSD. - Mark these with <tag>errorname</tag>. This - indicates the exact error that appears.</para> - - <example> - <title><tag>errorname</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[ -<screen><errorname>Panic: cannot mount root</errorname></screen> ]]> -</programlisting> - - - <para>Appearance:</para> - - <informalexample> - <screen><errorname>Panic: cannot mount root</errorname></screen> - </informalexample> - </example> - </sect3> - </sect2> - - <sect2> - <title>Images</title> - - <important> - <para>Image support in the documentation is currently extremely - experimental. I think the mechanisms described here are unlikely to - change, but that is not guaranteed.</para> - - <para>You will also need to install the - <package>graphics/ImageMagick</package> port, which is used to - convert between the different image formats. This is a big port, - and most of it is not required. However, while we are working on the - <filename>Makefile</filename>s and other infrastructure it makes - things easier. This port is <emphasis>not</emphasis> in the - <package>textproc/docproj</package> meta port, you must install it - by hand.</para> - - <para>The best example of what follows in practice is the - <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> document. - If you are unsure of the description that follows, take a look at the - files in that directory to see how everything hangs together. - Experiment with creating different formatted versions of the - document to see how the image markup appears in the formatted - output.</para> - </important> - - <sect3> - <title>Image formats</title> - - <para>We currently support two formats for images. The format you - should use will depend on the nature of your image.</para> - - <para>For images that are primarily vector based, such as network - diagrams, time lines, and similar, use Encapsulated Postscript, and - make sure that your images have the <filename>.eps</filename> - extension.</para> - - <para>For bitmaps, such as screen captures, use the Portable Network - Graphic format, and make sure that your images have the - <filename>.png</filename> extension.</para> - - <para>These are the <emphasis>only</emphasis> formats in which images - should be committed to the CVS repository.</para> - - <para>Use the right format for the right image. It is to be expected - that your documentation will have a mix of EPS and PNG images. The - <filename>Makefile</filename>s ensure that the correct format image - is chosen depending on the output format that you use for your - documentation. <emphasis>Do not commit the same image to the - repository in two different formats</emphasis>.</para> - - <important> - <para>It is anticipated that the Documentation Project will switch to - using the Scalable Vector Graphic (SVG) format for vector images. - However, the current state of SVG capable editing tools makes this - impractical.</para> - </important> - </sect3> - - <sect3> - <title>Markup</title> - - <para>The markup for an image is relatively simple. First, markup a - <tag>mediaobject</tag>. The <tag>mediaobject</tag> - can contain other, more specific objects. We are concerned with - two, the <tag>imageobject</tag> and the - <tag>textobject</tag>.</para> - - <para>You should include one <tag>imageobject</tag>, and two - <tag>textobject</tag> elements. The - <tag>imageobject</tag> will point to the name of the image - file that will be used (without the extension). The - <tag>textobject</tag> elements contain information that will - be presented to the user as well as, or instead of, the - image.</para> - - <para>There are two circumstances where this can happen.</para> - - <itemizedlist> - <listitem> - <para>When the reader is viewing the documentation in HTML. In - this case, each image will need to have associated alternate - text to show the user, typically whilst the image is loading, or - if they hover the mouse pointer over the image.</para> - </listitem> - - <listitem> - <para>When the reader is viewing the documentation in plain text. - In this case, each image should have an ASCII art equivalent to - show the user.</para> - </listitem> - </itemizedlist> - - <para>An example will probably make things easier to understand. - Suppose you have an image, called <filename>fig1.png</filename>, that - you want to include in the document. This image is of a rectangle - with an A inside it. The markup for this would be as - follows.</para> - - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="fig1"> <co xml:id="co-image-ext"/> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ <co xml:id="co-image-literal"/> -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> <co xml:id="co-image-phrase"/> - </textobject> -</mediaobject></programlisting> - - <calloutlist> - <callout arearefs="co-image-ext"> - <para>Include an <tag>imagedata</tag> element inside the - <tag>imageobject</tag> element. The - <literal>fileref</literal> attribute should contain the filename - of the image to include, without the extension. The stylesheets - will work out which extension should be added to the filename - automatically.</para> - </callout> - - <callout arearefs="co-image-literal"> - <para>The first <tag>textobject</tag> should contain a - <tag>literallayout</tag> element, where the - <literal>class</literal> attribute is set to - <literal>monospaced</literal>. This is your opportunity to - demonstrate your ASCII art skills. This content will be used if - the document is converted to plain text.</para> - - <para>Notice how the first and last lines of the content of the - <tag>literallayout</tag> element butt up next to the - element's tags. This ensures no extraneous white space is - included.</para> - </callout> - - <callout arearefs="co-image-phrase"> - <para>The second <tag>textobject</tag> should contain a - single <tag>phrase</tag> element. The contents of this - will become the <literal>alt</literal> attribute for the image - when this document is converted to HTML.</para> - </callout> - </calloutlist> - </sect3> - - <sect3> - <title><filename>Makefile</filename> entries</title> - - <para>Your images must be listed in the - <filename>Makefile</filename> in the <varname>IMAGES</varname> - variable. This variable should contain the name of all your - <emphasis>source</emphasis> images. For example, if you have - created three figures, <filename>fig1.eps</filename>, - <filename>fig2.png</filename>, <filename>fig3.png</filename>, then - your <filename>Makefile</filename> should have lines like this in - it.</para> - - <programlisting>… -IMAGES= fig1.eps fig2.png fig3.png -…</programlisting> - - <para>or</para> - - <programlisting>… -IMAGES= fig1.eps -IMAGES+= fig2.png -IMAGES+= fig3.png -…</programlisting> - - <para>Again, the <filename>Makefile</filename> will work out the - complete list of images it needs to build your source document, you - only need to list the image files <emphasis>you</emphasis> - provided.</para> - </sect3> - - <sect3> - <title>Images and chapters in subdirectories</title> - - <para>You must be careful when you separate your documentation into - smaller files (see <xref linkend="sgml-primer-include-using-gen-entities"/>) in - different directories.</para> - - <para>Suppose you have a book with three chapters, and the chapters - are stored in their own directories, called - <filename>chapter1/chapter.xml</filename>, - <filename>chapter2/chapter.xml</filename>, and - <filename>chapter3/chapter.xml</filename>. If each chapter has - images associated with it, I suggest you place those images in each - chapter's subdirectory (<filename>chapter1/</filename>, - <filename>chapter2/</filename>, and - <filename>chapter3/</filename>).</para> - - <para>However, if you do this you must include the directory names in - the <varname>IMAGES</varname> variable in the - <filename>Makefile</filename>, <emphasis>and</emphasis> you must - include the directory name in the <tag>imagedata</tag> - element in your document.</para> - - <para>For example, if you have <filename>chapter1/fig1.png</filename>, - then <filename>chapter1/chapter.xml</filename> should - contain:</para> - - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> <co xml:id="co-image-dir"/> - </imageobject> - - … - -</mediaobject></programlisting> - - <calloutlist> - <callout arearefs="co-image-dir"> - <para>The directory name must be included in the - <literal>fileref</literal> attribute.</para> - </callout> - </calloutlist> - - <para>The <filename>Makefile</filename> must contain:</para> - - <programlisting>… -IMAGES= chapter1/fig1.png -…</programlisting> - - <para>Then everything should just work.</para> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other parts of the same document</title> - - <para>Linking within the same document requires you to specify - where you are linking from (i.e., the text the user will click, or - otherwise indicate, as the source of the link) and where you are - linking to (the link's destination).</para> - - <para>Each element within DocBook has an attribute called - <literal>id</literal>. You can place text in this attribute to - uniquely name the element it is attached to.</para> - - <para>This value will be used when you specify the link - source.</para> - - <para>Normally, you will only be linking to chapters or sections, so - you would add the <literal>id</literal> attribute to these - elements.</para> - - <example> - <title><literal>id on chapters and sections</literal></title> - - <programlisting><![CDATA[<chapter id="chapter1"> - <title>Introduction</title> - - <para>This is the introduction. It contains a subsection, - which is identified as well.</para> - - <sect1 id="chapter1-sect1"> - <title>Sub-sect 1</title> - - <para>This is the subsection.</para> - </sect1> -</chapter>]]></programlisting> - </example> - - <para>Obviously, you should use more descriptive values. The values - must be unique within the document (i.e., not just the file, but the - document the file might be included in as well). Notice how the - <literal>id</literal> for the subsection is constructed by appending - text to the <literal>id</literal> of the chapter. This helps to - ensure that they are unique.</para> - - <para>If you want to allow the user to jump into a specific portion of - the document (possibly in the middle of a paragraph or an example), - use <tag>anchor</tag>. This element has no content, but - takes an <literal>id</literal> attribute.</para> - - <example> - <title><tag>anchor</tag></title> - - <programlisting><![CDATA[<para>This paragraph has an embedded - <anchor id="para1">link target in it. It will not show up in - the document.</para>]]></programlisting> - </example> - - <para>When you want to provide the user with a link they can activate - (probably by clicking) to go to a section of the document that has - an <literal>id</literal> attribute, you can use either - <tag>xref</tag> or <tag>link</tag>.</para> - - <para>Both of these elements have a <literal>linkend</literal> - attribute. The value of this attribute should be the value that you - have used in a <literal>id</literal> attribute (it does not matter - if that value has not yet occurred in your document; this will work - for forward links as well as backward links).</para> - - <para>If you use <tag>xref</tag> then you have no control over - the text of the link. It will be generated for you.</para> - - <example> - <title>Using <tag>xref</tag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example:</para> - - <programlisting><![CDATA[<para>More information can be found - in <xref linkend="chapter1">.</para> - -<para>More specific information can be found - in <xref linkend="chapter1-sect1">.</para>]]></programlisting> - - <para>The text of the link will be generated automatically, and will - look like (<emphasis>emphasized</emphasis> text indicates the text - that will be the link):</para> - - <blockquote> - <para>More information can be found in <emphasis>Chapter - One</emphasis>.</para> - - <para>More specific information can be found in <emphasis>the - section called Sub-sect 1</emphasis>.</para> - </blockquote> - </example> - - <para>Notice how the text from the link is derived from the section - title or the chapter number.</para> - - <note> - <para>This means that you <emphasis>cannot</emphasis> use - <tag>xref</tag> to link to an <literal>id</literal> - attribute on an <tag>anchor</tag> element. The - <tag>anchor</tag> has no content, so the - <tag>xref</tag> cannot generate the text for the - link.</para> - </note> - - <para>If you want to control the text of the link then use - <tag>link</tag>. This element wraps content, and the - content will be used for the link.</para> - - <example> - <title>Using <tag>link</tag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example.</para> - - <programlisting><![CDATA[<para>More information can be found in - <link linkend="chapter1">the first chapter</link>.</para> - -<para>More specific information can be found in - <link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting> - - <para>This will generate the following - (<emphasis>emphasized</emphasis> text indicates the text that will - be the link):</para> - - <blockquote> - <para>More information can be found in <emphasis>the first - chapter</emphasis>.</para> - - <para>More specific information can be found in - <emphasis>this</emphasis> section.</para> - </blockquote> - </example> - - <note> - <para>That last one is a bad example. Never use words like - <quote>this</quote> or <quote>here</quote> as the source for the - link. The reader will need to hunt around the surrounding context - to see where the link is actually taking them.</para> - </note> - - <note> - <para>You <emphasis>can</emphasis> use <tag>link</tag> to - include a link to an <literal>id</literal> on an - <tag>anchor</tag> element, since the - <tag>link</tag> content defines the text that will be used - for the link.</para> - </note> - </sect3> - - <sect3> - <title>Linking to documents on the WWW</title> - - <para>Linking to external documents is much simpler, as long as you - know the URL of the document you want to link to. Use - <tag>ulink</tag>. The <literal>url</literal> attribute is - the URL of the page that the link points to, and the content of the - element is the text that will be displayed for the user to - activate.</para> - - <example> - <title><tag>ulink</tag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>Of course, you could stop reading this document and - go to the <ulink url="&url.base;/index.html">FreeBSD - home page</ulink> instead.</para>]]></programlisting> - - <para>Appearance:</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> - </example> - </sect3> - </sect2> - </sect1> -</chapter> diff --git a/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml deleted file mode 100644 index eb17a7cd91..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml +++ /dev/null @@ -1,1543 +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.45 ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sgml-primer"> - <title>SGML Primer</title> - - <para>FDP 文件幾乎都是以 SGML 相關程式寫的。本章會介紹 SGML 是什麼、 - 如何閱讀、理解這些 SGML 原稿，以及本文件中所運用的各項 SGML 技巧。</para> - - <para>本節部分靈感啟發來自 Mark Galassi 的這篇 <link xlink:href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</link>。</para> - - <sect1 xml:id="sgml-primer-overview"> - <title>簡介</title> - - <para>Way back when, electronic text was simple to deal with. Admittedly, - you had to know which character set your document was written in (ASCII, - EBCDIC, or one of a number of others) but that was about it. Text was - text, and what you saw really was what you got. No frills, no - formatting, no intelligence.</para> - - <para>Inevitably, this was not enough. Once you have text in a - machine-usable format, you expect machines to be able to use it and - manipulate it intelligently. You would like to indicate that certain - phrases should be emphasized, or added to a glossary, or be hyperlinks. - You might want filenames to be shown in a <quote>typewriter</quote> style - font for viewing on screen, but as <quote>italics</quote> when printed, - or any of a myriad of other options for presentation.</para> - - <para>It was once hoped that Artificial Intelligence (AI) would make this - easy. Your computer would read in the document and automatically - identify key phrases, filenames, text that the reader should type in, - examples, and more. Unfortunately, real life has not happened quite - like that, and our computers require some assistance before they can - meaningfully process our text.</para> - - <para>More precisely, they need help identifying what is what. You or I - can look at - - <blockquote> - <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - - <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen> - </blockquote> - - and easily see which parts are filenames, which are commands to be typed - in, which parts are references to manual pages, and so on. But the - computer processing the document cannot. For this we need - markup.</para> - - <para><quote>Markup</quote> is commonly used to describe <quote>adding - value</quote> or <quote>increasing cost</quote>. The term takes on both - these meanings when applied to text. Markup is additional text included - in the document, distinguished from the document's content in some way, - so that programs that process the document can read the markup and use - it when making decisions about the document. Editors can hide the - markup from the user, so the user is not distracted by it.</para> - - <para>The extra information stored in the markup <emphasis>adds - value</emphasis> to the document. Adding the markup to the document - must typically be done by a person—after all, if computers could - recognize the text sufficiently well to add the markup then there would - be no need to add it in the first place. This <emphasis>increases the - cost</emphasis> (i.e., the effort required) to create the - document.</para> - - <para>The previous example is actually represented in this document like - this:</para> - - <programlisting><![CDATA[ -<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - -<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting> - - <para>As you can see, the markup is clearly separate from the - content.</para> - - <para>Obviously, if you are going to use markup you need to define what - your markup means, and how it should be interpreted. You will need a - markup language that you can follow when marking up your - documents.</para> - - <para>Of course, one markup language might not be enough. A markup - language for technical documentation has very different requirements - than a markup language that was to be used for cookery recipes. This, - in turn, would be very different from a markup language used to describe - poetry. What you really need is a first language that you use to write - these other markup languages. A <emphasis>meta markup - language</emphasis>.</para> - - <para>This is exactly what the Standard Generalized Markup Language (SGML) - is. Many markup languages have been written in SGML, including the two - most used by the FDP, HTML and DocBook.</para> - - <para>Each language definition is more properly called a Document Type - Definition (DTD). The DTD specifies the name of the elements that can - be used, what order they appear in (and whether some markup can be used - inside other markup) and related information. A DTD is sometimes - referred to as an <emphasis>application</emphasis> of SGML.</para> - - <para xml:id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis> - specification of all the elements that are allowed to appear, the order - in which they should appear, which elements are mandatory, which are - optional, and so forth. This makes it possible to write an SGML - <emphasis>parser</emphasis> which reads in both the DTD and a document - which claims to conform to the DTD. The parser can then confirm whether - or not all the elements required by the DTD are in the document in the - right order, and whether there are any errors in the markup. This is - normally referred to as <quote>validating the document</quote>.</para> - - <note> - <para>This processing simply confirms that the choice of elements, their - ordering, and so on, conforms to that listed in the DTD. It does - <emphasis>not</emphasis> check that you have used - <emphasis>appropriate</emphasis> markup for the content. If you - tried to mark up all the filenames in your document as function - names, the parser would not flag this as an error (assuming, of - course, that your DTD defines elements for filenames and functions, - and that they are allowed to appear in the same place).</para> - </note> - - <para>It is likely that most of your contributions to the Documentation - Project will consist of content marked up in either HTML or DocBook, - rather than alterations to the DTDs. For this reason this book will - not touch on how to write a DTD.</para> - </sect1> - - <sect1 xml:id="sgml-primer-elements"> - <title>Elements, tags, and attributes</title> - - <para>All the DTDs written in SGML share certain characteristics. This is - hardly surprising, as the philosophy behind SGML will inevitably show - through. One of the most obvious manifestations of this philosophy is - that of <emphasis>content</emphasis> and - <emphasis>elements</emphasis>.</para> - - <para>Your documentation (whether it is a single web page, or a lengthy - book) is considered to consist of content. This content is then divided - (and further subdivided) into elements. The purpose of adding markup is - to name and identify the boundaries of these elements for further - processing.</para> - - <para>For example, consider a typical book. At the very top level, the - book is itself an element. This <quote>book</quote> element obviously - contains chapters, which can be considered to be elements in their own - right. Each chapter will contain more elements, such as paragraphs, - quotations, and footnotes. Each paragraph might contain further - elements, identifying content that was direct speech, or the name of a - character in the story.</para> - - <para>You might like to think of this as <quote>chunking</quote> content. - At the very top level you have one chunk, the book. Look a little - deeper, and you have more chunks, the individual chapters. These are - chunked further into paragraphs, footnotes, character names, and so - on.</para> - - <para>Notice how you can make this differentiation between different - elements of the content without resorting to any SGML terms. It really - is surprisingly straightforward. You could do this with a highlighter - pen and a printout of the book, using different colors to indicate - different chunks of content.</para> - - <para>Of course, we do not have an electronic highlighter pen, so we need - some other way of indicating which element each piece of content belongs - to. In languages written in SGML (HTML, DocBook, et al) this is done by - means of <emphasis>tags</emphasis>.</para> - - <para>A tag is used to identify where a particular element starts, and - where the element ends. <emphasis>The tag is not part of the element - itself</emphasis>. Because each DTD was normally written to mark up - specific types of information, each one will recognize different - elements, and will therefore have different names for the tags.</para> - - <para>For an element called <replaceable>element-name</replaceable> the - start tag will normally look like - <literal><element-name></literal>. The - corresponding closing tag for this element is - <literal></element-name></literal>.</para> - - <example> - <title>Using an element (start and end tags)</title> - - <para>HTML has an element for indicating that the content enclosed by - the element is a paragraph, called <literal>p</literal>. This - element has both start and end tags.</para> - - <programlisting><![CDATA[<p>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.</p> - -<p>This is another paragraph. But this one is much shorter.</p>]]></programlisting> - </example> - - <para>Not all elements require an end tag. Some elements have no content. - For example, in HTML you can indicate that you want a horizontal line to - appear in the document. Obviously, this line has no content, so just - the start tag is required for this element.</para> - - <example> - <title>Using an element (start tag only)</title> - - <para>HTML has an element for indicating a horizontal rule, called - <literal>hr</literal>. This element does not wrap content, so only - has a start tag.</para> - - <programlisting><![CDATA[<p>This is a paragraph.</p> - -<hr> - -<p>This is another paragraph. A horizontal rule separates this - from the previous paragraph.</p>]]></programlisting> - </example> - - <para>If it is not obvious by now, elements can contain other elements. - In the book example earlier, the book element contained all the chapter - elements, which in turn contained all the paragraph elements, and so - on.</para> - - <example> - <title>Elements within elements; <tag>em</tag></title> - - <programlisting><![CDATA[<p>This is a simple <em>paragraph</em> where some - of the <em>words</em> have been <em>emphasized</em>.</p>]]></programlisting> - </example> - - <para>The DTD will specify the rules detailing which elements can contain - other elements, and exactly what they can contain.</para> - - <important> - <para>People often confuse the terms tags and elements, and use the - terms as if they were interchangeable. They are not.</para> - - <para>An element is a conceptual part of your document. An element has - a defined start and end. The tags mark where the element starts and - end.</para> - - <para>When this document (or anyone else knowledgeable about SGML) refers - to <quote>the <p> tag</quote> they mean the literal text - consisting of the three characters <literal><</literal>, - <literal>p</literal>, and <literal>></literal>. But the phrase - <quote>the <p> element</quote> refers to the whole - element.</para> - - <para>This distinction <emphasis>is</emphasis> very subtle. But keep it - in mind.</para> - </important> - - <para>Elements can have attributes. An attribute has a name and a value, - and is used for adding extra information to the element. This might be - information that indicates how the content should be rendered, or might - be something that uniquely identifies that occurrence of the element, or - it might be something else.</para> - - <para>An element's attributes are written <emphasis>inside</emphasis> the - start tag for that element, and take the form - <literal>attribute-name="attribute-value"</literal>.</para> - - <para>In sufficiently recent versions of HTML, the <tag>p</tag> - element has an attribute called <literal>align</literal>, which suggests - an alignment (justification) for the paragraph to the program displaying - the HTML.</para> - - <para>The <literal>align</literal> attribute can take one of four defined - values, <literal>left</literal>, <literal>center</literal>, - <literal>right</literal> and <literal>justify</literal>. If the - attribute is not specified then the default is - <literal>left</literal>.</para> - - <example> - <title>Using an element with an attribute</title> - - <programlisting><![CDATA[<p align="left">The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.</p> - -<p align="center">This may appear in the center.</p>]]></programlisting> - </example> - - <para>Some attributes will only take specific values, such as - <literal>left</literal> or <literal>justify</literal>. Others will - allow you to enter anything you want. If you need to include quotes - (<literal>"</literal>) within an attribute then use single quotes around - the attribute value.</para> - - <example> - <title>Single quotes around attributes</title> - - <programlisting><![CDATA[<p align='right'>I am on the right!</p>]]></programlisting> - </example> - - <para>Sometimes you do not need to use quotes around attribute values at - all. However, the rules for doing this are subtle, and it is far - simpler just to <emphasis>always</emphasis> quote your attribute - values.</para> - - <para>The information on attributes, elements, and tags is stored - in SGML catalogs. The various Documentation Project tools use - these catalog files to validate your work. The tools in - <package>textproc/docproj</package> include a variety of SGML catalog - files. The FreeBSD Documentation Project includes its own set - of catalog files. Your tools need to know about both sorts of - catalog files.</para> - - <sect2> - <title>For you to do…</title> - - <para>In order to run the examples in this document you will need to - install some software on your system and ensure that an environment - variable is set correctly.</para> - - <procedure> - <step> - <para>Download and install <package>textproc/docproj</package> - from the FreeBSD ports system. This is a - <emphasis>meta-port</emphasis> that should download and install - all of the programs and supporting files that are used by the - Documentation Project.</para> - </step> - - <step> - <para>Add lines to your shell startup files to set - <envar>SGML_CATALOG_FILES</envar>. (If you are not working - on the English version of the documentation, you will want - to substitute the correct directory for your - language.)</para> - - <example xml:id="sgml-primer-envars"> - <title><filename>.profile</filename>, for &man.sh.1; and - &man.bash.1; users</title> - - <programlisting>SGML_ROOT=/usr/local/share/xml -SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog -SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES -export SGML_CATALOG_FILES</programlisting> - </example> - - <example> - <title><filename>.cshrc</filename>, for &man.csh.1; and - &man.tcsh.1; users</title> - - <programlisting>setenv SGML_ROOT /usr/local/share/xml -setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog -setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES</programlisting> - </example> - - <para>Then either log out, and log back in again, or run those - commands from the command line to set the variable values.</para> - </step> - </procedure> - - <procedure> - <step> - <para>Create <filename>example.xml</filename>, and enter the - following text:</para> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> - -<html> - <head> - <title>An example HTML 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>]]></programlisting> - </step> - - <step> - <para>Try to validate this file using an SGML parser.</para> - - <para>Part of <package>textproc/docproj</package> is the - <command>nsgmls</command> <link linkend="sgml-primer-validating">validating - parser</link>. Normally, <command>nsgmls</command> reads in a document - marked up according to an SGML DTD and returns a copy of the - document's Element Structure Information Set (ESIS, but that is - not important right now).</para> - - <para>However, when <command>nsgmls</command> is given the <option>-s</option> - parameter, <command>nsgmls</command> will suppress its normal output, and - just print error messages. This makes it a useful way to check to - see if your document is valid or not.</para> - - <para>Use <command>nsgmls</command> to check that your document is - valid:</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.xml</userinput></screen> - - <para>As you will see, <command>nsgmls</command> returns without displaying any - output. This means that your document validated - successfully.</para> - </step> - - <step> - <para>See what happens when required elements are omitted. Try - removing the <tag>title</tag> and - <tag>/title</tag> tags, and re-run the validation.</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.xml</userinput> -nsgmls:example.xml:5:4:E: character data is not allowed here -nsgmls:example.xml:6:8:E: end tag for "HEAD" which is not finished</screen> - - <para>The error output from <command>nsgmls</command> is organized into - colon-separated groups, or columns.</para> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="2"> - <thead> - <row> - <entry>Column</entry> - <entry>Meaning</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>The name of the program generating the error. This - will always be <literal>nsgmls</literal>.</entry> - </row> - - <row> - <entry>2</entry> - <entry>The name of the file that contains the error.</entry> - </row> - - <row> - <entry>3</entry> - <entry>Line number where the error appears.</entry> - </row> - - <row> - <entry>4</entry> - <entry>Column number where the error appears.</entry> - </row> - - <row> - <entry>5</entry> - <entry>A one letter code indicating the nature of the - message. <literal>I</literal> indicates an informational - message, <literal>W</literal> is for warnings, and - <literal>E</literal> is for errors<footnote> - <para>It is not always the fifth column either. - <command>nsgmls -sv</command> displays - <literal>nsgmls:I: SP version "1.3"</literal> - (depending on the installed version). As you can see, - this is an informational message.</para> - </footnote>, and <literal>X</literal> is for - cross-references. As you can see, these messages are - errors.</entry> - </row> - - <row> - <entry>6</entry> - <entry>The text of the error message.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Simply omitting the <tag>title</tag> tags has - generated 2 different errors.</para> - - <para>The first error indicates that content (in this case, - characters, rather than the start tag for an element) has occurred - where the SGML parser was expecting something else. In this case, - the parser was expecting to see one of the start tags for elements - that are valid inside <tag>head</tag> (such as - <tag>title</tag>).</para> - - <para>The second error is because <tag>head</tag> elements - <emphasis>must</emphasis> contain a <tag>title</tag> - element. Because it does not <command>nsgmls</command> considers that the - element has not been properly finished. However, the closing tag - indicates that the element has been closed before it has been - finished.</para> - </step> - - <step> - <para>Put the <literal>title</literal> element back in.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="sgml-primer-doctype-declaration"> - <title>The DOCTYPE declaration</title> - - <para>The beginning of each document that you write must specify the name - of the DTD that the document conforms to. This is so that SGML parsers - can determine the DTD and ensure that the document does conform to - it.</para> - - <para>This information is generally expressed on one line, in the DOCTYPE - declaration.</para> - - <para>A typical declaration for a document written to conform with version - 4.0 of the HTML DTD looks like this:</para> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> - - <para>That line contains a number of different components.</para> - - <variablelist> - <varlistentry> - <term><literal><!</literal></term> - - <listitem> - <para>Is the <emphasis>indicator</emphasis> that indicates that this - is an SGML declaration. This line is declaring the document type. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>DOCTYPE</literal></term> - - <listitem> - <para>Shows that this is an SGML declaration for the document - type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>html</literal></term> - - <listitem> - <para>Names the first <link linkend="sgml-primer-elements">element</link> that - will appear in the document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term> - - <listitem> - <para>Lists the Formal Public Identifier (FPI)<indexterm> - <primary>Formal Public Identifier</primary> - </indexterm> - for the DTD that this - document conforms to. Your SGML parser will use this to find the - correct DTD when processing this document.</para> - - <para><literal>PUBLIC</literal> is not a part of the FPI, but - indicates to the SGML processor how to find the DTD referenced in - the FPI. Other ways of telling the SGML parser how to find the - DTD are shown <link linkend="sgml-primer-fpi-alternatives">later</link>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>></literal></term> - - <listitem> - <para>Returns to the document.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Formal Public Identifiers (FPIs)<indexterm significance="preferred"> - <primary>Formal Public Identifier</primary> - </indexterm> -</title> - - <note> - <para>You do not need to know this, but it is useful background, and - might help you debug problems when your SGML processor can not locate - the DTD you are using.</para> - </note> - - <para>FPIs must follow a specific syntax. This syntax is as - follows:</para> - - <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> - - <variablelist> - <varlistentry> - <term><replaceable>Owner</replaceable></term> - - <listitem> - <para>This indicates the owner of the FPI.</para> - - <para>If this string starts with <quote>ISO</quote> then this is an - ISO owned FPI. For example, the FPI <literal>"ISO - 8879:1986//ENTITIES Greek Symbols//EN"</literal> lists - <literal>ISO 8879:1986</literal> as being the owner for the set - of entities for Greek symbols. ISO 8879:1986 is the ISO number - for the SGML standard.</para> - - <para>Otherwise, this string will either look like - <literal>-//Owner</literal> or - <literal>+//Owner</literal> (notice - the only difference is the leading <literal>+</literal> or - <literal>-</literal>).</para> - - <para>If the string starts with <literal>-</literal> then the - owner information is unregistered, with a <literal>+</literal> - it identifies it as being registered.</para> - - <para>ISO 9070:1991 defines how registered names are generated; it - might be derived from the number of an ISO publication, an ISBN - code, or an organization code assigned according to ISO 6523. - In addition, a registration authority could be created in order - to assign registered names. The ISO council delegated this to - the American National Standards Institute (ANSI).</para> - - <para>Because the FreeBSD Project has not been registered the - owner string is <literal>-//FreeBSD</literal>. And as you can - see, the W3C are not a registered owner either.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Keyword</replaceable></term> - - <listitem> - <para>There are several keywords that indicate the type of - information in the file. Some of the most common keywords are - <literal>DTD</literal>, <literal>ELEMENT</literal>, - <literal>ENTITIES</literal>, and <literal>TEXT</literal>. - <literal>DTD</literal> is used only for DTD files, - <literal>ELEMENT</literal> is usually used for DTD fragments - that contain only entity or element declarations. - <literal>TEXT</literal> is used for SGML content (text and - tags).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Description</replaceable></term> - - <listitem> - <para>Any description you want to supply for the contents of this - file. This may include version numbers or any short text that - is meaningful to you and unique for the SGML system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Language</replaceable></term> - - <listitem> - <para>This is an ISO two-character code that identifies the native - language for the file. <literal>EN</literal> is used for - English.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3> - <title><filename>catalog</filename> files</title> - - <para>If you use the syntax above and process this document - using an SGML processor, the processor will need to have some way of - turning the FPI into the name of the file on your computer that - contains the DTD.</para> - - <para>In order to do this it can use a catalog file. A catalog file - (typically called <filename>catalog</filename>) contains lines that - map FPIs to filenames. For example, if the catalog file contained - the line:</para> - - <programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> - - <para>The SGML processor would know to look up the DTD from - <filename>strict.dtd</filename> in the <filename>4.0</filename> - subdirectory of whichever directory held the - <filename>catalog</filename> file that contained that line.</para> - - <para>Look at the contents of - <filename>/usr/local/share/xml/html/catalog</filename>. This is - the catalog file for the HTML DTDs that will have been installed as - part of the <package>textproc/docproj</package> port.</para> - </sect3> - - <sect3> - <title><envar>SGML_CATALOG_FILES</envar></title> - - <para>In order to locate a <filename>catalog</filename> file, your - SGML processor will need to know where to look. Many of them - feature command line parameters for specifying the path to one or - more catalogs.</para> - - <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to - point to the files. This environment variable should consist of a - colon-separated list of catalog files (including their full - path).</para> - - <para>Typically, you will want to include the following files:</para> - - <itemizedlist> - <listitem> - <para><filename>/usr/local/share/xml/docbook/4.1/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/xml/html/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/xml/iso8879/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/xml/jade/catalog</filename></para> - </listitem> - </itemizedlist> - - <para>You should <link linkend="sgml-primer-envars">already have done - this</link>.</para> - </sect3> - </sect2> - - <sect2 xml:id="sgml-primer-fpi-alternatives"> - <title>Alternatives to FPIs</title> - - <para>Instead of using an FPI to indicate the DTD that the document - conforms to (and therefore, which file on the system contains the DTD) - you can explicitly specify the name of the file.</para> - - <para>The syntax for this is slightly different:</para> - - <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> - - <para>The <literal>SYSTEM</literal> keyword indicates that the SGML - processor should locate the DTD in a system specific fashion. This - typically (but not always) means the DTD will be provided as a - filename.</para> - - <para>Using FPIs is preferred for reasons of portability. You do not - want to have to ship a copy of the DTD around with your document, and - if you used the <literal>SYSTEM</literal> identifier then everyone - would need to keep their DTDs in the same place.</para> - </sect2> - </sect1> - - <sect1 xml:id="sgml-primer-sgml-escape"> - <title>Escaping back to SGML</title> - - <para>Earlier in this primer I said that SGML is only used when writing a - DTD. This is not strictly true. There is certain SGML syntax that you - will want to be able to use within your documents. For example, - comments can be included in your document, and will be ignored by the - parser. Comments are entered using SGML syntax. Other uses for SGML - syntax in your document will be shown later too.</para> - - <para>Obviously, you need some way of indicating to the SGML processor - that the following content is not elements within the document, but is - SGML that the parser should act upon.</para> - - <para>These sections are marked by <literal><! ... ></literal> in - your document. Everything between these delimiters is SGML syntax as - you might find within a DTD.</para> - - <para>As you may just have realized, the <link linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link> - is an example of SGML syntax that you need to include in your - document…</para> - </sect1> - - <sect1 xml:id="sgml-primer-comments"> - <title>註解</title> - - <para>Comments are an SGML construction, and are normally only valid - inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape"/> - shows, it is possible to use SGML syntax within your document.</para> - - <para>The delimiter for SGML comments is the string - <quote><literal>--</literal></quote>. The first occurrence of this string - opens a comment, and the second closes it.</para> - - <example> - <title>SGML generic comment</title> - - <programlisting><!-- 測試註解 --></programlisting> - - <programlisting> -<!‐- 這是註解 -‐> - -<!‐- 這也是註解 -‐> - -<!‐- 要寫多行註解的話， - 這是其中之一的方式 -‐> - -<!‐- 要寫多行註解， -‐ - ‐- 也可以這樣子用 -‐></programlisting> - </example> - - <para>If you have used HTML before you may have been shown different rules - for comments. In particular, you may think that the string - <literal><!--</literal> opens a comment, and it is only closed by - <literal>--></literal>.</para> - - <para>This is <emphasis>not</emphasis> the case. A lot of web browsers - have broken HTML parsers, and will accept that as valid. However, the - SGML parsers used by the Documentation Project are much stricter, and - will reject documents that make that error.</para> - - <example> - <title>Erroneous SGML comments</title> - - <programlisting> -<!‐- This is in the comment -‐ - - THIS IS OUTSIDE THE COMMENT! - - ‐- back inside the comment -‐></programlisting> - - <para>The SGML parser will treat this as though it were actually:</para> - - <programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting> - - <para>This is not valid SGML, and may give confusing error - messages.</para> - - <programlisting><!‐‐‐‐‐ This is a very bad idea ‐‐‐‐‐></programlisting> - - <para>As the example suggests, <emphasis>do not</emphasis> write - comments like that.</para> - - <programlisting><!‐-===================================================-‐></programlisting> - - <para>That is a (slightly) better approach, but it still potentially - confusing to people new to SGML.</para> - </example> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add some comments to <filename>example.xml</filename>, and - check that the file still validates using <command>nsgmls</command>.</para> - </step> - - <step> - <para>Add some invalid comments to - <filename>example.xml</filename>, and see the error messages that - <command>nsgmls</command> gives when it encounters an invalid comment.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="sgml-primer-entities"> - <title>Entities</title> - - <para>Entities are a mechanism for assigning names to chunks of content. - As an SGML parser processes your document, any entities it finds are - replaced by the content of the entity.</para> - - <para>This is a good way to have re-usable, easily changeable chunks of - content in your SGML documents. It is also the only way to include one - marked up file inside another using SGML.</para> - - <para>There are two types of entities which can be used in two different - situations; <emphasis>general entities</emphasis> and - <emphasis>parameter entities</emphasis>.</para> - - <sect2 xml:id="sgml-primer-general-entities"> - <title>General Entities</title> - - <para>You cannot use general entities in an SGML context (although you - define them in one). They can only be used in your document. - Contrast this with <link linkend="sgml-primer-parameter-entities">parameter - entities</link>.</para> - - <para>Each general entity has a name. When you want to reference a - general entity (and therefore include whatever text it represents in - your document), you write - <literal>&entity-name;</literal>. For - example, suppose you had an entity called - <literal>current.version</literal> which expanded to the current - version number of your product. You could write:</para> - - <programlisting><![CDATA[<para>The current version of our product is - ¤t.version;.</para>]]></programlisting> - - <para>When the version number changes you can simply change the - definition of the value of the general entity and reprocess your - document.</para> - - <para>You can also use general entities to enter characters that you - could not otherwise include in an SGML document. For example, - <literal><</literal> and <literal>&</literal> cannot - normally appear in an SGML document. When the SGML - parser sees the <literal><</literal> - symbol it assumes that a tag (either a start tag - or an end tag) is about to appear, and when it sees the - <literal>&</literal> symbol - it assumes the next text will be the name of an entity.</para> - - <para>Fortunately, you can use the two general entities - <literal>&lt;</literal> and <literal>&amp;</literal> - whenever you need to include one or other of these.</para> - - <para>A general entity can only be defined within an SGML context. - Typically, this is done immediately after the DOCTYPE - declaration.</para> - - <example> - <title>Defining general entities</title> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY current.version "3.0-RELEASE"> -<!ENTITY last.version "2.2.7-RELEASE"> -]>]]></programlisting> - - <para>Notice how the DOCTYPE declaration has been extended by adding a - square bracket at the end of the first line. The two entities are - then defined over the next two lines, before the square bracket is - closed, and then the DOCTYPE declaration is closed.</para> - - <para>The square brackets are necessary to indicate that we are - extending the DTD indicated by the DOCTYPE declaration.</para> - </example> - </sect2> - - <sect2 xml:id="sgml-primer-parameter-entities"> - <title>Parameter entities</title> - - <para>Like <link linkend="sgml-primer-general-entities">general - entities</link>, parameter entities are used to assign names to - reusable chunks of text. However, where as general entities can only - be used within your document, parameter entities can only be used - within an <link linkend="sgml-primer-sgml-escape">SGML - context</link>.</para> - - <para>Parameter entities are defined in a similar way to general - entities. However, instead of using - <literal>&entity-name;</literal> to - refer to them, use - <literal>%entity-name;</literal><footnote> - <para><emphasis>P</emphasis>arameter entities use the - <emphasis>P</emphasis>ercent symbol.</para> - </footnote>. The definition also includes the <literal>%</literal> - between the <literal>ENTITY</literal> keyword and the name of the - entity.</para> - - <example> - <title>Defining parameter entities</title> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % param.some "some"> -<!ENTITY % param.text "text"> -<!ENTITY % param.new "%param.some more %param.text"> -]>]]></programlisting> - </example> - - <para>This may not seem particularly useful. It will be.</para> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add a general entity to - <filename>example.xml</filename>.</para> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ -<!ENTITY version "1.1"> -]> - -<html> - <head> - <title>An example HTML 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> - - <p>The current version of this document is: &version;</p> - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Validate the document using <command>nsgmls</command>.</para> - </step> - - <step> - <para>Load <filename>example.xml</filename> into your web browser - (you may need to copy it to <filename>example.html</filename> - before your browser recognizes it as an HTML document).</para> - - <para>Unless your browser is very advanced, you will not see the entity - reference <literal>&version;</literal> replaced with the - version number. Most web browsers have very simplistic parsers - which do not handle proper SGML<footnote> - <para>This is a shame. Imagine all the problems and hacks (such - as Server Side Includes) that could be avoided if they - did.</para> - </footnote>.</para> - </step> - - <step> - <para>The solution is to <emphasis>normalize</emphasis> your - document using an SGML normalizer. The normalizer reads in valid - SGML and outputs equally valid SGML which has been transformed in - some way. One of the ways in which the normalizer transforms the - SGML is to expand all the entity references in the document, - replacing the entities with the text that they represent.</para> - - <para>You can use <command>sgmlnorm</command> to do this.</para> - - <screen>&prompt.user; <userinput>sgmlnorm example.xml > example.html</userinput></screen> - - <para>You should find a normalized (i.e., entity references - expanded) copy of your document in - <filename>example.html</filename>, ready to load into your web - browser.</para> - </step> - - <step> - <para>If you look at the output from <command>sgmlnorm</command> - you will see that it does not include a DOCTYPE declaration at - the start. To include this you need to use the <option>-d</option> - option:</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.xml > example.html</userinput></screen> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="sgml-primer-include"> - <title>Using entities to include files</title> - - <para>Entities (both <link linkend="sgml-primer-general-entities">general</link> and <link linkend="sgml-primer-parameter-entities">parameter</link>) are - particularly useful when used to include one file inside another.</para> - - <sect2 xml:id="sgml-primer-include-using-gen-entities"> - <title>Using general entities to include files</title> - - <para>Suppose you have some content for an SGML book organized into - files, one file per chapter, called - <filename>chapter1.xml</filename>, - <filename>chapter2.xml</filename>, and so forth, with a - <filename>book.xml</filename> file that will contain these - chapters.</para> - - <para>In order to use the contents of these files as the values for your - entities, you declare them with the <literal>SYSTEM</literal> keyword. - This directs the SGML parser to use the contents of the named file as - the value of the entity.</para> - - <example> - <title>Using general entities to include files</title> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY chapter.1 SYSTEM "chapter1.xml"> -<!ENTITY chapter.2 SYSTEM "chapter2.xml"> -<!ENTITY chapter.3 SYSTEM "chapter3.xml"> -]> - -<html> - - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - - <warning> - <para>When using general entities to include other files within a - document, the files being included - (<filename>chapter1.xml</filename>, - <filename>chapter2.xml</filename>, and so on) <emphasis>must - not</emphasis> start with a DOCTYPE declaration. This is a syntax - error.</para> - </warning> - </sect2> - - <sect2> - <title>Using parameter entities to include files</title> - - <para>Recall that parameter entities can only be used inside an SGML - context. Why then would you want to include a file within an SGML - context?</para> - - <para>You can use this to ensure that you can reuse your general - entities.</para> - - <para>Suppose that you had many chapters in your document, and you - reused these chapters in two different books, each book organizing the - chapters in a different fashion.</para> - - <para>You could list the entities at the top of each book, but this - quickly becomes cumbersome to manage.</para> - - <para>Instead, place the general entity definitions inside one file, - and use a parameter entity to include that file within your - document.</para> - - <example> - <title>Using parameter entities to include files</title> - - <para>First, place your entity definitions in a separate file, called - <filename>chapters.ent</filename>. This file contains the - following:</para> - - <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml"> -<!ENTITY chapter.2 SYSTEM "chapter2.xml"> -<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting> - - <para>Now create a parameter entity to refer to the contents of the - file. Then use the parameter entity to load the file into the - document, which will then make all the general entities available - for use. Then use the general entities as before:</para> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % chapters SYSTEM "chapters.ent"> -%chapters; -]> - -<html> - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - </sect2> - - <sect2> - <title>For you to do…</title> - - <sect3> - <title>Use general entities to include files</title> - - <procedure> - <step> - <para>Create three files, <filename>para1.xml</filename>, - <filename>para2.xml</filename>, and - <filename>para3.xml</filename>.</para> - - <para>Put content similar to the following in each file:</para> - - <programlisting><![CDATA[<p>This is the first paragraph.</p>]]></programlisting> - </step> - - <step> - <para>Edit <filename>example.xml</filename> so that it looks like - this:</para> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.xml"> -<!ENTITY para2 SYSTEM "para2.xml"> -<!ENTITY para3 SYSTEM "para3.xml"> -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalizing - <filename>example.xml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.xml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> into your web - browser, and confirm that the - <filename>paran.xml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Use parameter entities to include files</title> - - <note> - <para>You must have taken the previous steps first.</para> - </note> - - <procedure> - <step> - <para>Edit <filename>example.xml</filename> so that it looks like - this:</para> - - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % entities SYSTEM "entities.xml"> %entities; -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Create a new file, <filename>entities.xml</filename>, with - this content:</para> - - <programlisting><![CDATA[<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.xml"> -<!ENTITY para2 SYSTEM "para2.xml"> -<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalizing - <filename>example.xml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.xml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> into your web - browser, and confirm that the - <filename>paran.xml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - </sect2> - </sect1> - - <sect1 xml:id="sgml-primer-marked-sections"> - <title>Marked sections</title> - - <para>SGML provides a mechanism to indicate that particular pieces of the - document should be processed in a special way. These are termed - <quote>marked sections</quote>.</para> - - <example> - <title>Structure of a marked section</title> - - <programlisting><![ <replaceable>KEYWORD</replaceable> [ - Contents of marked section -]]></programlisting> - </example> - - <para>As you would expect, being an SGML construct, a marked section - starts with <literal><!</literal>.</para> - - <para>The first square bracket begins to delimit the marked - section.</para> - - <para><replaceable>KEYWORD</replaceable> describes how this marked - section should be processed by the parser.</para> - - <para>The second square bracket indicates that the content of the marked - section starts here.</para> - - <para>The marked section is finished by closing the two square brackets, - and then returning to the document context from the SGML context with - <literal>></literal>.</para> - - <sect2> - <title>Marked section keywords</title> - - <sect3> - <title><literal>CDATA</literal>, <literal>RCDATA</literal></title> - - <para>These keywords denote the marked sections <emphasis>content - model</emphasis>, and allow you to change it from the - default.</para> - - <para>When an SGML parser is processing a document it keeps track - of what is called the <quote>content model</quote>.</para> - - <para>Briefly, the content model describes what sort of content the - parser is expecting to see, and what it will do with it when it - finds it.</para> - - <para>The two content models you will probably find most useful are - <literal>CDATA</literal> and <literal>RCDATA</literal>.</para> - - <para><literal>CDATA</literal> is for <quote>Character Data</quote>. - If the parser is in this content model then it is expecting to see - characters, and characters only. In this model the - <literal><</literal> and <literal>&</literal> - symbols lose their special status, and will be treated as ordinary - characters.</para> - - <para><literal>RCDATA</literal> is for <quote>Entity references and - character data</quote> If the parser is in this content model then it - is expecting to see characters <emphasis>and</emphasis> entities. - <literal><</literal> loses its special status, but - <literal>&</literal> will still be treated as - starting the beginning of a general entity.</para> - - <para>This is particularly useful if you are including some verbatim - text that contains lots of <literal><</literal> and - <literal>&</literal> characters. While you - could go through the text ensuring that every - <literal><</literal> is converted to a - <literal>&lt;</literal> and every <literal>&</literal> - is converted to a <literal>&amp;</literal>, it can be - easier to mark the section as only containing CDATA. When the SGML - parser encounters this it will ignore the - <literal><</literal> and <literal>&</literal> symbols - embedded in the content.</para> - - <note> - <para>When you use <literal>CDATA</literal> or - <literal>RCDATA</literal> in examples of text marked up in SGML, - keep in mind that the content of <literal>CDATA</literal> is not - validated. You have to check the included SGML text using other - means. You could, for example, write the example in another - document, validate the example code, and then paste it to your - <literal>CDATA</literal> content.</para> - </note> - <!-- The nesting of CDATA within the next example is disgusting --> - - <example> - <title>Using a CDATA marked section</title> - - <programlisting><para>Here is an example of how you would include some text - that contained many <literal>&lt;</literal> - and <literal>&amp;</literal> symbols. The sample - text is a fragment of HTML. The surrounding text (<para> and - <programlisting>) are from DocBook.</para> - -<programlisting> - <![CDATA[<![CDATA[ - <p>This is a sample that shows you some of the elements within - HTML. 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.</p> - - <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></programlisting> - - <para>If you look at the source for this document you will see this - technique used throughout.</para> - </example> - </sect3> - - <sect3> - <title><literal>INCLUDE</literal> and - <literal>IGNORE</literal></title> - - <para>If the keyword is <literal>INCLUDE</literal> then the contents - of the marked section will be processed. If the keyword is - <literal>IGNORE</literal> then the marked section is ignored and - will not be processed. It will not appear in the output.</para> - - <example> - <title>Using <literal>INCLUDE</literal> and - <literal>IGNORE</literal> in marked sections</title> - - <programlisting><![ INCLUDE [ - This text will be processed and included. -]]> - -<![ IGNORE [ - This text will not be processed or included. -]]></programlisting> - </example> - - <para>By itself, this is not too useful. If you wanted to remove text - from your document you could cut it out, or wrap it in - comments.</para> - - <para>It becomes more useful when you realize you can use <link linkend="sgml-primer-parameter-entities">parameter entities</link> - to control this. Remember that parameter entities can only be used - in SGML contexts, and the keyword of a marked section - <emphasis>is</emphasis> an SGML context.</para> - - <para>For example, suppose that you produced a hard-copy version of - some documentation and an electronic version. In the electronic - version you wanted to include some extra content that was not to - appear in the hard-copy.</para> - - <para>Create a parameter entity, and set its value to - <literal>INCLUDE</literal>. Write your document, using marked - sections to delimit content that should only appear in the - electronic version. In these marked sections use the parameter - entity in place of the keyword.</para> - - <para>When you want to produce the hard-copy version of the document, - change the parameter entity's value to <literal>IGNORE</literal> and - reprocess the document.</para> - - <example> - <title>Using a parameter entity to control a marked - section</title> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % electronic.copy "INCLUDE"> -]]> - -... - -<![ %electronic.copy [ - This content should only appear in the electronic - version of the document. -]]></programlisting> - - <para>When producing the hard-copy version, change the entity's - definition to:</para> - - <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> - - <para>On reprocessing the document, the marked sections that use - <literal>%electronic.copy</literal> as their keyword will be - ignored.</para> - </example> - </sect3> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Create a new file, <filename>section.xml</filename>, that - contains the following:</para> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % text.output "INCLUDE"> -]> - -<html> - <head> - <title>An example using marked sections</title> - </head> - - <body> - <p>This paragraph <![CDATA[contains many < - characters (< < < < <) so it is easier - to wrap it in a CDATA marked section ]]></p> - - <![IGNORE[ - <p>This paragraph will definitely not be included in the - output.</p> - ]]> - - <![<![CDATA[%text.output]]> [ - <p>This paragraph might appear in the output, or it - might not.</p> - - <p>Its appearance is controlled by the <![CDATA[%text.output]]> - parameter entity.</p> - ]]> - </body> -</html></programlisting> - </step> - - <step> - <para>Normalize this file using &man.xmlnorm.1; and examine the - output. Notice which paragraphs have appeared, which have - disappeared, and what has happened to the content of the CDATA - marked section.</para> - </step> - - <step> - <para>Change the definition of the <literal>text.output</literal> - entity from <literal>INCLUDE</literal> to - <literal>IGNORE</literal>. Re-normalize the file, and examine the - output to see what has changed.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="sgml-primer-conclusion"> - <title>Conclusion</title> - - <para>That is the conclusion of this SGML primer. For reasons of space - and complexity several things have not been covered in depth (or at - all). However, the previous sections cover enough SGML for you to be - able to follow the organization of the FDP documentation.</para> - </sect1> -</chapter> diff --git a/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml deleted file mode 100644 index c4feee84cb..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml +++ /dev/null @@ -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> diff --git a/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml deleted file mode 100644 index b1ef0c7460..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml +++ /dev/null @@ -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> diff --git a/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml deleted file mode 100644 index 8e2a94ad94..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml +++ /dev/null @@ -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> diff --git a/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml deleted file mode 100644 index 622e98e164..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml +++ /dev/null @@ -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> diff --git a/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml deleted file mode 100644 index 93e331fbe8..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml +++ /dev/null @@ -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ü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>然後，就開始翻文件囉，一開始翻譯的時候，先找些篇幅較短的文件會比較容易些 - — 像是 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>我們想不出來有啥原因，為什麼不把這些資訊提供給英文版呢？(或是德文、西班牙文、日文等 …) - 因為，有可能英語讀者跑去韓國時，會想買 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>簡單來說，長相一開頭會是 & 符號(&)，然後是該 entity 名稱，最後接上分號(;)。</para> - - <para>這些 entity 名稱都是 ISO8879 所制訂的，而 port tree 內則在 - <package>textproc/iso8879</package>。</para> - - <para>以下舉一些例子：</para> - - <segmentedlist> - <segtitle>Entity名稱</segtitle> - - <segtitle>實際樣子</segtitle> - - <segtitle>介紹</segtitle> - - <seglistitem> - <seg>&eacute;</seg> - <seg>é</seg> - <seg>小 <quote>e</quote>，並帶尖、重音(acute accent)</seg> - </seglistitem> - - <seglistitem> - <seg>&Eacute;</seg> - <seg>É</seg> - <seg>大 <quote>E</quote>，並帶尖、重音(acute accent)</seg> - </seglistitem> - - <seglistitem> - <seg>&uuml;</seg> - <seg>ü</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><!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $ ---></programlisting> - - <para>實際上的內容可能稍有不同，但每份原稿都會附上 $FreeBSD$ 這一行以及 - <literal>The FreeBSD Documentation Project</literal> 宣告。 - 請注意：$FreeBSD 開頭的這行是會由 CVS 隨著每次異動而自動更改的， - 所以，新檔案的話請保持原狀(也就是只要寫 <literal>$FreeBSD$</literal> 就好了)。</para> - - <para>翻譯文件中，必須都要有 $FreeBSD$ 這行，並且把 - <literal>FreeBSD Documentation Project</literal> 這行改為 - <literal>The FreeBSD 你的語系 - Documentation Project</literal>。</para> - - <para>此外，還必須加上第三行來指出你所翻譯的，到底是以英文版原稿的哪一版本為母本所做的翻譯。</para> - - <para>因此呢，西班牙文版(Spanish)的檔案開頭應該是長像這樣：</para> - - <programlisting><!-- - The FreeBSD Spanish Documentation Project - - $FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.3 1999/06/24 19:12:32 jesusr Exp $ - Original revision: 1.11 ---></programlisting> - </answer> - </qandaentry> - </qandaset> -</chapter> diff --git a/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml deleted file mode 100644 index 158d232029..0000000000 --- a/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml +++ /dev/null @@ -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>… 在這個 - <filename>/etc/rc.local</filename> 檔案 …</para> - </informalexample> - - <informalexample> - <para>… 在 - <filename>/etc/rc.local</filename> 檔 …</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><para></literal> - ，<emphasis>而非</emphasis> <literal><PARA></literal>。</para> - - <para>而 SGML 內文則是用大寫字母表示，像是： - <literal><!ENTITY…></literal> 及 - <literal><!DOCTYPE…></literal>， - <emphasis>而不是</emphasis> - <literal><!entity…></literal> 及 - <literal><!doctype…></literal>。</para> - </sect2> - - <sect2> - <title>縮寫字</title> - - <para>縮寫字(acronym)通常在書中第一次提到時，必須同時列出完整拼法， - 比如："Network Time Protocol (<acronym role="Network Time Protocol">NTP</acronym>)"。 - 定義縮寫字之後，應該儘量只使用該縮寫字(而非完整詞彙， - 除非使用完整詞彙可以更能表達語意)來表達即可。 - 通常每本書只會第一次提到時，才會列出完整詞彙， - 但若您高興也可以在每章第一次提到時又列出完整詞彙。</para> - - <para>此外，同一縮寫字在前三次使用時，須使用 <acronym> 標籤， - 並把完整詞彙附在 <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 …</literallayout> - - <para>請使用 <literal>&nbsp;</literal> 以避免同句子之間的斷行， - 以下示範如何使用 nonbreaking spaces：</para> - - <itemizedlist> - <listitem> - <para>在數字與單位之間：</para> - <programlisting><![CDATA[57600 bps]]></programlisting> - </listitem> - - <listitem> - <para>在程式名稱與版號之間：</para> - <programlisting><![CDATA[FreeBSD 4.7]]></programlisting> - </listitem> - - <listitem> - <para>multiword 之間 (使用時請小心，像是 <quote>The FreeBSD Brazilian - Portuguese Documentation Project</quote> 這類由三到四個字所組成的， - 則不用加。)：</para> - <programlisting><![CDATA[Sun 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> |