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

Remove unnecessary files.

Browse source
This commit is contained in:
Warren Block 2015-10-31 20:45:54 +00:00
parent 6457f53b95
commit 4f25f34ddd
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=47716
18 changed files with 0 additions and 8987 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
nl_NL.ISO8859-1/books/fdp-primer/chapters.ent
View file

@ -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">

529
nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
View file

@ -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>

2744
nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
View file

File diff suppressed because it is too large Load diff

170
nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml
View file

@ -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>

162
nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml
View file

@ -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>

255
nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml
View file

@ -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>

823
nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
View file

@ -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>

171
nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml
View file

@ -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>

108
nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml
View file

@ -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>

305
nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml
View file

@ -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>

75
nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml
View file

@ -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>

200
nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml
View file

@ -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>

141
nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml
View file

@ -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>

473
nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml
View file

@ -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>

177
nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml
View file

@ -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>

592
nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
View file

@ -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>

600
nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
View file

@ -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>

1433
nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
View file

File diff suppressed because it is too large Load diff