aboutsummaryrefslogtreecommitdiff
path: root/nl_NL.ISO8859-1
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2015-10-31 20:45:54 +0000
committerWarren Block <wblock@FreeBSD.org>2015-10-31 20:45:54 +0000
commit4f25f34ddde1b52238574033851c042a23d251e4 (patch)
treef6aef6e298e28d5cb7851fe409625539f7f73872 /nl_NL.ISO8859-1
parent6457f53b95a8cb3477f9bc6c862acec13493845e (diff)
downloaddoc-4f25f34ddde1b52238574033851c042a23d251e4.tar.gz
doc-4f25f34ddde1b52238574033851c042a23d251e4.zip
Remove unnecessary files.
Notes
Notes: svn path=/head/; revision=47716
Diffstat (limited to 'nl_NL.ISO8859-1')
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/chapters.ent29
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml529
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml2744
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml170
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml162
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml255
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml823
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml171
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml108
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml305
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml75
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml200
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml141
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml473
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml177
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml592
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml600
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml1433
18 files changed, 0 insertions, 8987 deletions
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/chapters.ent b/nl_NL.ISO8859-1/books/fdp-primer/chapters.ent
deleted file mode 100644
index 55c9cdcf53..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/chapters.ent
+++ /dev/null
@@ -1,29 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!--
- 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$
--->
-
-<!ENTITY chap.overview SYSTEM "overview/chapter.xml">
-<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
-<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml">
-<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
-<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml">
-<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
-<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml">
-<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml">
-<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml">
-<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
-<!ENTITY chap.translations SYSTEM "translations/chapter.xml">
-<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml">
-<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml">
-<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml">
-<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml">
-
-<!ENTITY app.examples SYSTEM "examples/appendix.xml">
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
deleted file mode 100644
index d2ef3545dd..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
+++ /dev/null
@@ -1,529 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<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 covers organization of the documentation build
- process and how &man.make.1; is used to control it.</para>
-
- <sect1 xml:id="doc-build-rendering">
- <title>Rendering DocBook into Output</title>
-
- <para>Different types of output can be produced from a single
- DocBook source file. The type of output desired is set with the
- <varname>FORMATS</varname> variable. A list of known formats is
- stored in <varname>KNOWN_FORMATS</varname>:</para>
-
- <screen xml:id="doc-build-rendering-known-formats">&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-&prompt.user; <userinput>make -V KNOWN_FORMATS</userinput></screen>
-
- <table xml:id="doc-build-rendering-common-formats" frame="none">
- <title>Common Output Formats</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry><varname>FORMATS</varname> Value</entry>
- <entry>File Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>html</literal></entry>
- <entry><acronym>HTML</acronym>, one file</entry>
- <entry>A single <filename>book.html</filename> or
- <filename>article.html</filename>.</entry>
- </row>
-
- <row>
- <entry><literal>html-split</literal></entry>
- <entry><acronym>HTML</acronym>, multiple files</entry>
- <entry>Multiple <acronym>HTML</acronym> files, one for
- each chapter or section, for use on a typical web
- site.</entry>
- </row>
-
- <row>
- <entry><literal>pdf</literal></entry>
- <entry><acronym>PDF</acronym></entry>
- <entry>Portable Document Format</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The default output format can vary by document, but is
- usually <literal>html-split</literal>. Other formats are chosen
- by setting <varname>FORMATS</varname> to a specific value.
- Multiple output formats can be created at a single time by
- setting <varname>FORMATS</varname> to a list of formats.</para>
-
- <example xml:id="doc-build-formats-example-html">
- <title>Build a Single HTML Output File</title>
-
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-&prompt.user; <userinput>make FORMATS=html</userinput></screen>
- </example>
-
- <example xml:id="doc-build-formats-example-html-split-pdf">
- <title>Build HTML-Split and <acronym>PDF</acronym> Output
- Files</title>
-
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-&prompt.user; <userinput>make FORMATS="html-split pdf"</userinput></screen>
- </example>
- </sect1>
-
- <sect1 xml:id="doc-build-toolset">
- <title>The &os; Documentation Build Toolset</title>
-
- <para>These are the tools used to build and install the
- <acronym>FDP</acronym> documentation.</para>
-
- <itemizedlist>
- <listitem>
- <para>The primary build tool is &man.make.1;, specifically
- <application>Berkeley Make</application>.</para>
- </listitem>
-
- <listitem>
- <para>Package building is handled by &os;'s
- &man.pkg.create.1;.</para>
- </listitem>
-
- <listitem>
- <para>&man.gzip.1; is used to create compressed versions of
- the document. &man.bzip2.1; archives are also supported.
- &man.tar.1; is used for package building.</para>
- </listitem>
-
- <listitem>
- <para>&man.install.1; is used to install the
- documentation.</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 xml:id="doc-build-makefiles">
-
- <title>Understanding <filename>Makefile</filename>s in the
- Documentation Tree</title>
-
- <para>There are three main types of <filename>Makefile</filename>s
- in the &os; 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.<replaceable>xxx</replaceable>.mk</filename>.</para>
- </listitem>
- </itemizedlist>
-
- <sect2 xml:id="sub-make">
- <title>Subdirectory <filename>Makefile</filename>s</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>The first four non-empty lines define the &man.make.1;
- variables <varname>SUBDIR</varname>,
- <varname>COMPAT_SYMLINK</varname>, and
- <varname>DOC_PREFIX</varname>.</para>
-
- <para>The <varname>SUBDIR</varname> statement and
- <varname>COMPAT_SYMLINK</varname> statement show 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>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 &os; 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 &man.make.1;
- builtin variable with the path to the current
- directory.</para>
-
- <para>The final line includes the &os; Documentation Project's
- project-wide &man.make.1; 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 <filename>Makefile</filename>s</title>
-
- <para>These <filename>Makefile</filename>s set &man.make.1;
- 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 allows
- committers to claim ownership of a document in the &os;
- Documentation Project, and take 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>
-
- <para>The <varname>DOC_PREFIX</varname> and include statements
- should be familiar already.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="make-includes">
- <title>&os; Documentation Project
- <application>Make</application> Includes</title>
-
- <para>&man.make.1; includes are 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><filename>doc.project.mk</filename></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> does not affect which
- documents can, or even will, be built. Its main use is
- creating links to commonly referenced documents into the
- &os; documentation install root.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Conditionals</title>
-
- <para>The <literal>.if defined(DOC)</literal> line is an
- example of a &man.make.1; 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><filename>doc.subdir.mk</filename></title>
-
- <para>This file is too long to explain in detail. These notes
- describe the most important features.</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><replaceable>target</replaceable>:
- <replaceable>dependency1 dependency2
- ...</replaceable></literal> tuples, where to build
- <literal>target</literal>, the given
- dependencies must be built first.</para>
-
- <para>After that descriptive tuple, instructions on how to
- build the target may be given, if the conversion process
- between the target and its dependencies are not previously
- defined, or if this particular conversion is not the same as
- the default conversion method.</para>
-
- <para>A special dependency <literal>.USE</literal> defines
- the equivalent of a macro.</para>
-
- <programlisting>_SUBDIRUSE: .USE
-.for entry in ${SUBDIR}
- @${ECHO} "===&gt; ${DIRPRFX}${entry}"
- @(cd ${.CURDIR}/${entry} &amp;&amp; \
- ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
-.endfor</programlisting>
-
- <para>In the above, <buildtarget>_SUBDIRUSE</buildtarget> is now
- a macro which will execute the given commands when it is
- listed as a dependency.</para>
-
- <para>What sets this macro apart from other targets?
- Basically, it is executed <emphasis>after</emphasis> the
- instructions given in the build procedure it is listed as a
- dependency to, and it does not adjust
- <varname>.TARGET</varname>, which is the variable which
- contains the name of the target currently being
- built.</para>
-
- <programlisting>clean: _SUBDIRUSE
- rm -f ${CLEANFILES}</programlisting>
-
- <para>In the above, <buildtarget>clean</buildtarget> will use
- the <buildtarget>_SUBDIRUSE</buildtarget> macro after it has
- executed the instruction
- <command>rm -f ${CLEANFILES}</command>. In effect, this
- causes <buildtarget>clean</buildtarget> to go further and
- further down the directory tree, deleting built files as it
- goes <emphasis>down</emphasis>, not on the way back
- up.</para>
-
- <sect4>
- <title>Provided Targets</title>
-
- <itemizedlist>
- <listitem>
- <para><buildtarget>install</buildtarget> and
- <buildtarget>package</buildtarget> both go down the
- directory tree calling the real versions of themselves
- in the subdirectories
- (<buildtarget>realinstall</buildtarget> and
- <buildtarget>realpackage</buildtarget>
- respectively).</para>
- </listitem>
-
- <listitem>
- <para><buildtarget>clean</buildtarget> removes files
- created by the build process (and goes down the
- directory tree too).
- <buildtarget>cleandir</buildtarget> does the same, and
- also removes the object directory, if any.</para>
- </listitem>
- </itemizedlist>
- </sect4>
- </sect3>
-
- <sect3>
- <title>More on Conditionals</title>
-
- <itemizedlist>
- <listitem>
- <para><literal>exists</literal> is another condition
- function which returns true if the given file
- exists.</para>
- </listitem>
-
- <listitem>
- <para><literal>empty</literal> returns true if the given
- variable is empty.</para>
- </listitem>
-
- <listitem>
- <para><literal>target</literal> returns true if the given
- target does not already exist.</para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Looping Constructs in <command>make
- (.for)</command></title>
-
- <para><literal>.for</literal> provides a way to repeat a set
- of instructions for each space-separated element in a
- variable. It does this by assigning a variable to contain
- the current element in the list being examined.</para>
-
- <programlisting>_SUBDIRUSE: .USE
-.for entry in ${SUBDIR}
- @${ECHO} "===&gt; ${DIRPRFX}${entry}"
- @(cd ${.CURDIR}/${entry} &amp;&amp; \
- ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
-.endfor</programlisting>
-
- <para>In the above, if <varname>SUBDIR</varname> is empty, no
- action is taken; if it has one or more elements, the
- instructions between <literal>.for</literal> and
- <literal>.endfor</literal> would repeat for every element,
- with <varname>entry</varname> being replaced with the value
- of the current element.</para>
- </sect3>
- </sect2>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
deleted file mode 100644
index 94bcb542d2..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
+++ /dev/null
@@ -1,2744 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="docbook-markup">
-
- <title>DocBook Markup</title>
-
- <sect1 xml:id="docbook-markup-introduction">
- <title>Introduction</title>
-
- <para>This chapter is an introduction to DocBook as it is used for
- &os; documentation. DocBook is a large and complex markup
- system, but the subset described here covers the parts that are
- most widely used for &os; documentation. While a moderate
- subset is covered, it is impossible to anticipate every
- situation. Please post questions that this document does
- not answer to the &a.doc;.</para>
-
- <para>DocBook was originally developed by HaL Computer Systems and
- O'Reilly &amp; Associates to be a Document Type Definition
- (<acronym>DTD</acronym>) for writing technical documentation
- <footnote><para>A short history can be found under <link
- xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</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 <acronym>XHTML</acronym>, 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>
-
- <para>The DocBook <acronym>DTD</acronym> is available from the
- Ports Collection in the
- <package>textproc/docbook-xml</package>
- port. It is automatically installed as part of the
- <package>textproc/docproj</package>
- port.</para>
-
- <note>
- <title>Formal Versus Informal</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>
-
- <note>
- <title>Inline Versus 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>
-
- <sect1 xml:id="docbook-markup-freebsd-extensions">
- <title>&os; Extensions</title>
-
- <para>The &os; Documentation Project has extended the DocBook
- <acronym>DTD</acronym> with additional elements and entities.
- These additions serve to make some of the markup easier or more
- precise.</para>
-
- <para>Throughout the rest of this document, the term
- <quote>DocBook</quote> is used to mean the &os;-extended
- DocBook <acronym>DTD</acronym>.</para>
-
- <note>
- <para>Most of these extensions are not unique to &os;, 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, &hellip;) be interested in
- collaborating on a standard DocBook extension set, please
- contact &a.doceng;.</para>
- </note>
-
- <sect2 xml:id="docbook-markup-freebsd-extensions-elements">
- <title>&os; Elements</title>
-
- <para>The additional &os; elements are not (currently) in the
- Ports Collection. They are stored in the &os; Subversion
- tree, as <link
- xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para>
-
- <para>&os;-specific elements used in the examples below are
- clearly marked.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-freebsd-extensions-entities">
- <title>&os; Entities</title>
-
- <para>This table shows some of the most useful entities
- available in the <acronym>FDP</acronym>. For a complete list,
- see the <filename>*.ent</filename> files in
- <filename>doc/share/xml</filename>.</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="3">
- <colspec colname="entity"/>
- <colspec colname="expandsto"/>
- <colspec colname="notes"/>
- <thead>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- </row>
- </thead>
-
- <tbody valign="top">
- <row>
- <entry namest="entity" nameend="notes"><emphasis>&os;
- Name Entities</emphasis></entry>
- </row>
-
- <row>
- <entry><literal>&amp;os;</literal></entry>
- <entry><literal>&os;</literal></entry>
- <entry/>
- </row>
-
- <row>
- <entry><literal>&amp;os.stable;</literal></entry>
- <entry><literal>&os.stable;</literal></entry>
- <entry/>
- </row>
-
- <row>
- <entry><literal>&amp;os.current;</literal></entry>
- <entry><literal>&os.current;</literal></entry>
- <entry/>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes">Manual Page
- Entities</entry>
- </row>
-
- <row>
- <entry><literal>&amp;man.ls.1;</literal></entry>
- <entry>&man.ls.1;</entry>
- <entry>Usage: <literal>&amp;man.ls.1; is the manual page
- for
- &lt;command&gt;ls&lt;/command&gt;.</literal></entry>
- </row>
-
- <row>
- <entry><literal>&amp;man.cp.1;</literal></entry>
- <entry>&man.cp.1;</entry>
- <entry>Usage: <literal>The manual page for
- &lt;command&gt;cp&lt;/command&gt; is
- &amp;man.cp.1;.</literal></entry>
- </row>
-
- <row>
- <entry><literal>&amp;man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry>
- <entry><emphasis>link to
- <replaceable>command</replaceable> manual page in
- section
- <replaceable>sectionnumber</replaceable></emphasis></entry>
- <entry>Entities are defined for all the
- <link xlink:href="&url.base;/cgi/man.cgi">&os; manual
- pages</link>.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes">&os; Mailing List
- Entities</entry>
- </row>
-
- <row>
- <entry><literal>&amp;a.doc;</literal></entry>
- <entry><literal>&a.doc;</literal></entry>
- <entry>Usage: <literal>A link to the
- &amp;a.doc;.</literal></entry>
- </row>
-
- <row>
- <entry><literal>&amp;a.questions;</literal></entry>
- <entry><literal>&a.questions;</literal></entry>
- <entry>Usage: <literal>A link to the
- &amp;a.questions;.</literal></entry>
- </row>
-
- <row>
- <entry><literal>&amp;a.<replaceable>listname</replaceable>;</literal></entry>
- <entry><emphasis>link to
- <replaceable>listname</replaceable></emphasis></entry>
- <entry>Entities are defined for all the <link
- xlink:href="&url.books.handbook;/eresources.html#eresources-mail">&os;
- mailing lists</link>.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes">&os; Document
- Link Entities</entry>
- </row>
-
- <row>
- <entry><literal>&amp;url.books.handbook;</literal></entry>
- <entry><literal>&url.books.handbook;</literal></entry>
- <entry>Usage: <literal>A link to the &lt;link
- xlink:href="&amp;url.books.handbook;/advanced-networking.html"&gt;Advanced
- Networking&lt;/link&gt; chapter of the
- Handbook.</literal></entry>
- </row>
-
- <row>
- <entry><literal>&amp;url.books.<replaceable>bookname</replaceable>;</literal></entry>
- <entry><emphasis>relative path to
- <replaceable>bookname</replaceable></emphasis></entry>
- <entry>Entities are defined for all the <link
- xlink:href="&url.doc.langbase;/books/">&os;
- books</link>.</entry>
- </row>
-
- <row>
- <entry><literal>&amp;url.articles.committers-guide;</literal></entry>
- <entry><literal>&url.articles.committers-guide;</literal></entry>
- <entry>Usage: <literal>A link to the &lt;link
- xlink:href="&amp;url.articles.committers-guide;"&gt;Committer's
- Guide&lt;/link&gt;
- article.</literal></entry>
- </row>
-
- <row>
- <entry><literal>&amp;url.articles.<replaceable>articlename</replaceable>;</literal></entry>
- <entry><emphasis>relative path to
- <replaceable>articlename</replaceable></emphasis></entry>
- <entry>Entities are defined for all the <link
- xlink:href="&url.doc.langbase;/articles/">&os;
- articles</link>.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes">Other Operating
- System Name Entities</entry>
- </row>
-
- <row>
- <entry><literal>&amp;linux;</literal></entry>
- <entry>&linux;</entry>
- <entry>The &linux; operating system.</entry>
- </row>
-
- <row>
- <entry><literal>&amp;unix;</literal></entry>
- <entry>&unix;</entry>
- <entry>The &unix; operating system.</entry>
- </row>
-
- <row>
- <entry><literal>&amp;windows;</literal></entry>
- <entry>&windows;</entry>
- <entry>The &windows; operating system.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes">Miscellaneous
- Entities</entry>
- </row>
-
- <row>
- <entry><literal>&amp;prompt.root;</literal></entry>
- <entry>&prompt.root;</entry>
- <entry>The <systemitem
- class="username">root</systemitem> user
- prompt.</entry>
- </row>
-
- <row>
- <entry><literal>&amp;prompt.user;</literal></entry>
- <entry>&prompt.user;</entry>
- <entry>A prompt for an unprivileged user.</entry>
- </row>
-
- <row>
- <entry><literal>&amp;postscript;</literal></entry>
- <entry>&postscript;</entry>
- <entry>The
- &postscript; programming language.</entry>
- </row>
-
- <row>
- <entry><literal>&amp;tex;</literal></entry>
- <entry>&tex;</entry>
- <entry>The
- &tex; typesetting language.</entry>
- </row>
-
- <row>
- <entry><literal>&amp;xorg;</literal></entry>
- <entry>&xorg;</entry>
- <entry>The &xorg; open source X
- Window System.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-fpi">
- <title>Formal Public Identifier (FPI)</title>
-
- <para>In compliance with the DocBook guidelines for writing
- <acronym>FPI</acronym>s for DocBook customizations, the
- <acronym>FPI</acronym> for the &os; extended DocBook
- <acronym>DTD</acronym> is:</para>
-
- <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
- </sect1>
-
- <sect1 xml:id="docbook-markup-document-structure">
- <title>Document Structure</title>
-
- <para>DocBook allows structuring documentation in several ways.
- The &os; Documentation Project uses two primary types of DocBook
- document: the book and the article.</para>
-
- <para>Books are 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. For example, 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>The nature of the document being written should be used to
- determine 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">&os;
- tutorials</link> are all marked up as articles, while this
- document, the <link
- xlink:href="&url.books.faq;/index.html">FAQ</link>,
- and the <link
- xlink:href="&url.books.handbook;/index.html">Handbook</link> are all marked up as books, for
- example.</para>
-
- <sect2 xml:id="docbook-markup-starting-a-book">
- <title>Starting a Book</title>
-
- <para>The content of a 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 is contained within
- <tag>info</tag>.</para>
-
- <example>
- <title>Boilerplate <tag>book</tag> with
- <tag>info</tag></title>
-
- <!-- Cannot put this in a marked section because of the
- replaceable elements -->
-
- <programlisting><tag class="starttag">book</tag>
- <tag class="starttag">info</tag>
- <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag>
-
- <tag class="starttag">author</tag>
- <tag class="starttag">personname</tag>
- <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
- <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
- <tag class="endtag">personname</tag>
-
- <tag class="starttag">affiliation</tag>
- <tag class="starttag">address</tag>
- <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag>
- <tag class="endtag">address</tag>
- <tag class="endtag">affiliation</tag>
- <tag class="endtag">author</tag>
-
- <tag class="starttag">copyright</tag>
- <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag>
- <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag>
- <tag class="endtag">copyright</tag>
-
- <tag class="starttag">releaseinfo</tag>&dollar;&os;&dollar;<tag class="endtag">releaseinfo</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">info</tag>
-
- &hellip;
-
-<tag class="endtag">book</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-starting-an-article">
- <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 is contained within
- <tag>info</tag>.</para>
-
- <example>
- <title>Boilerplate <tag>article</tag> with
- <tag>info</tag></title>
-
- <!-- Cannot put this in a marked section because of the
- replaceable elements -->
-
- <programlisting><tag class="starttag">article</tag>
- <tag class="starttag">info</tag>
- <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag>
-
- <tag class="starttag">author</tag>
- <tag class="starttag">personname</tag>
- <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
- <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
- <tag class="endtag">personname</tag>
-
- <tag class="starttag">affiliation</tag>
- <tag class="starttag">address</tag>
- <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag>
- <tag class="endtag">address</tag>
- <tag class="endtag">affiliation</tag>
- <tag class="endtag">author</tag>
-
- <tag class="starttag">copyright</tag>
- <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag>
- <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag>
- <tag class="endtag">copyright</tag>
-
- <tag class="starttag">releaseinfo</tag>&dollar;&os;&dollar;<tag class="endtag">releaseinfo</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">info</tag>
-
- &hellip;
-
-<tag class="endtag">article</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-indicating-chapters">
- <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><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag>
-
- ...
-<tag class="endtag">chapter</tag></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><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag><tag class="endtag">para</tag>
-<tag class="endtag">chapter</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-sections-below-chapters">
- <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><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag>
-
- &hellip;
- <tag class="endtag">sect1</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag>
-
- <tag class="starttag">sect2</tag>
- <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag>
-
- <tag class="starttag">sect3</tag>
- <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag>
-
- &hellip;
- <tag class="endtag">sect3</tag>
- <tag class="endtag">sect2</tag>
-
- <tag class="starttag">sect2</tag>
- <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag>
-
- &hellip;
- <tag class="endtag">sect2</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">chapter</tag></programlisting>
- </example>
-
- <note>
- <para>Section numbers are automatically generated and
- prepended to titles when the document is rendered to an
- output format. The generated section numbers and titles
- from the example above will be:</para>
-
- <itemizedlist>
- <listitem>
- <para>1.1. First Section</para>
- </listitem>
-
- <listitem>
- <para>1.2. Second Section</para>
- </listitem>
-
- <listitem>
- <para>1.2.1. First Sub-Section</para>
- </listitem>
-
- <listitem>
- <para>1.2.1.1. First Sub-Sub-Section</para>
- </listitem>
-
- <listitem>
- <para>1.2.2. Second Sub-Section</para>
- </listitem>
- </itemizedlist>
- </note>
- </sect2>
-
- <sect2 xml:id="docbook-markup-subdividing-part">
- <title>Subdividing Using <tag>part</tag>
- Elements</title>
-
- <para><tag>part</tag>s introduce another level 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><tag class="starttag">part</tag>
- <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag>
-
- <tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag>
-
- ...
- <tag class="endtag">chapter</tag>
-
- <tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag>
-
- ...
- <tag class="endtag">chapter</tag>
-
- <tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>History<tag class="endtag">title</tag>
-
- ...
- <tag class="endtag">chapter</tag>
-<tag class="endtag">part</tag></programlisting>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-block-elements">
- <title>Block Elements</title>
-
- <sect2 xml:id="docbook-markup-paragraphs">
- <title>Paragraphs</title>
-
- <para>DocBook supports three types of paragraphs:
- <tag>formalpara</tag>, <tag>para</tag>, and
- <tag>simpara</tag>.</para>
-
- <para>Almost all paragraphs in &os; documentation 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> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>This is a paragraph. It can contain just about any
- other element.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>This is a paragraph. It can contain just about any
- other element.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-block-quotations">
- <title>Block Quotations</title>
-
- <para>A block quotation is an extended quotation from another
- document that should not appear within the current paragraph.
- These are rarely needed.</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> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag>
-
-<tag class="starttag">blockquote</tag>
- <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag>
-
- <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag>
-
- <tag class="starttag">para</tag>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.<tag class="endtag">para</tag>
-<tag class="endtag">blockquote</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>A small excerpt from the US Constitution:</para>
-
- <blockquote>
- <title>Preamble to the Constitution of the United
- States</title>
-
- <attribution>Copied from a web site
- somewhere</attribution>
-
- <para>We the People of the United States, in Order to form
- a more perfect Union, establish Justice, insure domestic
- Tranquility, provide for the common defence, promote the
- general Welfare, and secure the Blessings of Liberty to
- ourselves and our Posterity, do ordain and establish
- this Constitution for the United States of
- America.</para>
- </blockquote>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-tips-notes">
- <title>Tips, Notes, Warnings, Cautions, and Important
- Information</title>
-
- <para>Extra information may need to be separated from
- the main body of the text. Typically this is
- <quote>meta</quote> information of which the user should be
- aware.</para>
-
- <para>Several types of admonitions are available:
- <tag>tip</tag>, <tag>note</tag>,
- <tag>warning</tag>, <tag>caution</tag>, and
- <tag>important</tag>.</para>
-
- <para>Which admonition to choose depends on the situation.
- The DocBook
- documentation suggests:</para>
-
- <itemizedlist>
- <listitem>
- <para>Note is for information that should be heeded by
- all readers.</para>
- </listitem>
-
- <listitem>
- <para>Important is a variation on Note.</para>
- </listitem>
-
- <listitem>
- <para>Caution is for information regarding possible data
- loss or software damage.</para>
- </listitem>
-
- <listitem>
- <para>Warning is for information regarding possible
- hardware damage or injury to life or limb.</para>
- </listitem>
- </itemizedlist>
-
- <example>
- <title><tag>tip</tag> and <tag>important</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">tip</tag>
- <tag class="starttag">para</tag>&amp;os&semi; may reduce stress.<tag class="endtag">para</tag>
-<tag class="endtag">tip</tag>
-
-<tag class="starttag">important</tag>
- <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions
- are visually jarring and can have the opposite of the
- intended effect.<tag class="endtag">para</tag>
-<tag class="endtag">important</tag></programlisting>
- </example>
-
- <para>Appearance:</para>
- <!-- Need to do this outside of the example -->
- <tip>
- <para>&os; may reduce stress.</para>
- </tip>
-
- <important>
- <para>Please use admonitions sparingly. Too many admonitions
- are visually jarring and can have the opposite of the
- intended effect.</para>
- </important>
- </sect2>
-
- <sect2 xml:id="docbook-markup-example">
- <title>Examples</title>
-
- <para>Examples can be shown with <tag>example</tag>.</para>
-
- <example>
- <title><tag>example</tag> Source</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">example</tag>
- <tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag>
-
- <tag class="starttag">screen</tag>&amp;prompt.user&semi; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag>
-<tag class="endtag">example</tag></programlisting>
- </example>
-
- <!-- Need to do this outside of the example -->
- <para>Appearance:</para>
-
- <example>
- <title>Rendered <tag>example</tag></title>
-
- <para>Empty files can be created easily:</para>
-
- <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-lists-and-procedures">
- <title>Lists and Procedures</title>
-
- <para>Information often needs to be presented as lists, or as a
- number of steps that must be carried out in order to
- accomplish a particular goal.</para>
-
- <para>To do this, use <tag>itemizedlist</tag>,
- <tag>orderedlist</tag>, <tag>variablelist</tag>, or
- <tag>procedure</tag>. There are other types of list
- elements in DocBook, but we will not cover them here.</para>
-
- <para><tag>itemizedlist</tag> and
- <tag>orderedlist</tag> are similar to their
- counterparts in <acronym>HTML</acronym>, <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 <acronym>HTML</acronym>'s <tag>li</tag>
- tags. However, unlike HTML, they are required.</para>
-
- <example>
- <title><tag>itemizedlist</tag> and
- <tag>orderedlist</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">itemizedlist</tag>
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-<tag class="endtag">itemizedlist</tag>
-
-<tag class="starttag">orderedlist</tag>
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-<tag class="endtag">orderedlist</tag></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>
-
- <para xml:id="docbook-markup-varlist">An alternate and often
- useful way of presenting information is the
- <tag>variablelist</tag>. These are lists where each entry has
- a term and a description. They are well suited for many types
- of descriptions, and present information in a form that is
- often easier for the reader than sections and
- subsections.</para>
-
- <para>A <tag>variablelist</tag> has a <tag>title</tag>, and then
- pairs of <tag>term</tag> and <tag>listitem</tag>
- entries.</para>
-
- <example xml:id="docbook-markup-variablelist-example">
- <title><tag>variablelist</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">variablelist</tag>
- <tag class="starttag">varlistentry</tag>
- <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>In parallel communications, groups of bits arrive
- at the same time over multiple communications
- channels.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
- <tag class="endtag">varlistentry</tag>
-
- <tag class="starttag">varlistentry</tag>
- <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>In serial communications, bits arrive one at a
- time over a single communications
- channel.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
- <tag class="endtag">varlistentry</tag>
-<tag class="endtag">variablelist</tag></programlisting>
-
- <para>Appearance:</para>
-
- <variablelist>
- <varlistentry>
- <term>Parallel</term>
-
- <listitem>
- <para>In parallel communications, groups of bits arrive
- at the same time over multiple communications
- channels.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Serial</term>
-
- <listitem>
- <para>In serial communications, bits arrive one at a
- time over a single communications channel.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </example>
-
- <para>A <tag>procedure</tag> shows a series of
- <tag>step</tag>s, which may in turn
- consist of more <tag>step</tag>s or
- <tag>substep</tag>s. Each <tag>step</tag>
- contains block elements and may include an optional title.</para>
-
- <para>Sometimes, steps are not sequential, but present a choice:
- do <emphasis>this</emphasis> or do <emphasis>that</emphasis>,
- but not both. For these alternative choices, use
- <tag>stepalternatives</tag>.</para>
-
- <example>
- <title><tag>procedure</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">procedure</tag>
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Finally, do one of these.<tag class="endtag">para</tag>
-
- <tag class="starttag">stepalternatives</tag>
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
- <tag class="endtag">stepalternatives</tag>
- <tag class="endtag">step</tag>
-<tag class="endtag">procedure</tag></programlisting>
-
- <para>Appearance:</para>
-
- <procedure>
- <step>
- <para>Do this.</para>
- </step>
-
- <step>
- <para>Then do this.</para>
- </step>
-
- <step>
- <para>And now do this.</para>
- </step>
-
- <step>
- <para>Finally, do one of these:</para>
-
- <stepalternatives>
- <step>
- <para>Go left.</para>
- </step>
-
- <step>
- <para>Go right.</para>
- </step>
- </stepalternatives>
- </step>
- </procedure>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-showing-file-samples">
- <title>Showing File Samples</title>
-
- <para>Fragments of a file (or perhaps a complete file) are shown
- by wrapping them 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> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>When finished, the program will look like
- this:<tag class="endtag">para</tag>
-
-<tag class="starttag">programlisting</tag>#include &amp;lt;stdio.h&amp;gt;
-
-int
-main(void)
-{
- printf("hello, world\n");
-}<tag class="endtag">programlisting</tag></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 finished, the program will look like this:</para>
-
- <programlisting>#include &lt;stdio.h&gt;
-
-int
-main(void)
-{
- printf("hello, world\n");
-}</programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-callouts">
- <title>Callouts</title>
-
- <para>A callout is a visual marker for referring to a
- piece of text or specific position within an
- example.</para>
-
- <para>Callouts are marked 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 describes each
- callout.</para>
-
- <example>
- <title><tag>co</tag> and
- <tag>calloutlist</tag> Example</title>
-
- <programlisting><tag class="starttag">para</tag>When finished, the program will look like
- this:<tag class="endtag">para</tag>
-
-<tag class="starttag">programlisting</tag>#include &amp;lt;stdio.h&amp;gt; <tag class="emptytag">co xml:id="co-ex-include"</tag>
-
-int <tag class="emptytag">co xml:id="co-ex-return"</tag>
-main(void)
-{
- printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag>
-}<tag class="endtag">programlisting</tag>
-
-<tag class="starttag">calloutlist</tag>
- <tag class="starttag">callout arearefs="co-ex-include"</tag>
- <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag>
- <tag class="endtag">callout</tag>
-
- <tag class="starttag">callout arearefs="co-ex-return"</tag>
- <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an
- int.<tag class="endtag">para</tag>
- <tag class="endtag">callout</tag>
-
- <tag class="starttag">callout arearefs="co-ex-printf"</tag>
- <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes
- <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag>
- <tag class="endtag">callout</tag>
-<tag class="endtag">calloutlist</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>When finished, the program will look like this:</para>
-
- <programlisting>#include &lt;stdio.h&gt; <co xml:id="co-ex-include"/>
-
-int <co xml:id="co-ex-return"/>
-main(void)
-{
- printf("hello, world\n"); <co xml:id="co-ex-printf"/>
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="co-ex-include">
- <para>Includes the standard IO header file.</para>
- </callout>
-
- <callout arearefs="co-ex-return">
- <para>Specifies that <function>main()</function> returns
- an int.</para>
- </callout>
-
- <callout arearefs="co-ex-printf">
- <para>The <function>printf()</function> call that writes
- <literal>hello, world</literal> to standard
- output.</para>
- </callout>
- </calloutlist>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-tables">
- <title>Tables</title>
-
- <para>Unlike <acronym>HTML</acronym>, DocBook does not need
- tables for layout purposes, as the stylesheet handles those
- issues. 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 there is 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> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">informaltable pgwide="1"</tag>
- <tag class="starttag">tgroup cols="2"</tag>
- <tag class="starttag">thead</tag>
- <tag class="starttag">row</tag>
- <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag>
- <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag>
- <tag class="endtag">row</tag>
- <tag class="endtag">thead</tag>
-
- <tag class="starttag">tbody</tag>
- <tag class="starttag">row</tag>
- <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag>
- <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag>
- <tag class="endtag">row</tag>
-
- <tag class="starttag">row</tag>
- <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag>
- <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag>
- <tag class="endtag">row</tag>
- <tag class="endtag">tbody</tag>
- <tag class="endtag">tgroup</tag>
-<tag class="endtag">informaltable</tag></programlisting>
-
- <para>Appearance:</para>
-
- <informaltable pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>This is Column Head 1</entry>
- <entry>This is Column Head 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Row 1, column 1</entry>
- <entry>Row 1, column 2</entry>
- </row>
-
- <row>
- <entry>Row 2, column 1</entry>
- <entry>Row 2, column 2</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </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>Table borders can be suppressed by setting the
- <literal>frame</literal> attribute to <literal>none</literal>
- in the <tag>informaltable</tag> element. For example,
- <literal>informaltable frame="none"</literal>.</para>
-
- <example>
- <title>Table with <literal>frame="none"</literal> Example</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>
- </sect2>
-
- <sect2 xml:id="docbook-markup-examples">
- <title>Examples for the User to Follow</title>
-
- <para>Examples for the user to follow are often necessary.
- Typically, these will consist of dialogs with the computer;
- the user types in a command, the user gets a response back,
- the user types 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>&amp;prompt.root;</literal> and
- <literal>&amp;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. To indicate the user is at a shell prompt,
- use one of <literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal> as necessary. They
- do not need to be inside
- <tag>prompt</tag>.</para>
-
- <note>
- <para><literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal> are &os;
- extensions to DocBook, and are not part of the
- original <acronym>DTD</acronym>.</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
- be displayed differently than system output text.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title><tag>screen</tag>, <tag>prompt</tag>,
- and <tag>userinput</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag>
-foo1
-foo2
-foo3
-&amp;prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag>
-foo2
-&amp;prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag>
-<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag>
-&amp;prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag>
-This is the file called 'foo2'<tag class="endtag">screen</tag></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>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-inline-elements">
- <title>In-line Elements</title>
-
- <sect2 xml:id="docbook-markup-inline-emphasizing">
- <title>Emphasizing Information</title>
-
- <para>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 the document, no equivalent of
- <acronym>HTML</acronym>'s <tag>b</tag> and
- <tag>i</tag>. If the information being presented is
- important, then consider presenting it in
- <tag>important</tag> rather than
- <tag>emphasis</tag>.</para>
-
- <example>
- <title><tag>emphasis</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>&amp;os&semi; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag>
- premiere &amp;unix;-like operating system for the Intel
- architecture.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>&os; is without doubt <emphasis>the</emphasis>
- premiere &unix;-like operating system for the Intel
- architecture.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-acronyms">
- <title>Acronyms</title>
-
- <para>Many computer terms are <emphasis>acronyms</emphasis>,
- words formed from the first letter of each word in a
- phrase. Acronyms are marked up into
- <tag>acronym</tag> elements. It is helpful to the
- reader when an acronym is defined on the first use, as shown
- in the example below.</para>
-
- <example>
- <title><tag>acronym</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149
- defined the use of avian carriers for transmission of
- Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The
- quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently
- transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>Request For Comments (<acronym>RFC</acronym>) 1149
- defined the use of avian carriers for transmission of
- Internet Protocol (<acronym>IP</acronym>) data. The
- quantity of <acronym>IP</acronym> data currently
- transmitted in that manner is unknown.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-quotations">
- <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>. Most of the markup tags available
- for normal text are also available from within a
- <tag>quote</tag>.</para>
-
- <example>
- <title><tag>quote</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>However, make sure that the search does not go beyond the
- <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>,
- as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></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 <acronym>RFC</acronym> 1535
- calls it.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-keys">
- <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 Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>To switch to the second virtual terminal, press
- <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>
- <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type
- <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag>
- <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>My window manager is configured so that
- <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>
- <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag>
- <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></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 changes,
- type <keycombo action="seq">
- <keycap>Esc</keycap>
- <keycap>:</keycap>
- <keycap>q</keycap>
- <keycap>!</keycap></keycombo>.</para>
-
- <para>My window manager is configured so that
- <keycombo action="simul">
- <keycap>Alt</keycap>
- <mousebutton>right</mousebutton></keycombo> mouse button
- is used to move windows.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-applications">
- <title>Applications, Commands, Options, and Cites</title>
-
- <para>Both applications and commands are frequently referred to
- when writing documentation. The distinction between them is
- that an application is the name of a program or suite of
- programs that fulfill a particular task. A command is the
- filename of a program that the user can type and run at a
- command line.</para>
-
- <para>It is often necessary to show some of the options that a
- command might take.</para>
-
- <para>Finally, it is often useful 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>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="xml-primer-general-entities">general
- entities</link> have been created to make this easier.
- Each entity takes the form
- <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</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 <acronym>FPI</acronym>:</para>
-
- <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
-
- <para>Therefore, the introduction to &os; documentation will
- usually include this:</para>
-
- <programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
-
-&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
-%man;
-
-&hellip;
-
-]&gt;</programlisting>
-
- <para>Use <tag>command</tag> to include a command
- name <quote>in-line</quote> but present it as something the
- user should type.</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>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
- notation to markup the first reference and use
- <tag>command</tag> to markup subsequent references.
- This makes the generated output, especially
- <acronym>HTML</acronym>, appear visually better.</para>
-
- <example>
- <title>Applications, Commands, and Options Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most
- widely used Unix mail application.<tag class="starttag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the
- <tag class="starttag">citerefentry</tag>
- <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>
- <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>
- <tag class="endtag">citerefentry</tag>, &amp;man.mailq.1;, and &amp;man.newaliases.1;
- programs.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag>
- <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>
- <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>
- <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current
- status of messages in the mail queue. Check this on the command
- line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></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>, &man.mailq.1;, and &man.newaliases.1;
- programs.</para>
-
- <para>One of the command line parameters to
- <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, <option>-bp</option>, will display the
- current status of messages in the mail queue. Check this
- on the command line by running
- <command>sendmail -bp</command>.</para>
- </example>
-
- <note>
- <para>Notice how the
- <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
- notation is easier to follow.</para>
- </note>
- </sect2>
-
- <sect2 xml:id="docbook-markup-files">
- <title>Files, Directories, Extensions, Device Names</title>
-
- <para>To refer to the name of a file, a directory, a file
- extension, or a device name, use <tag>filename</tag>.</para>
-
- <example>
- <title><tag>filename</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>The source for the Handbook in English is found in
- <tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>.
- The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>.
- There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a
- number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected
- by the system, and appears in
- <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>The source for the Handbook in English is found in
- <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
- The main file is called <filename>book.xml</filename>.
- There is also a <filename>Makefile</filename> and a number
- of files with a <filename>.ent</filename> extension.</para>
-
- <para><filename>kbd0</filename> is the first keyboard detected
- by the system, and appears in
- <filename>/dev</filename>.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-name-of-ports">
- <title>The Name of Ports</title>
-
- <note>
- <title>&os; Extension</title>
-
- <para>These elements are part of the &os; extension to
- DocBook, and do not exist in the original DocBook
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para>To include the name of a program from the &os;
- Ports Collection in the document, use the <tag>package</tag>
- tag. Since the Ports Collection can be installed in any
- number of locations, only include the category and the port
- name; do not include <filename>/usr/ports</filename>.</para>
-
- <para>By default, <tag>package</tag> refers to a binary package.
- To refer to a port that will be built from source, set the
- <literal>role</literal> attribute to
- <literal>port</literal>.</para>
-
- <example>
- <title><tag>package</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary
- package to view network traffic.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be
- built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>Install the <package>net/wireshark</package> binary
- package to view network traffic.</para>
-
- <para><package role="port">net/wireshark</package> can also be
- built and installed from the Ports Collection.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-hosts">
- <title>Hosts, Domains, IP Addresses, User Names, Group Names,
- and Other System Items</title>
-
- <note>
- <title>&os; Extension</title>
-
- <para>These elements are part of the &os; extension to
- DocBook, and do not exist in the original DocBook
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para>Information for <quote>system items</quote> is marked up
- with <tag>systemitem</tag>. The <literal>class</literal>
- attribute is used to identify the particular type of
- information shown.</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>class="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>class="etheraddress"</literal></term>
-
- <listitem>
- <para>The text is an Ethernet <acronym>MAC</acronym>
- address, expressed as a series of 2 digit hexadecimal
- numbers separated by colons.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>class="fqdomainname"</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>class="ipaddress"</literal></term>
-
- <listitem>
- <para>The text is an <acronym>IP</acronym> address,
- probably expressed as a dotted quad.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>class="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
- (<acronym>CIDR</acronym> notation).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>class="systemname"</literal></term>
-
- <listitem>
- <para>With <literal>class="systemname"</literal>
- the marked up information is the simple hostname, such
- as <literal>freefall</literal> or
- <literal>wcarchive</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>class="username"</literal></term>
-
- <listitem>
- <para>The text is a username, like
- <literal>root</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>class="groupname"</literal></term>
-
- <listitem>
- <para>The text is a groupname, like
- <literal>wheel</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title><tag>systemitem</tag> and Classes Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>The local machine can always be referred to by the
- name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP
- address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag>
- domain contains a number of different hosts, including
- <tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and
- <tag class="starttag">systemitem class="fqdomainname"</tag>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an
- interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>)
- <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of
- <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can
- also be expressed as
- <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies
- every network card in existence. A typical
- <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like
- <tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>To carry out most system administration functions
- requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></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 <acronym>IP</acronym> alias to an
- interface (using <command>ifconfig</command>)
- <emphasis>always</emphasis> use a netmask of
- <systemitem class="netmask">255.255.255.255</systemitem>
- (which can also be expressed as
- <systemitem class="netmask">0xffffffff</systemitem>).</para>
-
- <para>The <acronym>MAC</acronym> address uniquely identifies
- every network card in existence. A typical
- <acronym>MAC</acronym> address looks like <systemitem
- class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>
-
- <para>To carry out most system administration functions
- requires logging in as
- <systemitem class="username">root</systemitem>.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-uri">
- <title>Uniform Resource Identifiers
- (<acronym>URI</acronym>s)</title>
-
- <para>Occasionally it is useful to show a
- Uniform Resource Identifier (<acronym>URI</acronym>) without
- making it an active hyperlink. The <tag>uri</tag> element
- makes this possible:</para>
-
- <example>
- <title><tag>uri</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text:
- <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not
- create a link.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>This <acronym>URL</acronym> shows only as text:
- <uri>https://www.FreeBSD.org</uri>. It does not
- create a link.</para>
- </example>
-
- <para>To create links, see
- <xref linkend="docbook-markup-links"/>.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-email-addresses">
- <title>Email Addresses</title>
-
- <para>Email addresses are marked up as <tag>email</tag>
- elements. In the <acronym>HTML</acronym> output format, the
- wrapped text becomes a hyperlink to the email address. Other
- output formats that support hyperlinks may also make the email
- address into a link.</para>
-
- <example>
- <title><tag>email</tag> with a Hyperlink Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>An email address that does not actually exist, like
- <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an
- example.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>An email address that does not actually exist, like
- <email>notreal@example.com</email>, can be used as an
- example.</para>
- </example>
-
- <para>A &os;-specific extension allows setting the
- <literal>role</literal> attribute to <literal>nolink</literal>
- to prevent the creation of the hyperlink to the email
- address.</para>
-
- <example>
- <title><tag>email</tag> Without a Hyperlink Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>Sometimes a link to an email address like
- <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not
- desired.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>Sometimes a link to an email address like
- <email role="nolink">notreal@example.com</email> is not
- desired.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-describing-makefiles">
- <title>Describing <filename>Makefile</filename>s</title>
-
- <note>
- <title>&os; Extension</title>
-
- <para>These elements are part of the &os; extension to
- DocBook, and do not exist in the original DocBook
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para>Two elements exist to describe parts of
- <filename>Makefile</filename>s, <tag>buildtarget</tag>
- and <tag>varname</tag>.</para>
-
- <para><tag>buildtarget</tag> identifies a build target
- exported by a <filename>Makefile</filename> that can be
- given as a parameter to <command>make</command>.
- <tag>varname</tag> identifies a variable that can be
- set (in the environment, on the command line with
- <command>make</command>, or within the
- <filename>Makefile</filename>) to influence the
- process.</para>
-
- <example>
- <title><tag>buildtarget</tag> and
- <tag>varname</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag>
- are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and
- <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will
- rebuild the application, and invoking
- <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary
- files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the
- build process.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a
- number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag>
- and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></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>
- </sect2>
-
- <sect2 xml:id="docbook-markup-literal-text">
- <title>Literal Text</title>
-
- <para>Literal text, or text which should be entered verbatim, is
- often needed in documentation. This is text that is excerpted
- from another file, or which should be copied exactly as shown
- from the documentation into another file.</para>
-
- <para>Some of the time, <tag>programlisting</tag> will
- be sufficient to denote this text. But
- <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> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> 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.<tag class="endtag">para</tag></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>
- </sect2>
-
- <sect2 xml:id="docbook-markup-replaceable">
- <title>Showing Items That the User <emphasis>Must</emphasis>
- Fill In</title>
-
- <para>There will often be times when the user is shown
- what to do, or referred to a file or command line, but
- cannot simply copy the example provided. Instead, they
- must supply 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> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>
-
- <para>Appearance:</para>
-
- <informalexample>
- <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></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>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag>
- 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.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value
- for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <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>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-gui-buttons">
- <title>Showing <acronym>GUI</acronym> Buttons</title>
-
- <para>Buttons presented by a graphical user interface are marked
- with <tag>guibutton</tag>. To make the text look more
- like a graphical button, brackets and non-breaking spaces are
- added surrounding the text.</para>
-
- <example>
- <title><tag>guibutton</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>Edit the file, then click
- <tag class="starttag">guibutton</tag>[&amp;nbsp;Save&amp;nbsp;]<tag class="endtag">guibutton</tag> to save the
- changes.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>Edit the file, then click
- <guibutton>[&nbsp;Save&nbsp;]</guibutton> to save the
- changes.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-system-errors">
- <title>Quoting System Errors</title>
-
- <para>System errors generated by &os; are marked with
- <tag>errorname</tag>. This indicates the exact error
- that appears.</para>
-
- <example>
- <title><tag>errorname</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting>
-
- <para>Appearance:</para>
-
- <informalexample>
- <screen><errorname>Panic: cannot mount root</errorname></screen>
- </informalexample>
- </example>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-images">
- <title>Images</title>
-
- <important>
- <para>Image support in the documentation is somewhat
- experimental. The mechanisms described here are unlikely to
- change, but that is not guaranteed.</para>
-
- <para>To provide conversion between different image formats, the
- <package>graphics/ImageMagick</package>
- port must be installed. This port is not included in the
- <package>textproc/docproj</package> meta
- port, and must be installed separately.</para>
-
- <para>A good example of the use of images is the
- <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
- document. Examine the files in that directory to see how
- these elements are used together. Build different output
- formats to see how the format determines what images are shown
- in the rendered document.</para>
- </important>
-
- <sect2 xml:id="docbook-markup-image-formats">
- <title>Image Formats</title>
-
- <para>The following image formats are currently supported. An
- image file will automatically be converted to bitmap or vector
- image depending on the output document format.</para>
-
- <para>These are the <emphasis>only</emphasis> formats in which
- images should be committed to the documentation
- repository.</para>
-
- <variablelist>
- <varlistentry>
- <term><acronym>EPS</acronym> (Encapsulated
- Postscript)</term>
-
- <listitem>
- <para>Images that are primarily vector based, such as
- network diagrams, time lines, and similar, should be in
- this format. These images have a
- <filename>.eps</filename> extension.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><acronym>PNG</acronym> (Portable Network
- Graphic)</term>
-
- <listitem>
- <para>For bitmaps, such as screen captures, use this
- format. These images have the <filename>.png</filename>
- extension.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><acronym>PIC</acronym> (PIC graphics language)</term>
-
- <listitem>
- <para><acronym>PIC</acronym> is a language for drawing
- simple vector-based figures used in the &man.pic.1;
- utility. These images have the
- <filename>.pic</filename> extension.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><acronym>SCR</acronym> (SCReen capture)</term>
-
- <listitem>
- <para>This format is specific to screenshots of console
- output. The following command generates an SCR file
- <filename>shot.scr</filename> from video buffer of
- <filename>/dev/ttyv0</filename>:</para>
-
- <screen>&prompt.root; <userinput><command>vidcontrol -p</command> &lt; <filename><replaceable>/dev/ttyv0</replaceable></filename> &gt; <filename><replaceable>shot.scr</replaceable></filename></userinput></screen>
-
- <para>This is preferable to <acronym>PNG</acronym> format
- for screenshots because the <acronym>SCR</acronym> file
- contains plain text of the command lines so that it can
- be converted to a <acronym>PNG</acronym> image or a
- plain text depending on the output document
- format.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Use the appropriate format for each image. Documentation
- will often have a mix of <acronym>EPS</acronym> and
- <acronym>PNG</acronym> images. The
- <filename>Makefile</filename>s ensure that the correct format
- image is chosen depending on the output format used.
- <emphasis>Do not commit the same image to the repository in
- two different formats</emphasis>.</para>
-
- <important>
- <para>The Documentation Project may eventually switch to using
- the <acronym>SVG</acronym> (Scalable Vector Graphic) format
- for vector images. However, the current state of
- <acronym>SVG</acronym> capable editing tools makes this
- impractical.</para>
- </important>
- </sect2>
-
- <sect2 xml:id="docbook-markup-image-file-locations">
- <title>Image File Locations</title>
-
- <para>Image files can be stored in one of several locations,
- depending on the document and image:</para>
-
- <itemizedlist>
- <listitem>
- <para>In the same directory as the document itself, usually
- done for articles and small books that keep all their
- files in a single directory.</para>
- </listitem>
-
- <listitem>
- <para>In a subdirectory of the main document. Typically
- done when a large book uses separate subdirectories to
- organize individual chapters.</para>
-
- <para>When images are stored in a subdirectory of the
- main document directory, the subdirectory name must be
- included in their paths in the
- <filename>Makefile</filename> and the
- <tag>imagedata</tag> element.</para>
- </listitem>
-
- <listitem>
- <para>In a subdirectory of
- <filename>doc/share/images</filename> named after the
- document. For example, images for the Handbook are stored
- in <filename>doc/share/images/books/handbook</filename>.
- Images that work for multiple translations are stored in
- this upper level of the documentation file tree.
- Generally, these are images that can be used unchanged in
- non-English translations of the document.</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 xml:id="docbook-markup-image-markup">
- <title>Image Markup</title>
-
- <para>Images are included as part of 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>Include one <tag>imageobject</tag>, and two
- <tag>textobject</tag> elements. The <tag>imageobject</tag>
- will point to the name of the image file 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 itself.</para>
-
- <para>Text elements are shown to the reader in several
- situations. When the document is viewed in
- <acronym>HTML</acronym>, text elements are shown while the
- image is loading, or if the mouse pointer is hovered over the
- image, or if a text-only browser is being used. In formats
- like plain text where graphics are not possible, the text
- elements are shown instead of the graphical ones.</para>
-
- <para>This example shows how to include an image called
- <filename>fig1.png</filename> in a document. The image is a
- rectangle with an A inside it:</para>
-
- <programlisting><tag class="starttag">mediaobject</tag>
- <tag class="starttag">imageobject</tag>
- <tag class="starttag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/>
- <tag class="endtag">imageobject</tag>
-
- <tag class="starttag">textobject</tag>
- <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/>
-| A |
-+---------------+<tag class="endtag">literallayout</tag>
- <tag class="endtag">textobject</tag>
-
- <tag class="starttag">textobject</tag>
- <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/>
- <tag class="endtag">textobject</tag>
-<tag class="endtag">mediaobject</tag></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> contains a
- <tag>literallayout</tag> element, where the
- <literal>class</literal> attribute is set to
- <literal>monospaced</literal>. This is an opportunity to
- demonstrate <acronym>ASCII</acronym> 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> contains a
- single <tag>phrase</tag> element. The contents of
- this phrase will become the <literal>alt</literal>
- attribute for the image when this document is converted to
- <acronym>HTML</acronym>.</para>
- </callout>
- </calloutlist>
- </sect2>
-
- <sect2 xml:id="docbook-markup-image-makefile-entries">
- <title>Image <filename>Makefile</filename> Entries</title>
-
- <para>Images must be listed in the <filename>Makefile</filename>
- in the <varname>IMAGES</varname> variable. This variable must
- contain the names of all the <emphasis>source</emphasis>
- images. For example, if there are three figures,
- <filename>fig1.eps</filename>, <filename>fig2.png</filename>,
- <filename>fig3.png</filename>, then the
- <filename>Makefile</filename> should have lines like this in
- it.</para>
-
- <programlisting>&hellip;
-IMAGES= fig1.eps fig2.png fig3.png
-&hellip;</programlisting>
-
- <para>or</para>
-
- <programlisting>&hellip;
-IMAGES= fig1.eps
-IMAGES+= fig2.png
-IMAGES+= fig3.png
-&hellip;</programlisting>
-
- <para>Again, the <filename>Makefile</filename> will work out the
- complete list of images it needs to build the source document,
- you only need to list the image files <emphasis>you</emphasis>
- provided.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-images-in-subdirectories">
- <title>Images and Chapters in Subdirectories</title>
-
- <para>Be careful when separating documentation into smaller
- files in different directories (see <xref
- linkend="xml-primer-include-using-gen-entities"/>).</para>
-
- <para>Suppose there is 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, place those images in each
- chapter's subdirectory (<filename>chapter1/</filename>,
- <filename>chapter2/</filename>, and
- <filename>chapter3/</filename>).</para>
-
- <para>However, doing this requires including the directory
- names in the <varname>IMAGES</varname> variable in the
- <filename>Makefile</filename>, <emphasis>and</emphasis>
- including the directory name in the <tag>imagedata</tag>
- element in the document.</para>
-
- <para>For example, if the book has
- <filename>chapter1/fig1.png</filename>, then
- <filename>chapter1/chapter.xml</filename> should
- contain:</para>
-
- <programlisting><tag class="starttag">mediaobject</tag>
- <tag class="starttag">imageobject</tag>
- <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/>
- <tag class="endtag">imageobject</tag>
-
- &hellip;
-
-<tag class="endtag">mediaobject</tag></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>&hellip;
-IMAGES= chapter1/fig1.png
-&hellip;</programlisting>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-links">
- <title>Links</title>
-
- <note>
- <para>Links are also in-line elements. To show a
- <acronym>URI</acronym> without creating a link, see
- <xref linkend="docbook-markup-uri"/>.</para>
- </note>
-
- <sect2 xml:id="docbook-markup-links-ids">
- <title><literal>xml:id</literal> Attributes</title>
-
- <para>Most DocBook elements accept an <literal>xml:id</literal>
- attribute to give that part of the document a unique name.
- The <literal>xml:id</literal> can be used as a target for a
- crossreference or link.</para>
-
- <para>Any portion of the document that will be a link target
- must have an <literal>xml:id</literal> attribute. Assigning
- an <literal>xml:id</literal> to all chapters and sections,
- even if there are no current plans to link to them, is a good
- idea. These <literal>xml:id</literal>s can be used as unique
- reference points by anyone referring to the
- <acronym>HTML</acronym> version of the document.</para>
-
- <example>
- <title><literal>xml:id</literal> on Chapters and
- Sections Example</title>
-
- <programlisting><tag class="starttag">chapter xml:id="introduction"</tag>
- <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is the introduction. It contains a subsection,
- which is identified as well.<tag class="endtag">para</tag>
-
- <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag>
- <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">chapter</tag></programlisting>
- </example>
-
- <para>Use descriptive values for <literal>xml:id</literal>
- names. The values must be unique within the entire document,
- not just in a single file. In the example, the subsection
- <literal>xml:id</literal> is constructed by appending text to
- the chapter <literal>xml:id</literal>. This ensures that the
- <literal>xml:id</literal>s are unique. It also helps both
- reader and anyone editing the document to see where the link
- is located within the document, similar to a directory path to
- a file.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-links-crossreferences">
- <title>Crossreferences with <literal>xref</literal></title>
-
- <para><tag>xref</tag> provides the reader with a link to jump to
- another section of the document. The target
- <literal>xml:id</literal> is specified in the
- <literal>linkend</literal> attribute, and <tag>xref</tag>
- generates the link text automatically.</para>
-
- <example>
- <title><tag>xref</tag> Example</title>
-
- <para>Assume that this fragment appears somewhere in a
- document that includes the <literal>xml:id</literal>
- example shown above:</para>
-
- <programlisting><tag class="starttag">para</tag>More information can be found
- in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>More specific information can be found
- in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>The link text will be generated automatically, looking
- like (<emphasis>emphasized</emphasis> text indicates the
- link text):</para>
-
- <blockquote>
- <para>More information can be found in <emphasis>Chapter
- 1, Introduction</emphasis>.</para>
-
- <para>More specific information can be found in
- <emphasis>Section 1.1,
- <quote>More Details</quote></emphasis>.</para>
- </blockquote>
- </example>
-
- <para>The link text is generated automatically from the chapter
- and section number and <literal>title</literal>
- elements.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-links-to-web-documents">
- <title>Linking to Other Documents on the
- Web</title>
-
- <para>The link element described here allows the writer to
- define the link text. When link text is used, it is very important to be descriptive
- to give the reader an idea of where the link goes.
- Remember that DocBook can be rendered to multiple
- types of media. The reader might be looking at a printed book
- or other form of media where there are no links. If the link
- text is not descriptive enough, the reader might not be able to
- locate the linked section.</para>
-
- <para>The <literal>xlink:href</literal> attribute
- is the <acronym>URL</acronym> of the page,
- and the content of the element is the text that
- will be displayed for the user to activate.</para>
-
- <para>In many situations, it is preferable to show the actual
- <acronym>URL</acronym> rather than text. This can be done by
- leaving out the element text entirely.</para>
-
- <example>
- <title><tag>link</tag> to a &os; Documentation Web
- Page Example</title>
-
- <para>Link to the book or article <acronym>URL</acronym>
- entity. To link to a specific chapter in a book, add a
- slash and the chapter file name, followed by an optional
- anchor within the chapter. For articles, link to the
- article <acronym>URL</acronym> entity, followed by an
- optional anchor within the article.
- <acronym>URL</acronym> entities can be found in
- <filename>doc/share/xml/urls.ent</filename>.</para>
-
- <para>Usage for &os; book links:</para>
-
- <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">link
- xlink:href="&amp;url.books.handbook;/svn.html#svn-intro"</tag>SVN
- introduction<tag class="endtag">link</tag>, then pick the nearest mirror from
- the list of <tag class="starttag">link
- xlink:href="&amp;url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion
- mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>Read the <link
- xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
- introduction</link>, then pick the nearest mirror from
- the list of <link
- xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
- mirror sites</link>.</para>
-
- <para>Usage for &os; article links:</para>
-
- <programlisting><tag class="starttag">para</tag>Read this
- <tag class="starttag">link xlink:href="&amp;url.articles.bsdl-gpl;"</tag>article
- about the BSD license<tag class="endtag">link</tag>, or just the
- <tag class="starttag">link xlink:href="&amp;url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>Read this
- <link xlink:href="&url.articles.bsdl-gpl;">article
- about the BSD license</link>, or just the <link
- xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para>
- </example>
-
- <example>
- <title><tag>link</tag> to a &os; Web Page Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the
- <tag class="starttag">link xlink:href="&amp;url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></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>
-
- <example>
- <title><tag>link</tag> to an External Web
- Page Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on
- <tag class="starttag">link
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID
- Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>Appearance:</para>
-
- <para>Wikipedia has an excellent reference on <link
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
- Partition Tables</link>.</para>
-
- <para>The link text can be omitted to show the actual
- URL:</para>
-
- <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on
- GUID Partition Tables: <tag class="starttag">link
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>The same link can be entered using shorter
- notation instead of a separate ending tag:</para>
-
- <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on
- GUID Partition Tables: <tag class="emptytag">link
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para>The two methods are equivalent. Appearance:</para>
-
- <para>Wikipedia has an excellent reference on GUID Partition
- Tables: <uri
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para>
- </example>
- </sect2>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml
deleted file mode 100644
index d3453b379b..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml
+++ /dev/null
@@ -1,170 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- Copyright (c) 2013 Warren Block
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form 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 SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``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 THE
- AUTHORS OR CONTRIBUTORS 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 SOFTWARE,
- EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
- $FreeBSD$
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="editor-config">
-
- <title>Editor Configuration</title>
-
- <para>Adjusting text editor configuration can make working on
- document files quicker and easier, and help documents conform to
- <acronym>FDP</acronym> guidelines.</para>
-
- <sect1 xml:id="editor-config-vim">
- <title><application>Vim</application></title>
-
- <para>Install from <package>editors/vim</package>
- or <package>editors/vim-lite</package>.</para>
-
- <sect2 xml:id="editor-config-vim-config">
- <title>Configuration</title>
-
- <para>Edit <filename>~/.vimrc</filename>, adding these
- lines:</para>
-
- <programlisting>if has("autocmd")
- au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
- au BufNewFile,BufRead *.[1-9] call ShowSpecial()
-endif " has(autocmd)
-
-function Set_Highlights()
- "match ExtraWhitespace /^\s* \s*\|\s\+$/
- highlight default link OverLength ErrorMsg
- match OverLength /\%71v.\+/
- return 0
-endfunction
-
-function ShowSpecial()
- setlocal list listchars=tab:>>,trail:*,eol:$
- hi def link nontext ErrorMsg
- return 0
-endfunction " ShowSpecial()
-
-function Set_SGML()
- setlocal number
- syn match sgmlSpecial "&amp;[^;]*;"
- setlocal syntax=sgml
- setlocal filetype=xml
- setlocal shiftwidth=2
- setlocal textwidth=70
- setlocal tabstop=8
- setlocal softtabstop=2
- setlocal formatprg="fmt -p"
- setlocal autoindent
- setlocal smartindent
- " Rewrap paragraphs
- noremap P gqj
- " Replace spaces with tabs
- noremap T :s/ /\t/&lt;CR&gt;
- call ShowSpecial()
- call Set_Highlights()
- return 0
-endfunction " Set_SGML()</programlisting>
- </sect2>
-
- <sect2 xml:id="editor-config-vim-use">
- <title>Use</title>
-
- <para>Press <keycap>P</keycap> to reformat paragraphs or text that has been selected in Visual mode. Press
- <keycap>T</keycap> to replace groups of eight spaces with a
- tab.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="editor-config-emacs">
- <title><application>Emacs</application></title>
-
- <para>Install from
- <package>editors/emacs</package>
- or <package>editors/xemacs</package>.</para>
-
- <para>Edit <filename>~/.emacs</filename>, adding this
- line:</para>
-
- <programlisting>(add-hook 'nxml-mode-hook 'turn-on-auto-fill)</programlisting>
- </sect1>
-
- <sect1 xml:id="editor-config-nano">
- <title><application>nano</application></title>
-
- <para>Install from
- <package>editors/nano</package> or
- <package>editors/nano-devel</package>.</para>
-
- <sect2 xml:id="editor-config-nano-config">
- <title>Configuration</title>
-
- <para>Copy the sample <acronym>XML</acronym> syntax highlight
- file to the user's home directory:</para>
-
- <screen>&prompt.user; <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen>
-
- <para>Add these lines to the new
- <filename>~/.nanorc</filename>.</para>
-
- <programlisting>syntax "xml" "\.([jrs]html?|xml|xslt?)$"
-# trailing whitespace
-color ,blue "[[:space:]]+$"
-# multiples of eight spaces at the start a line
-# (after zero or more tabs) should be a tab
-color ,blue "^([TAB]*[ ]{8})+"
-# tabs after spaces
-color ,yellow "( )+TAB"
-# highlight indents that have an odd number of spaces
-color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"
-# lines longer than 70 characters
-color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"</programlisting>
-
- <para>Process the file to create embedded tabs:</para>
-
- <screen>&prompt.user; <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen>
- </sect2>
-
- <sect2 xml:id="editor-config-nano-use">
- <title>Use</title>
-
- <para>Specify additional helpful options when running the
- editor:</para>
-
- <screen>&prompt.user; <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen>
-
- <para>Users of &man.csh.1; can define an alias in
- <filename>~/.cshrc</filename> to automate these
- options:</para>
-
- <programlisting>alias nano "nano -AKipwz -r 70 -T8"</programlisting>
-
- <para>After the alias is defined, the options will be added
- automatically:</para>
-
- <screen>&prompt.user; <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen>
- </sect2>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml b/nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml
deleted file mode 100644
index 514ed39f46..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml
+++ /dev/null
@@ -1,162 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<appendix xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="examples">
-
- <title>Examples</title>
-
- <para>These examples are not exhaustive&mdash;they do not contain
- all the elements that might be desirable to use, particularly in a
- document's front matter. For more examples of DocBook markup,
- examine the <acronym>XML</acronym> source for this and other
- documents available in the <application>Subversion</application>
- <literal>doc</literal> repository, or available online starting at
- <uri
- xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para>
-
- <sect1 xml:id="examples-docbook-book">
- <title>DocBook <tag>book</tag></title>
-
- <example>
- <title>DocBook <tag>book</tag></title>
-
- <programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"&gt;
-
-<tag class="starttag">book xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:lang="en"</tag>
-
- <tag class="starttag">info</tag>
- <tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag>
-
- <tag class="starttag">author</tag>
- <tag class="starttag">personname</tag>
- <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
- <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
- <tag class="endtag">personname</tag>
-
- <tag class="starttag">affiliation</tag>
- <tag class="starttag">address</tag>
- <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>
- <tag class="endtag">address</tag>
- <tag class="endtag">affiliation</tag>
- <tag class="endtag">author</tag>
-
- <tag class="starttag">copyright</tag>
- <tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
- <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
- <tag class="endtag">copyright</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag>If your book has an abstract then it should go here.<tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">info</tag>
-
- <tag class="starttag">preface</tag>
- <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed
- here.<tag class="endtag">para</tag>
- <tag class="endtag">preface</tag>
-
- <tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is the first chapter in my book.<tag class="endtag">para</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is the first section in my book.<tag class="endtag">para</tag>
- <tag class="endtag">sect1</tag>
- <tag class="endtag">chapter</tag>
-<tag class="endtag">book</tag></programlisting>
- </example>
- </sect1>
-
- <sect1 xml:id="examples-docbook-article">
- <title>DocBook <tag>article</tag></title>
-
- <example>
- <title>DocBook <tag>article</tag></title>
-
- <programlisting>&lt;!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"&gt;
-
-<tag class="starttag">article xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:lang="en"</tag>
-
- <tag class="starttag">info</tag>
- <tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag>
-
- <tag class="starttag">author</tag>
- <tag class="starttag">personname</tag>
- <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
- <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
- <tag class="endtag">personname</tag>
-
- <tag class="starttag">affiliation</tag>
- <tag class="starttag">address</tag>
- <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>
- <tag class="endtag">address</tag>
- <tag class="endtag">affiliation</tag>
- <tag class="endtag">author</tag>
-
- <tag class="starttag">copyright</tag>
- <tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
- <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
- <tag class="endtag">copyright</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag>If your article has an abstract then it should go here.<tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">info</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is the first section in my article.<tag class="endtag">para</tag>
-
- <tag class="starttag">sect2</tag>
- <tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is the first sub-section in my article.<tag class="endtag">para</tag>
- <tag class="endtag">sect2</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">article</tag></programlisting>
- </example>
- </sect1>
-</appendix>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml
deleted file mode 100644
index 0deb064ee2..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ /dev/null
@@ -1,255 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">
- <title>Overview</title>
-
- <para>Welcome to the &os; Documentation Project
- (<acronym>FDP</acronym>). Quality documentation is crucial
- to the success of &os;, and we value your contributions very
- highly.</para>
-
- <para>This document describes how the <acronym>FDP</acronym> is
- organized, how to write and submit documentation, and how to
- effectively use the available tools.</para>
-
- <para>Everyone is welcome to contribute to the
- <acronym>FDP</acronym>. Willingness to contribute is the only
- membership requirement.</para>
-
- <para>This primer shows how to:</para>
-
- <itemizedlist>
- <listitem>
- <para>Identify which parts of &os; are maintained by the
- <acronym>FDP</acronym>.</para>
- </listitem>
-
- <listitem>
- <para>Install the required documentation tools and files.</para>
- </listitem>
-
- <listitem>
- <para>Make changes to the documentation.</para>
- </listitem>
-
- <listitem>
- <para>Submit changes back for review and inclusion in the &os;
- documentation.</para>
- </listitem>
- </itemizedlist>
-
- <sect1 xml:id="overview-doc">
- <title>The &os; Documentation Set</title>
-
- <para>The <acronym>FDP</acronym> is responsible for four
- categories of &os; documentation.</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Handbook</emphasis>: The Handbook is the
- comprehensive online resource and reference for &os;
- users.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym>
- uses a short question and answer format to address questions
- that are frequently asked on the various mailing lists and
- forums devoted to &os;. This format does not permit long
- and comprehensive answers.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Manual pages</emphasis>: The English language
- system manual pages are usually not written by the
- <acronym>FDP</acronym>, as they are part of the base system.
- However, the <acronym>FDP</acronym> can reword parts of
- existing manual pages to make them clearer or to correct
- inaccuracies.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Web site</emphasis>: This is the main &os;
- presence on the web, visible at <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link>
- and many mirrors around the world. The web site is
- typically a new user's first exposure to &os;.</para>
- </listitem>
- </itemizedlist>
-
- <para>Translation teams are responsible for translating the
- Handbook and web site into different languages. Manual pages
- are not translated at present.</para>
-
- <para>Documentation source for the &os; web site, Handbook, and
- <acronym>FAQ</acronym> is available in the documentation
- repository at
- <literal>https://svn.FreeBSD.org/doc/</literal>.</para>
-
- <para>Source for manual pages is available in a separate
- source repository located at
- <literal>https://svn.FreeBSD.org/base/</literal>.</para>
-
- <para>Documentation commit messages are visible with
- <command>svn log</command>. Commit messages are also
- archived at <uri xlink:href="&a.svn-doc-all.url;">&a.svn-doc-all.url;</uri>.</para>
-
- <para>Web frontends to both of these repositories are available at <link
- xlink:href="https://svnweb.FreeBSD.org/doc/"></link> and <link
- xlink:href="https://svnweb.FreeBSD.org/base/"></link>.</para>
-
- <para>Many people have written tutorials or how-to articles about
- &os;. Some are stored as part of the <acronym>FDP</acronym>
- files. In other cases, the author has decided to keep the
- documentation separate. The <acronym>FDP</acronym> endeavors to
- provide links to as much of this external documentation as
- possible.</para>
- </sect1>
-
- <sect1 xml:id="overview-quick-start">
- <title>Quick Start</title>
-
- <para>Some preparatory steps must be taken before editing the &os;
- documentation. First, subscribe to the &a.doc;. Some team
- members also interact on the <literal>#bsddocs</literal>
- <acronym>IRC</acronym> channel on
- <link xlink:href="http://www.efnet.org/">EFnet</link>. These people
- can help with questions or problems involving the
- documentation.</para>
-
- <procedure>
- <step>
- <para>Install the
- <package>textproc/docproj</package>
- package or port. This meta-port installs all of the
- software needed to edit and build &os; documentation.</para>
- </step>
-
- <step>
- <para>Install a local working copy of the documentation from
- the &os; repository in
- <filename>~/doc</filename> (see
- <xref linkend="working-copy"/>).</para>
-
- <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
- </step>
-
- <step>
- <para>Configure the text editor:</para>
-
- <itemizedlist>
- <listitem>
- <para>Word wrap set to 70 characters.</para>
- </listitem>
-
- <listitem>
- <para>Tab stops set to 2.</para>
- </listitem>
-
- <listitem>
- <para>Replace each group of 8 leading spaces with a
- single tab.</para>
- </listitem>
- </itemizedlist>
-
- <para>Specific editor configurations are listed in
- <xref linkend="editor-config"/>.</para>
- </step>
-
- <step>
- <para>Update the local working copy:</para>
-
- <screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
- </step>
-
- <step>
- <para>Edit the documentation files that require changes. If a
- file needs major changes, consult the mailing list for
- input.</para>
-
- <para>References to tag and entity usage can be found in
- <xref linkend="xhtml-markup"/> and
- <xref linkend="docbook-markup"/>.</para>
- </step>
-
- <step>
- <para>After editing, check for problems by running:</para>
-
- <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
-
- <para>Review the output and edit the file to fix any problems
- shown, then rerun the command to find any remaining
- problems. Repeat until all of the errors are
- resolved.</para>
- </step>
-
- <step>
- <para><emphasis>Always</emphasis> build-test changes before
- submitting them. Running <userinput>make</userinput> in the
- top-level directory of the documentation being edited will
- generate that documentation in split HTML format. For
- example, to build the English version of the Handbook in
- <acronym>HTML</acronym>, run <command>make</command> in the
- <filename>en_US.ISO8859-1/books/handbook/</filename>
- directory.</para>
- </step>
-
- <step>
- <para>When changes are complete and tested, generate a
- <quote>diff file</quote>:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc</userinput>
-&prompt.user; <userinput>svn diff &gt; <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
-
- <para>Give the diff file a descriptive name. In the example
- above, changes have been made to the
- <filename>bsdinstall</filename> portion of
- the Handbook.</para>
- </step>
-
- <step>
- <para>Submit the diff file using the web-based
- <link xlink:href="&url.base;/support.html#gnats">Problem
- Report</link> system. If using
- the web form, enter a synopsis of
- <emphasis>[patch] <replaceable>short description of
- problem</replaceable></emphasis>. Select the category
- <literal>docs</literal> and the class
- <literal>doc-bug</literal>. In the body of the message,
- enter a short description of the changes and any important
- details about them. Use the
- <guibutton>[&nbsp;Browse...&nbsp;]</guibutton> button to
- attach the diff file.</para>
- </step>
- </procedure>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
deleted file mode 100644
index f797f6b5c7..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
+++ /dev/null
@@ -1,823 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!--
- The FreeBSD Documentation Project
- $FreeBSD$
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="po-translations">
-
- <title><acronym>PO</acronym> Translations</title>
-
- <sect1 xml:id="po-translations-introduction">
- <title>Introduction</title>
-
- <para>The <link
- xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym>
- <application>gettext</application></link> system offers
- translators an easy way to create and maintain translations of
- documents. Translatable strings are extracted from the original
- document into a <acronym>PO</acronym> (Portable Object) file.
- Translated versions of the strings are entered with a separate
- editor. The strings can be used directly or built into a
- complete translated version of the original document.</para>
- </sect1>
-
- <sect1 xml:id="po-translations-quick-start">
- <title>Quick Start</title>
-
- <para>The procedure shown in
- <xref linkend="overview-quick-start"/> is assumed to have
- already been performed, but the <literal>TRANSLATOR</literal>
- option must be enabled in the
- <package role="port">textproc/docproj</package> port. If that
- option was not enabled, display the options menu and enable
- it, then reinstall the port:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
-&prompt.root; <userinput>make config</userinput>
-&prompt.root; <userinput>make clean deinstall install clean</userinput></screen>
-
- <para>This example shows the creation of a Spanish translation of
- the short <link xlink:href="&url.articles.leap-seconds.en;">Leap
- Seconds</link> article.</para>
-
- <procedure xml:id="po-translations-quick-start-install-po-editor">
- <title>Install a <acronym>PO</acronym> Editor</title>
-
- <step>
- <para>A <acronym>PO</acronym> editor is needed to edit
- translation files. This example uses
- <package role="ports">editors/poedit</package>.</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/editors/poedit</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
- </step>
- </procedure>
-
- <procedure xml:id="po-translations-quick-start-initial-setup">
- <title>Initial Setup</title>
-
- <para>When a new translation is first created, the directory
- structure and <filename>Makefile</filename> must be created or
- copied from the English original:</para>
-
- <step>
- <para>Create a directory for the new translation. The
- English article source is in
- <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename>.
- The Spanish translation will go in
- <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename>.
- The path is the same except for the name of the language
- directory.</para>
-
- <screen>&prompt.user; <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
- </step>
-
- <step>
- <para>Copy the <filename>Makefile</filename> from the original
- document into the translation directory:</para>
-
- <screen>&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
- ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
- </step>
- </procedure>
-
- <procedure xml:id="po-translations-quick-start-translation">
- <title>Translation</title>
-
- <para>Translating a document consists of two steps: extracting
- translatable strings from the original document, and entering
- translations for those strings. These steps are repeated
- until the translator feels that enough of the document has
- been translated to produce a usable translated
- document.</para>
-
- <step>
- <para>Extract the translatable strings from the original
- English version into a <acronym>PO</acronym> file:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
-&prompt.user; <userinput>make po</userinput></screen>
- </step>
-
- <step>
- <para>Use a <acronym>PO</acronym> editor to enter translations
- in the <acronym>PO</acronym> file. There are several
- different editors available. <filename>poedit</filename>
- from <package role="port">editors/poedit</package> is shown
- here.</para>
-
- <para>The <acronym>PO</acronym> file name is the
- two-character language code followed by an underline and a
- two-character region code. For Spanish, the file name is
- <filename>es_ES.po</filename>.</para>
-
- <screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen>
- </step>
- </procedure>
-
- <procedure xml:id="po-translations-quick-generating-a-translated-document">
- <title>Generating a Translated Document</title>
-
- <step>
- <para>Generate the translated document:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
-&prompt.user; <userinput>make tran</userinput></screen>
-
- <para>The name of the generated document matches the name
- of the English original, usually
- <filename>article.xml</filename> for articles or
- <filename>book.xml</filename> for books.</para>
- </step>
-
- <step>
- <para>Check the generated file by rendering it to
- <acronym>HTML</acronym> and viewing it with a
- web browser:</para>
-
- <screen>&prompt.user; <userinput>make FORMATS=html</userinput>
-&prompt.user; <userinput>firefox article.html</userinput></screen>
- </step>
- </procedure>
- </sect1>
-
- <sect1 xml:id="po-translations-creating">
- <title>Creating New Translations</title>
-
- <para>The first step to creating a new translated document is
- locating or creating a directory to hold it. &os; puts
- translated documents in a subdirectory named for their
- language and region in the format
- <filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable></filename>.
- <replaceable>lang</replaceable> is a two-character lowercase
- code. It is followed by an underscore character and then the
- two-character uppercase <replaceable>REGION</replaceable>
- code.</para>
-
- <table xml:id="po-translations-language-names" frame="none">
- <title>Language Names</title>
-
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Language</entry>
- <entry>Region</entry>
- <entry>Translated Directory Name</entry>
- <entry><acronym>PO</acronym> File Name</entry>
- <entry>Character Set</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>English</entry>
- <entry>United States</entry>
- <entry><filename>en_US.ISO8859-1</filename></entry>
- <entry><filename>en_US.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Bengali</entry>
- <entry>Bangladesh</entry>
- <entry><filename>bn_BD.UTF-8</filename></entry>
- <entry><filename>bn_BD.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Danish</entry>
- <entry>Denmark</entry>
- <entry><filename>da_DK.ISO8859-1</filename></entry>
- <entry><filename>da_DK.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>German</entry>
- <entry>Germany</entry>
- <entry><filename>de_DE.ISO8859-1</filename></entry>
- <entry><filename>de_DE.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Greek</entry>
- <entry>Greece</entry>
- <entry><filename>el_GR.ISO8859-7</filename></entry>
- <entry><filename>el_GR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-7</entry>
- </row>
-
- <row>
- <entry>Spanish</entry>
- <entry>Spain</entry>
- <entry><filename>es_ES.ISO8859-1</filename></entry>
- <entry><filename>es_ES.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>French</entry>
- <entry>France</entry>
- <entry><filename>fr_FR.ISO8859-1</filename></entry>
- <entry><filename>fr_FR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Hungarian</entry>
- <entry>Hungary</entry>
- <entry><filename>hu_HU.ISO8859-2</filename></entry>
- <entry><filename>hu_HU.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry>Italian</entry>
- <entry>Italy</entry>
- <entry><filename>it_IT.ISO8859-15</filename></entry>
- <entry><filename>it_IT.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-15</entry>
- </row>
-
- <row>
- <entry>Japanese</entry>
- <entry>Japan</entry>
- <entry><filename>ja_JP.eucJP</filename></entry>
- <entry><filename>ja_JP.po</filename></entry>
- <entry><acronym>EUC</acronym> JP</entry>
- </row>
-
- <row>
- <entry>Korean</entry>
- <entry>Korea</entry>
- <entry><filename>ko_KR.UTF-8</filename></entry>
- <entry><filename>ko_KR.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Mongolian</entry>
- <entry>Mongolia</entry>
- <entry><filename>mn_MN.UTF-8</filename></entry>
- <entry><filename>mn_MN.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Dutch</entry>
- <entry>Netherlands</entry>
- <entry><filename>nl_NL.ISO8859-1</filename></entry>
- <entry><filename>nl_NL.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Norwegian</entry>
- <entry>Norway</entry>
- <entry><filename>no_NO.ISO8859-1</filename></entry>
- <entry><filename>no_NO.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Polish</entry>
- <entry>Poland</entry>
- <entry><filename>pl_PL.ISO8859-2</filename></entry>
- <entry><filename>pl_PL.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry>Portuguese</entry>
- <entry>Brazil</entry>
- <entry><filename>pt_BR.ISO8859-1</filename></entry>
- <entry><filename>pt_BR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Russian</entry>
- <entry>Russia</entry>
- <entry><filename>ru_RU.KOI8-R</filename></entry>
- <entry><filename>ru_RU.po</filename></entry>
- <entry><acronym>KOI</acronym>8-R</entry>
- </row>
-
- <row>
- <entry>Serbian</entry>
- <entry>Serbia</entry>
- <entry><filename>sr_YU.ISO8859-2</filename></entry>
- <entry><filename>sr_YU.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry>Turkish</entry>
- <entry>Turkey</entry>
- <entry><filename>tr_TR.ISO8859-9</filename></entry>
- <entry><filename>tr_TR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-9</entry>
- </row>
-
- <row>
- <entry>Chinese</entry>
- <entry>China</entry>
- <entry><filename>zh_CN.UTF-8</filename></entry>
- <entry><filename>zh_CN.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Chinese</entry>
- <entry>Taiwan</entry>
- <entry><filename>zh_TW.UTF-8</filename></entry>
- <entry><filename>zh_TW.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The translations are in subdirectories of the main
- documentation directory, here assumed to be
- <filename>~/doc/</filename> as shown in
- <xref linkend="overview-quick-start"/>. For example, German
- translations are located in
- <filename>~/doc/de_DE.ISO8859-1/</filename>, and French
- translations are in
- <filename>~/doc/fr_FR.ISO8859-1/</filename>.</para>
-
- <para>Each language directory contains separate subdirectories
- named for the type of documents, usually
- <filename>articles/</filename> and
- <filename>books/</filename>.</para>
-
- <para>Combining these directory names gives the complete path to
- an article or book. For example, the French translation of the
- NanoBSD article is in
- <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename>,
- and the Mongolian translation of the Handbook is in
- <filename>~/doc/mn_MN.UTF-8/books/handbook/</filename>.</para>
-
- <para>A new language directory must be created when translating
- a document to a new language. If the language directory already
- exists, only a subdirectory in the
- <filename>articles/</filename> or <filename>books/</filename>
- directory is needed.</para>
-
- <para>&os; documentation builds are controlled by a
- <filename>Makefile</filename> in the same directory. With
- simple articles, the <filename>Makefile</filename> can often
- just be copied verbatim from the original English directory.
- The translation process combines multiple separate
- <filename>book.xml</filename> and
- <filename>chapter.xml</filename> files in books into a single
- file, so the <filename>Makefile</filename> for book translations
- must be copied and modified.</para>
-
- <example xml:id="po-translations-creating-example">
- <title>Creating a Spanish Translation of the Porter's
- Handbook</title>
-
- <para>Create a new Spanish translation of the
- <link xlink:href="&url.books.porters-handbook.en;">Porter's
- Handbook</link>. The original is a book in
- <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename>.</para>
-
- <procedure>
- <step>
- <para>The Spanish language books directory
- <filename>~/doc/es_ES.ISO8859-1/books/</filename> already
- exists, so only a new subdirectory for the Porter's
- Handbook is needed:</para>
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>
-&prompt.user; <userinput>svn mkdir porters-handbook</userinput>
-A porters-handbook</screen>
- </step>
-
- <step>
- <para>Copy the <filename>Makefile</filename> from the
- original book:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>
-A Makefile</screen>
-
- <para>Modify the contents of the
- <filename>Makefile</filename> to only expect a single
- <filename>book.xml</filename>:</para>
-
- <programlisting>#
-# $FreeBSD$
-#
-# Build the FreeBSD Porter's Handbook.
-#
-
-MAINTAINER=doc@FreeBSD.org
-
-DOC?= book
-
-FORMATS?= html-split
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-# XML content
-SRCS= book.xml
-
-# Images from the cross-document image library
-IMAGES_LIB+= callouts/1.png
-IMAGES_LIB+= callouts/2.png
-IMAGES_LIB+= callouts/3.png
-IMAGES_LIB+= callouts/4.png
-IMAGES_LIB+= callouts/5.png
-IMAGES_LIB+= callouts/6.png
-IMAGES_LIB+= callouts/7.png
-IMAGES_LIB+= callouts/8.png
-IMAGES_LIB+= callouts/9.png
-IMAGES_LIB+= callouts/10.png
-IMAGES_LIB+= callouts/11.png
-IMAGES_LIB+= callouts/12.png
-IMAGES_LIB+= callouts/13.png
-IMAGES_LIB+= callouts/14.png
-IMAGES_LIB+= callouts/15.png
-IMAGES_LIB+= callouts/16.png
-IMAGES_LIB+= callouts/17.png
-IMAGES_LIB+= callouts/18.png
-IMAGES_LIB+= callouts/19.png
-IMAGES_LIB+= callouts/20.png
-IMAGES_LIB+= callouts/21.png
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-SYMLINKS= ${DESTDIR} index.html handbook.html
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
-
- <para>Now the document structure is ready for the translator
- to begin translating with
- <command>make po</command>.</para>
- </step>
- </procedure>
- </example>
-
- <example xml:id="po-translations-creating-example-french">
- <title>Creating a French Translation of the
- <acronym>PGP</acronym> Keys Article</title>
-
- <para>Create a new French translation of the
- <link xlink:href="&url.articles.pgpkeys;"><acronym>PGP</acronym>
- Keys article</link>. The original is an article in
- <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename>.</para>
-
- <procedure>
- <step>
- <para>The French language article directory
- <filename>~/doc/fr_FR.ISO8859-1/articles/</filename>
- already exists, so only a new subdirectory for the
- <acronym>PGP</acronym> Keys article is needed:</para>
- <screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>
-&prompt.user; <userinput>svn mkdir pgpkeys</userinput>
-A pgpkeys</screen>
- </step>
-
- <step>
- <para>Copy the <filename>Makefile</filename> from the
- original article:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>
-&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>
-A Makefile</screen>
-
- <para>Check the contents of the
- <filename>Makefile</filename>. Because this is a simple
- article, in this case the <filename>Makefile</filename>
- can be used unchanged. The <literal>$&os;...$</literal>
- version string on the third line will be replaced by the
- version control system when this file is committed.</para>
-
- <programlisting>#
-# $FreeBSD$
-#
-# Article: PGP Keys
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-# To build with just key fingerprints, set FINGERPRINTS_ONLY.
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
-
- <para>With the document structure complete, the
- <acronym>PO</acronym> file can be created with
- <command>make po</command>.</para>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-translating">
- <title>Translating</title>
-
- <para>The <application>gettext</application> system greatly
- reduces the number of things that must be tracked by a
- translator. Strings to be translated are extracted from the
- original document into a <acronym>PO</acronym> file. Then a
- <acronym>PO</acronym> editor is used to enter the translated
- versions of each string.</para>
-
- <para>The &os; <acronym>PO</acronym> translation system does not
- overwrite <acronym>PO</acronym> files, so the extraction step
- can be run at any time to update the <acronym>PO</acronym>
- file.</para>
-
- <para>A <acronym>PO</acronym> editor is used to edit the file.
- <package role="port">editors/poedit</package> is shown in
- these examples because it is simple and has minimal
- requirements. Other <acronym>PO</acronym> editors offer
- features to make the job of translating easier. The Ports
- Collection offers several of these editors, including
- <package role="port">devel/gtranslator</package>.</para>
-
- <para>It is important to preserve the <acronym>PO</acronym> file.
- It contains all of the work that translators have done.</para>
-
- <example xml:id="po-translations-translating-example">
- <title>Translating the Porter's Handbook to Spanish</title>
-
- <para>Enter Spanish translations of the contents of the Porter's
- Handbook.</para>
-
- <procedure>
- <step>
- <para>Change to the Spanish Porter's Handbook directory and
- update the <acronym>PO</acronym> file. The generated
- <acronym>PO</acronym> file is called
- <filename>es_ES.po</filename> as shown in
- <xref linkend="po-translations-language-names"/>.</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-&prompt.user; <userinput>make po</userinput></screen>
- </step>
-
- <step>
- <para>Enter translations using a <acronym>PO</acronym>
- editor:</para>
-
- <screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-tips">
- <title>Tips for Translators</title>
-
- <sect2 xml:id="po-translations-tips-xmltags">
- <title>Preserving <acronym>XML</acronym> Tags</title>
-
- <para>Preserve <acronym>XML</acronym> tags that are shown in
- the English original.</para>
-
- <example>
- <title>Preserving <acronym>XML</acronym> Tags</title>
-
- <para>English original:</para>
-
- <programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting>
-
- <para>Spanish translation:</para>
-
- <programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-spaces">
- <title>Preserving Spaces</title>
-
- <para>Preserve existing spaces at the beginning and end of
- strings to be translated. The translated version must have
- these spaces also.</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-verbatim">
- <title>Verbatim Tags</title>
-
- <para>The contents of some tags should be copied verbatim, not
- translated:</para>
-
- <itemizedlist xml:id="po-translations-tips-verbatim-list">
- <listitem>
- <para><tag class="starttag">citerefentry</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">command</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">filename</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">literal</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">manvolnum</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">orgname</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">package</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">programlisting</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">prompt</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">refentrytitle</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">screen</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">userinput</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">varname</tag></para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <!--
- <sect2 xml:id="po-translations-tips-makefile">
- <title>Modifying the <filename>Makefile</filename></title>
-
- <para>What needs to be changed in the
- <filename>Makefile</filename>?</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-locale">
- <title>Setting Locales for Editing</title>
-
- <para>Locale settings so the <acronym>PO</acronym> editor works
- correctly?</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-poeditors">
- <title>Settings for Specific <acronym>PO</acronym>
- Editors</title>
-
- <para>Per bcr: turn off "intelligent quotes" in
- Mac poedit.</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-tm">
- <title>Using Translation Memory</title>
-
- <para>Using translation memory. Saving, updating, sharing
- with other members of a translation team.</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-submitting">
- <title>Submitting Translations</title>
-
- <para>Submitting translations as diffs, committing
- <acronym>PO</acronym> files.</para>
- </sect2>
- -->
- </sect1>
-
- <sect1 xml:id="po-translations-building">
- <title>Building a Translated Document</title>
-
- <para>A translated version of the original document can be created
- at any time. Any untranslated portions of the original will be
- included in English in the resulting document. Most
- <acronym>PO</acronym> editors have an indicator that shows how
- much of the translation has been completed. This makes it easy
- for the translator to see when enough strings have been
- translated to make building the final document
- worthwhile.</para>
-
- <example xml:id="po-translations-building-example">
- <title>Building the Spanish Porter's Handbook</title>
-
- <para>Build and preview the Spanish version of the Porter's
- Handbook that was created in an earlier example.</para>
-
- <procedure>
- <step>
- <para>Build the translated document. Because the original
- is a book, the generated document is
- <filename>book.xml</filename>.</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-&prompt.user; <userinput>make tran</userinput></screen>
- </step>
-
- <step>
- <para>Render the translated <filename>book.xml</filename> to
- <acronym>HTML</acronym> and view it with
- <application>Firefox</application>. This is the
- same procedure used with the English version of the
- documents, and other <varname>FORMATS</varname> can
- be used here in the same way. See <xref
- linkend="doc-build-rendering-common-formats"/>.</para>
-
- <screen>&prompt.user; <userinput>make FORMATS=html</userinput>
-&prompt.user; <userinput>firefox book.html</userinput></screen>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-submitting">
- <title>Submitting the New Translation</title>
-
- <para>Prepare the new translation files for submission. This
- example shows a new Spanish translation of the NanoBSD
- article in
- <filename>~/doc/es_ES.ISO8859-1/articles/nanobsd</filename>.</para>
-
- <procedure>
- <step>
- <para>The <acronym>PO</acronym> file must contain a &os;
- version string comment on the first line:</para>
-
- <programlisting>#&dollar;FreeBSD&dollar;</programlisting>
- </step>
-
- <step>
- <para>The <filename>Makefile</filename>, the
- <acronym>PO</acronym> file, and the generated
- <acronym>XML</acronym> translation must all be added to
- version control:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>
-&prompt.user; <userinput>ls</userinput>
-Makefile article.xml es_ES.po
-&prompt.user; <userinput>svn add Makefile article.xml es_ES.po</userinput>
-A Makefile
-A article.xml
-A es_ES.po</screen>
- </step>
-
- <step>
- <para>These files must also have the
- <application>Subversion</application>
- <literal>svn:keywords</literal> property set to
- <literal>FreeBSD=%H</literal>:</para>
-
- <screen>&prompt.user; <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput>
-property 'svn:keywords' set on 'Makefile'
-property 'svn:keywords' set on 'article.xml'
-property 'svn:keywords' set on 'es_ES.po'</screen>
- </step>
-
- <step>
- <para>A diff of these new files is created from the
- <filename>~/doc/</filename> base directory so the full path
- is shown with the filenames. This helps committers identify
- the target language directory.</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc</userinput>
-<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput></screen>
-
- <para>The diff file is now ready for attachment to a
- <link
- xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">documentation
- bug report</link> or <link
- xlink:href="https://reviews.freebsd.org/">code
- review</link>.</para>
- </step>
- </procedure>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml
deleted file mode 100644
index 03c12c8545..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml
+++ /dev/null
@@ -1,171 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<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 (can be
- installed from <package>editors/psgml</package>).
- 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 <function>sgml-insert-element</function>. You will
- be prompted for the name of the element to insert at the
- current point. You can use the <keycap>Tab</keycap> 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 <function>sgml-change-element-name</function>.
- 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 <function>sgml-tag-region</function>. Select some
- text (move to start of text, <command>C-space</command>,
- move to end of text, <command>C-space</command>) 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 <function>sgml-untag-element</function>. 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 <function>sgml-fill-element</function>. 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 <function>sgml-edit-attributes</function>. Opens a
- second buffer containing a list of all the attributes for
- the closest enclosing element, and their current values.
- Use <keycap>Tab</keycap> 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 <function>sgml-validate</function>. 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 <function>sgml-insert-end-tag</function>. 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/nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml
deleted file mode 100644
index 62764fb0e1..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml
+++ /dev/null
@@ -1,108 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="see-also">
- <title>See Also</title>
-
- <para>This document is deliberately not an exhaustive discussion of
- XML, 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-xml">
- <title>XML</title>
-
- <itemizedlist>
- <listitem>
- <para><link xlink:href="http://www.w3.org/XML/">W3C's XML page
- SGML/XML web page</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>
-
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml
deleted file mode 100644
index a5fb852efd..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml
+++ /dev/null
@@ -1,305 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">
- <title>Documentation Directory Structure</title>
-
- <para>Files and directories in the
- <filename>doc/</filename> tree follow a
- structure meant to:</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 must accommodate
- documents in many different languages and encodings. It is
- important that the documentation tree structure 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>
-
- <informaltable pgwide="1" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Directory</entry>
- <entry>Usage</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry valign="top">
- <filename>share</filename></entry>
-
- <entry>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 <acronym>XML</acronym> support files
- (such as the &os; extended DocBook
- <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry>
- </row>
-
- <row>
- <entry valign="top">
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
-
- <entry>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 when a
- translation team wants to provide documentation in the
- same language but in more than one encoding. This also
- avoids problems that might be caused by a future switch
- to Unicode.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-
- <sect1 xml:id="structure-locale">
- <title>The
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</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>
-
- <informaltable pgwide="1" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Directory</entry>
- <entry>Usage</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry valign="top">
- <filename>articles</filename></entry>
-
- <entry>Documentation marked up as a DocBook
- <tag>article</tag> (or equivalent). Reasonably
- short, and broken up into sections. Normally only
- available as one <acronym>XHTML</acronym> file.</entry>
- </row>
-
- <row>
- <entry valign="top"><filename>books</filename></entry>
-
- <entry>Documentation marked up as a DocBook
- <tag>book</tag> (or equivalent). Book length,
- and broken up into chapters. Normally available as both
- one large <acronym>XHTML</acronym> file (for people with
- fast connections, or who want to print it easily from a
- browser) and as a collection of linked, smaller
- files.</entry>
- </row>
-
- <row>
- <entry valign="top">
- <filename>man</filename></entry>
-
- <entry>For translations of the system manual pages. This
- directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename>
- directories, corresponding to the sections that have
- been translated.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
- directory will have all of these subdirectories. 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 in DocBook <acronym>XML</acronym>
- using the &os; DocBook extended <acronym>DTD</acronym>.</para>
-
- <para>The Handbook is organized as a DocBook
- <tag>book</tag>. The book is divided into
- <tag>part</tag>s, each of which contains 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. Post questions about Handbook organization to the
- &a.doc;.</para>
- </note>
-
- <sect4>
- <title><filename>Makefile</filename></title>
-
- <para>The <filename>Makefile</filename> defines some
- variables that affect how the <acronym>XML</acronym>
- 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>,
- 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="xml-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="xml-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="xml-primer-general-entities">general
- entities</link> that are used throughout the rest of the
- Handbook.</para>
- </sect4>
-
- <sect4>
- <title><filename role="directory"><replaceable>directory</replaceable>/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><tag class="starttag">chapter id="kernelconfig"</tag>
-...
-<tag class="endtag">chapter</tag></programlisting>
-
- <para>Then it will be called
- <filename>chapter.xml</filename> in the
- <filename>kernelconfig</filename> directory. In general,
- the entire contents of the chapter are in this one
- file.</para>
-
- <para>When the <acronym>XHTML</acronym> version of the
- Handbook is produced, this will yield
- <filename>kernelconfig.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. Now, it is possible
- to include images in each chapter. Images for each
- Handbook chapter are stored within <filename>share/images/books/handbook</filename>.
- The localized version of these images should be
- placed in the same directory as the <acronym>XML</acronym>
- sources for each chapter. Namespace collisions are
- 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>Do not name chapters or directories after
- their ordering within the Handbook. This ordering can
- change as the content within the Handbook is
- reorganized. Reorganization should be possible without
- renaming files, unless entire chapters are being
- promoted or demoted within the hierarchy.</para>
- </important>
-
- <para>The <filename>chapter.xml</filename> files are not
- complete <acronym>XML</acronym> documents that can be
- built individually. They can only be built
- as parts of the whole Handbook.</para>
- </sect4>
- </sect3>
- </sect2>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml
deleted file mode 100644
index d8d48f16ae..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml
+++ /dev/null
@@ -1,75 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="stylesheets">
- <title>Style Sheets</title>
-
- <para><acronym>XML</acronym> is concerned with content, and says
- nothing about how that content should be presented to the reader
- or rendered on paper. Multiple <emphasis>style sheet</emphasis>
- languages have been developed to describe visual layout, including
- Extensible Stylesheet Language Transformation
- (<acronym>XSLT</acronym>), Document Style Semantics and
- Specification Language (<acronym>DSSSL</acronym>), and Cascading
- Style Sheets (<acronym>CSS</acronym>).</para>
-
- <para>The <acronym>FDP</acronym> documents use
- <acronym>XSLT</acronym> stylesheets to transform DocBook into
- <acronym>XHTML</acronym>, and then <acronym>CSS</acronym>
- formatting is applied to the <acronym>XHTML</acronym> pages.
- Printable output is currently rendered with legacy
- <acronym>DSSSL</acronym> stylesheets, but this will probably
- change in the future.</para>
-
- <sect1 xml:id="stylesheets-css">
- <title><acronym>CSS</acronym></title>
-
- <para>Cascading Style Sheets (<acronym>CSS</acronym>) are a
- mechanism for attaching style information (font, weight, size,
- color, and so forth) to elements in an <acronym>XHTML</acronym>
- document without abusing <acronym>XHTML</acronym> to do
- so.</para>
-
- <sect2>
- <title>The DocBook Documents</title>
-
- <para>The &os; <acronym>XSLT</acronym> and
- <acronym>DSSSL</acronym> stylesheets refer to
- <filename>docbook.css</filename>, which is expected to be
- present in the same directory as the <acronym>XHTML</acronym>
- files. The project-wide <acronym>CSS</acronym> file is copied
- from <filename>doc/share/misc/docbook.css</filename> when
- documents are converted to <acronym>XHTML</acronym>, and is
- installed automatically.</para>
- </sect2>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml
deleted file mode 100644
index b5c617e7d3..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml
+++ /dev/null
@@ -1,200 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
- <title>The Website</title>
-
- <para>The &os; web site is part of the &os; documents. Files for
- the web site are stored in the
- <filename>en_US.ISO8859-1/htdocs</filename> subdirectory of the
- document tree directory, <filename>~/doc</filename> in this
- example.</para>
-
- <sect1 xml:id="the-website-env">
- <title>Environment Variables</title>
-
- <para>Several environment variables control which parts of the the
- web site are built or installed, and to which
- directories.</para>
-
- <tip>
- <para>The web build system uses &man.make.1;, and considers
- variables to be set when they have been defined, even if they
- are empty. The examples here show the recommended ways of
- defining and using these variables. Setting or defining these
- variables with other values or methods might lead to
- unexpected surprises.</para>
- </tip>
-
- <variablelist>
- <varlistentry xml:id="the-website-env-destdir">
- <term><varname>DESTDIR</varname></term>
-
- <listitem>
- <para>DESTDIR specifies the path where the web site files
- are to be installed.</para>
-
- <para>This variable is best set with &man.env.1; or the user
- shell's method of setting environment variables,
- <command>setenv</command> for &man.csh.1; or
- <command>export</command> for &man.sh.1;.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry xml:id="the-website-env-englishonly">
- <term><varname>ENGLISH_ONLY</varname></term>
-
- <listitem>
- <para>Default: undefined. Build and include all
- translations.</para>
-
- <para><userinput>ENGLISH_ONLY=yes</userinput>: use only
- the English documents and ignore all translations.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry xml:id="the-website-env-webonly">
- <term><varname>WEB_ONLY</varname></term>
-
- <listitem>
- <para>Default: undefined. Build both the web site
- and all the books and articles.</para>
-
- <para><userinput>WEB_ONLY=yes</userinput>: build or install
- only <acronym>HTML</acronym> pages from the
- <filename>en_US.ISO8859-1/htdocs</filename> directory.
- Other directories and documents, including books and
- articles, will be ignored.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry xml:id="the-website-env-weblang">
- <term><varname>WEB_LANG</varname></term>
-
- <listitem>
- <para>Default: undefined. Build and include all the
- available languages on the web site.</para>
-
- <para>Set to a space-separated list of languages to be
- included in the build
- or install. The formats are the same as the directory
- names in the document root directory. For example, to
- include the German and French documents:</para>
-
- <screen><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
- and <varname>ENGLISH_ONLY</varname> are &man.make.1; variables
- and can be set in <filename>/etc/make.conf</filename>,
- <filename>Makefile.inc</filename>, as environment variables on
- the command line, or in dot files.</para>
- </sect1>
-
- <sect1 xml:id="the-website-build">
- <title>Building and Installing the Web Pages</title>
-
- <para>Having obtained the documentation and web site source files,
- the web site can be built.</para>
-
- <para>An actual installation of the web site is run as the <systemitem class="username">root</systemitem>
- user because the permissions on the web server directory will
- not allow files to be installed by an unprivileged user.
- For testing, it can be useful to install the files as a normal
- user to a temporary directory.</para>
-
- <para>In these examples, the web site files are built by user
- <systemitem class="username">jru</systemitem> in their home
- directory, <filename>~/doc</filename>, with a full path of
- <filename>/usr/home/jru/doc</filename>.</para>
-
- <tip>
- <para>The web site build uses the <filename>INDEX</filename>
- from the Ports Collection and might fail if that file or
- <filename>/usr/ports</filename> is not
- present. The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
- Collection</link>.</para>
- </tip>
-
- <example xml:id="the-website-examples-build">
- <title>Build the Full Web Site and All Documents</title>
-
- <para>Build the web site and all documents. The resulting files
- are left in the document tree:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
-&prompt.user; <userinput>make all</userinput></screen>
- </example>
-
- <example xml:id="the-website-examples-buildinstall-englishonly">
- <title>Build Only the Web Site in English</title>
-
- <para>Build the web site only, in English, as user
- <systemitem class="username">jru</systemitem>, and install
- the resulting files into <filename>/tmp/www</filename> for
- testing:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
-&prompt.user; <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen>
- </example>
-
- <example xml:id="the-website-examples-buildinstall">
- <title>Build and Install the Web Site</title>
-
- <para>Build the web site and all documents as user
- <systemitem class="username">jru</systemitem>. Install the
- resulting files as
- <systemitem class="username">root</systemitem> into the
- default directory,
- <filename>/root/public_html</filename>:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
-&prompt.user; <userinput>make all</userinput>
-&prompt.user; <userinput>su -</userinput>
-Password:
-&prompt.root; <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </example>
-
- <para>The install process does not delete any old or outdated
- files that existed previously in the same directory. If a new
- copy of the site is built and installed every day, this command
- will find and delete all files that have not been updated in
- three days:</para>
-
- <screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml
deleted file mode 100644
index f911e934ab..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml
+++ /dev/null
@@ -1,141 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools">
- <title>Tools</title>
-
- <para>Several software tools are used to manage the FreeBSD
- documentation and render it to different output formats. Some of
- these tools are required and must be installed before working
- through the examples in the following chapters. Some are
- optional, adding capabilities or making the job of creating
- documentation less demanding.</para>
-
- <sect1 xml:id="tools-required">
- <title>Required Tools</title>
-
- <para>Install
- <package>textproc/docproj</package> from the
- Ports Collection. This <emphasis>meta-port</emphasis> installs
- all the applications required to do useful work with the &os;
- documentation. Some further notes on particular components are
- given below.</para>
-
- <sect2>
- <title><acronym>DTD</acronym>s and
- <acronym>Entities</acronym></title>
-
- <para>&os; documentation uses several Document Type Definitions
- (<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym>
- entities. These are all installed by the
- <package>textproc/docproj</package>
- port.</para>
-
- <variablelist>
- <varlistentry>
- <term><acronym>XHTML</acronym> <acronym>DTD</acronym>
- (<package>textproc/xhtml</package>)</term>
-
- <listitem>
- <para><acronym>XHTML</acronym> is the markup language of
- choice for the World Wide Web, and is used throughout
- the &os; web site.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term>
-
- <listitem>
- <para>DocBook is designed for marking up technical
- documentation. Most of the &os; documentation is
- written in DocBook.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ISO 8879 entities
- (<package>textproc/iso8879</package>)</term>
-
- <listitem>
- <para>Character entities from the ISO 8879:1986 standard
- used by many <acronym>DTD</acronym>s. Includes named
- mathematical symbols, additional characters in the Latin
- character set (accents, diacriticals, and so on), and
- Greek symbols.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- </sect1>
-
- <sect1 xml:id="tools-optional">
- <title>Optional Tools</title>
-
- <para>These applications are not required, but can make working on
- the documentation easier or add capabilities.</para>
-
- <sect2>
- <title>Software</title>
-
- <variablelist>
-
- <varlistentry>
- <term><application>Vim</application>
- (<package>editors/vim</package>)</term>
-
- <listitem>
- <para>A popular editor for working with
- <acronym>XML</acronym> and derived documents, like
- DocBook <acronym>XML</acronym>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Emacs</application> or
- <application>XEmacs</application>
- (<package>editors/emacs</package> or
- <package>editors/xemacs</package>)</term>
-
- <listitem>
- <para>Both of these editors include a special mode for
- editing documents marked up according to an
- <acronym>XML</acronym> <acronym>DTD</acronym>. This
- mode includes commands to reduce the amount of typing
- needed, and help reduce the possibility of
- errors.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml
deleted file mode 100644
index 51f93618dc..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml
+++ /dev/null
@@ -1,473 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="translations">
- <title>Translations</title>
-
- <para>This is the FAQ for people translating the FreeBSD
- documentation (FAQ, Handbook, tutorials, manual pages, and others)
- to different languages.</para>
-
- <para>It is <emphasis>very</emphasis> heavily based on the
- translation FAQ from the FreeBSD German Documentation Project,
- originally written by Frank Gr&uuml;nder
- <email>elwood@mc5sys.in-berlin.de</email> and translated back to
- English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
-
- <para>The FAQ is maintained by the &a.doceng;.</para>
-
- <qandaset>
- <qandaentry>
- <question>
- <para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
- mean?</para>
- </question>
-
- <answer>
- <para><phrase>i18n</phrase> means
- <phrase>internationalization</phrase> and
- <phrase>l10n</phrase> means <phrase>localization</phrase>.
- They are just a convenient shorthand.</para>
-
- <para><phrase>i18n</phrase> can be read as <quote>i</quote>
- followed by 18 letters, followed by <quote>n</quote>.
- Similarly, <phrase>l10n</phrase> is <quote>l</quote>
- followed by 10 letters, followed by <quote>n</quote>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Is there a mailing list for translators?</para>
- </question>
-
- <answer>
- <para>Yes. Different translation groups have their own
- mailing lists. The <link xlink:href="http://www.freebsd.org/docproj/translations.html">list
- of translation projects</link> has more information about
- the mailing lists and web sites run by each translation
- project. In addition there is
- <email>freebsd-translators@freebsd.org</email> for general
- translation discussion.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Are more translators needed?</para>
- </question>
-
- <answer>
- <para>Yes. The more people work on translation the faster it
- gets done, and the faster changes to the English
- documentation are mirrored in the translated
- documents.</para>
-
- <para>You do not have to be a professional translator to be
- able to help.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What languages do I need to know?</para>
- </question>
-
- <answer>
- <para>Ideally, you will have a good knowledge of written
- English, and obviously you will need to be fluent in the
- language you are translating to.</para>
-
- <para>English is not strictly necessary. For example, you
- could do a Hungarian translation of the FAQ from the Spanish
- translation.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What software do I need to know?</para>
- </question>
-
- <answer>
- <para>It is strongly recommended that you maintain a local
- copy of the FreeBSD Subversion repository (at least the
- documentation part). This can be done by running:</para>
-
- <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen>
-
- <para><link xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link>
- is a public <literal>SVN</literal> server.
- Verify the server
- certificate from the list of <link xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
- mirror sites</link>.</para>
-
- <note>
- <para>This will require the <package>devel/subversion</package> package to
- be installed.</para>
- </note>
-
- <para>You should be comfortable using
- <application>svn</application>. This will allow you to see
- what has changed between different versions of the files
- that make up the documentation.</para>
-
- <para>For example, to view the differences between revisions
- <literal>r33733</literal> and <literal>r33734</literal> of
- <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>,
- run:</para>
-
- <screen>&prompt.user; <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How do I find out who else might be translating to the
- same language?</para>
- </question>
-
- <answer>
- <para>The <link xlink:href="http://www.FreeBSD.org/docproj/translations.html">Documentation
- Project translations page</link> lists the translation
- efforts that are currently known about. If others are
- already working on translating documentation to your
- language, please do not duplicate their efforts. Instead,
- contact them to see how you can help.</para>
-
- <para>If no one is listed on that page as translating for your
- language, then send a message to the &a.doc; in case someone
- else is thinking of doing a translation, but has not
- announced it yet.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>No one else is translating to my language. What do I
- do?</para>
- </question>
-
- <answer>
- <para>Congratulations, you have just started the
- <quote>FreeBSD <replaceable>your-language-here</replaceable>
- Documentation Translation Project</quote>. Welcome
- aboard.</para>
-
- <para>First, decide whether or not you have got the time to
- spare. Since you are the only person working on your
- language at the moment it is going to be your responsibility
- to publicize your work and coordinate any volunteers that
- might want to help you.</para>
-
- <para>Write an email to the Documentation Project mailing
- list, announcing that you are going to translate the
- documentation, so the Documentation Project translations
- page can be maintained.</para>
-
- <para>If there is already someone in your country providing
- FreeBSD mirroring services you should contact them and ask
- if you can have some webspace for your project, and possibly
- an email address or mailing list services.</para>
-
- <para>Then pick a document and start translating. It is best
- to start with something fairly small&mdash;either the FAQ,
- or one of the tutorials.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>I have translated some documentation, where do I send
- it?</para>
- </question>
-
- <answer>
- <para>That depends. If you are already working with a
- translation team (such as the Japanese team, or the German
- team) then they will have their own procedures for handling
- submitted documentation, and these will be outlined on their
- web pages.</para>
-
- <para>If you are the only person working on a particular
- language (or you are responsible for a translation project
- and want to submit your changes back to the FreeBSD project)
- then you should send your translation to the FreeBSD project
- (see the next question).</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>I am the only person working on translating to this
- language, how do I submit my translation?</para>
-
- <para>or</para>
-
- <para>We are a translation team, and want to submit
- documentation that our members have translated for
- us.</para>
- </question>
-
- <answer>
- <para>First, make sure your translation is organized properly.
- This means that it should drop into the existing
- documentation tree and build straight away.</para>
-
- <para>Currently, the FreeBSD documentation is stored in a top
- level directory called <filename>head/</filename>.
- Directories below this are named according to the language
- code they are written in, as defined in ISO639
- (<filename>/usr/share/misc/iso639</filename> on a version of
- FreeBSD newer than 20th January 1999).</para>
-
- <para>If your language can be encoded in different ways (for
- example, Chinese) then there should be directories below
- this, one for each encoding format you have provided.</para>
-
- <para>Finally, you should have directories for each
- document.</para>
-
- <para>For example, a hypothetical Swedish translation might
- look like:</para>
-
- <programlisting>head/
- sv_SE.ISO8859-1/
- Makefile
- htdocs/
- docproj/
- books/
- faq/
- Makefile
- book.xml</programlisting>
-
- <para><literal>sv_SE.ISO8859-1</literal> is the name of the
- translation, in
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
- form. Note the two Makefiles, which will be used to build
- the documentation.</para>
-
- <para>Use &man.tar.1; and &man.gzip.1; to compress up your
- documentation, and send it to the project.</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>Put <filename>swedish-docs.tar.gz</filename> somewhere.
- If you do not have access to your own webspace (perhaps your
- ISP does not let you have any) then you can email
- &a.doceng;, and arrange to email the files when it is
- convenient.</para>
-
- <para>Either way, you should use Bugzilla to submit a
- report indicating that you have submitted the documentation.
- It would be very helpful if you could get other people to
- look over your translation and double check it first, since
- it is unlikely that the person committing it will be fluent
- in the language.</para>
-
- <para>Someone (probably the Documentation Project Manager,
- currently &a.doceng;) will then take your translation and
- confirm that it builds. In particular, the following things
- will be looked at:</para>
-
- <orderedlist>
- <listitem>
- <para>Do all your files use RCS strings (such as
- "ID")?</para>
- </listitem>
-
- <listitem>
- <para>Does <command>make all</command> in the
- <filename>sv_SE.ISO8859-1</filename> directory work
- correctly?</para>
- </listitem>
-
- <listitem>
- <para>Does <command>make install</command> work
- correctly?</para>
- </listitem>
- </orderedlist>
-
- <para>If there are any problems then whoever is looking at the
- submission will get back to you to work them out.</para>
-
- <para>If there are no problems your translation will be
- committed as soon as possible.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Can I include language or country specific text in my
- translation?</para>
- </question>
-
- <answer>
- <para>We would prefer that you did not.</para>
-
- <para>For example, suppose that you are translating the
- Handbook to Korean, and want to include a section about
- retailers in Korea in your Handbook.</para>
-
- <para>There is no real reason why that information should not
- be in the English (or German, or Spanish, or Japanese, or
- &hellip;) versions as well. It is feasible that an English
- speaker in Korea might try to pick up a copy of FreeBSD
- whilst over there. It also helps increase FreeBSD's
- perceived presence around the globe, which is not a bad
- thing.</para>
-
- <para>If you have country specific information, please submit
- it as a change to the English Handbook (using
- Bugzilla) and then translate the change back to your
- language in the translated Handbook.</para>
-
- <para>Thanks.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How should language specific characters be
- included?</para>
- </question>
-
- <answer>
- <para>Non-ASCII characters in the documentation should be
- included using SGML entities.</para>
-
- <para>Briefly, these look like an ampersand (&amp;), the name
- of the entity, and a semi-colon (;).</para>
-
- <para>The entity names are defined in ISO8879, which is in the
- ports tree as <package>textproc/iso8879</package>.</para>
-
- <para>A few examples include:</para>
-
- <segmentedlist>
- <segtitle>Entity</segtitle>
-
- <segtitle>Appearance</segtitle>
-
- <segtitle>Description</segtitle>
-
- <seglistitem>
- <seg>&amp;eacute;</seg>
- <seg>&eacute;</seg>
- <seg>Small <quote>e</quote> with an acute accent</seg>
- </seglistitem>
-
- <seglistitem>
- <seg>&amp;Eacute;</seg>
- <seg>&Eacute;</seg>
- <seg>Large <quote>E</quote> with an acute accent</seg>
- </seglistitem>
-
- <seglistitem>
- <seg>&amp;uuml;</seg>
- <seg>&uuml;</seg>
- <seg>Small <quote>u</quote> with an umlaut</seg>
- </seglistitem>
- </segmentedlist>
-
- <para>After you have installed the iso8879 port, the files in
- <filename>/usr/local/share/xml/iso8879</filename> contain
- the complete list.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Addressing the reader</para>
- </question>
-
- <answer>
- <para>In the English documents, the reader is addressed as
- <quote>you</quote>, there is no formal/informal distinction
- as there is in some languages.</para>
-
- <para>If you are translating to a language which does
- distinguish, use whichever form is typically used in other
- technical documentation in your language. If in doubt, use
- a mildly polite form.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Do I need to include any additional information in my
- translations?</para>
- </question>
-
- <answer>
- <para>Yes.</para>
-
- <para>The header of the English version of each document will
- look something like this:</para>
-
- <programlisting>&lt;!--
- The FreeBSD Documentation Project
-
- &dollar;FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z &dollar;
---&gt;</programlisting>
-
- <para>The exact boilerplate may change, but it will always
- include a &dollar;FreeBSD&dollar; line and the phrase
- <literal>The FreeBSD Documentation Project</literal>.
- Note that the &dollar;FreeBSD part is expanded automatically
- by Subversion, so it should be empty (just
- <literal>&dollar;FreeBSD&dollar;</literal>) for new
- files.</para>
-
- <para>Your translated documents should include their own
- &dollar;FreeBSD&dollar; line, and change the
- <literal>FreeBSD Documentation Project</literal> line to
- <literal>The FreeBSD <replaceable>language</replaceable>
- Documentation Project</literal>.</para>
-
- <para>In addition, you should add a third line which indicates
- which revision of the English text this is based on.</para>
-
- <para>So, the Spanish version of this file might start:</para>
-
- <programlisting>&lt;!--
- The FreeBSD Spanish Documentation Project
-
- &dollar;FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs &dollar;
- Original revision: r38674
---&gt;</programlisting>
- </answer>
- </qandaentry>
- </qandaset>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml
deleted file mode 100644
index 2291246250..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml
+++ /dev/null
@@ -1,177 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- Copyright (c) 2013 Warren Block
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form 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 SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``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 THE
- AUTHORS OR CONTRIBUTORS 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 SOFTWARE,
- EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
- $FreeBSD$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="working-copy">
- <title>The Working Copy</title>
-
- <para>The <emphasis>working copy</emphasis> is a copy of the &os;
- repository documentation tree downloaded onto the local computer.
- Changes are made to the local working copy, tested, and then
- submitted as patches to be committed to the main
- repository.</para>
-
- <para>A full copy of the documentation tree can occupy 700 megabytes
- of disk space. Allow for a full gigabyte of space to have room
- for temporary files and test versions of various output
- formats.</para>
-
- <para><link xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link>
- is used to manage the &os; documentation files. It is installed
- by <package>textproc/docproj</package> as one of
- the required applications.</para>
-
- <sect1 xml:id="working-copy-doc-and-src">
- <title>Documentation and Manual Pages</title>
-
- <para>&os; documentation is not just books and articles. Manual
- pages for all the commands and configuration files are also part
- of the documentation, and part of the <acronym>FDP</acronym>'s
- territory. Two repositories are involved:
- <literal>doc</literal> for the books and articles, and
- <literal>base</literal> for the operating system and manual
- pages. To edit manual pages, the <literal>base</literal>
- repository must be checked out separately.</para>
-
- <para>Repositories may contain multiple versions of documentation
- and source code. New modifications are almost always made only
- to the latest version, called <literal>head</literal>.</para>
- </sect1>
-
- <sect1 xml:id="working-copy-choosing-directory">
- <title>Choosing a Directory</title>
-
- <para>&os; documentation is traditionally stored in
- <filename>/usr/doc/</filename>, and system
- source code with manual pages in
- <filename>/usr/src/</filename>. These
- directory trees are relocatable, and users may want to put the
- working copies in other locations to avoid interfering with
- existing information in the main directories. The examples
- that follow use <filename>~/doc</filename>
- and <filename>~/src</filename>, both
- subdirectories of the user's home directory.</para>
- </sect1>
-
- <sect1 xml:id="working-copy-checking-out">
- <title>Checking Out a Copy</title>
-
- <para>A download of a working copy from the repository is called
- a <emphasis>checkout</emphasis>, and done with
- <command>svn checkout</command>. This example checks out a
- copy of the latest version (<literal>head</literal>) of
- the main documentation tree:</para>
-
- <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
-
- <para>A checkout of the source code to work on manual pages is
- very similar:</para>
-
- <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
- </sect1>
-
- <sect1 xml:id="working-copy-updating">
- <title>Updating a Working Copy</title>
-
- <para>The documents and files in the &os; repository change daily.
- People modify files and commit changes frequently. Even a short
- time after an initial checkout, there will already be
- differences between the local working copy and the main &os;
- repository. To update the local version with the changes that
- have been made to the main repository, use
- <command>svn update</command> on the directory containing the
- local working copy:</para>
-
- <screen>&prompt.user; <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>
-
- <para>Get in the protective habit of using
- <command>svn update</command> before editing document files.
- Someone else may have edited that file very recently, and the
- local working copy will not include the latest changes until it
- has been updated. Editing the newest version of a file is much
- easier than trying to combine an older, edited local file with
- the newer version from the repository.</para>
- </sect1>
-
- <sect1 xml:id="working-copy-revert">
- <title>Reverting Changes</title>
-
- <para>Sometimes it turns out that changes were
- not necessary after all, or the writer just wants to start over.
- Files can be <quote>reset</quote> to their unchanged form with
- <command>svn revert</command>. For example, to erase the edits
- made to <filename>chapter.xml</filename> and reset it to
- unmodified form:</para>
-
- <screen>&prompt.user; <userinput>svn revert chapter.xml</userinput></screen>
- </sect1>
-
- <sect1 xml:id="working-copy-making-diff">
- <title>Making a Diff</title>
-
- <para>After edits to a file or group of files are completed, the
- differences between the local working copy and the version on
- the &os; repository must be collected into a single file for
- submission. These <emphasis>diff</emphasis> files are produced
- by redirecting the output of <command>svn diff</command> into a
- file:</para>
-
- <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput>
-&prompt.user; <userinput>svn diff &gt; <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen>
-
- <para>Give the file a meaningful name that identifies the
- contents. The example above is for spelling fixes to the whole
- documentation tree.</para>
-
- <para>If the diff file is to be submitted with the web
- <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a &os;
- problem report</link></quote> interface, add a
- <filename>.txt</filename> extension to give the earnest and
- simple-minded web form a clue that the contents are plain
- text.</para>
-
- <para>Be careful: <command>svn diff</command> includes all changes
- made in the current directory and any subdirectories. If there
- are files in the working copy with edits that are not ready to
- be submitted yet, provide a list of only the files that are to
- be included:</para>
-
- <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput>
-&prompt.user; <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> &gt; <replaceable>disks-printers.diff</replaceable></userinput></screen>
- </sect1>
-
- <sect1 xml:id="working-copy-subversion-references">
- <title><application>Subversion</application> References</title>
-
- <para>These examples show very basic usage of
- <application>Subversion</application>. More detail is available
- in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link>
- and the <link xlink:href="http://subversion.apache.org/docs/">Subversion
- documentation</link>.</para>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
deleted file mode 100644
index 59f0945fdb..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
+++ /dev/null
@@ -1,592 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style">
- <title>Writing Style</title>
-
- <sect1 xml:id="writing-style-tips">
- <title>Tips</title>
-
- <para>Technical documentation can be improved by consistent use of
- several principles. Most of these can be classified into three
- goals: <emphasis>be clear</emphasis>,
- <emphasis>be complete</emphasis>, and
- <emphasis>be concise</emphasis>. These goals can conflict with
- each other. Good writing consists of a balance between
- them.</para>
-
- <sect2 xml:id="writing-style-be-clear">
- <title>Be Clear</title>
-
- <para>Clarity is extremely important. The reader may be a
- novice, or reading the document in a second language. Strive
- for simple, uncomplicated text that clearly explains the
- concepts.</para>
-
- <para>Avoid flowery or embellished speech, jokes, or colloquial
- expressions. Write as simply and clearly as possible. Simple
- text is easier to understand and translate.</para>
-
- <para>Keep explanations as short, simple, and clear as possible.
- Avoid empty phrases like <quote>in order to</quote>, which
- usually just means <quote>to</quote>. Avoid potentially
- patronizing words like <quote>basically</quote>. Avoid Latin
- terms like <quote>i.e.</quote> or <quote>cf.</quote>, which
- may be unknown outside of academic or scientific
- groups.</para>
-
- <para>Write in a formal style. Avoid addressing the reader
- as <quote>you</quote>. For example, say
- <quote>copy the file to <filename>/tmp</filename></quote>
- rather than <quote>you can copy the file to
- <filename>/tmp</filename></quote>.</para>
-
- <para>Give clear, correct, <emphasis>tested</emphasis> examples.
- A trivial example is better than no example. A good example
- is better yet. Do not give bad examples, identifiable by
- apologies or sentences like <quote>but really it should never
- be done that way</quote>. Bad examples are worse than no
- examples. Give good examples, because <emphasis>even when
- warned not to use the example as shown</emphasis>, the
- reader will usually just use the example as shown.</para>
-
- <para>Avoid <emphasis>weasel words</emphasis> like
- <quote>should</quote>, <quote>might</quote>,
- <quote>try</quote>, or <quote>could</quote>. These words
- imply that the speaker is unsure of the facts, and
- create doubt in the reader.</para>
-
- <para>Similarly, give instructions as imperative commands: not
- <quote>you should do this</quote>, but merely
- <quote>do this</quote>.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-be-complete">
- <title>Be Complete</title>
-
- <para>Do not make assumptions about the reader's abilities or
- skill level. Tell them what they need to know. Give links to
- other documents to provide background information without
- having to recreate it. Put yourself in the reader's place,
- anticipate the questions they will ask, and answer
- them.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-be-concise">
- <title>Be Concise</title>
-
- <para>While features should be documented completely, sometimes
- there is so much information that the reader cannot easily
- find the specific detail needed. The balance between being
- complete and being concise is a challenge. One approach is to
- have an introduction, then a <quote>quick start</quote>
- section that describes the most common situation, followed by
- an in-depth reference section.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="writing-style-guidelines">
- <title>Guidelines</title>
-
- <para>To promote consistency between the myriad authors of the
- &os; documentation, some guidelines have been drawn up for
- authors to follow.</para>
-
- <variablelist>
- <varlistentry>
- <term>Use American English Spelling</term>
-
- <listitem>
- <para>There are several variants of English, with different
- spellings for the same word. Where spellings differ, use
- the American English variant. <quote>color</quote>, not
- <quote>colour</quote>, <quote>rationalize</quote>, not
- <quote>rationalise</quote>, and so on.</para>
-
- <note>
- <para>The use of British English may be accepted in the
- case of a contributed article, however the spelling must
- be consistent within the whole document. The other
- documents such as books, web site, manual pages, etc.
- will have to use American English.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Do not use contractions</term>
-
- <listitem>
- <para>Do not use contractions. Always spell the phrase out
- in full. <quote>Don't use contractions</quote> is
- wrong.</para>
-
- <para>Avoiding contractions makes for a more formal tone, is
- more precise, and is slightly easier for
- translators.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Use the serial comma</term>
-
- <listitem>
- <para>In a list of items within a paragraph, separate each
- item from the others with a comma. Separate the last item
- from the others with a comma and the word
- <quote>and</quote>.</para>
-
- <para>For example:</para>
-
- <blockquote>
- <para>This is a list of one, two and three items.</para>
- </blockquote>
-
- <para>Is this a list of three items, <quote>one</quote>,
- <quote>two</quote>, and <quote>three</quote>, or a list of
- two items, <quote>one</quote> and <quote>two and
- three</quote>?</para>
-
- <para>It is better to be explicit and include a serial
- comma:</para>
-
- <blockquote>
- <para>This is a list of one, two, and three items.</para>
- </blockquote>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Avoid redundant phrases</term>
-
- <listitem>
- <para>Do not use redundant phrases. In particular,
- <quote>the command</quote>, <quote>the file</quote>, and
- <quote>man command</quote> are often redundant.</para>
-
- <para>For example, commands:</para>
-
- <informalexample>
- <para>Wrong: Use the <command>svn</command> command to
- update sources.</para>
- </informalexample>
-
- <informalexample>
- <para>Right: Use <command>svn</command> to update
- sources.</para>
- </informalexample>
-
- <para>Filenames:</para>
-
- <informalexample>
- <para>Wrong: &hellip; in the filename
- <filename>/etc/rc.local</filename>&hellip;</para>
- </informalexample>
-
- <informalexample>
- <para>Right: &hellip; in
- <filename>/etc/rc.local</filename>&hellip;</para>
- </informalexample>
-
- <para>Manual page references (the second example uses
- <tag>citerefentry</tag> with the
- <literal>&amp;man.csh.1;</literal> entity):.</para>
-
- <informalexample>
- <para>Wrong: See <command>man csh</command> for more
- information.</para>
- </informalexample>
-
- <informalexample>
- <para>Right: See &man.csh.1;.</para>
- </informalexample>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Two spaces between sentences</term>
-
- <listitem>
- <para>Always use two spaces between sentences, as it
- improves readability and eases use of tools such as
- <application>Emacs</application>.</para>
-
- <para>A period and spaces followed by a capital letter
- does not always mark a new sentence, especially in names.
- <quote>Jordan K. Hubbard</quote> is a good example. It
- has a capital <literal>H</literal> following a period and
- a space, and is certainly not a new sentence.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of
- Style</link>, by William Strunk.</para>
- </sect1>
-
- <sect1 xml:id="writing-style-guide">
- <title>Style Guide</title>
-
- <para>To keep the source for the documentation consistent when
- many different people are editing it, please follow these style
- conventions.</para>
-
- <sect2>
- <title>Letter Case</title>
-
- <para>Tags are entered in lower case, <tag>para</tag>,
- <emphasis>not</emphasis> <tag>PARA</tag>.</para>
-
- <para>Text that appears in SGML contexts is generally written in
- upper case, <literal>&lt;!ENTITY&hellip;&gt;</literal>, and
- <literal>&lt;!DOCTYPE&hellip;&gt;</literal>,
- <emphasis>not</emphasis>
- <literal>&lt;!entity&hellip;&gt;</literal> and
- <literal>&lt;!doctype&hellip;&gt;</literal>.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-acronyms">
- <title>Acronyms</title>
-
- <para>Acronyms should be defined the first time they appear in a
- document, as in:
- <quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>.
- After the acronym has been defined, use the acronym alone
- unless it makes more sense contextually to use the whole term.
- Acronyms are usually defined only once per chapter or per
- document.</para>
-
- <para>All acronyms should be enclosed in
- <tag>acronym</tag> tags.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-indentation">
- <title>Indentation</title>
-
- <para>The first line in each file starts with no indentation,
- <emphasis>regardless</emphasis> of the indentation level of
- the file which might contain the current file.</para>
-
- <para>Opening tags increase the indentation level by two spaces.
- Closing tags decrease the indentation level by two spaces.
- Blocks of eight spaces at the start of a line should be
- replaced with a tab. Do not use spaces in front of tabs, and
- do not add extraneous whitespace at the end of a line.
- Content within elements should be indented by two spaces if
- the content runs over more than one line.</para>
-
- <para>For example, the source for this section looks like
- this:</para>
-
- <programlisting><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">sect2</tag>
- <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>The first line in each file starts with no indentation,
- <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of
- the file which might contain the current file.<tag class="endtag">para</tag>
-
- ...
- <tag class="endtag">sect2</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">chapter</tag></programlisting>
-
- <para>Tags containing long attributes follow the same
- rules. Following the indentation rules in this case helps
- editors and writers see which content is inside the
- tags:</para>
-
- <programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link
- linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag>
- section if there are problems booting. Powering down and
- disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk
- will allow it to be kept as an offline backup.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &amp;os;
- system. Refer to the article <tag class="starttag">link
- xlink:href="&amp;url.articles.gjournal-desktop;"</tag>Implementing UFS
- Journaling on a Desktop PC<tag class="endtag">link</tag> for detailed
- instructions.<tag class="endtag">para</tag></programlisting>
-
- <para>When an element is too long to fit on the remainder of a
- line without wrapping, moving the start tag to the next line
- can make the source easier to read. In this example, the
- <literal>systemitem</literal> element has been moved to the
- next line to avoid wrapping and indenting:</para>
-
- <programlisting><tag class="starttag">para</tag>With file flags, even
- <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be
- prevented from removing or altering files.<tag class="endtag">para</tag></programlisting>
-
- <para>Configurations to help various text editors conform to
- these guidelines can be found in
- <xref linkend="editor-config"/>.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-tag-style">
- <title>Tag Style</title>
-
- <sect3 xml:id="writing-style-tag-style-spacing">
- <title>Tag Spacing</title>
-
- <para>Tags that start at the same indent as a previous tag
- should be separated by a blank line, and those that are not
- at the same indent as a previous tag should not:</para>
-
- <informalexample>
- <programlisting><tag class="starttag">article lang='en'</tag>
- <tag class="starttag">articleinfo</tag>
- <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag>
-
- <tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag>...
- ...
- ...<tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">articleinfo</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>...<tag class="endtag">para</tag>
- <tag class="endtag">sect1</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>...<tag class="endtag">para</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">article</tag></programlisting>
- </informalexample>
- </sect3>
-
- <sect3 xml:id="writing-style-tag-style-separating">
- <title>Separating Tags</title>
-
- <para>Tags like <tag>itemizedlist</tag> which will
- always have further tags inside them, and in fact do not
- take character data themselves, are always on a line by
- themselves.</para>
-
- <para>Tags like <tag>para</tag> and
- <tag>term</tag> do not need other tags to contain
- normal character data, and their contents begin immediately
- after the tag, <emphasis>on the same line</emphasis>.</para>
-
- <para>The same applies to when these two types of tags
- close.</para>
-
- <para>This leads to an obvious problem when mixing these
- tags.</para>
-
- <para>When a starting tag which cannot contain character data
- directly follows a tag of the type that requires other tags
- within it to use character data, they are on separate lines.
- The second tag should be properly indented.</para>
-
- <para>When a tag which can contain character data closes
- directly after a tag which cannot contain character data
- closes, they co-exist on the same line.</para>
- </sect3>
- </sect2>
-
- <sect2 xml:id="writing-style-whitespace-changes">
- <title>Whitespace Changes</title>
-
- <para><emphasis>Do not commit changes
- to content at the same time as changes to
- formatting</emphasis>.</para>
-
- <para>When content and whitespace changes are kept separate,
- translation teams can easily see whether a change was content
- that must be translated or only whitespace.</para>
-
- <para>For example, if two sentences have been added to a
- paragraph so that the line lengths now go
- over 80 columns, first commit the change with the too-long
- lines. Then fix the line wrapping, and commit this
- second change. In the commit message for the second change,
- indicate that this is a whitespace-only change that can be
- ignored by translators.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-nonbreaking-space">
- <title>Non-Breaking Space</title>
-
- <para>Avoid line breaks in places where they look ugly or make
- it difficult to follow a sentence. Line breaks depend on the
- width of the chosen output medium. In particular, viewing the
- HTML documentation with a text browser can lead to badly
- formatted paragraphs like the next one:</para>
-
- <literallayout class="monospaced">Data capacity ranges from 40 MB to 15
-GB. Hardware compression &hellip;</literallayout>
-
- <para>The general entity <literal>&amp;nbsp;</literal> prohibits
- line breaks between parts belonging together. Use
- non-breaking spaces in the following places:</para>
-
- <itemizedlist>
- <listitem>
- <para>between numbers and units:</para>
- <programlisting>57600&amp;nbsp;bps</programlisting>
- </listitem>
-
- <listitem>
- <para>between program names and version numbers:</para>
- <programlisting>&amp;os;&amp;nbsp;9.2</programlisting>
- </listitem>
-
- <listitem>
- <para>between multiword names (use with caution when
- applying this to more than 3-4 word names like
- <quote>The &os; Brazilian Portuguese Documentation
- Project</quote>):</para>
- <programlisting><![CDATA[Sun&nbsp;Microsystems]]></programlisting>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
- <sect1 xml:id="writing-style-word-list">
- <title>Word List</title>
-
- <para>This list of words shows the correct spelling and
- capitalization when used in &os; documentation. If a word is
- not on this list, ask about it on the &a.doc;.</para>
-
- <informaltable frame="none" pgwide="0">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Word</entry>
- <entry>XML Code</entry>
- <entry>Notes</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>CD-ROM</entry>
-
- <entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry>
- </row>
-
- <row>
- <entry>DoS (Denial of Service)</entry>
- <entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry>
- </row>
-
- <row>
- <entry>email</entry>
- </row>
-
- <row>
- <entry>file system</entry>
- </row>
-
- <row>
- <entry>IPsec</entry>
- </row>
-
- <row>
- <entry>Internet</entry>
- </row>
-
- <row>
- <entry>manual page</entry>
- </row>
-
- <row>
- <entry>mail server</entry>
- </row>
-
- <row>
- <entry>name server</entry>
- </row>
-
- <row>
- <entry>Ports Collection</entry>
- </row>
-
- <row>
- <entry>read-only</entry>
- </row>
-
- <row>
- <entry>Soft Updates</entry>
- </row>
-
- <row>
- <entry>stdin</entry>
- <entry><tag class="starttag">varname</tag>stdin<tag class="endtag">varname</tag></entry>
- </row>
-
- <row>
- <entry>stdout</entry>
- <entry><tag class="starttag">varname</tag>stdout<tag class="endtag">varname</tag></entry>
- </row>
-
- <row>
- <entry>stderr</entry>
- <entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry>
- </row>
-
- <row>
- <entry>Subversion</entry>
-
- <entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry>
- <entry>Do not refer to the Subversion application as
- <literal>SVN</literal> in upper case. To refer to the
- command, use <tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>.</entry>
- </row>
-
- <row>
- <entry>&unix;</entry>
- <entry><literal>&amp;unix;</literal></entry>
- </row>
-
- <row>
- <entry>web server</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
deleted file mode 100644
index a0c6907d5b..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
+++ /dev/null
@@ -1,600 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xhtml-markup">
- <title><acronym>XHTML</acronym> Markup</title>
-
- <sect1 xml:id="xhtml-markup-introduction">
- <title>Introduction</title>
-
- <para>This chapter describes usage of the <acronym>XHTML</acronym>
- markup language used for the &os; web site.</para>
-
- <para><acronym>XHTML</acronym> is the <acronym>XML</acronym>
- version of the HyperText Markup Language, the markup language of
- choice on the World Wide Web. More information can be found at
- <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>
-
- <para><acronym>XHTML</acronym> is used to mark up pages on the
- &os; web site. It is usually not used to mark up other
- documentation, since DocBook offers a far richer set of elements
- from which to choose. Consequently, <acronym>XHTML</acronym>
- pages will normally only be encountered when writing for the web
- site.</para>
-
- <para><acronym>HTML</acronym> has gone through a number of
- versions. The <acronym>XML</acronym>-compliant version
- described here is called <acronym>XHTML</acronym>. The latest
- widespread version is <acronym>XHTML</acronym> 1.0, available in
- both <emphasis>strict</emphasis> and
- <emphasis>transitional</emphasis> variants.</para>
-
- <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
- available from the Ports Collection in
- <package>textproc/xhtml</package>. They are
- automatically installed by the <package>textproc/docproj</package> port.</para>
-
- <note>
- <para>This is <emphasis>not</emphasis> an exhaustive list of
- elements, since that would just repeat the documentation for
- <acronym>XHTML</acronym>. The aim is to list those elements
- most commonly used. Please post questions about elements or
- uses not covered here to the &a.doc;.</para>
- </note>
-
- <note>
- <title>Inline Versus 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>
-
- <sect1 xml:id="xhtml-markup-fpi">
- <title>Formal Public Identifier (<acronym>FPI</acronym>)</title>
-
- <para>There are a number of <acronym>XHTML</acronym>
- <acronym>FPI</acronym>s, depending upon the version, or
- <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
- a document conforms. Most <acronym>XHTML</acronym> documents on
- the &os; web site comply with the transitional version of
- <acronym>XHTML</acronym> 1.0.</para>
-
- <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
- </sect1>
-
- <sect1 xml:id="xhtml-markup-sectional-elements">
- <title>Sectional Elements</title>
-
- <para>An <acronym>XHTML</acronym> 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 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 <acronym>XHTML</acronym> Document
- Structure</title>
-
- <programlisting><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- <tag class="starttag">body</tag>
-
- &hellip;
-
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </example>
- </sect1>
-
- <sect1 xml:id="xhtml-markup-block-elements">
- <title>Block Elements</title>
-
- <sect2 xml:id="xhtml-markup-block-elements-headings">
- <title>Headings</title>
-
- <para><acronym>XHTML</acronym> has tags to denote headings in
- the 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>,
- and Other Header Tags</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag>
-
-&lt;!-- Document introduction goes here --&gt;
-
-<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag>
-
-&lt;!-- Content for the first section goes here --&gt;
-
-<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag>
-
-&lt;!-- Content for the first sub-section goes here --&gt;
-
-<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag>
-
-&lt;!-- Content for the second section goes here --&gt;</programlisting>
- </example>
-
- <para>Generally, an <acronym>XHTML</acronym> 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. Do not
- leave gaps in the numbering.</para>
- </sect2>
-
- <sect2 xml:id="xhtml-markup-block-elements-paragraphs">
- <title>Paragraphs</title>
-
- <para><acronym>XHTML</acronym> supports a single paragraph
- element, <tag>p</tag>.</para>
-
- <example>
- <title><tag>p</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>This is a paragraph. It can contain just about any
- other element.<tag class="endtag">p</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="xhtml-markup-block-elements-block-quotations">
- <title>Block Quotations</title>
-
- <para>A block quotation is an extended quotation from another
- document that will appear in a separate paragraph.</para>
-
- <example>
- <title><tag>blockquote</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag>
-
-<tag class="starttag">blockquote</tag>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.<tag class="endtag">blockquote</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="xhtml-markup-block-elements-lists">
- <title>Lists</title>
-
- <para><acronym>XHTML</acronym> can present the user with three
- types of lists: ordered, unordered, and definition.</para>
-
- <para>Entries in an ordered list will be numbered, while entries
- in an unordered list will be preceded by bullet points.
- Definition lists have two sections for each entry. The first
- section is the term being defined, and the second section is
- the definition.</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> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>An unordered list. Listitems will probably be
- preceded by bullets.<tag class="endtag">p</tag>
-
-<tag class="starttag">ul</tag>
- <tag class="starttag">li</tag>First item<tag class="endtag">li</tag>
-
- <tag class="starttag">li</tag>Second item<tag class="endtag">li</tag>
-
- <tag class="starttag">li</tag>Third item<tag class="endtag">li</tag>
-<tag class="endtag">ul</tag>
-
-<tag class="starttag">p</tag>An ordered list, with list items consisting of multiple
- paragraphs. Each item (note: not each paragraph) will be
- numbered.<tag class="endtag">p</tag>
-
-<tag class="starttag">ol</tag>
- <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item. It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag>
-
- <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
-
- <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third
- item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
-<tag class="endtag">ol</tag></programlisting>
- </example>
-
- <example>
- <title>Definition Lists with <tag>dl</tag></title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">dl</tag>
- <tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag>
-
- <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
-
- <tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag>
-
- <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
-
- <tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag>
-
- <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
-<tag class="endtag">dl</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="xhtml-markup-block-elements-preformatted-text">
- <title>Pre-formatted Text</title>
-
- <para>Pre-formatted text is shown to the user exactly as it is
- in the file. Text is shown in a fixed font. Multiple spaces
- and line breaks are shown exactly as they are in the
- file.</para>
-
- <para>Wrap pre-formatted text in the <tag>pre</tag>
- element.</para>
-
- <example>
- <title><tag>pre</tag> Example</title>
-
- <para>For example, the <tag>pre</tag> tags could be
- used to mark up an email message:</para>
-
- <programlisting><tag class="starttag">pre</tag> 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
-
- &amp;lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&amp;gt;
-
- Comments appreciated.
-
- N<tag class="endtag">pre</tag></programlisting>
-
- <para>Keep in mind that <literal>&lt;</literal> and
- <literal>&amp;</literal> still are recognized as special
- characters in pre-formatted text. This is why the example
- shown had to use <literal>&amp;lt;</literal> instead of
- <literal>&lt;</literal>. For consistency,
- <literal>&amp;gt;</literal> was used in place of
- <literal>&gt;</literal>, too. Watch out for the special
- characters that may appear in text copied from a plain-text
- source, like an email message or program code.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="xhtml-markup-block-elements-tables">
- <title>Tables</title>
-
- <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 the <tag>p</tag>element is not needed.</para>
-
- <example>
- <title>Simple Use of <tag>table</tag></title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag>
-
-<tag class="starttag">table</tag>
- <tag class="starttag">tr</tag>
- <tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag>
-
- <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-
- <tag class="starttag">tr</tag>
- <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
-
- <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-<tag class="endtag">table</tag></programlisting>
- </example>
-
- <para>A cell can span multiple rows and columns by adding the
- <tag class="attribute">rowspan</tag> or
- <tag class="attribute">colspan</tag> attributes with
- values for the number of rows or columns to be spanned.</para>
-
- <example>
- <title>Using
- <tag class="attribute">rowspan</tag></title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to
- it on the right.<tag class="endtag">p</tag>
-
-<tag class="starttag">table</tag>
- <tag class="starttag">tr</tag>
- <tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-
- <tag class="starttag">tr</tag>
- <tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag>
-
- <tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-<tag class="endtag">table</tag></programlisting>
- </example>
-
- <example>
- <title>Using
- <tag class="attribute">colspan</tag></title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag>
-
-<tag class="starttag">table</tag>
- <tag class="starttag">tr</tag>
- <tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-
- <tag class="starttag">tr</tag>
- <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
-
- <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-<tag class="endtag">table</tag></programlisting>
- </example>
-
- <example>
- <title>Using <tag class="attribute">rowspan</tag> and
- <tag class="attribute">colspan</tag>
- Together</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of
- cells merged into one. The other cells are normal.<tag class="endtag">p</tag>
-
-<tag class="starttag">table</tag>
- <tag class="starttag">tr</tag>
- <tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag>
-
- <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-
- <tag class="starttag">tr</tag>
- &lt;!-- Because the large cell on the left merges into
- this row, the first &lt;td&gt; will occur on its
- right --&gt;
-
- <tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-
- <tag class="starttag">tr</tag>
- <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
-
- <tag class="starttag">td</tag>Bottom middle cell<tag class="endtag">td</tag>
-
- <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
- <tag class="endtag">tr</tag>
-<tag class="endtag">table</tag></programlisting>
- </example>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xhtml-markup-inline-elements">
- <title>In-line Elements</title>
-
- <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">
- <title>Emphasizing Information</title>
-
- <para>Two levels of emphasis are available in
- <acronym>XHTML</acronym>, <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><tag>em</tag> is typically rendered in italic
- and <tag>strong</tag> is rendered in bold. This is
- not always the case, and should not be relied upon. According
- to best practices, web pages only hold structural and
- semantical information, and stylesheets are later applied to
- them. Think of semantics, not formatting, when using these
- tags.</para>
-
- <example>
- <title><tag>em</tag> and
- <tag>strong</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while
- <tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text">
- <title>Indicating Fixed-Pitch Text</title>
-
- <para>Content that should be rendered in a fixed pitch
- (typewriter) typeface is tagged with <tag>tt</tag>
- (for <quote>teletype</quote>).</para>
-
- <example>
- <title><tag>tt</tag> Example</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>Many system settings are stored in
- <tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="xhtml-markup-inline-elements-links">
- <title>Links</title>
-
- <note>
- <para>Links are also inline elements.</para>
- </note>
-
- <sect3 xml:id="xhtml-markup-inline-elements-linking">
- <title>Linking to Other Documents on the Web</title>
-
- <para>A link points to the <acronym>URL</acronym> of a
- document on the web. The link is indicated with
- <tag>a</tag>, and the
- <tag class="attribute">href</tag> attribute contains
- the <acronym>URL</acronym> of the target document. The
- content of the element becomes the link, indicated to the
- user by showing it in a different color or with an
- underline.</para>
-
- <example>
- <title>Using
- <tag class="starttag">a href="..."</tag></title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p</tag>More information is available at the
- <tag class="starttag">a href="http://www.&amp;os;.org/"</tag>&amp;os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>This link always takes the user to the top of the linked
- document.</para>
- </sect3>
-
- <sect3 xml:id="xhtml-markup-inline-elements-specific-parts">
- <title>Linking to Specific Parts of Documents</title>
-
- <para>To link to a specific point within a document, that
- document must include an <emphasis>anchor</emphasis> at the
- desired point. Anchors are included by setting the
- <tag class="attribute">id</tag> attribute of an
- element to a name. This example creates an anchor by
- setting the <tag class="attribute">id</tag>
- attribute of a <tag class="element">p</tag>
- element.</para>
-
- <example>
- <title>Creating an Anchor</title>
-
- <para>Usage:</para>
-
- <programlisting><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced
- in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>Links to anchors are similar to plain links, but include
- a <literal>#</literal> symbol and the anchor's
- <acronym>ID</acronym> at the end of the
- <acronym>URL</acronym>.</para>
-
- <example>
- <title>Linking to a Named Part of a Different
- Document</title>
-
- <para>The <literal>samplepara</literal> example is part of a
- document called <filename>foo.html</filename>. A link to
- that specific paragraph in the document is constructed in
- this example.</para>
-
- <programlisting><tag class="starttag">p</tag>More information can be found in the
- <tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of
- <tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>To link to a named anchor within the same document, omit
- the document's <acronym>URL</acronym>, and just use the
- <literal>#</literal> symbol followed by the name of the
- anchor.</para>
-
- <example>
- <title>Linking to a Named Part of the Same Document</title>
-
- <para>The <literal>samplepara</literal> example
- resides in this document. To link to it:</para>
-
- <programlisting><tag class="starttag">p</tag>More information can be found in the
- <tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this
- document.<tag class="endtag">p</tag></programlisting>
- </example>
- </sect3>
- </sect2>
- </sect1>
-</chapter>
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
deleted file mode 100644
index f076dfc2b5..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
+++ /dev/null
@@ -1,1433 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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$
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-primer">
- <title>XML Primer</title>
-
- <para>Most <acronym>FDP</acronym> documentation is written with
- markup languages based on <acronym>XML</acronym>. This chapter
- explains what that means, how to read and understand the
- documentation source, and the <acronym>XML</acronym> techniques
- used.</para>
-
- <para>Portions of this section were inspired by Mark Galassi's
- <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
- Going With DocBook</link>.</para>
-
- <sect1 xml:id="xml-primer-overview">
- <title>Overview</title>
-
- <para>In the original days of computers, electronic text was
- simple. There were a few character sets like
- <acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, 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. When text is in a
- machine-usable format, machines are expected to be able to use
- and manipulate it intelligently. Authors want to indicate that
- certain phrases should be emphasized, or added to a glossary, or
- made into hyperlinks. Filenames could 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. The computer would read 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 computers still
- require assistance before they can meaningfully process
- text.</para>
-
- <para>More precisely, they need help identifying what is what.
- Consider this text:</para>
-
- <blockquote>
- <para>To remove <filename>/tmp/foo</filename>, use
- &man.rm.1;.</para>
-
- <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
- </blockquote>
-
- <para>It is easy to 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&mdash;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> (the effort required) to
- create the document.</para>
-
- <para>The previous example is actually represented in this
- document like this:</para>
-
- <programlisting><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &amp;man.rm.1;.<tag class="endtag">para</tag>
-
-<tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>
-
- <para>The markup is clearly separate from the content.</para>
-
- <para>Markup languages define what the markup means and how it
- should be interpreted.</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 is intended for cookery
- recipes. This, in turn, would be very different from a markup
- language used to describe poetry. What is really needed is a
- first language used to write these other markup languages. A
- <emphasis>meta markup language</emphasis>.</para>
-
- <para>This is exactly what the eXtensible Markup
- Language (<acronym>XML</acronym>) is. Many markup languages
- have been written in <acronym>XML</acronym>, including the two
- most used by the <acronym>FDP</acronym>,
- <acronym>XHTML</acronym> and DocBook.</para>
-
- <para>Each language definition is more properly called a grammar,
- vocabulary, schema or Document Type Definition
- (<acronym>DTD</acronym>). There are various languages to
- specify an <acronym>XML</acronym> grammar, or
- <emphasis>schema</emphasis>.</para>
-
- <para xml:id="xml-primer-validating">A schema 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
- <acronym>XML</acronym> <emphasis>parser</emphasis> which reads
- in both the schema and a document which claims to conform to the
- schema. The parser can then confirm whether or not all the
- elements required by the vocabulary 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>Validation confirms that the choice of
- elements, their ordering, and so on, conforms to that listed
- in the grammar. It does <emphasis>not</emphasis> check
- whether <emphasis>appropriate</emphasis> markup has been used
- for the content. If all the filenames in a document were
- marked up as function names, the parser would not flag this as
- an error (assuming, of course, that the schema defines
- elements for filenames and functions, and that they are
- allowed to appear in the same place).</para>
- </note>
-
- <para>Most contributions to the Documentation
- Project will be content marked up in either
- <acronym>XHTML</acronym> or DocBook, rather than alterations to
- the schemas. For this reason, this book will not touch on how
- to write a vocabulary.</para>
- </sect1>
-
- <sect1 xml:id="xml-primer-elements">
- <title>Elements, Tags, and Attributes</title>
-
- <para>All the vocabularies written in <acronym>XML</acronym> share
- certain characteristics. This is hardly surprising, as the
- philosophy behind <acronym>XML</acronym> 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>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>It may be helpful to think of this as
- <quote>chunking</quote> content. At the very top level is one
- chunk, the book. Look a little deeper, and there are more
- chunks, the individual chapters. These are chunked further into
- paragraphs, footnotes, character names, and so on.</para>
-
- <para>Notice how this differentiation between different elements
- of the content can be made without resorting to any
- <acronym>XML</acronym> terms. It really is surprisingly
- straightforward. This could be done 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
- <acronym>XML</acronym> (<acronym>XHTML</acronym>, 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 grammar 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 <tag class="starttag"><replaceable>element-name</replaceable></tag>.
- The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para>
-
- <example>
- <title>Using an Element (Start and End Tags)</title>
-
- <para><acronym>XHTML</acronym> has an element for indicating
- that the content enclosed by the element is a paragraph,
- called <tag>p</tag>.</para>
-
- <programlisting><tag class="starttag">p</tag>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.<tag class="endtag">p</tag>
-
-<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>Some elements have no content. For example, in
- <acronym>XHTML</acronym>, a horizontal line can be included in
- the document. For these <quote>empty</quote> elements,
- <acronym>XML</acronym> introduced a shorthand form that is
- completely equivalent to the two-tag version:</para>
-
- <example>
- <title>Using an Element Without Content</title>
-
- <para><acronym>XHTML</acronym> has an element for indicating a
- horizontal rule, called <tag>hr</tag>. This element
- does not wrap content, so it looks like this:</para>
-
- <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
-<tag class="starttag">hr</tag><tag class="endtag">hr</tag>
-
-<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
- from the previous paragraph.<tag class="endtag">p</tag></programlisting>
-
- <para>The shorthand version consists of a single tag:</para>
-
- <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
-<tag class="emptytag">hr</tag>
-
-<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
- from the previous paragraph.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>As shown above, 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><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some
- of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>The grammar consists of rules that describe 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 ends.</para>
-
- <para>When this document (or anyone else knowledgeable about
- <acronym>XML</acronym>) refers to
- <quote>the <tag class="starttag">p</tag> tag</quote>
- they mean the literal text consisting of the three characters
- <literal>&lt;</literal>, <literal>p</literal>, and
- <literal>&gt;</literal>. But the phrase
- <quote>the <tag>p</tag> 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><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
-
- <para>In <acronym>XHTML</acronym>, the <tag>p</tag>
- element has an attribute called
- <tag class="attribute">align</tag>, which suggests an
- alignment (justification) for the paragraph to the program
- displaying the <acronym>XHTML</acronym>.</para>
-
- <para>The <tag class="attribute">align</tag> 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><tag class="starttag">p align="left"</tag>The inclusion of the align attribute
- on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag>
-
-<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>Some attributes only take specific values, such as
- <literal>left</literal> or <literal>justify</literal>. Others
- allow any value.</para>
-
- <example>
- <title>Single Quotes Around Attributes</title>
-
- <programlisting><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para>Attribute values in <acronym>XML</acronym> must be enclosed
- in either single or double quotes. Double quotes are
- traditional. Single quotes are useful when the attribute value
- contains double quotes.</para>
-
- <para>Information about attributes, elements, and tags is stored
- in catalog files. The Documentation Project uses standard
- DocBook catalogs and includes additional catalogs for
- &os;-specific features. Paths to the catalog files are defined
- in an environment variable so they can be found by the document
- build tools.</para>
-
- <sect2>
- <title>To Do&hellip;</title>
-
- <para>Before running the examples in this document, install
- <package>textproc/docproj</package> from
- the &os; Ports Collection. This is a
- <emphasis>meta-port</emphasis> that downloads and installs
- the standard programs and supporting files needed by the
- Documentation Project. &man.csh.1; users must use
- <command>rehash</command> for the shell to recognize new
- programs after they have been installed, or log out
- and then log back in again.</para>
-
- <procedure>
- <step>
- <para>Create <filename>example.xml</filename>, and enter
- this text:</para>
-
- <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag>
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para>Try to validate this file using an
- <acronym>XML</acronym> parser.</para>
-
- <para><package>textproc/docproj</package>
- includes the <command>xmllint</command>
- <link linkend="xml-primer-validating">validating
- parser</link>.</para>
-
- <para>Use <command>xmllint</command> to validate the
- document:</para>
-
- <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput></screen>
-
- <para><command>xmllint</command> returns without displaying
- any output, showing that the document validated
- successfully.</para>
- </step>
-
- <step>
- <para>See what happens when required elements are omitted.
- Delete the line with the
- <tag class="starttag">title</tag> and
- <tag class="endtag">title</tag> tags, and re-run
- the validation.</para>
-
- <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput>
-example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen>
-
- <para>This shows that the validation error comes from the
- <replaceable>fifth</replaceable> line of the
- <replaceable>example.xml</replaceable> file and that the
- content of the <tag class="starttag">head</tag> is
- the part which does not follow the rules of the
- <acronym>XHTML</acronym> grammar.</para>
-
- <para>Then <command>xmllint</command> shows the line where
- the error was found and marks the exact character position
- with a <literal>^</literal> sign.</para>
- </step>
-
- <step>
- <para>Replace the <tag>title</tag> element.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-doctype-declaration">
- <title>The DOCTYPE Declaration</title>
-
- <para>The beginning of each document can specify the name of the
- <acronym>DTD</acronym> to which the document conforms. This
- DOCTYPE declaration is used by <acronym>XML</acronym> parsers to
- identify the <acronym>DTD</acronym> and ensure that the document
- does conform to it.</para>
-
- <para>A typical declaration for a document written to conform with
- version 1.0 of the <acronym>XHTML</acronym>
- <acronym>DTD</acronym> looks like this:</para>
-
- <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting>
-
- <para>That line contains a number of different components.</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>&lt;!</literal></term>
-
- <listitem>
- <para>The <emphasis>indicator</emphasis> shows
- this is an <acronym>XML</acronym> declaration.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>DOCTYPE</literal></term>
-
- <listitem>
- <para>Shows that this is an <acronym>XML</acronym>
- declaration of the document type.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>html</literal></term>
-
- <listitem>
- <para>Names the first
- <link linkend="xml-primer-elements">element</link> that
- will appear in the document.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
-
- <listitem>
- <para>Lists the Formal Public Identifier
- (<acronym>FPI</acronym>)
- <indexterm>
- <primary>Formal Public Identifier</primary>
- </indexterm>
- for the <acronym>DTD</acronym> to which this document
- conforms. The <acronym>XML</acronym> parser uses this to
- find the correct <acronym>DTD</acronym> when processing
- this document.</para>
-
- <para><literal>PUBLIC</literal> is not a part of the
- <acronym>FPI</acronym>, but indicates to the
- <acronym>XML</acronym> processor how to find the
- <acronym>DTD</acronym> referenced in the
- <acronym>FPI</acronym>. Other ways of telling the
- <acronym>XML</acronym> parser how to find the
- <acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
-
- <listitem>
- <para>A local filename or a <acronym>URL</acronym> to find
- the <acronym>DTD</acronym>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>&gt;</literal></term>
-
- <listitem>
- <para>Ends the declaration and returns to the
- document.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <sect2>
- <title>Formal Public Identifiers
- (<acronym>FPI</acronym>s)</title>
-
- <indexterm significance="preferred">
- <primary>Formal Public Identifier</primary>
- </indexterm>
-
- <note>
- <para>It is not necessary to know this, but it is useful
- background, and might help debug problems when the
- <acronym>XML</acronym> processor can not locate the
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para><acronym>FPI</acronym>s must follow a specific
- syntax:</para>
-
- <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
-
- <variablelist>
- <varlistentry>
- <term><replaceable>Owner</replaceable></term>
-
- <listitem>
- <para>The owner of the <acronym>FPI</acronym>.</para>
-
- <para>The beginning of the string identifies the owner of
- the <acronym>FPI</acronym>. For example, the
- <acronym>FPI</acronym>
- <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.
- <acronym>ISO</acronym> 8879:1986 is the International
- Organization for Standardization
- (<acronym>ISO</acronym>) number for the
- <acronym>SGML</acronym> standard, the predecessor (and a
- superset) of <acronym>XML</acronym>.</para>
-
- <para>Otherwise, this string will either look like
- <literal>-//<replaceable>Owner</replaceable></literal>
- or
- <literal>+//<replaceable>Owner</replaceable></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> identifying it as
- registered.</para>
-
- <para><acronym>ISO</acronym> 9070:1991 defines how
- registered names are generated. It might be derived
- from the number of an <acronym>ISO</acronym>
- publication, an <acronym>ISBN</acronym> code, or an
- organization code assigned according to
- <acronym>ISO</acronym> 6523. Additionally, a
- registration authority could be created in order to
- assign registered names. The <acronym>ISO</acronym>
- council delegated this to the American National
- Standards Institute (<acronym>ANSI</acronym>).</para>
-
- <para>Because the &os; Project has not been registered,
- the owner string is <literal>-//&os;</literal>. As seen
- in the example, the <acronym>W3C</acronym> 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 <acronym>DTD</acronym> files,
- <literal>ELEMENT</literal> is usually used for
- <acronym>DTD</acronym> fragments that contain only
- entity or element declarations. <literal>TEXT</literal>
- is used for <acronym>XML</acronym> content (text and
- tags).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>Description</replaceable></term>
-
- <listitem>
- <para>Any description can be given for the contents
- of this file. This may include version numbers or any
- short text that is meaningful and unique for the
- <acronym>XML</acronym> system.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>Language</replaceable></term>
-
- <listitem>
- <para>An <acronym>ISO</acronym> 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>With the syntax above, an <acronym>XML</acronym>
- processor needs to have some way of turning the
- <acronym>FPI</acronym> into the name of the file containing
- the <acronym>DTD</acronym>. A catalog file (typically
- called <filename>catalog</filename>) contains lines that map
- <acronym>FPI</acronym>s to filenames. For example, if the
- catalog file contained the line:</para>
-
-<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog -->
-
- <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting>
-
- <para>The <acronym>XML</acronym> processor knows that the
- <acronym>DTD</acronym> is called
- <filename>transitional.dtd</filename> in the
- <filename>1.0</filename> subdirectory of the directory that
- held <filename>catalog</filename>.</para>
-
- <para>Examine the contents of
- <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
- This is the catalog file for the <acronym>XHTML</acronym>
- <acronym>DTD</acronym>s that were installed as part of the
- <package>textproc/docproj</package> port.</para>
- </sect3>
- </sect2>
-
- <sect2 xml:id="xml-primer-fpi-alternatives">
- <title>Alternatives to <acronym>FPI</acronym>s</title>
-
- <para>Instead of using an <acronym>FPI</acronym> to indicate the
- <acronym>DTD</acronym> to which the document conforms (and
- therefore, which file on the system contains the
- <acronym>DTD</acronym>), the filename can be explicitly
- specified.</para>
-
- <para>The syntax is slightly different:</para>
-
- <programlisting><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting>
-
- <para>The <literal>SYSTEM</literal> keyword indicates that the
- <acronym>XML</acronym> processor should locate the
- <acronym>DTD</acronym> in a system specific fashion. This
- typically (but not always) means the <acronym>DTD</acronym>
- will be provided as a filename.</para>
-
- <para>Using <acronym>FPI</acronym>s is preferred for reasons of
- portability. If the <literal>SYSTEM</literal> identifier is
- used, then the <acronym>DTD</acronym> must be provided and
- kept in the same location for everyone.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-xml-escape">
- <title>Escaping Back to <acronym>XML</acronym></title>
-
- <para>Some of the underlying <acronym>XML</acronym> syntax can be
- useful within documents. For example, comments can be included
- in the document, and will be ignored by the parser. Comments
- are entered using <acronym>XML</acronym> syntax. Other uses for
- <acronym>XML</acronym> syntax will be shown later.</para>
-
- <para><acronym>XML</acronym> sections begin with a
- <literal>&lt;!</literal> tag and end with a
- <literal>&gt;</literal>. These sections contain instructions
- for the parser rather than elements of the document. Everything
- between these tags is <acronym>XML</acronym> syntax. The
- <link linkend="xml-primer-doctype-declaration">DOCTYPE
- declaration</link> shown earlier is an example of
- <acronym>XML</acronym> syntax included in the document.</para>
-
- </sect1>
-
- <sect1 xml:id="xml-primer-comments">
- <title>Comments</title>
-
- <para>Comments are an <acronym>XML</acronym> construct, and are
- normally only valid inside a <acronym>DTD</acronym>. However,
- as <xref linkend="xml-primer-xml-escape"/> shows, it is possible
- to use <acronym>XML</acronym> syntax within the document.</para>
-
- <para>The delimiter for XML 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><acronym>XML</acronym> Generic Comment</title>
-
- <programlisting>&lt;!-- This is inside the comment --&gt;
-
-&lt;!-- This is another comment --&gt;
-
-&lt;!-- This is one way
- of doing multiline comments --&gt;
-
-&lt;!-- This is another way of --
- -- doing multiline comments --&gt;</programlisting>
- </example>
-
- <para><acronym>XHTML</acronym> users may be familiar with different
- rules for comments. In particular, it is often believed that
- the string <literal>&lt;!--</literal> opens a comment, and it is
- only closed by <literal>--&gt;</literal>.</para>
-
- <para>This is <emphasis>not</emphasis> correct. Many web browsers
- have broken <acronym>XHTML</acronym> parsers, and will accept
- incorrect input as valid. However, the <acronym>XML</acronym>
- parsers used by the Documentation Project are more strict, and
- will reject documents with that error.</para>
-
- <example>
- <title>Erroneous <acronym>XML</acronym> Comments</title>
-
- <programlisting>&lt;!-- This is in the comment --
-
- THIS IS OUTSIDE THE COMMENT!
-
- -- back inside the comment --&gt;</programlisting>
-
- <para>The <acronym>XML</acronym> parser will treat this as
- though it were actually:</para>
-
- <programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
-
- <para>That is not valid <acronym>XML</acronym>, and may give
- confusing error messages.</para>
- </example>
-
- <sect2>
- <title>To Do&hellip;</title>
-
- <procedure>
- <step>
- <para>Add some comments to
- <filename>example.xml</filename>, and check that the file
- still validates using <command>xmllint</command>.</para>
- </step>
-
- <step>
- <para>Add some invalid comments to
- <filename>example.xml</filename>, and see the error
- messages that <command>xmllint</command> gives when it
- encounters an invalid comment.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-entities">
- <title>Entities</title>
-
- <para>Entities are a mechanism for assigning names to chunks of
- content. As an <acronym>XML</acronym> parser processes a
- 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 <acronym>XML</acronym> documents. It is
- also the only way to include one marked up file inside another
- using <acronym>XML</acronym>.</para>
-
- <para>There are two types of entities for two different
- situations: <emphasis>general entities</emphasis> and
- <emphasis>parameter entities</emphasis>.</para>
-
- <sect2 xml:id="xml-primer-general-entities">
- <title>General Entities</title>
-
- <para>General entities are used to assign names to reusable
- chunks of text. These entities can only be used in the
- document. They cannot be used in an
- <acronym>XML</acronym> context.</para>
-
- <para>To include the text of a general entity in the document,
- include
- <literal>&amp;<replaceable>entity-name</replaceable>;</literal>
- in the text. For example, consider a general entity called
- <literal>current.version</literal> which expands to the
- current version number of a product. To use it in the
- document, write:</para>
-
- <programlisting><tag class="starttag">para</tag>The current version of our product is
- &amp;current.version;.<tag class="endtag">para</tag></programlisting>
-
- <para>When the version number changes, edit the definition of
- the general entity, replacing the value. Then reprocess the
- document.</para>
-
- <para>General entities can also be used to enter characters that
- could not otherwise be included in an <acronym>XML</acronym>
- document. For example, <literal>&lt;</literal> and
- <literal>&amp;</literal> cannot normally appear in an
- <acronym>XML</acronym> document. The <acronym>XML</acronym>
- parser sees the <literal>&lt;</literal> symbol as the start of
- a tag. Likewise, when the <literal>&amp;</literal> symbol is
- seen, the next text is expected to be an entity name.</para>
-
- <para>These symbols can be included by using two predefined
- general entities: <literal>&amp;lt;</literal> and
- <literal>&amp;amp;</literal>.</para>
-
- <para>General entities can only be defined within an
- <acronym>XML</acronym> context. Such definitions are usually
- done immediately after the DOCTYPE declaration.</para>
-
- <example>
- <title>Defining General Entities</title>
-
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY current.version "3.0-RELEASE"&gt;
-&lt;!ENTITY last.version "2.2.7-RELEASE"&gt;
-]&gt;</programlisting>
-
- <para>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, the
- square bracket is closed, and then the DOCTYPE declaration
- is closed.</para>
-
- <para>The square brackets are necessary to indicate that the
- DTD indicated by the DOCTYPE declaration is being
- extended.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="xml-primer-parameter-entities">
- <title>Parameter Entities</title>
-
- <para>Parameter entities, like
- <link linkend="xml-primer-general-entities">general
- entities</link>, are used to assign names to reusable chunks
- of text. But parameter entities can only be used within an
- <link linkend="xml-primer-xml-escape">XML
- context</link>.</para>
-
- <para>Parameter entity definitions are similar to those for
- general entities. However, parameter entries are included
- with
- <literal>%<replaceable>entity-name</replaceable>;</literal>.
- The definition also includes the <literal>%</literal> between
- the <literal>ENTITY</literal> keyword and the name of the
- entity.</para>
-
- <para>For a mnemonic, think
- <quote><emphasis>P</emphasis>arameter entities use the
- <emphasis>P</emphasis>ercent symbol</quote>.</para>
-
- <example>
- <title>Defining Parameter Entities</title>
-
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY % param.some "some"&gt;
-&lt;!ENTITY % param.text "text"&gt;
-&lt;!ENTITY % param.new "%param.some more %param.text"&gt;
-
-&lt;!-- %param.new now contains "some more text" --&gt;
-]&gt;</programlisting>
- </example>
- </sect2>
-
- <sect2>
- <title>To Do&hellip;</title>
-
- <procedure>
- <step>
- <para>Add a general entity to
- <filename>example.xml</filename>.</para>
-
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY version "1.1"&gt;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- &lt;!-- There may be some comments in here as well --&gt;
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para>Validate the document using
- <command>xmllint</command>.</para>
- </step>
-
- <step>
- <para>Load <filename>example.xml</filename> into a web
- browser. It may have to be copied to
- <filename>example.html</filename> before the browser
- recognizes it as an <acronym>XHTML</acronym>
- document.</para>
-
- <para>Older browsers with simple parsers may not render this
- file as expected. The entity reference
- <literal>&amp;version;</literal> may not be replaced by
- the version number, or the <acronym>XML</acronym> context
- closing <literal>]&gt;</literal> may not be recognized and
- instead shown in the output.</para>
- </step>
-
- <step>
- <para>The solution is to <emphasis>normalize</emphasis> the
- document with an <acronym>XML</acronym> normalizer. The
- normalizer reads valid <acronym>XML</acronym> and writes
- equally valid <acronym>XML</acronym> which has been
- transformed in some way. One way the normalizer
- transforms the input is by expanding all the entity
- references in the document, replacing the entities with
- the text that they represent.</para>
-
- <para><command>xmllint</command> can be used for this. It
- also has an option to drop the initial
- <acronym>DTD</acronym> section so that the closing
- <literal>]&gt;</literal> does not confuse browsers:</para>
-
- <screen>&prompt.user; <userinput>xmllint --noent --dropdtd example.xml &gt; example.html</userinput></screen>
-
- <para>A normalized copy of the document with entities
- expanded is produced in <filename>example.html</filename>,
- ready to load into a web browser.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-include">
- <title>Using Entities to Include Files</title>
-
- <para>Both
- <link linkend="xml-primer-general-entities">general</link> and
- <link linkend="xml-primer-parameter-entities">parameter</link>
- entities are particularly useful for including one file inside
- another.</para>
-
- <sect2 xml:id="xml-primer-include-using-gen-entities">
- <title>Using General Entities to Include Files</title>
-
- <para>Consider some content for an <acronym>XML</acronym> 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> that will contain these
- chapters.</para>
-
- <para>In order to use the contents of these files as the values
- for entities, they are declared with the
- <literal>SYSTEM</literal> keyword. This directs the
- <acronym>XML</acronym> parser to include the contents of the
- named file as the value of the entity.</para>
-
- <example>
- <title>Using General Entities to Include Files</title>
-
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY chapter.1 SYSTEM "chapter1.xml"&gt;
-&lt;!ENTITY chapter.2 SYSTEM "chapter2.xml"&gt;
-&lt;!ENTITY chapter.3 SYSTEM "chapter3.xml"&gt;
-&lt;!-- And so forth --&gt;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- &lt;!-- Use the entities to load in the chapters --&gt;
-
- &amp;chapter.1;
- &amp;chapter.2;
- &amp;chapter.3;
-<tag class="endtag">html</tag></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 because entities are
- low-level constructs and they are resolved before any
- parsing happens.</para>
- </warning>
- </sect2>
-
- <sect2>
- <title>Using Parameter Entities to Include Files</title>
-
- <para>Parameter entities can only be used inside an
- <acronym>XML</acronym> context. Including a file in an
- <acronym>XML</acronym> context can be used
- to ensure that general entities are reusable.</para>
-
- <para>Suppose that there are many chapters in the document, and
- these chapters were reused in two different books, each book
- organizing the chapters in a different fashion.</para>
-
- <para>The entities could be listed at the top of each book, but
- that 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
- the document.</para>
-
- <example>
- <title>Using Parameter Entities to Include Files</title>
-
- <para>Place the entity definitions in a separate file
- called <filename>chapters.ent</filename> and
- containing this text:</para>
-
- <programlisting>&lt;!ENTITY chapter.1 SYSTEM "chapter1.xml"&gt;
-&lt;!ENTITY chapter.2 SYSTEM "chapter2.xml"&gt;
-&lt;!ENTITY chapter.3 SYSTEM "chapter3.xml"&gt;</programlisting>
-
- <para>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>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!-- Define a parameter entity to load in the chapter general entities --&gt;
-&lt;!ENTITY % chapters SYSTEM "chapters.ent"&gt;
-
-&lt;!-- Now use the parameter entity to load in this file --&gt;
-%chapters;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- &amp;chapter.1;
- &amp;chapter.2;
- &amp;chapter.3;
-<tag class="endtag">html</tag></programlisting>
- </example>
- </sect2>
-
- <sect2>
- <title>To Do&hellip;</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 like this in each file:</para>
-
- <programlisting><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting>
- </step>
-
- <step>
- <para>Edit <filename>example.xml</filename> so that it
- looks like this:</para>
-
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY version "1.1"&gt;
-&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
-&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
-&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
-
- &amp;para1;
- &amp;para2;
- &amp;para3;
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para>Produce <filename>example.html</filename> by
- normalizing <filename>example.xml</filename>.</para>
-
- <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
- </step>
-
- <step>
- <para>Load <filename>example.html</filename> into the web
- browser and confirm that the
- <filename>para<replaceable>n</replaceable>.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>The previous steps must have completed before this
- step.</para>
- </note>
-
- <procedure>
- <step>
- <para>Edit <filename>example.xml</filename> so that it
- looks like this:</para>
-
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY % entities SYSTEM "entities.ent"&gt; %entities;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
-
- &amp;para1;
- &amp;para2;
- &amp;para3;
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para>Create a new file called
- <filename>entities.ent</filename> with this
- content:</para>
-
- <programlisting>&lt;!ENTITY version "1.1"&gt;
-&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
-&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
-&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;</programlisting>
- </step>
-
- <step>
- <para>Produce <filename>example.html</filename> by
- normalizing <filename>example.xml</filename>.</para>
-
- <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
- </step>
-
- <step>
- <para>Load <filename>example.html</filename> into the web
- browser and confirm that the
- <filename>para<replaceable>n</replaceable>.xml</filename>
- files have been included in
- <filename>example.html</filename>.</para>
- </step>
- </procedure>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-marked-sections">
- <title>Marked Sections</title>
-
- <para><acronym>XML</acronym> provides a mechanism to indicate that
- particular pieces of the document should be processed in a
- special way. These are called
- <quote>marked sections</quote>.</para>
-
- <example>
- <title>Structure of a Marked Section</title>
-
- <programlisting>&lt;![<replaceable>KEYWORD</replaceable>[
- Contents of marked section
-]]&gt;</programlisting>
- </example>
-
- <para>As expected of an <acronym>XML</acronym> construct, a marked
- section starts with <literal>&lt;!</literal>.</para>
-
- <para>The first square bracket begins the marked section.</para>
-
- <para><replaceable>KEYWORD</replaceable> describes how this marked
- section is to be processed by the parser.</para>
-
- <para>The second square bracket indicates the start of the
- marked section's content.</para>
-
- <para>The marked section is finished by closing the two square
- brackets, and then returning to the document context from the
- <acronym>XML</acronym> context with
- <literal>&gt;</literal>.</para>
-
- <sect2 xml:id="xml-primer-marked-section-keywords">
- <title>Marked Section Keywords</title>
-
- <sect3 xml:id="xml-primer-cdata">
- <title><literal>CDATA</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 <acronym>XML</acronym> parser is processing a
- document, it keeps track of the
- <quote>content model</quote>.</para>
-
- <para>The content model describes the
- content the parser is expecting to see and what it will do
- with that content.</para>
-
- <para>The <literal>CDATA</literal> content model is one of the
- most useful.</para>
-
- <para><literal>CDATA</literal> is for
- <quote>Character Data</quote>. When the parser is in this
- content model, it expects to see only characters. In this
- model the <literal>&lt;</literal> and
- <literal>&amp;</literal> symbols lose their special status,
- and will be treated as ordinary characters.</para>
-
- <note>
- <para>When using <literal>CDATA</literal> in examples of
- text marked up in <acronym>XML</acronym>, remember that
- the content of <literal>CDATA</literal> is not validated.
- The included text must be check with other means. For
- example, the content could be written in another document,
- validated, and then pasted into the
- <literal>CDATA</literal> section.</para>
- </note>
-
- <example>
- <title>Using a <literal>CDATA</literal> Marked
- Section</title>
-
- <programlisting><tag class="starttag">para</tag>Here is an example of how to include some text that contains
- many <tag class="starttag">literal</tag>&amp;lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;amp;<tag class="endtag">literal</tag>
- symbols. The sample text is a fragment of
- <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and
- <tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag>
-
-<tag class="starttag">programlisting</tag>&lt;![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the
- elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. 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.<tag class="endtag">p</tag>
-
- <tag class="starttag">ul</tag>
- <tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag>
- <tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag>
- <tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag>
- <tag class="endtag">ul</tag>
-
- <tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]&gt;<tag class="endtag">programlisting</tag></programlisting>
- </example>
- </sect3>
-
- <sect3 xml:id="xml-primer-include-ignore">
- <title><literal>INCLUDE</literal> and
- <literal>IGNORE</literal></title>
-
- <para>When the keyword is <literal>INCLUDE</literal>, then the
- contents of the marked section will be processed. When the
- keyword is <literal>IGNORE</literal>, 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>&lt;![INCLUDE[
- This text will be processed and included.
-]]&gt;
-
-&lt;![IGNORE[
- This text will not be processed or included.
-]]&gt;</programlisting>
- </example>
-
- <para>By itself, this is not too useful. Text to be
- removed from the document could be cut out, or wrapped
- in comments.</para>
-
- <para>It becomes more useful when controlled by
- <link linkend="xml-primer-parameter-entities">parameter
- entities</link>, yet this usage is limited
- to entity files.</para>
-
- <para>For example, suppose that documentation was produced in
- a hard-copy version and an electronic version. Some extra
- text is desired in the electronic version content that was
- not to appear in the hard-copy.</para>
-
- <para>Create an entity file that defines general entities to
- include each chapter and guard these definitions with a
- parameter entity that can be set to either
- <literal>INCLUDE</literal> or <literal>IGNORE</literal> to
- control whether the entity is defined. After these
- conditional general entity definitions, place one more
- definition for each general entity to set them to an empty
- value. This technique makes use of the fact that entity
- definitions cannot be overridden but the first definition
- always takes effect. So the inclusion of the chapter is
- controlled with the corresponding parameter entity. Set to
- <literal>INCLUDE</literal>, the first general entity
- definition will be read and the second one will be ignored.
- Set to <literal>IGNORE</literal>, the first definition will
- be ignored and the second one will take effect.</para>
-
- <example>
- <title>Using a Parameter Entity to Control a Marked
- Section</title>
-
- <programlisting>&lt;!ENTITY % electronic.copy "INCLUDE"&gt;
-
-&lt;![%electronic.copy;[
-&lt;!ENTITY chap.preface SYSTEM "preface.xml"&gt;
-]]&gt;
-
-&lt;!ENTITY chap.preface ""&gt;</programlisting>
-
- <para>When producing the hard-copy version, change the
- parameter entity's definition to:</para>
-
- <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"&gt;</programlisting>
- </example>
- </sect3>
- </sect2>
-
- <sect2>
- <title>To Do&hellip;</title>
-
- <procedure>
- <step>
- <para>Modify <filename>entities.ent</filename> to
- contain the following:</para>
-
- <programlisting>&lt;!ENTITY version "1.1"&gt;
-&lt;!ENTITY % conditional.text "IGNORE"&gt;
-
-&lt;![%conditional.text;[
-&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
-]]&gt;
-
-&lt;!ENTITY para1 ""&gt;
-
-&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
-&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;</programlisting>
- </step>
-
- <step>
- <para>Normalize <filename>example.xml</filename>
- and notice that the conditional text is not present in the
- output document. Set the parameter entity
- guard to <literal>INCLUDE</literal> and regenerate the
- normalized document and the text will appear again.
- This method makes sense if there are more
- conditional chunks depending on the same condition. For
- example, to control generating printed or online
- text.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-conclusion">
- <title>Conclusion</title>
-
- <para>That is the conclusion of this <acronym>XML</acronym>
- primer. For reasons of space and complexity, several things
- have not been covered in depth (or at all). However, the
- previous sections cover enough <acronym>XML</acronym> to
- introduce the organization of the <acronym>FDP</acronym>
- documentation.</para>
- </sect1>
-</chapter>