aboutsummaryrefslogtreecommitdiff
path: root/nl_NL.ISO8859-1
diff options
context:
space:
mode:
authorSergio Carlavilla Delgado <carlavilla@FreeBSD.org>2021-01-25 23:31:29 +0000
committerSergio Carlavilla Delgado <carlavilla@FreeBSD.org>2021-01-25 23:31:29 +0000
commit989d921f5d4ac8d8b7c831c13b8954ad1901be24 (patch)
treea5d768f9af4b55422fdf5b17064879ae1c7ce032 /nl_NL.ISO8859-1
parent0cff342f42461c5081b98bce7581f43df319e4f4 (diff)
downloaddoc-989d921f5d4ac8d8b7c831c13b8954ad1901be24.tar.gz
doc-989d921f5d4ac8d8b7c831c13b8954ad1901be24.zip
Migrate doc to Hugo/AsciiDoctor
I'm very pleased to announce the release of our new website and documentation using the new toolchain with Hugo and AsciiDoctor. To get more information about the new toolchain please read the FreeBSD Documentation Project Primer[1], Hugo docs[2] and AsciiDoctor docs[3]. Acknowledgment: Benedict Reuschling <bcr@> Glen Barber <gjb@> Hiroki Sato <hrs@> Li-Wen Hsu <lwhsu@> Sean Chittenden <seanc@> The FreeBSD Foundation [1] https://docs.FreeBSD.org/en/books/fdp-primer/ [2] https://gohugo.io/documentation/ [3] https://docs.asciidoctor.org/home/ Approved by: doceng, core
Diffstat (limited to 'nl_NL.ISO8859-1')
-rw-r--r--nl_NL.ISO8859-1/Makefile13
-rw-r--r--nl_NL.ISO8859-1/Makefile.inc3
-rw-r--r--nl_NL.ISO8859-1/articles/Makefile11
-rw-r--r--nl_NL.ISO8859-1/articles/Makefile.inc7
-rw-r--r--nl_NL.ISO8859-1/articles/contributing/Makefile22
-rw-r--r--nl_NL.ISO8859-1/articles/contributing/article.xml543
-rw-r--r--nl_NL.ISO8859-1/articles/explaining-bsd/Makefile22
-rw-r--r--nl_NL.ISO8859-1/articles/explaining-bsd/article.xml286
-rw-r--r--nl_NL.ISO8859-1/articles/explaining-bsd/nl_NL.po1176
-rw-r--r--nl_NL.ISO8859-1/articles/leap-seconds/Makefile19
-rw-r--r--nl_NL.ISO8859-1/articles/leap-seconds/article.xml64
-rw-r--r--nl_NL.ISO8859-1/articles/leap-seconds/nl_NL.po138
-rw-r--r--nl_NL.ISO8859-1/articles/problem-reports/Makefile22
-rw-r--r--nl_NL.ISO8859-1/articles/problem-reports/article.xml1331
-rw-r--r--nl_NL.ISO8859-1/articles/solid-state/Makefile20
-rw-r--r--nl_NL.ISO8859-1/articles/solid-state/article.xml509
-rw-r--r--nl_NL.ISO8859-1/articles/solid-state/nl_NL.po510
-rw-r--r--nl_NL.ISO8859-1/books/Makefile12
-rw-r--r--nl_NL.ISO8859-1/books/Makefile.inc8
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/Makefile27
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/book.xml9003
-rw-r--r--nl_NL.ISO8859-1/books/fdp-primer/nl_NL.po9504
-rw-r--r--nl_NL.ISO8859-1/books/handbook/Makefile326
-rw-r--r--nl_NL.ISO8859-1/books/handbook/advanced-networking/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/advanced-networking/chapter.xml6346
-rw-r--r--nl_NL.ISO8859-1/books/handbook/audit/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/audit/chapter.xml777
-rw-r--r--nl_NL.ISO8859-1/books/handbook/basics/Makefile17
-rw-r--r--nl_NL.ISO8859-1/books/handbook/basics/chapter.xml2968
-rw-r--r--nl_NL.ISO8859-1/books/handbook/basics/example-dir1.dot7
-rw-r--r--nl_NL.ISO8859-1/books/handbook/basics/example-dir2.dot8
-rw-r--r--nl_NL.ISO8859-1/books/handbook/basics/example-dir3.dot8
-rw-r--r--nl_NL.ISO8859-1/books/handbook/basics/example-dir4.dot9
-rw-r--r--nl_NL.ISO8859-1/books/handbook/basics/example-dir5.dot9
-rw-r--r--nl_NL.ISO8859-1/books/handbook/bibliography/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/bibliography/chapter.xml541
-rw-r--r--nl_NL.ISO8859-1/books/handbook/book.xml303
-rw-r--r--nl_NL.ISO8859-1/books/handbook/boot/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/boot/chapter.xml1076
-rw-r--r--nl_NL.ISO8859-1/books/handbook/bsdinstall/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/bsdinstall/chapter.xml36
-rw-r--r--nl_NL.ISO8859-1/books/handbook/chapters.ent74
-rw-r--r--nl_NL.ISO8859-1/books/handbook/colophon.xml20
-rw-r--r--nl_NL.ISO8859-1/books/handbook/config/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/config/chapter.xml3585
-rw-r--r--nl_NL.ISO8859-1/books/handbook/cutting-edge/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/cutting-edge/chapter.xml3209
-rw-r--r--nl_NL.ISO8859-1/books/handbook/desktop/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/desktop/chapter.xml1445
-rw-r--r--nl_NL.ISO8859-1/books/handbook/disks/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/disks/chapter.xml4875
-rw-r--r--nl_NL.ISO8859-1/books/handbook/dtrace/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/dtrace/chapter.xml398
-rw-r--r--nl_NL.ISO8859-1/books/handbook/eresources/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/eresources/chapter.xml2442
-rw-r--r--nl_NL.ISO8859-1/books/handbook/filesystems/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/filesystems/chapter.xml898
-rw-r--r--nl_NL.ISO8859-1/books/handbook/firewalls/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/firewalls/chapter.xml3535
-rw-r--r--nl_NL.ISO8859-1/books/handbook/geom/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/geom/chapter.xml1322
-rw-r--r--nl_NL.ISO8859-1/books/handbook/install/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/install/chapter.xml5189
-rw-r--r--nl_NL.ISO8859-1/books/handbook/install/example-dir1.dot7
-rw-r--r--nl_NL.ISO8859-1/books/handbook/install/example-dir2.dot8
-rw-r--r--nl_NL.ISO8859-1/books/handbook/install/example-dir3.dot8
-rw-r--r--nl_NL.ISO8859-1/books/handbook/install/example-dir4.dot9
-rw-r--r--nl_NL.ISO8859-1/books/handbook/install/example-dir5.dot9
-rw-r--r--nl_NL.ISO8859-1/books/handbook/introduction/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/introduction/chapter.xml975
-rw-r--r--nl_NL.ISO8859-1/books/handbook/jails/Makefile19
-rw-r--r--nl_NL.ISO8859-1/books/handbook/jails/chapter.xml1043
-rw-r--r--nl_NL.ISO8859-1/books/handbook/kernelconfig/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/kernelconfig/chapter.xml1636
-rw-r--r--nl_NL.ISO8859-1/books/handbook/l10n/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/l10n/chapter.xml1049
-rw-r--r--nl_NL.ISO8859-1/books/handbook/linuxemu/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/linuxemu/chapter.xml1427
-rw-r--r--nl_NL.ISO8859-1/books/handbook/mac/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/mac/chapter.xml2160
-rw-r--r--nl_NL.ISO8859-1/books/handbook/mail/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/mail/chapter.xml2210
-rw-r--r--nl_NL.ISO8859-1/books/handbook/mirrors/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/mirrors/chapter.xml3442
-rw-r--r--nl_NL.ISO8859-1/books/handbook/multimedia/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/multimedia/chapter.xml1982
-rw-r--r--nl_NL.ISO8859-1/books/handbook/network-servers/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/network-servers/chapter.xml5982
-rwxr-xr-xnl_NL.ISO8859-1/books/handbook/nl_NL.po110989
-rw-r--r--nl_NL.ISO8859-1/books/handbook/pgpkeys/Makefile22
-rw-r--r--nl_NL.ISO8859-1/books/handbook/pgpkeys/chapter.xml50
-rw-r--r--nl_NL.ISO8859-1/books/handbook/ports/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/ports/chapter.xml1754
-rw-r--r--nl_NL.ISO8859-1/books/handbook/ppp-and-slip/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml3292
-rw-r--r--nl_NL.ISO8859-1/books/handbook/preface/preface.xml830
-rw-r--r--nl_NL.ISO8859-1/books/handbook/printing/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/printing/chapter.xml5250
-rw-r--r--nl_NL.ISO8859-1/books/handbook/security/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/security/chapter.xml4222
-rw-r--r--nl_NL.ISO8859-1/books/handbook/serialcomms/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/serialcomms/chapter.xml3289
-rw-r--r--nl_NL.ISO8859-1/books/handbook/txtfiles.ent74
-rw-r--r--nl_NL.ISO8859-1/books/handbook/users/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/users/chapter.xml1169
-rw-r--r--nl_NL.ISO8859-1/books/handbook/vinum/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/vinum/chapter.xml1352
-rw-r--r--nl_NL.ISO8859-1/books/handbook/virtualization/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/virtualization/chapter.xml1287
-rw-r--r--nl_NL.ISO8859-1/books/handbook/x11/Makefile18
-rw-r--r--nl_NL.ISO8859-1/books/handbook/x11/chapter.xml1774
-rw-r--r--nl_NL.ISO8859-1/flyer/Makefile19
-rw-r--r--nl_NL.ISO8859-1/flyer/flyer.tex222
-rw-r--r--nl_NL.ISO8859-1/htdocs/4xx.xml29
-rw-r--r--nl_NL.ISO8859-1/htdocs/Makefile90
-rw-r--r--nl_NL.ISO8859-1/htdocs/Makefile.inc6
-rw-r--r--nl_NL.ISO8859-1/htdocs/about.xml111
-rw-r--r--nl_NL.ISO8859-1/htdocs/administration.xml491
-rw-r--r--nl_NL.ISO8859-1/htdocs/applications.xml155
-rw-r--r--nl_NL.ISO8859-1/htdocs/art.xml140
-rw-r--r--nl_NL.ISO8859-1/htdocs/community.xsl134
-rw-r--r--nl_NL.ISO8859-1/htdocs/doc/Makefile47
-rw-r--r--nl_NL.ISO8859-1/htdocs/docs.xml25
-rw-r--r--nl_NL.ISO8859-1/htdocs/features.xml136
-rw-r--r--nl_NL.ISO8859-1/htdocs/index.xsl322
-rw-r--r--nl_NL.ISO8859-1/htdocs/internet.xml149
-rw-r--r--nl_NL.ISO8859-1/htdocs/logo.xml121
-rw-r--r--nl_NL.ISO8859-1/htdocs/mailto.xml55
-rw-r--r--nl_NL.ISO8859-1/htdocs/privacy.xml194
-rw-r--r--nl_NL.ISO8859-1/htdocs/publish.xml708
-rw-r--r--nl_NL.ISO8859-1/htdocs/relnotes.xml160
-rw-r--r--nl_NL.ISO8859-1/htdocs/send-pr.xml169
-rw-r--r--nl_NL.ISO8859-1/htdocs/support.xml52
-rw-r--r--nl_NL.ISO8859-1/htdocs/where.xml259
-rw-r--r--nl_NL.ISO8859-1/share/tools/checkupdate/notify6
-rw-r--r--nl_NL.ISO8859-1/share/xml/bibliography.xml931
-rw-r--r--nl_NL.ISO8859-1/share/xml/catalog.xml43
-rw-r--r--nl_NL.ISO8859-1/share/xml/entities.ent29
-rw-r--r--nl_NL.ISO8859-1/share/xml/glossary.ent2084
-rw-r--r--nl_NL.ISO8859-1/share/xml/header.l10n.ent124
-rw-r--r--nl_NL.ISO8859-1/share/xml/l10n.ent40
-rw-r--r--nl_NL.ISO8859-1/share/xml/libcommon.xsl415
-rw-r--r--nl_NL.ISO8859-1/share/xml/mailing-lists.ent625
-rw-r--r--nl_NL.ISO8859-1/share/xml/mirrors-local.xsl33
-rw-r--r--nl_NL.ISO8859-1/share/xml/navibar.l10n.ent199
-rw-r--r--nl_NL.ISO8859-1/share/xml/newsgroups.ent13
-rw-r--r--nl_NL.ISO8859-1/share/xml/release.l10n.ent127
-rw-r--r--nl_NL.ISO8859-1/share/xml/teams.ent49
-rw-r--r--nl_NL.ISO8859-1/share/xml/trademarks.ent404
-rw-r--r--nl_NL.ISO8859-1/share/xml/translators.ent8
-rw-r--r--nl_NL.ISO8859-1/share/xml/transtable-local.xsl28
-rw-r--r--nl_NL.ISO8859-1/share/xml/transtable.xml373
152 files changed, 0 insertions, 229912 deletions
diff --git a/nl_NL.ISO8859-1/Makefile b/nl_NL.ISO8859-1/Makefile
deleted file mode 100644
index 74db4ab004..0000000000
--- a/nl_NL.ISO8859-1/Makefile
+++ /dev/null
@@ -1,13 +0,0 @@
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/Makefile
-# %SRCID% 38826
-#
-
-SUBDIR = articles
-SUBDIR+= books
-
-COMPAT_SYMLINK = nl
-
-DOC_PREFIX?= ${.CURDIR}/..
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/Makefile.inc b/nl_NL.ISO8859-1/Makefile.inc
deleted file mode 100644
index 453700a49b..0000000000
--- a/nl_NL.ISO8859-1/Makefile.inc
+++ /dev/null
@@ -1,3 +0,0 @@
-# $FreeBSD$
-
-DOC_PREFIX?= ${.CURDIR}/../..
diff --git a/nl_NL.ISO8859-1/articles/Makefile b/nl_NL.ISO8859-1/articles/Makefile
deleted file mode 100644
index 32c1b35a29..0000000000
--- a/nl_NL.ISO8859-1/articles/Makefile
+++ /dev/null
@@ -1,11 +0,0 @@
-# $FreeBSD$
-
-SUBDIR =
-SUBDIR+= contributing
-SUBDIR+= explaining-bsd
-SUBDIR+= leap-seconds
-SUBDIR+= problem-reports
-SUBDIR+= solid-state
-
-DOC_PREFIX?= ${.CURDIR}/../..
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/articles/Makefile.inc b/nl_NL.ISO8859-1/articles/Makefile.inc
deleted file mode 100644
index 1377b681e7..0000000000
--- a/nl_NL.ISO8859-1/articles/Makefile.inc
+++ /dev/null
@@ -1,7 +0,0 @@
-#
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/articles/Makefile.inc
-# %SRCID% 39534
-
-DESTDIR?= ${DOCDIR}/nl_NL.ISO8859-1/articles/${.CURDIR:T}
diff --git a/nl_NL.ISO8859-1/articles/contributing/Makefile b/nl_NL.ISO8859-1/articles/contributing/Makefile
deleted file mode 100644
index 900332688a..0000000000
--- a/nl_NL.ISO8859-1/articles/contributing/Makefile
+++ /dev/null
@@ -1,22 +0,0 @@
-#
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/articles/contributing/Makefile
-# %SRCID% 39631
-#
-# Article: Contributing to FreeBSD
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?=gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/articles/contributing/article.xml b/nl_NL.ISO8859-1/articles/contributing/article.xml
deleted file mode 100644
index e5033f159b..0000000000
--- a/nl_NL.ISO8859-1/articles/contributing/article.xml
+++ /dev/null
@@ -1,543 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
-<!--
- $FreeBSD$
-
- %SOURCE% en_US.ISO8859-1/articles/contributing/article.xml
- %SRCID% 41645
--->
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="nl">
- <info><title>Bijdragen aan &os;</title>
-
-
- <abstract>
- <para><emphasis>Vertaald door Renť Ladan</emphasis>.</para>
-
- <para>Dit artikel beschrijft de verschillende manieren waarop een
- individu of organisatie kan bijdragen aan het &os;
- Project.</para>
- </abstract>
-
- <authorgroup>
- <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Bijgedragen door </contrib></author>
- </authorgroup>
-
- <legalnotice xml:id="trademarks" role="trademarks">
- &tm-attrib.freebsd;
- &tm-attrib.ieee;
- &tm-attrib.general;
- </legalnotice>
-
- <pubdate>$FreeBSD$</pubdate>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
- </info>
-
- <indexterm><primary>bijdragen</primary></indexterm>
-
- <para>Dus u wilt bijdragen aan &os;? Dat is mooi! &os;
- <emphasis>bouwt</emphasis> op de bijdragen van zijn gebruikers om te
- overleven. Uw bijdragen worden niet alleen gewaardeerd, ze zijn van
- vitaal belang voor de aanhoudende groei van &os;.</para>
-
- <para>In tegenstelling tot wat sommige mensen u laten geloven, hoeft u
- geen doorgewinterde programmeur of een goede vriend van het coreteam
- van &os; te zijn opdat uw bijdragen geaccepteerd worden. Een groot
- en groeiend aantal internationale bijdragende vrijwilligers, van een
- grote variŽteit aan leeftijden en technische expertisegebieden,
- ontwikkelen &os;. Er is altijd meer werk te doen dan dat er mensen
- zijn om het uit te voeren, en meer hulp wordt altijd
- gewaardeerd.</para>
-
- <para>Het &os; project is verantwoordelijk voor een complete omgeving
- van een besturingssysteem, en niet slechts voor alleen een kernel of
- een paar verspreide gereedschappen. Hierom staan op onze
- <filename>TODO</filename>-lijsten een groot aantal verschillende
- taken: van documentatie, beta-testing en -presentatie, tot de
- systeeminstaller en ver gespecialiseerde soorten van
- kernelontwikkeling. Mensen van alle niveaus op bijna alle gebieden
- kunnen zeer waarschijnlijk meehelpen aan het project.</para>
-
- <para>CommerciŽle entiteiten die betrokken zijn in
- &os;-gerelateerde ondernemingen worden ook aangemoedigd om contact
- met ons op te nemen. Heeft u een speciale uitbreiding nodig om uw
- product te laten werken? U zult zien dat wij ontvankelijk zijn voor
- uw verzoeken, op de voorwaarde dat ze niet te vreemdsoortig zijn.
- Werkt u aan een product met toegevoegde waarde? Laat het ons weten!
- Misschien kunnen we op sommige punten samenwerken. De wereld van
- vrije software heeft te maken met vele bestaande aannamen over hoe
- software wordt ontwikkeld, verkocht, en onderhouden, en we verzoeken
- u om er op zijn minst nog eens naar te kijken.</para>
-
- <sect1 xml:id="contrib-what">
- <title>Wat is er nodig</title>
-
- <para>De onderstaande lijst van taken en deelprojecten representeert
- een soort amalgaam van verschillende
- <filename>TODO</filename>-lijsten en verzoeken van
- gebruikers.</para>
-
- <sect2 xml:id="non-programmer-tasks">
- <title>Voortdurende taken voor niet-programmeurs</title>
-
- <para>Veel mensen die betrokken zijn bij &os; zijn geen
- programmeurs. Het Project omvat documentatieschrijvers,
- Webontwerpers, en mensen ter ondersteuning. Deze mensen hoeven
- alleen een tijdsinvestering en een wil om te leren bij te
- dragen.</para>
-
- <orderedlist>
- <listitem>
- <para>Lees regelmatig de FAQ en het Handboek door. Laat het
- ons weten als er iets slecht is uitgelegd, is verlopen of
- gewoon helemaal verkeerd is. Of stuur een reparatie in
- (Docbook is niet moeilijk te leren, maar er is geen bezwaar
- tegen inzendingen in ASCII).</para>
- </listitem>
-
- <listitem>
- <para>Help bij het vertalen van &os;-documentatie in uw eigen
- taal. Als er al documentatie in uw taal bestaat, kunt u
- helpen door aanvullende documenten te vertalen of te
- controleren dat de vertalingen up-to-date zijn. Kijk eerst
- op <link xlink:href="&url.books.fdp-primer.en;/translations.html">Translations
- FAQ</link> in de &os; Documentation Project Primer. U
- bindt zich niet aan het vertalen van elk &os;-document door
- dit te doen &mdash; als vrijwilliger kunt u zo veel of zo
- weinig vertalen als u wilt. Als iemand eenmaal begint te
- vertalen, sluiten andere mensen zich hier bijna altijd bij
- aan. Als u slechts de tijd of energie heeft om
- ťťn document te vertalen, vertaal dan
- alstublieft de installatie-instructies.</para>
- </listitem>
-
- <listitem>
- <para>Lees af en toe (of regelmatig) de &a.questions; en
- &ng.misc;. Het kan veel voldoening geven om uw expertise te
- delen en mensen helpen met het oplossen van hun problemen;
- soms leert u zelf misschien iets nieuws! Deze fora kunnen
- ook een inspiratiebron zijn voor dingen om aan te
- werken.</para>
- </listitem>
- </orderedlist>
- </sect2>
-
- <sect2 xml:id="ongoing-programmer-tasks">
- <title>Voortdurende taken voor programmeurs</title>
-
- <para>Voor de meeste van de hier genoemde taken is een
- aanzienlijke tijdsinvestering, of diepe kennis van de kernel van
- &os;, of beide nodig. Er zijn echter ook vele nuttige taken die
- geschikt zijn voor <quote>weekend hackers</quote>.</para>
-
- <orderedlist>
- <listitem>
- <para>Als u &os;-CURRENT draait en een goede
- Internetverbinding heeft, dan is er een machine <systemitem class="fqdomainname">current.FreeBSD.org</systemitem> die elke dag een
- volledige uitgave bouwt&mdash;probeer zo nu en dan om de
- nieuwste uitgave ervan te installeren en rapporteer alle
- fouten in het proces.</para>
- </listitem>
-
- <listitem>
- <para>Lees de &a.bugs;. Er kunnen problemen zijn waarop u
- constructief commentaar kunt geven of waarvoor u testbare
- patches kunt geven. U kunt zelfs proberen om een van de
- problemen zelf op te lossen.</para>
- </listitem>
-
- <listitem>
- <para>Als u bugfixes weet die succesvol op -CURRENT zijn
- toegepast maar nog niet na een redelijk interval naar
- -STABLE zijn samengevoegd (normaliter een aantal weken),
- stuur de committer dan een beleefde herinnering.</para>
- </listitem>
-
- <listitem>
- <para>Verplaats bijgedragen software naar
- <filename>src/contrib</filename> in de
- broncodeboom.</para>
- </listitem>
-
- <listitem>
- <para>Verzeker dat de code in <filename>src/contrib</filename> up-to-date
- is.</para>
- </listitem>
-
- <listitem>
- <para>Bouw de broncodeboom (of slechts een gedeelte ervan) met
- extra waarschuwingen aangezet en ruim de waarschuwingen
- op.</para>
- </listitem>
-
- <listitem>
- <para>Repareer waarschuwingen voor ports die verouderde dingen
- zoals <function>gets()</function> of
- <filename>malloc.h</filename> gebruiken.</para>
- </listitem>
-
- <listitem>
- <para>Als u ports heeft bijgedragen en u &os;-specifieke
- veranderingen moest maken, stuur dan uw patches terug naar
- de originele auteurs (dit maakt het gemakkelijker
- voor u wanneer ze de volgende versie uitbrengen).</para>
- </listitem>
-
- <listitem>
- <para>Verkrijg kopieŽn van formele standaarden zoals
- &posix;. Enkele links over deze standaarden staan op de
- website van het <link xlink:href="&url.base;/projects/c99/index.html">&os; C99 &amp; POSIX
- Standards Conformance Project</link>. Vergelijk het
- gedrag van &os; met dat wat de standaard voorschrijft. Als
- het gedrag verschilt, met name in subtiele of obscure
- gedeelten van de specificatie, stuur er dan een PR over op.
- Indien mogelijk, zoek uit hoe het te repareren en voeg een
- patch bij het PR. Als u meent dat de standaard verkeerd is,
- vraag dan het standaardorgaan om de vraag te
- overwegen.</para>
- </listitem>
-
- <listitem>
- <para>Suggereer verdere taken voor deze lijst!</para>
- </listitem>
- </orderedlist>
- </sect2>
-
- <sect2>
- <title>Spit de PR-database door</title>
-
- <indexterm><primary>probleemrapportdatabase</primary></indexterm>
-
- <para>De <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">&os;
- PR-lijst</link> laat alle huidige actieve probleemrapportages
- en verzoeken voor verrijkingen zien die door gebruikers van &os;
- zijn ingestuurd. De PR-database bevat zowel taken voor
- programmeurs als voor niet-programmeurs. Bekijk de open PR's,
- en kijk of iets uw interesse wekt. Sommige van deze kunnen heel
- simpele taken zijn waarvoor gewoon een extra paar ogen nodig is
- om te bevestigen dat de reparatie in de PR een goede is. Andere
- kunnen veel complexer zijn, of bevatten in het geheel geen
- reparatie.</para>
-
- <para>Begin met de PR's die nog niet aan iemand anders zijn
- toegekend. Als een PR aan iemand anders is toegekend, maar het
- eruit ziet als iets wat u aankunt, stuur dan een email naar de
- persoon waaraan het is toegekend en vraag of u eraan kunt werken
- &mdash;ze kunnen al een patch hebben die klaar is om getest te
- worden, of verdere ideeŽn hebben die u met ze kan
- bespreken.</para>
- </sect2>
-
- <sect2>
- <title>Kies een van de punten van de <quote>IdeeŽn</quote>
- pagina</title>
-
- <para>De <link xlink:href="http://wiki.freebsd.org/IdeasPage">&os;-lijst van
- projecten en ideeŽn voor vrijwilligers</link> is ook
- beschikbaar voor mensen die aan het &os;-project willen
- bijdragen. Deze lijst wordt regelmatig bijgewerkt en bevat
- punten voor zowel programmeurs als niet-programmeurs met
- informatie over elk project.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="contrib-how">
- <title>Hoe bij te dragen</title>
-
- <para>Bijdragen aan het systeem vallen over het algemeen in
- ťťn of meer van de volgende 5
- categoriŽn:</para>
-
- <sect2 xml:id="contrib-general">
- <title>Foutrapportages en algemeen commentaar</title>
-
- <para>Een idee of suggestie van <emphasis>algemene</emphasis>
- technische aard dient naar &a.hackers; gemaild te worden.
- Evenzo kunnen mensen die in dit soort dingen geÔnteresseerd
- zijn (en een tolerantie voor <emphasis>grote</emphasis>
- hoeveelheden mail hebben!) zich abonneren op de &a.hackers;.
- Zie <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">Het
- &os; Handboek</link> voor meer informatie over deze en andere
- mailinglijsten.</para>
-
- <para>Als u een bug vindt of een specifieke verandering opstuurt,
- gebruik dan alstublieft het programma &man.send-pr.1; of het
- <link xlink:href="&url.base;/send-pr.html">webgebaseerde
- equivalent</link> om het te rapporteren. Probeer om elk veld
- van het bugrapport in te vullen. Voeg patches direct bij het
- rapport tenzij ze 65kB overschrijden. Als de patch geschikt is
- om op de broncodeboom te worden toegepast, vermeld dan
- <literal>[PATCH]</literal> in het overzicht van het rapport.
- Wanneer u patches bijvoegt, gebruik dan
- <emphasis>geen</emphasis> knippen-en-plakken omdat
- knippen-en-plakken tabs in spaties omzet en de patches
- onbruikbaar maakt. Overweeg wanneer patches veel groter zijn
- dan 20 kB om ze te comprimeren (bijvoorbeeld met &man.gzip.1; of
- &man.bzip2.1;) en &man.uuencode.1; te gebruiken om hun
- gecomprimeerde vorm in uw probleemrapport op te nemen.</para>
-
- <para>Na het opsturen van een rapport dient u een bevestiging met
- daarbij een volgnummer te krijgen. Bewaar dit volgnummer zodat
- u ons op de hoogte kunt houden met details over het probleem
- door mail te sturen naar &a.bugfollowup;. Gebruik het nummer
- als het berichtonderwerp, bijvoorbeeld <literal>"Re:
- kern/3377"</literal>. Aanvullende informatie voor elk
- foutrapport dient op deze manier opgestuurd te worden.</para>
-
- <para>Als u geen bevestiging ontvangt binnen een redelijke tijd (3
- dagen tot een week, afhankelijk van uw emailverbinding) of als
- u, om enige reden, het commando &man.send-pr.1; niet kunt
- gebruiken, dan kunt u iemand vragen om het voor u op te sturen
- door mail te sturen naar de &a.bugs;.</para>
-
- <para>Zie ook <link xlink:href="&url.articles.problem-reports;/article.html">dit
- artikel</link> over het schrijven van goede
- probleemrapporten.</para>
- </sect2>
-
- <sect2>
- <title>Veranderingen aan de documentatie</title>
-
- <indexterm><primary>documentatie-inzendingen</primary></indexterm>
-
- <para>Veranderingen aan de documentatie worden overzien door de
- &a.doc;. Bekijk de <link xlink:href="&url.books.fdp-primer.en;/index.html">&os; Documentation
- Primer</link> voor volledige instructies. Stuur bijdragen en
- veranderingen (zelfs kleine zijn welkom!) door &man.send-pr.1;
- te gebruiken zoals beschreven is in <link linkend="contrib-general">Foutrapportages en algemeen
- commentaar</link>.</para>
- </sect2>
-
- <sect2>
- <title>Veranderingen aan bestaande broncode</title>
-
- <indexterm><primary>&os;-CURRENT</primary></indexterm>
-
- <para>Een toevoeging of verandering aan de bestaande broncode is
- een iets lastigere zaak en hangt in grote mate af van hoe ver u
- achterloopt met de huidige toestand van &os;-ontwikkelingen. Er
- is een speciale doorgaande uitgave van &os; die bekend staat als
- <quote>&os;-CURRENT</quote> die op verscheidene manieren
- beschikbaar wordt gesteld voor het gemak van ontwikkelaars die
- actief aan het systeem werken. Zie <link xlink:href="&url.books.handbook;/current-stable.html">Het &os;
- Handboek</link> voor meer informatie over het verkrijgen en
- gebruiken van &os;-CURRENT.</para>
-
- <para>Het werken met oudere broncode betekent helaas dat uw
- veranderingen soms te verouderd of te ver afgedwaald zijn om
- eenvoudig in &os; gerŽintegreerd te worden. De kansen
- hierop kunnen enigszins geminimaliseerd worden door een
- abonnement te nemen op de &a.announce; en de &a.current;
- lijsten, waar discussies over de huidige toestand van het
- systeem plaatsvinden.</para>
-
- <para>Aannemende dat u in staat bent om redelijk recente broncode
- veilig te stellen om uw veranderingen op te baseren, is de
- volgende stap het produceren van een verzameling diffs om naar
- de onderhoudsmensen van &os; te sturen. Dit wordt gedaan met
- het commando &man.diff.1;.</para>
-
- <para>Het geprefereerde &man.diff.1;-formaat voor het opsturen van
- patches is het verenigde uitvoerformaat gegenereerd door
- <command>diff -u</command>.</para>
-
- <indexterm>
- <primary><command>diff</command></primary>
- </indexterm>
-
- <screen>&prompt.user; <userinput>diff -u oudbestand nieuwbestand</userinput></screen>
-
- <para>of</para>
-
- <screen>&prompt.user; <userinput>diff -u -r -N oudemap nieuwemap</userinput></screen>
-
- <para>zouden een verzameling van verenigde diffs genereren voor het
- gegeven bronbestand of maphiŽrarchie.</para>
-
- <para>Zie &man.diff.1; voor meer details.</para>
-
- <para>Als u eenmaal een verzameling aan diffs heeft (welke u kunt
- testen met het commando &man.patch.1;), dient u ze op te sturen
- voor opname in &os;. Gebruik het programma &man.send-pr.1;
- zoals beschreven in <link linkend="contrib-general">Foutrapportages en algemeen
- commentaar</link>. Stuur de diffs <emphasis>niet</emphasis>
- alleen naar de &a.hackers; op omdat ze dan verloren raken! We
- stellen uw toezending erg op prijs (dit is een
- vrijwilligersproject!); omdat we het druk hebben kan het zijn
- dat we het niet direct kunnen behandelen, maar het blijft in de
- PR-database totdat we het doen. Geef uw toezending aan door
- <literal>[PATCH]</literal> in het overzicht van het rapport op
- te nemen.</para>
-
- <indexterm>
- <primary><command>uuencode</command></primary>
- </indexterm>
-
- <para>Als u het geschikt acht (bijvoorbeeld als u bestanden
- toegevoegd, verwijderd, of hernoemd heeft), bundelt u uw
- veranderingen in een <command>tar</command>-bestand en draait u
- het programma &man.uuencode.1; erop. Archieven die met
- &man.shar.1; zijn aangemaakt zijn ook welkom.</para>
-
- <para>Als uw verandering mogelijk gevoelig van aard is,
- bijvoorbeeld als u onzeker bent over copyright-zaken die de
- verdere distributie ervan dicteren, dan dient u het direct naar
- &a.core; te sturen in plaats
- van het met &man.send-pr.1; op te sturen. Het &a.core; bereikt
- een veel kleinere groep mensen die veel dagelijks werk op &os;
- doen. Merk op dat deze groep het ook <emphasis>erg
- druk</emphasis> heeft, daarom dient u alleen mail naar hen te
- sturen als dit echt noodzakelijk is.</para>
-
- <para>Bekijk alstublieft &man.intro.9; en &man.style.9; voor wat
- informatie over de codeerstijl. We zouden het op prijs stellen
- als u op zijn minst op de hoogte bent van deze informatie
- voordat u code opstuurt.</para>
- </sect2>
-
- <sect2>
- <title>Nieuwe code of grote pakketten met toegevoegde waarde</title>
-
- <para>In het geval van een significante bijdrage van een grote
- bijdrage aan werk, of van een belangrijke nieuwe mogelijkheid
- aan &os;, is het bijna altijd nodig om de veranderingen als
- uuencoded tar-bestanden te versturen of ze naar een web- of
- FTP-site up te loaden zodat andere mensen ze kunnen benaderen.
- Als u geen toegang heeft tot een web- of FTP-site, vraag dan een
- geschikte &os;-mailinglijst om iemand de veranderingen voor u te
- laten hosten.</para>
-
- <para>Bij het werken met grote hoeveelheden code komt het
- gevoelige onderwerp van copyright ook altijd naar voren.
- Acceptabele copyrights voor code voor opname in &os;
- zijn:</para>
-
- <orderedlist>
- <listitem>
- <para>Het BSD-copyright<indexterm><primary>BSD-copyright</primary></indexterm>. Dit copyright wordt het meeste
- verkozen wegens zijn natuur van <quote>geen
- voorwaarden</quote> en de algemene aantrekkelijkheid voor
- commerciŽle ondernemingen. Ver van het ontmoedigen van
- dit soort commercieel gebruik, moedigt het &os; Project
- zulke participatie door commerciŽle interesses actief
- aan die uiteindelijk geneigd kunnen zijn om zelf iets in
- &os; te investeren.</para>
- </listitem>
-
- <listitem>
- <para>De GNU General Public License<indexterm><primary>GNU General Public License</primary></indexterm>, of <quote>GPL</quote><indexterm><primary>GPL</primary><see>GNU General Public License</see></indexterm>.
- Deze licentie is niet zo populair bij ons wegens de extra
- hoeveelheid moeite die gevraagd wordt van iedereen die de
- code voor commerciŽle doeleinden gebruikt, maar vanwege
- de grote hoeveelheid aan ge-GPL-de code die we momenteel
- nodig hebben (compiler, assembler, tekstopmaker, enz.) zou
- het dom zijn om aanvullende bijdragen onder deze licentie te
- verwerpen. Code onder de GPL gaat ook naar een ander deel
- van de boom, namelijk <filename>/sys/gnu</filename> of <filename>/usr/src/gnu</filename>, en is daardoor
- eenvoudig te herkennen voor iedereen voor wie de GPL
- problemen geeft.</para>
- </listitem>
- </orderedlist>
-
- <para>Bijdragen die onder een ander soort copyright vallen moeten
- zorgvuldig worden herzien voordat hun opname in &os; wordt
- overwogen. Bijdragen waarvoor nogal beperkende commerciŽle
- copyrights gelden worden over het algemeen verworpen, alhoewel
- de auteurs altijd worden aangemoedigd om zulke veranderingen via
- hun eigen kanalen beschikbaar te maken.</para>
-
- <para>Om een copyright in <quote>BSD-stijl</quote> op uw werk te
- plaatsen, dient u de volgende tekst aan het uiterste begin van
- elk broncodebestand te plaatsen dat u wilt beschermen, en
- daarbij de tekst tussen de <literal>%%</literal> door de juiste
- informatie te vervangen:</para>
-
- <programlisting>Copyright (c) %%juiste_jaren_hier%%
- %%uw_naam_hier%%, %%uw_staat%% %%uw_postcode%%.
- 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 as
- the first lines of this file unmodified.
-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 %%uw_naam_hier%% ``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 %%uw_naam_hier%% 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.
-
- &dollar;Id&dollar;</programlisting>
-
- <para>Voor uw gemak staat een kopie van deze tekst in
- <filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para>
- </sect2>
-
- <sect2>
- <title>Geld, hardware, of Internettoegang</title>
-
- <para>We accepteren altijd graag donaties om het &os; Project
- verder te verspreiden en in een vrijwilligersonderneming zoals
- het onze kan een klein beetje een groot verschil maken!
- Hardwaredonaties zijn ook erg belangrijk om onze lijst van
- ondersteunde randapparatuur uit te breiden aangezien ons het
- over het algemeen aan de middelen ontbreekt om zelf zulke dingen
- te kopen.</para>
-
- <sect3 xml:id="donations">
- <title>Geld doneren</title>
-
- <para>De &os; Foundation is een non-profit, belastinguitgesloten
- stichting die opgericht is om de doelen van het &os; Project
- verder te verspreiden. Als een 501(c)3-entiteit is de
- Foundation over het algemeen uitgesloten van
- inkomstenbelasting van de overheid van de Verenigde Staten alsook van
- inkomstenbelasting van de staat Colorado. Donaties aan een
- entiteit die van belasting is uitgesloten zijn vaak aftrekbaar
- van het belastbaar overheidsinkomen.</para>
-
- <para>Donaties kunnen als check verstuurd worden aan:
- <address>
- The FreeBSD Foundation
- <street>P.O. Box 20247</street>
- <city>Boulder</city>,
- <state>CO</state> <postcode>80308</postcode>
- <country>USA</country>
- </address></para>
-
- <para>De &os; Foundation is nu in staat om donaties via het web
- met PayPal te ontvangen. Om een donatie te maken bezoekt u de
- <link xlink:href="http://www.freebsdfoundation.org">website</link>
- van de Foundation.</para>
-
- <para>Meer informatie over de &os; Foundation kan gevonden
- worden in <link xlink:href="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The
- FreeBSD Foundation -- an Introduction</link>. Om de
- Foundation per email te bereiken, schrijft u naar
- <email>bod@FreeBSDFoundation.org</email>.</para>
- </sect3>
-
- <sect3>
- <title>Hardware doneren</title>
-
- <para>Het &os; Project accepteert graag hardwaredonaties die het
- goed kan gebruiken. Als u geÔnteresseerd bent in het
- doneren<indexterm><primary>donaties</primary></indexterm> van hardware, neem dan contact op met het <link xlink:href="&url.base;/donations/">Donations Liaison
- Office</link>.</para>
- </sect3>
- </sect2>
- </sect1>
-
- <index/>
-</article>
diff --git a/nl_NL.ISO8859-1/articles/explaining-bsd/Makefile b/nl_NL.ISO8859-1/articles/explaining-bsd/Makefile
deleted file mode 100644
index d094bff0e4..0000000000
--- a/nl_NL.ISO8859-1/articles/explaining-bsd/Makefile
+++ /dev/null
@@ -1,22 +0,0 @@
-#
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/articles/explaining-bsd/Makefile
-# %SRCID% 39631
-#
-# Article: Explaining BSD
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/articles/explaining-bsd/article.xml b/nl_NL.ISO8859-1/articles/explaining-bsd/article.xml
deleted file mode 100644
index 64052b8071..0000000000
--- a/nl_NL.ISO8859-1/articles/explaining-bsd/article.xml
+++ /dev/null
@@ -1,286 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
-<!-- $FreeBSD$ -->
-<!-- The FreeBSD Documentation Project -->
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="nl_NL">
- <info><title>Uitleg over BSD</title>
-
-
- <author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname><affiliation> <address><email>grog@FreeBSD.org</email></address> </affiliation></author>
-
- <legalnotice xml:id="trademarks" role="trademarks">
- <para>FreeBSD is een geregistreerd handelsmerk van de FreeBSD Foundation.</para>
- <para>AMD, AMD Athlon, AMD Opteron, Athlon, √Član, Opteron, en PCnet zijn handelsmerken van Advanced Micro Devices, Inc.</para>
- <para>Apple, AirPort, FireWire, Mac, Macintosh, Mac OS, Quicktime, en TrueType zijn handelsmerken van Apple Computer, Inc., geregistreerd in de Verenigde Staten en andere landen.</para>
- <para>Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, en Xeon zijn handelsmerken of geregistreerde handelsmerken van Intel Corporation of haar dochterondernemingen in de Verenigde Staten en andere landen.</para>
- <para>Linux is een geregistreerd handelsmerk van Linus Torvalds.</para>
- <para>Motif, OSF/1, en UNIX zijn geregistreerde handelsmerken en IT DialTone en The Open Group zijn handelsmerken van The Open Group in de Verenigde Staten en andere landen.</para>
- <para>SPARC, SPARC64, en UltraSPARC zijn handelsmerken van SPARC International, Inc. in de Verenigde Staten en andere landen. SPARC International, Inc. bezit alle handelsmerken van SPARC en staat onder licentie het juiste gebruik van deze handelsmerken toe door zijn leden.</para>
- <para>Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice, SunOS en VirtualBox zijn handelsmerken of geregistreerde handelsmerken van Sun Microsystems, Inc. in de Verenigde Staten en andere landen.</para>
- <para>UNIX is een geregistreerd handelsmerk van The Open Group in de Verenigde Staten en andere landen.</para>
- <para>Veel van de termen die door fabrikanten en verkopers worden gebruikt om hun producten te onderscheiden worden geclaimd als handelsmerk. Op de plaatsen waar deze handelsmerken in dit document voorkomen, en het FreeBSD Project op de hoogte was van de claim op het handelsmerk, worden de termen gevolgd door het symbool <quote>‚ĄĘ</quote> of het symbool <quote>¬ģ</quote>.</para>
- </legalnotice>
-
- <pubdate xml:lang="en">$FreeBSD$</pubdate>
-
- <releaseinfo xml:lang="en">$FreeBSD$</releaseinfo>
-
- <abstract>
- <para>In de open-source wereld is het woord <quote>Linux</quote> bijna een synoniem van <quote>besturingssysteem</quote>, maar het is niet het enige open-source <trademark class="registered">UNIX</trademark> besturingssysteem. Volgens de <link xlink:href="http://www.leb.net/hzo/ioscount/data/r.9904.txt">Internet Operating System Counter</link>, draait sinds april 1999 31.3% van de machines op de wereld die met een netwerk verbonden zijn Linux. 14.6% draait BSD <trademark class="registered">UNIX</trademark>. Sommige van 's werelds grootste webinstallaties, zoals <link xlink:href="http://www.yahoo.com/">Yahoo!</link>, draaien BSD. De drukste FTP-server van de wereld van 1999 (nu buiten werking), <link xlink:href="ftp://ftp.cdrom.com/">ftp.cdrom.com</link>, gebruikte BSD om 1.4 TB aan gegevens per dag over te brengen. Het is duidelijk dat dit geen nichemarkt is: BSD is een goed bewaard geheim.</para>
-
- <para>Dus wat is het geheim? Waarom is BSD niet bekender? Dit artikel behandelt deze en andere vragen.</para>
-
- <para>&gt;In dit artikel zullen verschillen tussen BSD en Linux <emphasis>zo</emphasis> worden aangegeven.</para>
- </abstract>
- </info>
-
- <sect1 xml:id="what-is-bsd">
- <title>Wat is BSD?</title>
-
- <para>BSD is een afkorting van <quote>Berkeley Software Distribution</quote>. Het is de naam van broncodedistributies van de universiteit van California te Berkeley, wat origineel uitbreidingen waren van het besturingssysteem <trademark class="registered">UNIX</trademark> van AT&amp;T Research. Verschillende projecten over open-source besturingssystemen zijn gebaseerd op een uitgave van deze broncode die bekend staat als 4.4BSD-Lite. Ze omvatten ook een aantal pakketten van andere open-source projecten, opmerkelijk genoeg onder andere van het GNU-project. Het besturingssysteem in het geheel omvat:</para>
-
- <itemizedlist>
- <listitem>
- <para>De BSD-kernel, die proces-scheduling, geheugenbeheer, symmetrische multi-processing (SMP), apparaatstuurprogramma's, etcetera afhandelt.</para>
-
- <para><emphasis>In tegenstelling tot de Linux-kernel zijn er een aantal verschillende BSD-kernels met verschillende mogelijkheden.</emphasis></para>
- </listitem>
-
- <listitem>
- <para>De C-bibliotheek, de basis-API voor het systeem.</para>
-
- <para><emphasis>De C-bibliotheek van BSD is gebaseerd op code van Berkeley, niet van het GNU-project.</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Gereedschappen zoals shells, bestandsgereedschappen, compilers en linkers.</para>
-
- <para><emphasis>Sommige gereedschappen zijn afgeleid van het GNU-project, andere niet.</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Het X Window-systeem, wat grafisch afbeelden afhandelt.</para>
-
- <para>Het X Window-systeem dat in de meeste versies van BSD wordt gebruikt wordt onderhouden door het <link xlink:href="http://www.X.org/">X.Org project</link>. FreeBSD staat de gebruiker toe om te keizen uit verschillende bureaubladen, zoals <application>GNOME</application>, <application>KDE</application> of <application>Xfce</application>; en lichtgewicht vensterbeheerders zoals <application>Openbox</application>, <application>Fluxbox</application> of <application>Awesome</application>.</para>
- </listitem>
-
- <listitem>
- <para>Vele andere programma's en gereedschappen.</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 xml:id="what-a-real-unix">
- <title>Wat, een echte <trademark class="registered">UNIX</trademark>?</title>
-
- <para>De BSD-besturingssystemen zijn geen klonen, maar open-source afgeleiden van AT&amp;T's Research <trademark class="registered">UNIX</trademark> besturingssysteem, wat ook de voorouder is van het moderne <trademark class="registered">UNIX</trademark> System V. Dit kan als een verrassing komen. Hoe kon dit gebeuren als AT&amp;T nooit zijn code als open-source heeft uitgegeven?</para>
-
- <para>Het is waar dat AT&amp;T <trademark class="registered">UNIX</trademark> niet open-source is, en wat betreft copyright is BSD zeer zeker <emphasis>niet</emphasis> <trademark class="registered">UNIX</trademark>, maar van de andere kant heeft AT&amp;T bronnen ge√Įmporteerd van andere projecten, nota bene de Computer Science Research Group (CSRG) van de University of California in Berkeley, CA. In 1976 is de CSRG begonnen met het uitgeven van tapes van hun software, die ze <emphasis>Berkeley Software Distribution</emphasis> of <emphasis>BSD</emphasis> noemden.</para>
-
- <para>Initi√ęle BSD-uitgaven bestonden grotendeels uit gebruikersprogramma's, maar dat veranderde enorm toen CSRG in een contract belandde met het Defense Advanced Research Projects Agency (DARPA) om de communicatieprotocollen in hun netwerk, ARPANET, te vernieuwen. De nieuwe protocollen stonden bekend als <emphasis>Internet Protocols</emphasis>, later <emphasis>TCP/IP</emphasis> na de belangrijkste protocollen. De eerste wijdverbreide implementatie die gedistribueerd werd was deel van 4.2BSD, in 1982.</para>
-
- <para>In de loop van de jaren 80 ontsproten er een aantal nieuwe werkstationbedrijven. Vele verkozen het om <trademark class="registered">UNIX</trademark> te licenseren boven het ontwikkelen van hun eigen besturingssystemen. In het bijzonder licenseerde Sun Microsystems <trademark class="registered">UNIX</trademark> en implementeerde het een versie van 4.2BSD, wat ze <trademark>SunOS</trademark> noemden. Toen AT&amp;T zelf <trademark class="registered">UNIX</trademark> commercieel mocht verkopen, begonnen ze met een ietwat kale basisimplementatie genaamd System III, die snel gevolgd werd door System V. De codebase van System V bevatte geen netwerkcode, dus bevatten alle implementaties aanvullende software van de BSD, waaronder de TCP/IP-software, maar ook gereedschappen zoals de <emphasis>csh</emphasis>-shell en de tekstverwerker <emphasis>vi</emphasis>. Deze uitbreidingen stonden gezamenlijk bekend als de <emphasis>Berkeley Extensions</emphasis>.</para>
-
- <para>De BSD-tapes bevatten de broncode van AT&amp;T en hadden dus een <trademark class="registered">UNIX</trademark> bronlicentie nodig. Tegen 1990 raakten de fondsen van de CSRG uitgeput, en er dreigde sluiting. Sommige leden van de groep besloten om de BSD-code uit te geven, welke Open Source was, zonder de propri√ętaire code van AT&amp;T. Dit gebeurde eindelijk met de <emphasis>Networking Tape 2</emphasis>, gewoonlijk bekend als <emphasis>Net/2</emphasis>. Net/2 was geen compleet besturingssysteem: ongeveer 20% van de kernelcode ontbrak. Een van de leden van de CSRG, William F. Jolitz, schreef de overblijvende code en gaf het in het begin van 1992 uit als <emphasis>386BSD</emphasis>. In diezelfde tijd begon een andere groep van ex-CSRG-leden een commercieel bedrijf genaamd <link xlink:href="http://www.bsdi.com/">Berkeley Software Design Inc.</link> en gaf een betaversie van een besturingssysteem genaamd <link xlink:href="http://www.bsdi.com/">BSD/386</link> uit, welke op dezelfde bronnen was gebaseerd. De naam van het besturingssysteem werd later veranderd in BSD/OS.</para>
-
- <para>386BSD werd nooit een stabiel besturingssysteem. In plaats daarvan splitsten er twee andere projecten van af in 1993: <link xlink:href="http;//www.NetBSD.org/">NetBSD</link> en <link xlink:href="@@URL_RELPREFIX@@/index.html">FreeBSD</link>. De twee projecten groeiden oorspronkelijk uit elkaar wegens verschillen in de hoeveelheid geduld om op verbeteringen aan 386BSD te wachten: de mensen van NetBSD begonnen in het begin van het jaar, en de eerste versie van FreeBSD was niet klaar voor het einde van het jaar. In de tussentijd waren de codebases genoeg uit elkaar gegroeid om samenvoegen ervan moeilijk te maken. Tevens hadden de projecten verschillende doelen, wat we hieronder zullen zien. In 1996 splitste <link xlink:href="http://www.OpenBSD.org/">OpenBSD</link> zich af van NetBSD, en in 2003 splitste <link xlink:href="http://www.dragonflybsd.org/">DragonFlyBSD</link> zich af van FreeBSD.</para>
- </sect1>
-
- <sect1 xml:id="why-is-bsd-not-better-known">
- <title>Waarom is BSD niet bekender?</title>
-
- <para>Om een aantal redenen is BSD relatief onbekend:</para>
-
- <orderedlist>
- <listitem>
- <para>De BSD-ontwikkelaars zijn vaak meer ge√Įnteresseerd in het verbeteren van hun code dan het aan de man brengen.</para>
- </listitem>
-
- <listitem>
- <para>Veel van de populariteit van Linux komt door factoren buiten de Linux-projecten, zoals de pers, en door bedrijven die zijn opgericht om Linux-diensten aan te bieden. Tot voor kort hadden de open-source BSDs zulke voorstanders niet.</para>
- </listitem>
-
- <listitem>
- <para>BSD-ontwikkelaars zijn vaak meer ervaren dan Linux-ontwikkelaars, en hebben minder interesse in het systeem gemakkelijk in gebruik te maken. Nieuwelingen voelen zich vaak meer op hun gemak met Linux.</para>
- </listitem>
-
- <listitem>
- <para>In 1992 klaagde AT&amp;T <link xlink:href="http://www.bsdi.com/">BSDI</link>, de verkoper van BSD/386, aan op verdenking dat het product code bevatte waarover AT&amp;T copyright had. De zaak werd buiten de rechtbank om in 1994 beslist, maar het spook van de rechtszaak blijft mensen achtervolgen. Een artikel uit maart 2000 dat op het web werd gepubliceerd claimde dat de zaak <quote>recentelijk beslist</quote> was.</para>
-
- <para>Eén detail dat de rechtszaak ophelderde is de naamgeving: in de jaren 80 stond BSD bekend als <quote>BSD <trademark class="registered">UNIX</trademark></quote>. Met het nemen van de laatste vestiging van AT&amp;T-code van BSD, verloor het ook het recht op de naam <trademark class="registered">UNIX</trademark>. U zult dus verwijzingen in boektitels zien naar <quote>het besturingssysteem 4.3BSD <trademark class="registered">UNIX</trademark></quote> en <quote>het besturingssysteem 4.4BSD</quote>.</para>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1 xml:id="comparing-bsd-and-linux">
- <title>BSD en Linux vergelijken</title>
-
- <para>Wat is nou echt het verschil tussen bijvoorbeeld Debian Linux en FreeBSD? Voor de gemiddelde gebruiker is het verschil verrassend klein: beiden zijn <trademark class="registered">UNIX</trademark>-achtige besturingssystemen. Beiden worden ontwikkeld door niet-commerci√ęle projecten (dit geldt uiteraard niet voor vele andere distributies van Linux). In de volgende sectie wordt BSD bekeken en vergeleken met Linux. De beschrijving is het beste van toepassing op FreeBSD, dat een geschatte 80% van alle BSD-installaties voor rekening neemt, maar de verschillen van NetBSD, OpenBSD, en DragonFlyBSD zijn klein.</para>
-
- <sect2>
- <title>Wie bezit BSD?</title>
-
- <para>Geen enkel persoon of bedrijf bezit BSD. Het wordt tontwikkeld en verspreid door een gemeenschap van zeer technische en toegewijde wereldwijde contribuanten. Sommige onderdelen van BSD zijn open-source projecten op zichzelf en worden beheerd door verschillende projectbeheerders.</para>
- </sect2>
-
- <sect2>
- <title>Hoe wordt BSD ontwikkeld en bijgewerkt?</title>
-
- <para>De BSD-kernels worden ontwikkeld en bijgewerkt volgens het Open Source ontwikkelmodel. Elk project beheerst een publiek toegankelijke <emphasis>broncodeboom</emphasis> onder <link xlink:href="https://subversion.apache.org/">Subversion</link> (SVN), wat alle bronbestanden voor het project bevat, inclusief documentatie en andere toevallige bestanden. SVN stelt gebruikers in staat om een <quote>check out</quote> te doen (met andere woorden, om een kopie te maken) van elke gewenste versie van het systeem.</para>
-
- <para>Een grote groep van wereldwijde ontwikkelaars dragen bij aan verbeteringen aan BSD. Ze zijn verdeeld in drie soorten:</para>
-
- <itemizedlist>
- <listitem>
- <para><firstterm>Contributors</firstterm> schrijven code of documentatie. Ze hebben geen toestemming om direct naar de broncodeboom te committen (code toe te voegen). Om hun code aan het systeem toe te voegen, moet het herzien en ingecheckt worden door een geregistreerde ontwikkelaar, die een <emphasis>committer</emphasis> wordt genoemd.</para>
- </listitem>
-
- <listitem>
- <para><firstterm>Committers</firstterm> zijn ontwikkelaars met schrijftoegang tot de broncodeboom. Om committer te worden, moet een individu kennis en kunde laten zien in het gebied waarin hij actief is.</para>
-
- <para>Het is aan de discretie van de individuele committer of hij instemming moet krijgen voordat er veranderingen naar de broncodeboom worden gecommit. In het algemeen mag een ervaren committer veranderingen maken waarvan duidelijk is dat ze correct zijn zonder hiervoor consensus te verkrijgen. Een committer van het documentatieproject bijvoorbeeld mag typografische of grammaticale fouten verbeteren zonder dat deze herzien worden. Van de andere kant wordt van ontwikkelaars die verreikende of gecompliceerde veranderingen maken verwacht dat ze hun veranderingen ter herziening insturen voordat ze deze committen. In het uiterste geval kan een lid van het coreteam met een functie als Principal Architect eisen dat de veranderingen uit de boom verwijderd worden, een proces dat bekend staat als <firstterm>backing out</firstterm>. Alle committers ontvangen email die elke individuele commit beschrijft, het is dus niet mogelijk om heimelijk te committen.</para>
- </listitem>
-
- <listitem>
- <para>Het <firstterm>Coreteam</firstterm>. FreeBSD en NetBSD hebben elk een coreteam dat het project beheert. De coreteams zijn in de loop van de projecten ontstaan, en hun rol is niet altijd eenduidig gedefinieerd. Het is niet nodig om ontwikkelaar te zijn om lid te zijn van het coreteam, hoewel het normaal is. De regels voor het coreteam verschillen per project, maar in het algemeen hebben ze een grotere inspraak in de richting van het project dan niet-leden van het coreteam hebben.</para>
- </listitem>
- </itemizedlist>
-
- <para>Deze opstelling verschilt in een aantal opzichten van die van Linux:</para>
-
- <orderedlist>
- <listitem>
- <para>Geen enkel persoon heerst over de inhoud van het systeem. In de praktijk is dit verschil overdreven, aangezien de Principal Architect kan eisen dat code gebacked-out wordt, en zelfs in het Linux-project mogen meerdere mensen veranderingen maken.</para>
- </listitem>
-
- <listitem>
- <para>Van de andere kant <emphasis>is</emphasis> er een centraal repository, een enkele plaats waar u de gehele broncode van het besturingssysteem kunt vinden, inclusief alle oudere versies.</para>
- </listitem>
-
- <listitem>
- <para>BSD-projecten beheren het gehele <quote>Besturingssysteem</quote>, niet alleen de kernel. Dit onderscheid is slechts van beperkt nut: noch BSD noch Linux is nuttig zonder applicaties. De applicaties die onder BSD gebruikt worden zijn vaak dezelfde als de applicaties die onder Linux gebruikt worden.</para>
- </listitem>
-
- <listitem>
- <para>Een gevolg van het formele beheer van een enkele SVN-broncodeboom is dat de BSD-ontwikkeling helder is, en dat het mogelijk is om elke versie van het systeem aan de hand van het uitgavenummer of datum te benaderen. SVN staat ook incrementele wijzigingen aan het systeem toe: het repository van FreeBSD bijvoorbeeld wordt ongeveer 100 keer per dag bijgewerkt. De meeste van deze veranderingen zijn klein.</para>
- </listitem>
- </orderedlist>
- </sect2>
-
- <sect2>
- <title>BSD-uitgaven</title>
-
- <para>FreeBSD, NetBSD, en OpenBSD bieden het systeem in drie verschillende <quote>uitgaven</quote> aan. Net als bij Linux worden aan uitgaven nummers zoals 1.4.1 of 3.5 toegekend. Tevens heeft het versienummer een achtervoegsel die het doel aangeeft:</para>
-
- <orderedlist>
- <listitem>
- <para>De ontwikkelversie van het systeem wordt <firstterm>CURRENT</firstterm> genoemd. FreeBSD kent een nummer aan CURRENT toe, bijvoorbeeld FreeBSD 5.0-CURRENT. NetBSD hanteert een lichtelijk ander schema voor de naamgeving en voegt een achtervoegsel van een enkele letter toe welke veranderingen aan de interne interfaces aangeeft, bijvoorbeeld NetBSD 1.4.3G. OpenBSD kent geen nummer toe(<quote>OpenBSD-current</quote>). Alle nieuwe ontwikkelingen aan het systeem komen in deze tak terecht.</para>
- </listitem>
-
- <listitem>
- <para>De projecten brengen met regelmatige tussenpozen, tussen twee en vier keer per jaar, een <firstterm>RELEASE</firstterm>-versie van het systeem uit, welke beschikbaar is op CD-ROM en vrij te downloaden is van FTP-sites, bijvoorbeeld OpenBSD 2.6-RELEASE of NetBSD 1.4-RELEASE. De RELEASE-versie is bedoeld voor eindgebruikers en is de normale versie van het systeem. NetBSD biedt ook <emphasis>patch-uitgaven</emphasis> aan met een derde cijfer, bijvoorbeeld NetBSD 1.4.2.</para>
- </listitem>
-
- <listitem>
- <para>Wanneer er bugs in een RELEASE-versie worden gevonden, worden ze gerepareeed, en worden de reparaties toegevoegd aan de SVN-boom. In FreeBSD wordt de resulterende versie de <firstterm>STABLE</firstterm>-versie genoemd, terwijl het in NetBSD en OpenBSD de RELEASE-versie blijft heten. Kleinere nieuwe eigenschappen kunnen ook aan deze tak worden toegevoegd na een testperiode in de CURRENT-tak. Beveiligings- en andere belangrijke reparaties worden ook op alle ondersteunde RELEASE-versies toegepast.</para>
- </listitem>
- </orderedlist>
-
- <para><emphasis>In contrast hiermee onderhoudt Linux twee gescheiden codebomen: de stabiele versie en de ontwikkelversie. Stabiele versies hebben een even klein versienummer, zoals 2.0, 2.2, of 2.4. Ontwikkelversies hebben een oneven klein versienummer, zoals 2.1, 2.3, of 2.5. In alle gevallen wordt het nummer gevolgd door een nog een nummer dat de exacte uitgave aangeeft. Verder voegt elke verkoper zijn eigen gebruikersprogramma's en gereedschappen toe, dus is de naam van de distributie ook belangrijk. Elke verkoper van distributies kent ook versienummers aan de distributie toe, dus kan een volledige omschrijving iets zijn als <quote>TurboLinux 6.0 met kernel 2.2.14</quote> zijn.</emphasis></para>
- </sect2>
-
- <sect2>
- <title>Welke versies van BSD zijn beschikbaar?</title>
-
- <para>In tegenstelling tot de vele Linux-distributies, zijn er slechts vier grote open-source BSDs. Elk BSD-project beheert zijn eigen broncodeboom en zijn eigen kernel. In de praktijk schijnt er echter minder divergentie te zijn tussen de gebruikerscode van de projecten dan dat er in Linux is.</para>
-
- <para>Het is moeilijk om de doelen van elk project te categoriseren: de verschillen zijn erg subjectief. Het volgende geldt ongeveer:</para>
-
- <itemizedlist>
- <listitem>
- <para>FreeBSD richt zich op hoge prestaties en gebruikersgemak voor eindgebruikers, en is een favoriet van aanbieders van webinhoud. Het draait op een <link xlink:href="@@URL_RELPREFIX@@/platforms/">aantal platformen</link> en heeft aanzienlijk meer gebruikers dan de andere projecten.</para>
- </listitem>
-
- <listitem>
- <para>NetBSD gaat voor maximale portabiliteit: <quote>of course it runs NetBSD</quote>. Het draait op machines vari√ęrend van palmtops tot grote servers, en het is zelfs gebruikt in ruimtemissies van NASA. Het is een bijzonder goede keuze om op oude niet-<trademark class="registered">Intel</trademark> hardware te draaien.</para>
- </listitem>
-
- <listitem>
- <para>OpenBSD gaat voor beveiliging en code-puurheid: het gebruikt een combinatie van het open-source concept en rigoureuze codeherzieningen om een systeem te maken dat aantoonbaar correct is, waardoor het de keuze is van beveiligingsbewuste organisaties zoals banken, beurzen, en afdelingen van de Amerikaanse overheid. Net als NetBSD draait het op een aantal platformen.</para>
- </listitem>
-
- <listitem>
- <para>DragonFlyBSD gaat voor hoge prestaties en schaalbaarheid vari√ęrend van een UP-systeem van een enkele computer tot een reusachtig geclusterd systeem. DragonFlyBSD heeft verscheidene technische langetermijndoelen, maar de focus ligt op het bieden van een SMP-capabele infrastructuur dat eenvoudig te begrijpen en te onderhouden is, en waarvoor eenvoudig te ontwikkelen is.</para>
- </listitem>
- </itemizedlist>
-
- <para>Er zijn ook twee aanvullende BSD <trademark class="registered">UNIX</trademark> besturingssystemen die niet open-source zijn, BSD/OS en <trademark class="registered">Mac OS</trademark> X van Apple:</para>
-
- <itemizedlist>
- <listitem>
- <para>BSD/OS was de oudste van de afgeleiden van 4.4BSD. Het was niet open-source, alhoewel licenties voor de broncode tegen relatief kosten beschikbaar waren. Het leek in vele opzichten op FreeBSD. Twee jaar na de aankoop van BSDi door Wind River Systems slaagde BSD/OS er niet in om als een onafhankelijk product te overleven. Ondersteuning en broncode kunnnen nog steeds beschikbaar zijn van Wind River, maar alle nieuwe ontwikkelingen zijn gericht op het embedded besturingssysteem VxWorks.</para>
- </listitem>
-
- <listitem>
- <para><link xlink:href="http://www.apple.com/macosx/server/"><trademark class="registered">Mac¬†OS</trademark> X</link> is de nieuwste versie van het besturingssysteem voor de <trademark class="registered">Mac</trademark> lijn van <trademark class="registered">Apple</trademark>. De BSD-kern van dit besturingssysteem, <link xlink:href="http://developer.apple.com/darwin/">Darwin</link> is beschikbaar als een volledig werkend open-source besturingssysteem voor x86- en PPC-computers. Het grafische systeem Aqua/Quartz en vele andere propri√ętaire aspecten van <trademark class="registered">Mac¬†OS</trademark> X blijven echter closed-source. Verschillende Darwin-ontwikkelaars zijn ook FreeBSD-committers, en vice-versa.</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Hoe verschilt de BSD-licentie van de publieke GNU-licentie?</title>
-
- <para>Linux is beschikbaar onder de <link xlink:href="http://www.fsf.org/copyleft/gpl.html">GNU General Public License</link> (GPL), welke ontwikkeld is om closed-source software te elimineren. In het bijzonder moet elk afgeleid werk van een product dat onder de GPL is vrijgegeven ook met de broncode geleverd worden indien dat gevraagd wordt. In tegenstelling hiermee is de <link xlink:href="http://www.opensource.org/licenses/bsd-license.html">BSD-licentie</link> minder beperkend: distributies met alleen binairen zijn toegestaan. Dit is in het bijzonder aantrekkelijk voor embedded applicaties.</para>
- </sect2>
-
- <sect2>
- <title>Wat moet ik nog meer weten?</title>
-
- <para>Aangezien er minder applicaties beschikbaar zijn voor BSD dan voor Linux, hebben de ontwikkelaars van BSD een Linux-compatibiliteitspakket ontwikkeld, wat het mogelijk maakt om Linux-programma's onder BSD te draaien. Het pakket bevat zowel kernelwijzigingen, om Linux-systeemaanroepen correct uit te voeren, en Linux-compatibiliteitsbestanden zoals de C-bibliotheek. Er is geen merkbaar verschil in uitvoersnelheid tussen een Linux-applicatie die op een Linux-machine draait en een Linux-applicatie die op een BSD-machine die dezelfde snelheid heeft draait.</para>
-
- <para>De <quote>alles van één leverancier</quote>-natuur van BSD dat upgrades veel makkelijker af te handelen zijn dan dat vaak met Linux het geval is. BSD handelt upgrades aan bibliotheekversies af door compatibiliteitsmodulen voor eerdere bibliotheekversies aan te bieden, dus is het mogelijk om binairen die enige jaren oud zijn zonder problemen te draaien.</para>
- </sect2>
-
- <sect2>
- <title>Wat zou ik moeten gebruiken, BSD of Linux?</title>
-
- <para>Wat betekent dit allemaal in de praktijk? Wie zou BSD moeten gebruiken, en wie Linux?</para>
-
- <para>Dit is een erg moeilijke vraag om te beantwoorden. Hier zijn wat richtlijnen:</para>
-
- <itemizedlist>
- <listitem>
- <para><quote>If it ain't broke, don't fix it</quote>: als u al een open-source besturingssysteem gebruikt, en u er tevreden over bent, dan is er waarschijnlijk geen goede reden om over te stappen.</para>
- </listitem>
-
- <listitem>
- <para>BSD-systemen, in het bijzonder FreeBSD, kunnen merkbaar beter presteren dan Linux. Maar dit geldt niet voor alles. In veel gevallen zijn er weinig of geen prestatieverschillen. In sommige gevallen kan Linux beter presteren dan FreeBSD.</para>
- </listitem>
-
- <listitem>
- <para>In het algemeen hebben BSD-systemen een betere naam qua betrouwbaarheid, voornamelijk als het resultaat van een volwassenere codebase.</para>
- </listitem>
-
- <listitem>
- <para>BSD-projecten hebben een betere naam qua kwaliteit en volledigheid van hun documentatie. De verschillende documentatieprojecten richten zich op het bieden van actief bijgewerkte documentatie, in vele talen, en op het behandelen van alle aspecten van het systeem.</para>
- </listitem>
-
- <listitem>
- <para>De BSD-licentie kan aantrekkelijker zijn dan de GPL.</para>
- </listitem>
-
- <listitem>
- <para>BSD kan de meeste Linux-binairen uitvoeren, terwijl Linux geen BSD-binairen kan uitvoeren. Vele implementaties van BSD kunnen ook binairen van andere <trademark class="registered">UNIX</trademark>-achtige systemen uitvoeren. Als gevolg kan BSD een eenvoudigere migratieroute zijn van andere systemen dan dat Linux zou zijn.</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Wie biedt ondersteuning, diensten, en training voor BSD aan?</title>
-
- <para>BSDi / <link xlink:href="http://www.freebsdmall.com">FreeBSD Mall Inc.</link> bieden sinds bijna een decennium ondersteuningscontracten aan voor FreeBSD.</para>
-
- <para>Verder heeft elk project een lijst van in te huren consultants: <link xlink:href="@@URL_RELPREFIX@@/commercial/consult_bycat.html">FreeBSD</link>, <link xlink:href="http://www.netbsd.org/gallery/consultants.html">NetBSD</link>, en <link xlink:href="http://www.openbsd.org/support.html">OpenBSD</link>.</para>
- </sect2>
- </sect1>
-</article>
diff --git a/nl_NL.ISO8859-1/articles/explaining-bsd/nl_NL.po b/nl_NL.ISO8859-1/articles/explaining-bsd/nl_NL.po
deleted file mode 100644
index 4fae3eee91..0000000000
--- a/nl_NL.ISO8859-1/articles/explaining-bsd/nl_NL.po
+++ /dev/null
@@ -1,1176 +0,0 @@
-msgid ""
-msgstr ""
-"Project-Id-Version: FreeBSD Documentation Project\n"
-"POT-Creation-Date: 2015-10-27 20:02+0100\n"
-"PO-Revision-Date: 2015-10-27 20:06+0100\n"
-"Last-Translator: René Ladan <rene@freebsd.org>\n"
-"Language-Team: Dutch <freebsd-translators@freebsd.org>\n"
-"Language: nl_NL\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=UTF-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Poedit 1.8.4\n"
-
-#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
-msgctxt "_"
-msgid "translator-credits"
-msgstr "vertaling"
-
-#. (itstool) path: info/title
-#: article.translate.xml:6
-msgid "Explaining BSD"
-msgstr "Uitleg over BSD"
-
-#. (itstool) path: affiliation/address
-#: article.translate.xml:10
-#, no-wrap
-msgid "<email>grog@FreeBSD.org</email>"
-msgstr "<email>grog@FreeBSD.org</email>"
-
-#. (itstool) path: info/author
-#: article.translate.xml:9
-msgid ""
-"<personname><firstname>Greg</firstname><surname>Lehey</surname></"
-"personname><affiliation> <_:address-1/> </affiliation>"
-msgstr ""
-"<personname><firstname>Greg</firstname><surname>Lehey</surname></"
-"personname><affiliation> <_:address-1/> </affiliation>"
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:14
-msgid "FreeBSD is a registered trademark of the FreeBSD Foundation."
-msgstr "FreeBSD is een geregistreerd handelsmerk van de FreeBSD Foundation."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:16
-msgid ""
-"AMD, AMD Athlon, AMD Opteron, AMD Phenom, AMD Sempron, AMD Turion, Athlon, "
-"√Član, Opteron, and PCnet are trademarks of Advanced Micro Devices, Inc."
-msgstr ""
-"AMD, AMD Athlon, AMD Opteron, Athlon, √Član, Opteron, en PCnet zijn "
-"handelsmerken van Advanced Micro Devices, Inc."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:19
-msgid ""
-"Apple, AirPort, FireWire, iMac, iPhone, iPad, Mac, Macintosh, Mac OS, "
-"Quicktime, and TrueType are trademarks of Apple Inc., registered in the U.S. "
-"and other countries."
-msgstr ""
-"Apple, AirPort, FireWire, Mac, Macintosh, Mac OS, Quicktime, en TrueType "
-"zijn handelsmerken van Apple Computer, Inc., geregistreerd in de Verenigde "
-"Staten en andere landen."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:24
-msgid ""
-"Intel, Celeron, Centrino, Core, EtherExpress, i386, i486, Itanium, Pentium, "
-"and Xeon are trademarks or registered trademarks of Intel Corporation or its "
-"subsidiaries in the United States and other countries."
-msgstr ""
-"Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, en Xeon zijn "
-"handelsmerken of geregistreerde handelsmerken van Intel Corporation of haar "
-"dochterondernemingen in de Verenigde Staten en andere landen."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:28
-msgid "Linux is a registered trademark of Linus Torvalds."
-msgstr "Linux is een geregistreerd handelsmerk van Linus Torvalds."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:30
-msgid ""
-"Motif, OSF/1, and UNIX are registered trademarks and IT DialTone and The "
-"Open Group are trademarks of The Open Group in the United States and other "
-"countries."
-msgstr ""
-"Motif, OSF/1, en UNIX zijn geregistreerde handelsmerken en IT DialTone en "
-"The Open Group zijn handelsmerken van The Open Group in de Verenigde Staten "
-"en andere landen."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:34
-msgid ""
-"SPARC, SPARC64, and UltraSPARC are trademarks of SPARC International, Inc in "
-"the United States and other countries. SPARC International, Inc owns all of "
-"the SPARC trademarks and under licensing agreements allows the proper use of "
-"these trademarks by its members."
-msgstr ""
-"SPARC, SPARC64, en UltraSPARC zijn handelsmerken van SPARC International, "
-"Inc. in de Verenigde Staten en andere landen. SPARC International, Inc. "
-"bezit alle handelsmerken van SPARC en staat onder licentie het juiste "
-"gebruik van deze handelsmerken toe door zijn leden."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:39
-msgid ""
-"Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, "
-"Netra, OpenJDK, Solaris, StarOffice, SunOS and VirtualBox are trademarks or "
-"registered trademarks of Sun Microsystems, Inc. in the United States and "
-"other countries."
-msgstr ""
-"Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, "
-"Netra, OpenJDK, Solaris, StarOffice, SunOS en VirtualBox zijn handelsmerken "
-"of geregistreerde handelsmerken van Sun Microsystems, Inc. in de Verenigde "
-"Staten en andere landen."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:44
-msgid ""
-"UNIX is a registered trademark of The Open Group in the United States and "
-"other countries."
-msgstr ""
-"UNIX is een geregistreerd handelsmerk van The Open Group in de Verenigde "
-"Staten en andere landen."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:46
-msgid ""
-"Many of the designations used by manufacturers and sellers to distinguish "
-"their products are claimed as trademarks. Where those designations appear in "
-"this document, and the FreeBSD Project was aware of the trademark claim, the "
-"designations have been followed by the <quote>‚ĄĘ</quote> or the <quote>¬ģ</"
-"quote> symbol."
-msgstr ""
-"Veel van de termen die door fabrikanten en verkopers worden gebruikt om hun "
-"producten te onderscheiden worden geclaimd als handelsmerk. Op de plaatsen "
-"waar deze handelsmerken in dit document voorkomen, en het FreeBSD Project op "
-"de hoogte was van de claim op het handelsmerk, worden de termen gevolgd door "
-"het symbool <quote>‚ĄĘ</quote> of het symbool <quote>¬ģ</quote>."
-
-#. (itstool) path: info/pubdate
-#. (itstool) path: info/releaseinfo
-#: article.translate.xml:54 article.translate.xml:56
-msgid ""
-"$FreeBSD$"
-msgstr ""
-"$FreeBSD$"
-
-#. (itstool) path: abstract/para
-#: article.translate.xml:59
-msgid ""
-"In the open source world, the word <quote>Linux</quote> is almost synonymous "
-"with <quote>Operating System</quote>, but it is not the only open source "
-"<trademark class=\"registered\">UNIX</trademark> operating system. According "
-"to the <link xlink:href=\"http://www.leb.net/hzo/ioscount/data/r.9904.txt"
-"\">Internet Operating System Counter</link>, as of April 1999 31.3% of the "
-"world's network connected machines run Linux. 14.6% run BSD <trademark class="
-"\"registered\">UNIX</trademark>. Some of the world's largest web operations, "
-"such as <link xlink:href=\"http://www.yahoo.com/\">Yahoo!</link>, run BSD. "
-"The world's busiest FTP server of 1999 (now defunct), <link xlink:href="
-"\"ftp://ftp.cdrom.com/\">ftp.cdrom.com</link>, used BSD to transfer 1.4 TB "
-"of data a day. Clearly this is not a niche market: BSD is a well-kept secret."
-msgstr ""
-"In de open-source wereld is het woord <quote>Linux</quote> bijna een "
-"synoniem van <quote>besturingssysteem</quote>, maar het is niet het enige "
-"open-source <trademark class=\"registered\">UNIX</trademark> "
-"besturingssysteem. Volgens de <link xlink:href=\"http://www.leb.net/hzo/"
-"ioscount/data/r.9904.txt\">Internet Operating System Counter</link>, draait "
-"sinds april 1999 31.3% van de machines op de wereld die met een netwerk "
-"verbonden zijn Linux. 14.6% draait BSD <trademark class=\"registered\">UNIX</"
-"trademark>. Sommige van 's werelds grootste webinstallaties, zoals <link "
-"xlink:href=\"http://www.yahoo.com/\">Yahoo!</link>, draaien BSD. De drukste "
-"FTP-server van de wereld van 1999 (nu buiten werking), <link xlink:href="
-"\"ftp://ftp.cdrom.com/\">ftp.cdrom.com</link>, gebruikte BSD om 1.4 TB aan "
-"gegevens per dag over te brengen. Het is duidelijk dat dit geen nichemarkt "
-"is: BSD is een goed bewaard geheim."
-
-#. (itstool) path: abstract/para
-#: article.translate.xml:70
-msgid ""
-"So what is the secret? Why is BSD not better known? This white paper "
-"addresses these and other questions."
-msgstr ""
-"Dus wat is het geheim? Waarom is BSD niet bekender? Dit artikel behandelt "
-"deze en andere vragen."
-
-#. (itstool) path: abstract/para
-#: article.translate.xml:73
-msgid ""
-"Throughout this paper, differences between BSD and Linux will be noted "
-"<emphasis>like this</emphasis>."
-msgstr ""
-">In dit artikel zullen verschillen tussen BSD en Linux <emphasis>zo</"
-"emphasis> worden aangegeven."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:79
-msgid "What is BSD?"
-msgstr "Wat is BSD?"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:81
-msgid ""
-"BSD stands for <quote>Berkeley Software Distribution</quote>. It is the name "
-"of distributions of source code from the University of California, Berkeley, "
-"which were originally extensions to AT&amp;T's Research <trademark class="
-"\"registered\">UNIX</trademark> operating system. Several open source "
-"operating system projects are based on a release of this source code known "
-"as 4.4BSD-Lite. In addition, they comprise a number of packages from other "
-"Open Source projects, including notably the GNU project. The overall "
-"operating system comprises:"
-msgstr ""
-"BSD is een afkorting van <quote>Berkeley Software Distribution</quote>. Het "
-"is de naam van broncodedistributies van de universiteit van California te "
-"Berkeley, wat origineel uitbreidingen waren van het besturingssysteem "
-"<trademark class=\"registered\">UNIX</trademark> van AT&amp;T Research. "
-"Verschillende projecten over open-source besturingssystemen zijn gebaseerd "
-"op een uitgave van deze broncode die bekend staat als 4.4BSD-Lite. Ze "
-"omvatten ook een aantal pakketten van andere open-source projecten, "
-"opmerkelijk genoeg onder andere van het GNU-project. Het besturingssysteem "
-"in het geheel omvat:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:92
-msgid ""
-"The BSD kernel, which handles process scheduling, memory management, "
-"symmetric multi-processing (SMP), device drivers, etc."
-msgstr ""
-"De BSD-kernel, die proces-scheduling, geheugenbeheer, symmetrische multi-"
-"processing (SMP), apparaatstuurprogramma's, etcetera afhandelt."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:96
-msgid ""
-"<emphasis>Unlike the Linux kernel, there are several different BSD kernels "
-"with differing capabilities.</emphasis>"
-msgstr ""
-"<emphasis>In tegenstelling tot de Linux-kernel zijn er een aantal "
-"verschillende BSD-kernels met verschillende mogelijkheden.</emphasis>"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:101
-msgid "The C library, the base API for the system."
-msgstr "De C-bibliotheek, de basis-API voor het systeem."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:103
-msgid ""
-"<emphasis>The BSD C library is based on code from Berkeley, not the GNU "
-"project.</emphasis>"
-msgstr ""
-"<emphasis>De C-bibliotheek van BSD is gebaseerd op code van Berkeley, niet "
-"van het GNU-project.</emphasis>"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:108
-msgid "Utilities such as shells, file utilities, compilers and linkers."
-msgstr ""
-"Gereedschappen zoals shells, bestandsgereedschappen, compilers en linkers."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:111
-msgid ""
-"<emphasis>Some of the utilities are derived from the GNU project, others are "
-"not.</emphasis>"
-msgstr ""
-"<emphasis>Sommige gereedschappen zijn afgeleid van het GNU-project, andere "
-"niet.</emphasis>"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:116
-msgid "The X Window system, which handles graphical display."
-msgstr "Het X Window-systeem, wat grafisch afbeelden afhandelt."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:118
-msgid ""
-"The X Window system used in most versions of BSD is maintained by the <link "
-"xlink:href=\"http://www.X.org/\">X.Org project</link>. FreeBSD allows the "
-"user to choose from a variety of desktop environments, such as "
-"<application>Gnome</application>, <application>KDE</application>, or "
-"<application>Xfce</application>; and lightweight window managers like "
-"<application>Openbox</application>, <application>Fluxbox</application>, or "
-"<application>Awesome</application>."
-msgstr ""
-"Het X Window-systeem dat in de meeste versies van BSD wordt gebruikt wordt "
-"onderhouden door het <link xlink:href=\"http://www.X.org/\">X.Org project</"
-"link>. FreeBSD staat de gebruiker toe om te keizen uit verschillende "
-"bureaubladen, zoals <application>GNOME</application>, <application>KDE</"
-"application> of <application>Xfce</application>; en lichtgewicht "
-"vensterbeheerders zoals <application>Openbox</application>, "
-"<application>Fluxbox</application> of <application>Awesome</application>."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:131
-msgid "Many other programs and utilities."
-msgstr "Vele andere programma's en gereedschappen."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:137
-msgid "What, a real <trademark class=\"registered\">UNIX</trademark>?"
-msgstr "Wat, een echte <trademark class=\"registered\">UNIX</trademark>?"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:139
-msgid ""
-"The BSD operating systems are not clones, but open source derivatives of "
-"AT&amp;T's Research <trademark class=\"registered\">UNIX</trademark> "
-"operating system, which is also the ancestor of the modern <trademark class="
-"\"registered\">UNIX</trademark> System V. This may surprise you. How could "
-"that happen when AT&amp;T has never released its code as open source?"
-msgstr ""
-"De BSD-besturingssystemen zijn geen klonen, maar open-source afgeleiden van "
-"AT&amp;T's Research <trademark class=\"registered\">UNIX</trademark> "
-"besturingssysteem, wat ook de voorouder is van het moderne <trademark class="
-"\"registered\">UNIX</trademark> System V. Dit kan als een verrassing "
-"komen. Hoe kon dit gebeuren als AT&amp;T nooit zijn code als open-source "
-"heeft uitgegeven?"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:145
-msgid ""
-"It is true that AT&amp;T <trademark class=\"registered\">UNIX</trademark> is "
-"not open source, and in a copyright sense BSD is very definitely "
-"<emphasis>not</emphasis> <trademark class=\"registered\">UNIX</trademark>, "
-"but on the other hand, AT&amp;T has imported sources from other projects, "
-"noticeably the Computer Sciences Research Group (CSRG) of the University of "
-"California in Berkeley, CA. Starting in 1976, the CSRG started releasing "
-"tapes of their software, calling them <emphasis>Berkeley Software "
-"Distribution</emphasis> or <emphasis>BSD</emphasis>."
-msgstr ""
-"Het is waar dat AT&amp;T <trademark class=\"registered\">UNIX</trademark> "
-"niet open-source is, en wat betreft copyright is BSD zeer zeker "
-"<emphasis>niet</emphasis> <trademark class=\"registered\">UNIX</trademark>, "
-"maar van de andere kant heeft AT&amp;T bronnen ge√Įmporteerd van andere "
-"projecten, nota bene de Computer Science Research Group (CSRG) van de "
-"University of California in Berkeley, CA. In 1976 is de CSRG begonnen met "
-"het uitgeven van tapes van hun software, die ze <emphasis>Berkeley Software "
-"Distribution</emphasis> of <emphasis>BSD</emphasis> noemden."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:153
-msgid ""
-"Initial BSD releases consisted mainly of user programs, but that changed "
-"dramatically when the CSRG landed a contract with the Defense Advanced "
-"Research Projects Agency (DARPA) to upgrade the communications protocols on "
-"their network, ARPANET. The new protocols were known as the "
-"<emphasis>Internet Protocols</emphasis>, later <emphasis>TCP/IP</emphasis> "
-"after the most important protocols. The first widely distributed "
-"implementation was part of 4.2BSD, in 1982."
-msgstr ""
-"Initi√ęle BSD-uitgaven bestonden grotendeels uit gebruikersprogramma's, maar "
-"dat veranderde enorm toen CSRG in een contract belandde met het Defense "
-"Advanced Research Projects Agency (DARPA) om de communicatieprotocollen in "
-"hun netwerk, ARPANET, te vernieuwen. De nieuwe protocollen stonden bekend "
-"als <emphasis>Internet Protocols</emphasis>, later <emphasis>TCP/IP</"
-"emphasis> na de belangrijkste protocollen. De eerste wijdverbreide "
-"implementatie die gedistribueerd werd was deel van 4.2BSD, in 1982."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:162
-msgid ""
-"In the course of the 1980s, a number of new workstation companies sprang up. "
-"Many preferred to license <trademark class=\"registered\">UNIX</trademark> "
-"rather than developing operating systems for themselves. In particular, Sun "
-"Microsystems licensed <trademark class=\"registered\">UNIX</trademark> and "
-"implemented a version of 4.2BSD, which they called <trademark>SunOS</"
-"trademark>. When AT&amp;T themselves were allowed to sell <trademark class="
-"\"registered\">UNIX</trademark> commercially, they started with a somewhat "
-"bare-bones implementation called System III, to be quickly followed by "
-"System V. The System V code base did not include networking, so all "
-"implementations included additional software from the BSD, including the TCP/"
-"IP software, but also utilities such as the <emphasis>csh</emphasis> shell "
-"and the <emphasis>vi</emphasis> editor. Collectively, these enhancements "
-"were known as the <emphasis>Berkeley Extensions</emphasis>."
-msgstr ""
-"In de loop van de jaren 80 ontsproten er een aantal nieuwe "
-"werkstationbedrijven. Vele verkozen het om <trademark class=\"registered"
-"\">UNIX</trademark> te licenseren boven het ontwikkelen van hun eigen "
-"besturingssystemen. In het bijzonder licenseerde Sun Microsystems "
-"<trademark class=\"registered\">UNIX</trademark> en implementeerde het een "
-"versie van 4.2BSD, wat ze <trademark>SunOS</trademark> noemden. Toen AT&amp;"
-"T zelf <trademark class=\"registered\">UNIX</trademark> commercieel mocht "
-"verkopen, begonnen ze met een ietwat kale basisimplementatie genaamd System "
-"III, die snel gevolgd werd door System V. De codebase van System V bevatte "
-"geen netwerkcode, dus bevatten alle implementaties aanvullende software van "
-"de BSD, waaronder de TCP/IP-software, maar ook gereedschappen zoals de "
-"<emphasis>csh</emphasis>-shell en de tekstverwerker <emphasis>vi</"
-"emphasis>. Deze uitbreidingen stonden gezamenlijk bekend als de "
-"<emphasis>Berkeley Extensions</emphasis>."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:175
-msgid ""
-"The BSD tapes contained AT&amp;T source code and thus required a <trademark "
-"class=\"registered\">UNIX</trademark> source license. By 1990, the CSRG's "
-"funding was running out, and it faced closure. Some members of the group "
-"decided to release the BSD code, which was Open Source, without the AT&amp;T "
-"proprietary code. This finally happened with the <emphasis>Networking Tape "
-"2</emphasis>, usually known as <emphasis>Net/2</emphasis>. Net/2 was not a "
-"complete operating system: about 20% of the kernel code was missing. One of "
-"the CSRG members, William F. Jolitz, wrote the remaining code and released "
-"it in early 1992 as <emphasis>386BSD</emphasis>. At the same time, another "
-"group of ex-CSRG members formed a commercial company called <link xlink:href="
-"\"http://www.bsdi.com/\">Berkeley Software Design Inc.</link> and released a "
-"beta version of an operating system called <link xlink:href=\"http://www."
-"bsdi.com/\">BSD/386</link>, which was based on the same sources. The name of "
-"the operating system was later changed to BSD/OS."
-msgstr ""
-"De BSD-tapes bevatten de broncode van AT&amp;T en hadden dus een <trademark "
-"class=\"registered\">UNIX</trademark> bronlicentie nodig. Tegen 1990 "
-"raakten de fondsen van de CSRG uitgeput, en er dreigde sluiting. Sommige "
-"leden van de groep besloten om de BSD-code uit te geven, welke Open Source "
-"was, zonder de propri√ętaire code van AT&amp;T. Dit gebeurde eindelijk met "
-"de <emphasis>Networking Tape 2</emphasis>, gewoonlijk bekend als "
-"<emphasis>Net/2</emphasis>. Net/2 was geen compleet besturingssysteem: "
-"ongeveer 20% van de kernelcode ontbrak. Een van de leden van de CSRG, "
-"William F. Jolitz, schreef de overblijvende code en gaf het in het begin van "
-"1992 uit als <emphasis>386BSD</emphasis>. In diezelfde tijd begon een "
-"andere groep van ex-CSRG-leden een commercieel bedrijf genaamd <link xlink:"
-"href=\"http://www.bsdi.com/\">Berkeley Software Design Inc.</link> en gaf "
-"een betaversie van een besturingssysteem genaamd <link xlink:href=\"http://"
-"www.bsdi.com/\">BSD/386</link> uit, welke op dezelfde bronnen was "
-"gebaseerd. De naam van het besturingssysteem werd later veranderd in BSD/OS."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:191
-msgid ""
-"386BSD never became a stable operating system. Instead, two other projects "
-"split off from it in 1993: <link xlink:href=\"http://www.NetBSD.org/"
-"\">NetBSD</link> and <link xlink:href=\"@@URL_RELPREFIX@@/index.html"
-"\">FreeBSD</link>. The two projects originally diverged due to differences "
-"in patience waiting for improvements to 386BSD: the NetBSD people started "
-"early in the year, and the first version of FreeBSD was not ready until the "
-"end of the year. In the meantime, the code base had diverged sufficiently to "
-"make it difficult to merge. In addition, the projects had different aims, as "
-"we will see below. In 1996, <link xlink:href=\"http://www.OpenBSD.org/"
-"\">OpenBSD</link> split off from NetBSD, and in 2003, <link xlink:href="
-"\"http://www.dragonflybsd.org/\">DragonFlyBSD</link> split off from FreeBSD."
-msgstr ""
-"386BSD werd nooit een stabiel besturingssysteem. In plaats daarvan "
-"splitsten er twee andere projecten van af in 1993: <link xlink:href=\"http;//"
-"www.NetBSD.org/\">NetBSD</link> en <link xlink:href=\"@@URL_RELPREFIX@@/"
-"index.html\">FreeBSD</link>. De twee projecten groeiden oorspronkelijk uit "
-"elkaar wegens verschillen in de hoeveelheid geduld om op verbeteringen aan "
-"386BSD te wachten: de mensen van NetBSD begonnen in het begin van het jaar, "
-"en de eerste versie van FreeBSD was niet klaar voor het einde van het jaar. "
-"In de tussentijd waren de codebases genoeg uit elkaar gegroeid om "
-"samenvoegen ervan moeilijk te maken. Tevens hadden de projecten "
-"verschillende doelen, wat we hieronder zullen zien. In 1996 splitste <link "
-"xlink:href=\"http://www.OpenBSD.org/\">OpenBSD</link> zich af van NetBSD, en "
-"in 2003 splitste <link xlink:href=\"http://www.dragonflybsd.org/"
-"\">DragonFlyBSD</link> zich af van FreeBSD."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:208
-msgid "Why is BSD not better known?"
-msgstr "Waarom is BSD niet bekender?"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:210
-msgid "For a number of reasons, BSD is relatively unknown:"
-msgstr "Om een aantal redenen is BSD relatief onbekend:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:214
-msgid ""
-"The BSD developers are often more interested in polishing their code than "
-"marketing it."
-msgstr ""
-"De BSD-ontwikkelaars zijn vaak meer ge√Įnteresseerd in het verbeteren van hun "
-"code dan het aan de man brengen."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:219
-msgid ""
-"Much of Linux's popularity is due to factors external to the Linux projects, "
-"such as the press, and to companies formed to provide Linux services. Until "
-"recently, the open source BSDs had no such proponents."
-msgstr ""
-"Veel van de populariteit van Linux komt door factoren buiten de Linux-"
-"projecten, zoals de pers, en door bedrijven die zijn opgericht om Linux-"
-"diensten aan te bieden. Tot voor kort hadden de open-source BSDs zulke "
-"voorstanders niet."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:226
-msgid ""
-"BSD developers tend to be more experienced than Linux developers, and have "
-"less interest in making the system easy to use. Newcomers tend to feel more "
-"comfortable with Linux."
-msgstr ""
-"BSD-ontwikkelaars zijn vaak meer ervaren dan Linux-ontwikkelaars, en hebben "
-"minder interesse in het systeem gemakkelijk in gebruik te maken. "
-"Nieuwelingen voelen zich vaak meer op hun gemak met Linux."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:232
-msgid ""
-"In 1992, AT&amp;T sued <link xlink:href=\"http://www.bsdi.com/\">BSDI</"
-"link>, the vendor of BSD/386, alleging that the product contained AT&amp;T-"
-"copyrighted code. The case was settled out of court in 1994, but the spectre "
-"of the litigation continues to haunt people. In March 2000 an article "
-"published on the web claimed that the court case had been <quote>recently "
-"settled</quote>."
-msgstr ""
-"In 1992 klaagde AT&amp;T <link xlink:href=\"http://www.bsdi.com/\">BSDI</"
-"link>, de verkoper van BSD/386, aan op verdenking dat het product code "
-"bevatte waarover AT&amp;T copyright had. De zaak werd buiten de rechtbank "
-"om in 1994 beslist, maar het spook van de rechtszaak blijft mensen "
-"achtervolgen. Een artikel uit maart 2000 dat op het web werd gepubliceerd "
-"claimde dat de zaak <quote>recentelijk beslist</quote> was."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:240
-msgid ""
-"One detail that the lawsuit did clarify is the naming: in the 1980s, BSD was "
-"known as <quote>BSD <trademark class=\"registered\">UNIX</trademark></"
-"quote>. With the elimination of the last vestige of AT&amp;T code from BSD, "
-"it also lost the right to the name <trademark class=\"registered\">UNIX</"
-"trademark>. Thus you will see references in book titles to <quote>the 4.3BSD "
-"<trademark class=\"registered\">UNIX</trademark> operating system</quote> "
-"and <quote>the 4.4BSD operating system</quote>."
-msgstr ""
-"Eén detail dat de rechtszaak ophelderde is de naamgeving: in de jaren 80 "
-"stond BSD bekend als <quote>BSD <trademark class=\"registered\">UNIX</"
-"trademark></quote>. Met het nemen van de laatste vestiging van AT&amp;T-"
-"code van BSD, verloor het ook het recht op de naam <trademark class="
-"\"registered\">UNIX</trademark>. U zult dus verwijzingen in boektitels zien "
-"naar <quote>het besturingssysteem 4.3BSD <trademark class=\"registered"
-"\">UNIX</trademark></quote> en <quote>het besturingssysteem 4.4BSD</quote>."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:252
-msgid "Comparing BSD and Linux"
-msgstr "BSD en Linux vergelijken"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:254
-msgid ""
-"So what is really the difference between, say, Debian Linux and FreeBSD? For "
-"the average user, the difference is surprisingly small: Both are <trademark "
-"class=\"registered\">UNIX</trademark> like operating systems. Both are "
-"developed by non-commercial projects (this does not apply to many other "
-"Linux distributions, of course). In the following section, we will look at "
-"BSD and compare it to Linux. The description applies most closely to "
-"FreeBSD, which accounts for an estimated 80% of the BSD installations, but "
-"the differences from NetBSD, OpenBSD and DragonFlyBSD are small."
-msgstr ""
-"Wat is nou echt het verschil tussen bijvoorbeeld Debian Linux en FreeBSD? "
-"Voor de gemiddelde gebruiker is het verschil verrassend klein: beiden zijn "
-"<trademark class=\"registered\">UNIX</trademark>-achtige "
-"besturingssystemen. Beiden worden ontwikkeld door niet-commerci√ęle "
-"projecten (dit geldt uiteraard niet voor vele andere distributies van "
-"Linux). In de volgende sectie wordt BSD bekeken en vergeleken met Linux. "
-"De beschrijving is het beste van toepassing op FreeBSD, dat een geschatte "
-"80% van alle BSD-installaties voor rekening neemt, maar de verschillen van "
-"NetBSD, OpenBSD, en DragonFlyBSD zijn klein."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:265
-msgid "Who owns BSD?"
-msgstr "Wie bezit BSD?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:267
-msgid ""
-"No one person or corporation owns BSD. It is created and distributed by a "
-"community of highly technical and committed contributors all over the world. "
-"Some of the components of BSD are Open Source projects in their own right "
-"and managed by different project maintainers."
-msgstr ""
-"Geen enkel persoon of bedrijf bezit BSD. Het wordt tontwikkeld en verspreid "
-"door een gemeenschap van zeer technische en toegewijde wereldwijde "
-"contribuanten. Sommige onderdelen van BSD zijn open-source projecten op "
-"zichzelf en worden beheerd door verschillende projectbeheerders."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:275
-msgid "How is BSD developed and updated?"
-msgstr "Hoe wordt BSD ontwikkeld en bijgewerkt?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:277
-msgid ""
-"The BSD kernels are developed and updated following the Open Source "
-"development model. Each project maintains a publicly accessible "
-"<emphasis>source tree</emphasis> under <link xlink:href=\"https://subversion."
-"apache.org/\">Subversion</link> (SVN), which contains all source files for "
-"the project, including documentation and other incidental files. SVN allows "
-"users to <quote>check out</quote> (in other words, to extract a copy of) any "
-"desired version of the system."
-msgstr ""
-"De BSD-kernels worden ontwikkeld en bijgewerkt volgens het Open Source "
-"ontwikkelmodel. Elk project beheerst een publiek toegankelijke "
-"<emphasis>broncodeboom</emphasis> onder <link xlink:href=\"https://"
-"subversion.apache.org/\">Subversion</link> (SVN), wat alle bronbestanden "
-"voor het project bevat, inclusief documentatie en andere toevallige "
-"bestanden. SVN stelt gebruikers in staat om een <quote>check out</quote> te "
-"doen (met andere woorden, om een kopie te maken) van elke gewenste versie "
-"van het systeem."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:286
-msgid ""
-"A large number of developers worldwide contribute to improvements to BSD. "
-"They are divided into three kinds:"
-msgstr ""
-"Een grote groep van wereldwijde ontwikkelaars dragen bij aan verbeteringen "
-"aan BSD. Ze zijn verdeeld in drie soorten:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:291
-msgid ""
-"<firstterm>Contributors</firstterm> write code or documentation. They are "
-"not permitted to commit (add code) directly to the source tree. In order for "
-"their code to be included in the system, it must be reviewed and checked in "
-"by a registered developer, known as a <emphasis>committer</emphasis>."
-msgstr ""
-"<firstterm>Contributors</firstterm> schrijven code of documentatie. Ze "
-"hebben geen toestemming om direct naar de broncodeboom te committen (code "
-"toe te voegen). Om hun code aan het systeem toe te voegen, moet het herzien "
-"en ingecheckt worden door een geregistreerde ontwikkelaar, die een "
-"<emphasis>committer</emphasis> wordt genoemd."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:299
-msgid ""
-"<firstterm>Committers</firstterm> are developers with write access to the "
-"source tree. In order to become a committer, an individual must show ability "
-"in the area in which they are active."
-msgstr ""
-"<firstterm>Committers</firstterm> zijn ontwikkelaars met schrijftoegang tot "
-"de broncodeboom. Om committer te worden, moet een individu kennis en kunde "
-"laten zien in het gebied waarin hij actief is."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:304
-msgid ""
-"It is at the individual committer's discretion whether they should obtain "
-"authority before committing changes to the source tree. In general, an "
-"experienced committer may make changes which are obviously correct without "
-"obtaining consensus. For example, a documentation project committer may "
-"correct typographical or grammatical errors without review. On the other "
-"hand, developers making far-reaching or complicated changes are expected to "
-"submit their changes for review before committing them. In extreme cases, a "
-"core team member with a function such as Principal Architect may order that "
-"changes be removed from the tree, a process known as <firstterm>backing out</"
-"firstterm>. All committers receive mail describing each individual commit, "
-"so it is not possible to commit secretly."
-msgstr ""
-"Het is aan de discretie van de individuele committer of hij instemming moet "
-"krijgen voordat er veranderingen naar de broncodeboom worden gecommit. In "
-"het algemeen mag een ervaren committer veranderingen maken waarvan duidelijk "
-"is dat ze correct zijn zonder hiervoor consensus te verkrijgen. Een "
-"committer van het documentatieproject bijvoorbeeld mag typografische of "
-"grammaticale fouten verbeteren zonder dat deze herzien worden. Van de "
-"andere kant wordt van ontwikkelaars die verreikende of gecompliceerde "
-"veranderingen maken verwacht dat ze hun veranderingen ter herziening "
-"insturen voordat ze deze committen. In het uiterste geval kan een lid van "
-"het coreteam met een functie als Principal Architect eisen dat de "
-"veranderingen uit de boom verwijderd worden, een proces dat bekend staat als "
-"<firstterm>backing out</firstterm>. Alle committers ontvangen email die elke "
-"individuele commit beschrijft, het is dus niet mogelijk om heimelijk te "
-"committen."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:321
-msgid ""
-"The <firstterm>Core team</firstterm>. FreeBSD and NetBSD each have a core "
-"team which manages the project. The core teams developed in the course of "
-"the projects, and their role is not always well-defined. It is not necessary "
-"to be a developer in order to be a core team member, though it is normal. "
-"The rules for the core team vary from one project to the other, but in "
-"general they have more say in the direction of the project than non-core "
-"team members have."
-msgstr ""
-"Het <firstterm>Coreteam</firstterm>. FreeBSD en NetBSD hebben elk een "
-"coreteam dat het project beheert. De coreteams zijn in de loop van de "
-"projecten ontstaan, en hun rol is niet altijd eenduidig gedefinieerd. Het "
-"is niet nodig om ontwikkelaar te zijn om lid te zijn van het coreteam, "
-"hoewel het normaal is. De regels voor het coreteam verschillen per project, "
-"maar in het algemeen hebben ze een grotere inspraak in de richting van het "
-"project dan niet-leden van het coreteam hebben."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:332
-msgid "This arrangement differs from Linux in a number of ways:"
-msgstr "Deze opstelling verschilt in een aantal opzichten van die van Linux:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:336
-msgid ""
-"No one person controls the content of the system. In practice, this "
-"difference is overrated, since the Principal Architect can require that code "
-"be backed out, and even in the Linux project several people are permitted to "
-"make changes."
-msgstr ""
-"Geen enkel persoon heerst over de inhoud van het systeem. In de praktijk is "
-"dit verschil overdreven, aangezien de Principal Architect kan eisen dat code "
-"gebacked-out wordt, en zelfs in het Linux-project mogen meerdere mensen "
-"veranderingen maken."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:343
-msgid ""
-"On the other hand, there <emphasis>is</emphasis> a central repository, a "
-"single place where you can find the entire operating system sources, "
-"including all older versions."
-msgstr ""
-"Van de andere kant <emphasis>is</emphasis> er een centraal repository, een "
-"enkele plaats waar u de gehele broncode van het besturingssysteem kunt "
-"vinden, inclusief alle oudere versies."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:349
-msgid ""
-"BSD projects maintain the entire <quote>Operating System</quote>, not only "
-"the kernel. This distinction is only marginally useful: neither BSD nor "
-"Linux is useful without applications. The applications used under BSD are "
-"frequently the same as the applications used under Linux."
-msgstr ""
-"BSD-projecten beheren het gehele <quote>Besturingssysteem</quote>, niet "
-"alleen de kernel. Dit onderscheid is slechts van beperkt nut: noch BSD noch "
-"Linux is nuttig zonder applicaties. De applicaties die onder BSD gebruikt "
-"worden zijn vaak dezelfde als de applicaties die onder Linux gebruikt worden."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:357
-msgid ""
-"As a result of the formalized maintenance of a single SVN source tree, BSD "
-"development is clear, and it is possible to access any version of the system "
-"by release number or by date. SVN also allows incremental updates to the "
-"system: for example, the FreeBSD repository is updated about 100 times a "
-"day. Most of these changes are small."
-msgstr ""
-"Een gevolg van het formele beheer van een enkele SVN-broncodeboom is dat de "
-"BSD-ontwikkeling helder is, en dat het mogelijk is om elke versie van het "
-"systeem aan de hand van het uitgavenummer of datum te benaderen. SVN staat "
-"ook incrementele wijzigingen aan het systeem toe: het repository van FreeBSD "
-"bijvoorbeeld wordt ongeveer 100 keer per dag bijgewerkt. De meeste van deze "
-"veranderingen zijn klein."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:368
-msgid "BSD releases"
-msgstr "BSD-uitgaven"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:370
-msgid ""
-"FreeBSD, NetBSD and OpenBSD provide the system in three different "
-"<quote>releases</quote>. As with Linux, releases are assigned a number such "
-"as 1.4.1 or 3.5. In addition, the version number has a suffix indicating its "
-"purpose:"
-msgstr ""
-"FreeBSD, NetBSD, en OpenBSD bieden het systeem in drie verschillende "
-"<quote>uitgaven</quote> aan. Net als bij Linux worden aan uitgaven nummers "
-"zoals 1.4.1 of 3.5 toegekend. Tevens heeft het versienummer een "
-"achtervoegsel die het doel aangeeft:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:377
-msgid ""
-"The development version of the system is called <firstterm>CURRENT</"
-"firstterm>. FreeBSD assigns a number to CURRENT, for example FreeBSD 5.0-"
-"CURRENT. NetBSD uses a slightly different naming scheme and appends a single-"
-"letter suffix which indicates changes in the internal interfaces, for "
-"example NetBSD 1.4.3G. OpenBSD does not assign a number (<quote>OpenBSD-"
-"current</quote>). All new development on the system goes into this branch."
-msgstr ""
-"De ontwikkelversie van het systeem wordt <firstterm>CURRENT</firstterm> "
-"genoemd. FreeBSD kent een nummer aan CURRENT toe, bijvoorbeeld FreeBSD 5.0-"
-"CURRENT. NetBSD hanteert een lichtelijk ander schema voor de naamgeving en "
-"voegt een achtervoegsel van een enkele letter toe welke veranderingen aan de "
-"interne interfaces aangeeft, bijvoorbeeld NetBSD 1.4.3G. OpenBSD kent geen "
-"nummer toe(<quote>OpenBSD-current</quote>). Alle nieuwe ontwikkelingen aan "
-"het systeem komen in deze tak terecht."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:387
-msgid ""
-"At regular intervals, between two and four times a year, the projects bring "
-"out a <firstterm>RELEASE</firstterm> version of the system, which is "
-"available on CD-ROM and for free download from FTP sites, for example "
-"OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. The RELEASE version is intended "
-"for end users and is the normal version of the system. NetBSD also provides "
-"<emphasis>patch releases</emphasis> with a third digit, for example NetBSD "
-"1.4.2."
-msgstr ""
-"De projecten brengen met regelmatige tussenpozen, tussen twee en vier keer "
-"per jaar, een <firstterm>RELEASE</firstterm>-versie van het systeem uit, "
-"welke beschikbaar is op CD-ROM en vrij te downloaden is van FTP-sites, "
-"bijvoorbeeld OpenBSD 2.6-RELEASE of NetBSD 1.4-RELEASE. De RELEASE-versie "
-"is bedoeld voor eindgebruikers en is de normale versie van het systeem. "
-"NetBSD biedt ook <emphasis>patch-uitgaven</emphasis> aan met een derde "
-"cijfer, bijvoorbeeld NetBSD 1.4.2."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:398
-msgid ""
-"As bugs are found in a RELEASE version, they are fixed, and the fixes are "
-"added to the SVN tree. In FreeBSD, the resultant version is called the "
-"<firstterm>STABLE</firstterm> version, while in NetBSD and OpenBSD it "
-"continues to be called the RELEASE version. Smaller new features can also be "
-"added to this branch after a period of test in the CURRENT branch. Security "
-"and other important bug fixes are also applied to all supported RELEASE "
-"versions."
-msgstr ""
-"Wanneer er bugs in een RELEASE-versie worden gevonden, worden ze "
-"gerepareeed, en worden de reparaties toegevoegd aan de SVN-boom. In FreeBSD "
-"wordt de resulterende versie de <firstterm>STABLE</firstterm>-versie "
-"genoemd, terwijl het in NetBSD en OpenBSD de RELEASE-versie blijft heten. "
-"Kleinere nieuwe eigenschappen kunnen ook aan deze tak worden toegevoegd na "
-"een testperiode in de CURRENT-tak. Beveiligings- en andere belangrijke "
-"reparaties worden ook op alle ondersteunde RELEASE-versies toegepast."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:408
-msgid ""
-"<emphasis>By contrast, Linux maintains two separate code trees: the stable "
-"version and the development version. Stable versions have an even minor "
-"version number, such as 2.0, 2.2 or 2.4. Development versions have an odd "
-"minor version number, such as 2.1, 2.3 or 2.5. In each case, the number is "
-"followed by a further number designating the exact release. In addition, "
-"each vendor adds their own userland programs and utilities, so the name of "
-"the distribution is also important. Each distribution vendor also assigns "
-"version numbers to the distribution, so a complete description might be "
-"something like <quote>TurboLinux 6.0 with kernel 2.2.14</quote></emphasis>"
-msgstr ""
-"<emphasis>In contrast hiermee onderhoudt Linux twee gescheiden codebomen: "
-"de stabiele versie en de ontwikkelversie. Stabiele versies hebben een even "
-"klein versienummer, zoals 2.0, 2.2, of 2.4. Ontwikkelversies hebben een "
-"oneven klein versienummer, zoals 2.1, 2.3, of 2.5. In alle gevallen wordt "
-"het nummer gevolgd door een nog een nummer dat de exacte uitgave aangeeft. "
-"Verder voegt elke verkoper zijn eigen gebruikersprogramma's en "
-"gereedschappen toe, dus is de naam van de distributie ook belangrijk. Elke "
-"verkoper van distributies kent ook versienummers aan de distributie toe, dus "
-"kan een volledige omschrijving iets zijn als <quote>TurboLinux 6.0 met "
-"kernel 2.2.14</quote> zijn.</emphasis>"
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:422
-msgid "What versions of BSD are available?"
-msgstr "Welke versies van BSD zijn beschikbaar?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:424
-msgid ""
-"In contrast to the numerous Linux distributions, there are only four major "
-"open source BSDs. Each BSD project maintains its own source tree and its own "
-"kernel. In practice, though, there appear to be fewer divergences between "
-"the userland code of the projects than there is in Linux."
-msgstr ""
-"In tegenstelling tot de vele Linux-distributies, zijn er slechts vier grote "
-"open-source BSDs. Elk BSD-project beheert zijn eigen broncodeboom en zijn "
-"eigen kernel. In de praktijk schijnt er echter minder divergentie te zijn "
-"tussen de gebruikerscode van de projecten dan dat er in Linux is."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:430
-msgid ""
-"It is difficult to categorize the goals of each project: the differences are "
-"very subjective. Basically,"
-msgstr ""
-"Het is moeilijk om de doelen van elk project te categoriseren: de "
-"verschillen zijn erg subjectief. Het volgende geldt ongeveer:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:435
-msgid ""
-"FreeBSD aims for high performance and ease of use by end users, and is a "
-"favourite of web content providers. It runs on a <link xlink:href="
-"\"@@URL_RELPREFIX@@/platforms/\">number of platforms</link> and has "
-"significantly more users than the other projects."
-msgstr ""
-"FreeBSD richt zich op hoge prestaties en gebruikersgemak voor "
-"eindgebruikers, en is een favoriet van aanbieders van webinhoud. Het draait "
-"op een <link xlink:href=\"@@URL_RELPREFIX@@/platforms/\">aantal platformen</"
-"link> en heeft aanzienlijk meer gebruikers dan de andere projecten."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:442
-msgid ""
-"NetBSD aims for maximum portability: <quote>of course it runs NetBSD</"
-"quote>. It runs on machines from palmtops to large servers, and has even "
-"been used on NASA space missions. It is a particularly good choice for "
-"running on old non-<trademark class=\"registered\">Intel</trademark> "
-"hardware."
-msgstr ""
-"NetBSD gaat voor maximale portabiliteit: <quote>of course it runs NetBSD</"
-"quote>. Het draait op machines vari√ęrend van palmtops tot grote servers, en "
-"het is zelfs gebruikt in ruimtemissies van NASA. Het is een bijzonder goede "
-"keuze om op oude niet-<trademark class=\"registered\">Intel</trademark> "
-"hardware te draaien."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:450
-msgid ""
-"OpenBSD aims for security and code purity: it uses a combination of the open "
-"source concept and rigorous code reviews to create a system which is "
-"demonstrably correct, making it the choice of security-conscious "
-"organizations such as banks, stock exchanges and US Government departments. "
-"Like NetBSD, it runs on a number of platforms."
-msgstr ""
-"OpenBSD gaat voor beveiliging en code-puurheid: het gebruikt een combinatie "
-"van het open-source concept en rigoureuze codeherzieningen om een systeem te "
-"maken dat aantoonbaar correct is, waardoor het de keuze is van "
-"beveiligingsbewuste organisaties zoals banken, beurzen, en afdelingen van de "
-"Amerikaanse overheid. Net als NetBSD draait het op een aantal platformen."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:459
-msgid ""
-"DragonFlyBSD aims for high performance and scalability under everything from "
-"a single-node UP system to a massively clustered system. DragonFlyBSD has "
-"several long-range technical goals, but focus lies on providing a SMP-"
-"capable infrastructure that is easy to understand, maintain and develop for."
-msgstr ""
-"DragonFlyBSD gaat voor hoge prestaties en schaalbaarheid vari√ęrend van een "
-"UP-systeem van een enkele computer tot een reusachtig geclusterd systeem. "
-"DragonFlyBSD heeft verscheidene technische langetermijndoelen, maar de focus "
-"ligt op het bieden van een SMP-capabele infrastructuur dat eenvoudig te "
-"begrijpen en te onderhouden is, en waarvoor eenvoudig te ontwikkelen is."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:467
-msgid ""
-"There are also two additional BSD <trademark class=\"registered\">UNIX</"
-"trademark> operating systems which are not open source, BSD/OS and Apple's "
-"<trademark class=\"registered\">Mac OS</trademark> X:"
-msgstr ""
-"Er zijn ook twee aanvullende BSD <trademark class=\"registered\">UNIX</"
-"trademark> besturingssystemen die niet open-source zijn, BSD/OS en "
-"<trademark class=\"registered\">Mac OS</trademark> X van Apple:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:472
-msgid ""
-"BSD/OS was the oldest of the 4.4BSD derivatives. It was not open source, "
-"though source code licenses were available at relatively low cost. It "
-"resembled FreeBSD in many ways. Two years after the acquisition of BSDi by "
-"Wind River Systems, BSD/OS failed to survive as an independent product. "
-"Support and source code may still be available from Wind River, but all new "
-"development is focused on the VxWorks embedded operating system."
-msgstr ""
-"BSD/OS was de oudste van de afgeleiden van 4.4BSD. Het was niet open-"
-"source, alhoewel licenties voor de broncode tegen relatief kosten "
-"beschikbaar waren. Het leek in vele opzichten op FreeBSD. Twee jaar na de "
-"aankoop van BSDi door Wind River Systems slaagde BSD/OS er niet in om als "
-"een onafhankelijk product te overleven. Ondersteuning en broncode kunnnen "
-"nog steeds beschikbaar zijn van Wind River, maar alle nieuwe ontwikkelingen "
-"zijn gericht op het embedded besturingssysteem VxWorks."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:483
-msgid ""
-"<link xlink:href=\"http://www.apple.com/macosx/server/\"><trademark class="
-"\"registered\">Mac OS</trademark> X</link> is the latest version of the "
-"operating system for <trademark class=\"registered\">Apple</trademark>'s "
-"<trademark class=\"registered\">Mac</trademark> line. The BSD core of this "
-"operating system, <link xlink:href=\"http://developer.apple.com/darwin/"
-"\">Darwin</link>, is available as a fully functional open source operating "
-"system for x86 and PPC computers. The Aqua/Quartz graphics system and many "
-"other proprietary aspects of <trademark class=\"registered\">Mac OS</"
-"trademark> X remain closed-source, however. Several Darwin developers are "
-"also FreeBSD committers, and vice-versa."
-msgstr ""
-"<link xlink:href=\"http://www.apple.com/macosx/server/\"><trademark class="
-"\"registered\">Mac OS</trademark> X</link> is de nieuwste versie van het "
-"besturingssysteem voor de <trademark class=\"registered\">Mac</trademark> "
-"lijn van <trademark class=\"registered\">Apple</trademark>. De BSD-kern van "
-"dit besturingssysteem, <link xlink:href=\"http://developer.apple.com/darwin/"
-"\">Darwin</link> is beschikbaar als een volledig werkend open-source "
-"besturingssysteem voor x86- en PPC-computers. Het grafische systeem Aqua/"
-"Quartz en vele andere propri√ętaire aspecten van <trademark class=\"registered"
-"\">Mac OS</trademark> X blijven echter closed-source. Verschillende Darwin-"
-"ontwikkelaars zijn ook FreeBSD-committers, en vice-versa."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:499
-msgid "How does the BSD license differ from the GNU Public license?"
-msgstr "Hoe verschilt de BSD-licentie van de publieke GNU-licentie?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:502
-msgid ""
-"Linux is available under the <link xlink:href=\"http://www.fsf.org/copyleft/"
-"gpl.html\">GNU General Public License</link> (GPL), which is designed to "
-"eliminate closed source software. In particular, any derivative work of a "
-"product released under the GPL must also be supplied with source code if "
-"requested. By contrast, the <link xlink:href=\"http://www.opensource.org/"
-"licenses/bsd-license.html\">BSD license</link> is less restrictive: binary-"
-"only distributions are allowed. This is particularly attractive for embedded "
-"applications."
-msgstr ""
-"Linux is beschikbaar onder de <link xlink:href=\"http://www.fsf.org/copyleft/"
-"gpl.html\">GNU General Public License</link> (GPL), welke ontwikkeld is om "
-"closed-source software te elimineren. In het bijzonder moet elk afgeleid "
-"werk van een product dat onder de GPL is vrijgegeven ook met de broncode "
-"geleverd worden indien dat gevraagd wordt. In tegenstelling hiermee is de "
-"<link xlink:href=\"http://www.opensource.org/licenses/bsd-license.html\">BSD-"
-"licentie</link> minder beperkend: distributies met alleen binairen zijn "
-"toegestaan. Dit is in het bijzonder aantrekkelijk voor embedded applicaties."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:515
-msgid "What else should I know?"
-msgstr "Wat moet ik nog meer weten?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:517
-msgid ""
-"Since fewer applications are available for BSD than Linux, the BSD "
-"developers created a Linux compatibility package, which allows Linux "
-"programs to run under BSD. The package includes both kernel modifications, "
-"in order to correctly perform Linux system calls, and Linux compatibility "
-"files such as the C library. There is no noticeable difference in execution "
-"speed between a Linux application running on a Linux machine and a Linux "
-"application running on a BSD machine of the same speed."
-msgstr ""
-"Aangezien er minder applicaties beschikbaar zijn voor BSD dan voor Linux, "
-"hebben de ontwikkelaars van BSD een Linux-compatibiliteitspakket ontwikkeld, "
-"wat het mogelijk maakt om Linux-programma's onder BSD te draaien. Het "
-"pakket bevat zowel kernelwijzigingen, om Linux-systeemaanroepen correct uit "
-"te voeren, en Linux-compatibiliteitsbestanden zoals de C-bibliotheek. Er is "
-"geen merkbaar verschil in uitvoersnelheid tussen een Linux-applicatie die op "
-"een Linux-machine draait en een Linux-applicatie die op een BSD-machine die "
-"dezelfde snelheid heeft draait."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:526
-msgid ""
-"The <quote>all from one supplier</quote> nature of BSD means that upgrades "
-"are much easier to handle than is frequently the case with Linux. BSD "
-"handles library version upgrades by providing compatibility modules for "
-"earlier library versions, so it is possible to run binaries which are "
-"several years old with no problems."
-msgstr ""
-"De <quote>alles van één leverancier</quote>-natuur van BSD dat upgrades veel "
-"makkelijker af te handelen zijn dan dat vaak met Linux het geval is. BSD "
-"handelt upgrades aan bibliotheekversies af door compatibiliteitsmodulen voor "
-"eerdere bibliotheekversies aan te bieden, dus is het mogelijk om binairen "
-"die enige jaren oud zijn zonder problemen te draaien."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:534
-msgid "Which should I use, BSD or Linux?"
-msgstr "Wat zou ik moeten gebruiken, BSD of Linux?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:536
-msgid ""
-"What does this all mean in practice? Who should use BSD, who should use "
-"Linux?"
-msgstr ""
-"Wat betekent dit allemaal in de praktijk? Wie zou BSD moeten gebruiken, en "
-"wie Linux?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:539
-msgid "This is a very difficult question to answer. Here are some guidelines:"
-msgstr ""
-"Dit is een erg moeilijke vraag om te beantwoorden. Hier zijn wat "
-"richtlijnen:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:544
-msgid ""
-"<quote>If it ain't broke, don't fix it</quote>: If you already use an open "
-"source operating system, and you are happy with it, there is probably no "
-"good reason to change."
-msgstr ""
-"<quote>If it ain't broke, don't fix it</quote>: als u al een open-source "
-"besturingssysteem gebruikt, en u er tevreden over bent, dan is er "
-"waarschijnlijk geen goede reden om over te stappen."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:550
-msgid ""
-"BSD systems, in particular FreeBSD, can have notably higher performance than "
-"Linux. But this is not across the board. In many cases, there is little or "
-"no difference in performance. In some cases, Linux may perform better than "
-"FreeBSD."
-msgstr ""
-"BSD-systemen, in het bijzonder FreeBSD, kunnen merkbaar beter presteren dan "
-"Linux. Maar dit geldt niet voor alles. In veel gevallen zijn er weinig of "
-"geen prestatieverschillen. In sommige gevallen kan Linux beter presteren "
-"dan FreeBSD."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:557
-msgid ""
-"In general, BSD systems have a better reputation for reliability, mainly as "
-"a result of the more mature code base."
-msgstr ""
-"In het algemeen hebben BSD-systemen een betere naam qua betrouwbaarheid, "
-"voornamelijk als het resultaat van een volwassenere codebase."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:563
-msgid ""
-"BSD projects have a better reputation for the quality and completeness of "
-"their documentation. The various documentation projects aim to provide "
-"actively updated documentation, in many languages, and covering all aspects "
-"of the system."
-msgstr ""
-"BSD-projecten hebben een betere naam qua kwaliteit en volledigheid van hun "
-"documentatie. De verschillende documentatieprojecten richten zich op het "
-"bieden van actief bijgewerkte documentatie, in vele talen, en op het "
-"behandelen van alle aspecten van het systeem."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:570
-msgid "The BSD license may be more attractive than the GPL."
-msgstr "De BSD-licentie kan aantrekkelijker zijn dan de GPL."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:574
-msgid ""
-"BSD can execute most Linux binaries, while Linux can not execute BSD "
-"binaries. Many BSD implementations can also execute binaries from other "
-"<trademark class=\"registered\">UNIX</trademark> like systems. As a result, "
-"BSD may present an easier migration route from other systems than Linux "
-"would."
-msgstr ""
-"BSD kan de meeste Linux-binairen uitvoeren, terwijl Linux geen BSD-binairen "
-"kan uitvoeren. Vele implementaties van BSD kunnen ook binairen van andere "
-"<trademark class=\"registered\">UNIX</trademark>-achtige systemen "
-"uitvoeren. Als gevolg kan BSD een eenvoudigere migratieroute zijn van "
-"andere systemen dan dat Linux zou zijn."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:584
-msgid "Who provides support, service, and training for BSD?"
-msgstr "Wie biedt ondersteuning, diensten, en training voor BSD aan?"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:586
-msgid ""
-"BSDi / <link xlink:href=\"http://www.freebsdmall.com\">FreeBSD Mall, Inc.</"
-"link> have been providing support contracts for FreeBSD for nearly a decade."
-msgstr ""
-"BSDi / <link xlink:href=\"http://www.freebsdmall.com\">FreeBSD Mall Inc.</"
-"link> bieden sinds bijna een decennium ondersteuningscontracten aan voor "
-"FreeBSD."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:590
-msgid ""
-"In addition, each of the projects has a list of consultants for hire: <link "
-"xlink:href=\"@@URL_RELPREFIX@@/commercial/consult_bycat.html\">FreeBSD</"
-"link>, <link xlink:href=\"http://www.netbsd.org/gallery/consultants.html"
-"\">NetBSD</link>, and <link xlink:href=\"http://www.openbsd.org/support.html"
-"\">OpenBSD</link>."
-msgstr ""
-"Verder heeft elk project een lijst van in te huren consultants: <link xlink:"
-"href=\"@@URL_RELPREFIX@@/commercial/consult_bycat.html\">FreeBSD</link>, "
-"<link xlink:href=\"http://www.netbsd.org/gallery/consultants.html\">NetBSD</"
-"link>, en <link xlink:href=\"http://www.openbsd.org/support.html\">OpenBSD</"
-"link>."
-
-#~ msgid ""
-#~ "There is a perception that the BSD projects are fragmented and "
-#~ "belligerent. The <link xlink:href=\"http://interactive.wsj.com/bin/login?"
-#~ "Tag=/&amp;URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651."
-#~ "djm&amp;\">Wall Street Journal</link> spoke of <quote>balkanization</"
-#~ "quote> of the BSD projects. Like the law suit, this perception bases "
-#~ "mainly on ancient history."
-#~ msgstr ""
-#~ "De indruk heerst dat de BSD-projecten gefragmenteerd en oorlogvoerend "
-#~ "zijn. De <link xlink:href=\"http://interactive.wsj.com/bin/login?Tag=/"
-#~ "&amp;URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&amp;"
-#~ "\">Wall Street Journal</link> sprak van <quote>balkanizatie</quote> van "
-#~ "de BSD-projecten. Net als de rechtszaak is dit beeld voornamelijk op een "
-#~ "oude geschiedenis gebaseerd."
diff --git a/nl_NL.ISO8859-1/articles/leap-seconds/Makefile b/nl_NL.ISO8859-1/articles/leap-seconds/Makefile
deleted file mode 100644
index 890b94f26e..0000000000
--- a/nl_NL.ISO8859-1/articles/leap-seconds/Makefile
+++ /dev/null
@@ -1,19 +0,0 @@
-#
-# $FreeBSD$
-#
-# Article: Leap Seconds
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/articles/leap-seconds/article.xml b/nl_NL.ISO8859-1/articles/leap-seconds/article.xml
deleted file mode 100644
index c06757fbc1..0000000000
--- a/nl_NL.ISO8859-1/articles/leap-seconds/article.xml
+++ /dev/null
@@ -1,64 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="leapseconds" xml:lang="nl_NL">
-
- <info>
- <title>Ondersteuning voor schrikkelseconden in FreeBSD</title>
-
- <pubdate>$FreeBSD$</pubdate>
- </info>
-
- <sect1 xml:id="leapseconds-definition">
- <title>Introductie</title>
-
- <para>Een <emphasis>schrikkelseconde</emphasis> is een ad-hoc correctie van één seconde om de atomaire tijd te synchroniseren met de omwenteling van de aarde. Dit artikel beschrijft hoe FreeBSD omgaat met schrikkelseconden.</para>
-
- <para>Op het moment van schrijven zal de volgende schrikkelseconde plaatsvinden op 2015-juni-30 23:59:60 UTC. Deze schrikkelseconde zal plaatsvinden op een werkdag voor Noord- en Zuid-Amerika en het Aziatische/Pacifische gebied.</para>
-
- <para>Schrikkelseconden worden aangekondigd door <link xlink:href="http://datacenter.iers.org/"><acronym>IERS</acronym></link> op <link xlink:href="http://datacenter.iers.org/web/guest/bulletins/-/somos/5Rgv/product/16">Bulletin C</link>.</para>
-
- <para>Het standaardgedrag van schrikkelseconden is beschreven in <link xlink:href="https://tools.ietf.org/html/rfc7164#section-3">RFC 7164</link>. Zie ook <citerefentry><refentrytitle>time2posix</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
- </sect1>
-
- <sect1 xml:id="leapseconds-posix">
- <title>De standaardomgang met schrikkelseconden op FreeBSD</title>
-
- <para>De eenvoudigste manier om met schrikkelseconden om te gaan is met de tijdregels van <acronym>POSIX</acronym> die FreeBSD standaard gebruikt, gecombineerd met <link xlink:href="@@URL_RELPREFIX@@/doc/nl_NL.ISO8859-1/books/handbook/network-ntp.html"><acronym>NTP</acronym></link>. Wanneer <citerefentry><refentrytitle>ntpd</refentrytitle><manvolnum>8</manvolnum></citerefentry> draait en de tijd gesynchroniseerd is met de bovenliggende <acronym>NTP</acronym>-servers die schrikkelseconden correct afhandelen, zal de schrikkelseconde ervoor zorgen dat de systeemtijd automatisch de laatste seconde van de dag herhaalt. Er zijn geen andere aanpassingen nodig.</para>
-
- <para>Als de bovenliggende <acronym>NTP</acronym>-servers schrikkelseconden niet correct afhandelen, zal <citerefentry><refentrytitle>ntpd</refentrytitle><manvolnum>8</manvolnum></citerefentry> de tijd met één seconde laten verspringen nadat de foutieve bovenliggende server dit opgemerkt heeft en zelf is versprongen.</para>
-
- <para>Als <acronym>NTP</acronym> niet wordt gebruikt, is het nodig om de systeemklok handmatig aan te passen nadat de schrikkelseconde is verstreken.</para>
- </sect1>
-
- <sect1 xml:id="leapseconds-cautions">
- <title>Waarschuwingen</title>
-
- <para>Schrikkelseconden worden wereldwijd op hetzelfde moment ingevoegd: middernacht <acronym>UTC</acronym>. In Japan is dit in het midden van de ochtend, in het Pacifisch gebied in het midden van de dag, in Amerika in de namiddag en in Europa in de nacht.</para>
-
- <para>We geloven en verwachten dat FreeBSD, mits voorzien van een correcte en stabiele <acronym>NTP</acronym>-dienst, zal werken als ontworpen tijdens deze schrikkelseconde, zoals het tijdens de voorgaande deed.</para>
-
- <para>We waarschuwen echter dat praktisch geen enkele toepassing de kernel ooit om schrikkelseconden heeft gevraagd. Onze verwachting is dat, zoals ontworpen, schrikkelseconden in feite een herhaling zijn van de seconde voor de schrikkelseconde, wat een verassing is voor de meeste toepassingsprogrammeurs.</para>
-
- <para>Andere besturingssystemen en computers kunnen de schrikkelseconde op een andere manier dan FreeBSD afhandelen, en systemen zonder correcte en stabiele <acronym>NTP</acronym>-dienst zullen in het geheel niks van schrikkelseconden weten.</para>
-
- <para>Het komt voor dat computers crashen vanwege schrikkelseconden, en ervaring laat zien dat een groot gedeelte van alle publieke <acronym>NTP</acronym>-servers de schrikkelseconde onjuist kunnen aankondigen en afhandelen.</para>
-
- <para>Probeer er alstublieft voor te zorgen dat er niks ergs gebeurt vanwege de schrikkelseconde.</para>
- </sect1>
-
- <sect1 xml:id="leapseconds-testing">
- <title>Testen</title>
-
- <para>Het is mogelijk om te kijken of een schrikkelseconde zal worden gebruikt. Vanwege de aard van <acronym>NTP</acronym> kan de test tot 24 uur voor de schrikkelseconde werken. Sommige grote bronnen van referentieklokken kondigen schrikkelseconden slechts één uur van te voren aan. Ondervraag de daemon <acronym>NTP</acronym>:</para>
-
- <screen><prompt>%</prompt> <userinput>ntpq -c 'rv 0 leap'</userinput></screen>
-
- <para>Uitvoer die <literal>leap_add_sec</literal> bevat wijst op correcte ondersteuning van de schrikkelseconde. Voorafgaand aan de 24 uur die tot de schrikkelseconde leiden, of nadat de schrikkelseconde is verstreken, zal <literal>leap_none</literal> zichtbaar zijn.</para>
- </sect1>
-
- <sect1 xml:id="leapseconds-conclusion">
- <title>Conclusie</title>
-
- <para>In de praktijk zijn schrikkelseconden meestal geen probleem op FreeBSD. We hopen dat dit overzicht helpt met wat te verwachten en hoe schrikkelseconden gladder te laten verlopen.</para>
- </sect1>
-</article>
diff --git a/nl_NL.ISO8859-1/articles/leap-seconds/nl_NL.po b/nl_NL.ISO8859-1/articles/leap-seconds/nl_NL.po
deleted file mode 100644
index 454d070a7b..0000000000
--- a/nl_NL.ISO8859-1/articles/leap-seconds/nl_NL.po
+++ /dev/null
@@ -1,138 +0,0 @@
-msgid ""
-msgstr ""
-"Project-Id-Version: FreeBSD Documentation Project\n"
-"POT-Creation-Date: 2015-09-02 23:09+0200\n"
-"PO-Revision-Date: 2015-09-03 22:24+0100\n"
-"Last-Translator: Renť Ladan <rene@freebsd.org>\n"
-"Language-Team: Dutch <freebsd-translators@freebsd.org>\n"
-"Language: nl_NL\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=iso-8859-1\n"
-"Content-Transfer-Encoding: 8bit\n"
-
-#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
-msgctxt "_"
-msgid "translator-credits"
-msgstr "vertaling"
-
-#. (itstool) path: info/title
-#: article.translate.xml:6
-msgid "FreeBSD Support for Leap Seconds"
-msgstr "Ondersteuning voor schrikkelseconden in FreeBSD"
-
-#. (itstool) path: info/pubdate
-#: article.translate.xml:8
-msgid "$FreeBSD$"
-msgstr "$FreeBSD$"
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:12
-msgid "Introduction"
-msgstr "Introductie"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:14
-msgid "A <emphasis>leap second</emphasis> is an ad-hoc one-second correction to synchronize atomic timescales with Earth rotation. This article describes how FreeBSD interacts with leap seconds."
-msgstr "Een <emphasis>schrikkelseconde</emphasis> is een ad-hoc correctie van ťťn seconde om de atomaire tijd te synchroniseren met de omwenteling van de aarde. Dit artikel beschrijft hoe FreeBSD omgaat met schrikkelseconden."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:19
-msgid "As of this writing, the next leap second will occur at 2015-Jun-30 23:59:60 UTC. This leap second will occur during a business day for North and South America and the Asia/Pacific region."
-msgstr "Op het moment van schrijven zal de volgende schrikkelseconde plaatsvinden op 2015-juni-30 23:59:60 UTC. Deze schrikkelseconde zal plaatsvinden op een werkdag voor Noord- en Zuid-Amerika en het Aziatische/Pacifische gebied."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:24
-msgid "Leap seconds are announced by <link xlink:href=\"http://datacenter.iers.org/\"><acronym>IERS</acronym></link> on <link xlink:href=\"http://datacenter.iers.org/web/guest/bulletins/-/somos/5Rgv/product/16\">Bulletin C</link>."
-msgstr "Schrikkelseconden worden aangekondigd door <link xlink:href=\"http://datacenter.iers.org/\"><acronym>IERS</acronym></link> op <link xlink:href=\"http://datacenter.iers.org/web/guest/bulletins/-/somos/5Rgv/product/16\">Bulletin C</link>."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:28
-msgid "Standard leap second behavior is described in <link xlink:href=\"https://tools.ietf.org/html/rfc7164#section-3\">RFC 7164</link>. Also see <citerefentry><refentrytitle>time2posix</refentrytitle><manvolnum>3</manvolnum></citerefentry>."
-msgstr "Het standaardgedrag van schrikkelseconden is beschreven in <link xlink:href=\"https://tools.ietf.org/html/rfc7164#section-3\">RFC 7164</link>. Zie ook <citerefentry><refentrytitle>time2posix</refentrytitle><manvolnum>3</manvolnum></citerefentry>."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:33
-msgid "Default Leap Second Handling on FreeBSD"
-msgstr "De standaardomgang met schrikkelseconden op FreeBSD"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:35
-msgid "The easiest way to handle leap seconds is with the <acronym>POSIX</acronym> time rules FreeBSD uses by default, combined with <link xlink:href=\"@@URL_RELPREFIX@@/doc/nl_NL.ISO8859-1/books/handbook/network-ntp.html\"><acronym>NTP</acronym></link>. When <citerefentry><refentrytitle>ntpd</refentrytitle><manvolnum>8</manvolnum></citerefentry> is running and the time is synchronized with upstream <acronym>NTP</acronym> servers that handle leap seconds correctly, the leap second will cause the system time to automatically repeat the last second of the day. No other adjustments are necessary."
-msgstr "De eenvoudigste manier om met schrikkelseconden om te gaan is met de tijdregels van <acronym>POSIX</acronym> die FreeBSD standaard gebruikt, gecombineerd met <link xlink:href=\"@@URL_RELPREFIX@@/doc/nl_NL.ISO8859-1/books/handbook/network-ntp.html\"><acronym>NTP</acronym></link>. Wanneer <citerefentry><refentrytitle>ntpd</refentrytitle><manvolnum>8</manvolnum></citerefentry> draait en de tijd gesynchroniseerd is met de bovenliggende <acronym>NTP</acronym>-servers die schrikkelseconden correct afhandelen, zal de schrikkelseconde ervoor zorgen dat de systeemtijd automatisch de laatste seconde van de dag herhaalt. Er zijn geen andere aanpassingen nodig."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:44
-msgid "If the upstream <acronym>NTP</acronym> servers do not handle leap seconds correctly, <citerefentry><refentrytitle>ntpd</refentrytitle><manvolnum>8</manvolnum></citerefentry> will step the time by one second after the errant upstream server has noticed and stepped itself."
-msgstr "Als de bovenliggende <acronym>NTP</acronym>-servers schrikkelseconden niet correct afhandelen, zal <citerefentry><refentrytitle>ntpd</refentrytitle><manvolnum>8</manvolnum></citerefentry> de tijd met ťťn seconde laten verspringen nadat de foutieve bovenliggende server dit opgemerkt heeft en zelf is versprongen."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:49
-msgid "If <acronym>NTP</acronym> is not being used, manual adjustment of the system clock will be required after the leap second has passed."
-msgstr "Als <acronym>NTP</acronym> niet wordt gebruikt, is het nodig om de systeemklok handmatig aan te passen nadat de schrikkelseconde is verstreken."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:55
-msgid "Cautions"
-msgstr "Waarschuwingen"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:57
-msgid "Leap seconds are inserted at the same instant all over the world: <acronym>UTC</acronym> midnight. In Japan that is mid-morning, in the Pacific mid-day, in the Americas late afternoon, and in Europe at night."
-msgstr "Schrikkelseconden worden wereldwijd op hetzelfde moment ingevoegd: middernacht <acronym>UTC</acronym>. In Japan is dit in het midden van de ochtend, in het Pacifisch gebied in het midden van de dag, in Amerika in de namiddag en in Europa in de nacht."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:62
-msgid "We believe and expect that FreeBSD, if provided correct and stable <acronym>NTP</acronym> service, will work as designed during this leap second, as it did during the previous ones."
-msgstr "We geloven en verwachten dat FreeBSD, mits voorzien van een correcte en stabiele <acronym>NTP</acronym>-dienst, zal werken als ontworpen tijdens deze schrikkelseconde, zoals het tijdens de voorgaande deed."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:67
-msgid "However, we caution that practically no applications have ever asked the kernel about leap seconds. Our experience is that, as designed, leap seconds are essentially a replay of the second before the leap second, and this is a surprise to most application programmers."
-msgstr "We waarschuwen echter dat praktisch geen enkele toepassing de kernel ooit om schrikkelseconden heeft gevraagd. Onze verwachting is dat, zoals ontworpen, schrikkelseconden in feite een herhaling zijn van de seconde voor de schrikkelseconde, wat een verassing is voor de meeste toepassingsprogrammeurs."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:73
-msgid "Other operating systems and other computers may or may not handle the leap-second the same way as FreeBSD, and systems without correct and stable <acronym>NTP</acronym> service will not know anything about leap seconds at all."
-msgstr "Andere besturingssystemen en computers kunnen de schrikkelseconde op een andere manier dan FreeBSD afhandelen, en systemen zonder correcte en stabiele <acronym>NTP</acronym>-dienst zullen in het geheel niks van schrikkelseconden weten."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:78
-msgid "It is not unheard of for computers to crash because of leap seconds, and experience has shown that a large fraction of all public <acronym>NTP</acronym> servers might handle and announce the leap second incorrectly."
-msgstr "Het komt voor dat computers crashen vanwege schrikkelseconden, en ervaring laat zien dat een groot gedeelte van alle publieke <acronym>NTP</acronym>-servers de schrikkelseconde onjuist kunnen aankondigen en afhandelen."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:83
-msgid "Please try to make sure nothing horrible happens because of the leap second."
-msgstr "Probeer er alstublieft voor te zorgen dat er niks ergs gebeurt vanwege de schrikkelseconde."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:88
-msgid "Testing"
-msgstr "Testen"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:90
-msgid "It is possible to test whether a leap second will be used. Due to the nature of <acronym>NTP</acronym>, the test might work up to 24 hours before the leap second. Some major reference clock sources only announce leap seconds one hour ahead of the event. Query the <acronym>NTP</acronym> daemon:"
-msgstr "Het is mogelijk om te kijken of een schrikkelseconde zal worden gebruikt. Vanwege de aard van <acronym>NTP</acronym> kan de test tot 24 uur voor de schrikkelseconde werken. Sommige grote bronnen van referentieklokken kondigen schrikkelseconden slechts ťťn uur van te voren aan. Ondervraag de daemon <acronym>NTP</acronym>:"
-
-#. (itstool) path: sect1/screen
-#: article.translate.xml:96
-#, no-wrap
-msgid "<prompt>%</prompt> <userinput>ntpq -c 'rv 0 leap'</userinput>"
-msgstr "<prompt>%</prompt> <userinput>ntpq -c 'rv 0 leap'</userinput>"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:98
-msgid "Output that includes <literal>leap_add_sec</literal> indicates proper support of the leap second. Before the 24 hours leading up to the leap second, or after the leap second has passed, <literal>leap_none</literal> will be shown."
-msgstr "Uitvoer die <literal>leap_add_sec</literal> bevat wijst op correcte ondersteuning van de schrikkelseconde. Voorafgaand aan de 24 uur die tot de schrikkelseconde leiden, of nadat de schrikkelseconde is verstreken, zal <literal>leap_none</literal> zichtbaar zijn."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:105
-msgid "Conclusion"
-msgstr "Conclusie"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:107
-msgid "In practice, leap seconds are usually not a problem on FreeBSD. We hope that this overview helps clarify what to expect and how to make the leap second event proceed more smoothly."
-msgstr "In de praktijk zijn schrikkelseconden meestal geen probleem op FreeBSD. We hopen dat dit overzicht helpt met wat te verwachten en hoe schrikkelseconden gladder te laten verlopen."
-
diff --git a/nl_NL.ISO8859-1/articles/problem-reports/Makefile b/nl_NL.ISO8859-1/articles/problem-reports/Makefile
deleted file mode 100644
index 1f0804f44b..0000000000
--- a/nl_NL.ISO8859-1/articles/problem-reports/Makefile
+++ /dev/null
@@ -1,22 +0,0 @@
-#
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/articles/problem-reports/Makefile
-# %SRCID% 39631
-#
-# Article: Writing FreeBSD Problem Reports
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?=gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/articles/problem-reports/article.xml b/nl_NL.ISO8859-1/articles/problem-reports/article.xml
deleted file mode 100644
index 497bfd9738..0000000000
--- a/nl_NL.ISO8859-1/articles/problem-reports/article.xml
+++ /dev/null
@@ -1,1331 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
-<!--
- $FreeBSD$
-
- %SOURCE% en_US.ISO8859-1/articles/problem-reports/article.xml
- %SRCID% 41645
--->
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="nl">
- <info><title>Probleemrapporten voor &os; schrijven</title>
-
-
- <legalnotice xml:id="trademarks" role="trademarks">
- &tm-attrib.freebsd;
- &tm-attrib.ibm;
- &tm-attrib.intel;
- &tm-attrib.sparc;
- &tm-attrib.sun;
- &tm-attrib.general;
- </legalnotice>
-
- <pubdate>$FreeBSD$</pubdate>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
- <abstract>
- <para>Dit artikel beschrijft hoe een probleemrapport het beste
- geformuleerd en naar het &os; Project verzonden kan
- worden.</para>
-
- <para><emphasis>Vertaald door Renť Ladan</emphasis>.</para>
- </abstract>
-
- <authorgroup>
- <author><personname><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></personname><contrib>Bijgedragen door </contrib></author>
-
- <author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
- </authorgroup>
- </info>
-
- <indexterm><primary>probleemrapporten</primary></indexterm>
-
- <section xml:id="pr-intro">
- <title>Introductie</title>
-
- <para>Eťn van de meest frustrerende ervaringen die een
- gebruiker van software kan hebben is om een probleemrapport in te
- sturen om het vervolgens afgehandeld te zien met een korte en
- onbehulpzame uitleg als <quote>geen bug</quote> of <quote>fout
- PR</quote>. Evenzo is ťťn van de meest
- frustrerende ervaringen als ontwikkelaar van software om
- overspoeld te worden met probleemrapporten die niet echt een
- probleemrapport zijn maar ondersteuningsverzoeken, of die weinig
- tot geen informatie bevatten over wat het probleem is en hoe het
- te reproduceren.</para>
-
- <para>Dit document poogt te beschrijven hoe goede probleemrapporten
- te schrijven. Wat is een goed probleemrapport? Kort door de
- bocht is een goed probleemrapport een rapport dat geanalyseerd kan
- worden en waar snel mee kan worden omgegaan, voor de wederzijdse
- voldoening van zowel de gebruiker als de ontwikkelaar.</para>
-
- <para>Hoewel de nadruk van dit artikel ligt op probleemrapporten
- voor &os;, zou het meeste ook in sterke mate op andere
- softwareprojecten van toepassing moeten zijn.</para>
-
- <para>Merk op dat dit artikel thematisch in plaats van chronologisch
- is ingedeeld, dus u dient het hele document te lezen alvorens een
- probleemrapport in te sturen, en het niet als een stapsgewijze
- tutorial te behandelen.</para>
- </section>
-
- <section xml:id="pr-when">
- <title>Wanneer een probleemrapport te versturen</title>
-
- <para>Er zijn vele soorten problemen, die niet allemaal geschikt
- zijn voor een probleemrapport. Natuurlijk is niemand perfect dus
- zal het soms voorkomen dat u overtuigd bent dat u een bug in een
- programma heeft gevonden terwijl u in feite de syntaxis voor een
- commando verkeerd begrepen heeft of een typefout in een
- instellingenbestand gemaakt heeft (hoewel dat soms zelf al op
- slechte documentatie of slechte foutafhandeling in de applicatie
- kan wijzen). Er zijn nog steeds veel gevallen waarin het insturen
- van een probleemrapport duidelijk <emphasis>niet</emphasis> de
- juiste handeling is, en het alleen tot frustratie bij uzelf en de
- ontwikkelaars leidt. Omgekeerd zijn er gevallen waarin het juist
- kan zijn om een probleemrapport in te sturen over iets anders dan
- een bug&mdash;bijvoorbeeld voor een verbetering of een
- nieuwe mogelijkheid.</para>
-
- <para>Dus hoe wordt bepaald of iets wel of niet een bug is? Een
- eenvoudige vuistregel is dat uw probleem <emphasis>geen</emphasis>
- bug is als het als een vraag kan worden uitgedrukt (meestal van de
- vorm <quote>Hoe doe ik X?</quote> of <quote>Waar kan ik Y
- vinden?</quote>). Het is niet altijd zo zwart-wit, maar de
- vraagregel gaat in de meeste gevallen op. Overweeg, als u een
- antwoord zoekt, om uw vraag aan de &a.questions; te
- stellen.</para>
-
- <para>Enkele gevallen waar het juist kan zijn om een probleemrapport
- in te sturen over iets dat geen bug is zijn:</para>
-
- <itemizedlist>
- <listitem>
- <para>Meldingen van updates aan extern onderhouden software
- (over het algemeen ports, maar ook extern onderhouden
- componenten van het basissysteem zoals BIND of verscheidene
- gereedschappen van GNU).</para>
-
- <para>Voor onbeheerde ports (<varname>MAINTAINER</varname> bevat
- <literal>ports@FreeBSD.org</literal>) kan zo'n updatemelding
- opgepakt worden door een geÔnteresseerde committer, of u
- kunt gevraagd worden om een patch aan te leveren om de port
- bij te werken; door dit van te voren aan te bieden verhoogt u
- in sterke mate de kans dat de port binnen een redelijk
- tijdsbestek wordt bijgewerkt.</para>
-
- <para>Als de port beheerd wordt, zijn PR's die nieuwe
- stroomopwaartse uitgaven aankondigen niet erg nuttig aangezien
- ze aanvullend werk voor de committers genereren, en
- waarschijnlijk weet de beheerder al dat er een nieuwe versie
- uit is, ze hebben er waarschijnlijk met de ontwikkelaars aan
- gewerkt, ze zijn waarschijnlijk regressietesten aan het
- uitvoeren, enzovoorts.</para>
-
- <para>In beide gevallen zal het volgen van het proces zoals
- beschreven in het <link xlink:href="&url.books.porters-handbook.en;/port-upgrading.html">
- Porters Handboek</link> tot de beste resultaten leiden. (U
- bent misschien ook geÔnteresseerd in <link xlink:href="&url.articles.contributing-ports;/article.html">
- Bijdragen aan de &os; Portscollectie</link>.)</para>
- </listitem>
- </itemizedlist>
-
- <para>Een bug die niet reproduceerbaar is kan zelden gerepareerd
- worden. Als een bug slechts eenmalig voorkwam en u deze niet kunt
- reproduceren, en het bij niemand anders lijkt voor te komen, dan
- bestaat de kans dat geen van de ontwikkelaars het kan reproduceren
- of kan uitzoeken wat er mis is. Dit betekent niet dat het niet
- gebeurde, maar wel dat de kans dat uw probleemrapport ooit tot een
- reparatie leidt erg klein is. Om het allemaal erger te maken,
- worden dit soort bugs vaak veroorzaakt door falende harde schijven
- of oververhitte processoren &mdash; u dient altijd te proberen om
- deze oorzaken, indien mogelijk, uit te sluiten voordat u een PR
- instuurt.</para>
-
- <para>Vervolgens, om te besluiten aan wie u uw probleemrapport dient
- te sturen, moet u weten dat de software waaruit &os; bestaat uit
- verschillende elementen is opgebouwd:</para>
-
- <itemizedlist>
- <listitem>
- <para>Code in het basissysteem die geschreven is en onderhouden
- wordt door &os;-vrijwilligers, zoals de kernel, de
- C-bibliotheek, en de apparaatstuurprogramma's (gecategoriseerd
- als <literal>kern</literal>); de binaire hulpmiddelen
- (<literal>bin</literal>); de handleidingpagina's en
- documentatie (<literal>docs</literal>); en de webpagina's
- (<literal>www</literal>). Alle bugs in deze gebieden dienen
- aan de &os;-ontwikkelaars gerapporteerd te worden.</para>
- </listitem>
-
- <listitem>
- <para>Code in het basissysteem die geschreven is en onderhouden
- wordt door anderen, en in &os; is geÔmporteerd en
- aangepast. Voorbeelden zijn <application>bind</application>,
- &man.gcc.1;, en &man.sendmail.8;. De meeste bugs in deze
- gebieden dienen aan de &os;-ontwikkelaars gerapporteerd te
- worden; maar in sommige gevallen kan het zijn dat ze aan de
- originele auteurs gerapporteerd moeten worden als de problemen
- niet specifiek voor &os; zijn. Gewoonlijk vallen deze bugs in
- ofwel de categorie <literal>bin</literal> ofwel de categorie
- <literal>gnu</literal>.</para>
- </listitem>
-
- <listitem>
- <para>Individuele applicaties die niet in het basissysteem
- zitten maar in plaats daarvan deel zijn van de Portscollectie
- van &os; (categorie <literal>ports</literal>). De meeste van
- deze applicaties zijn niet geschreven door &os;-ontwikkelaars;
- wat &os; biedt is slechts een raamwerk om de applicatie te
- installeren. Daarom dient u alleen een probleem aan de
- &os;-ontwikkelaars te rapporteren als u gelooft dat het
- probleem specifiek voor &os; is; anders dient u het aan de
- auteurs van de software te rapporteren.</para>
- </listitem>
- </itemizedlist>
-
- <para>Daarna dient u vast te stellen of het probleem actueel is. Er
- zijn maar weinig dingen die een ontwikkelaar meer irriteren dan
- het ontvangen van een probleemrapport over een bug die reeds
- gerepareerd is.</para>
-
- <para>Als het probleem in het basissysteem zit, dient u eerst het
- FAQ-gedeelte over <link xlink:href="&url.books.faq.en;/introduction.html#LATEST-VERSION">
- &os;-versies</link> te lezen als u niet reeds bekend bent met
- het onderwerp. Het is niet mogelijk voor &os; om problemen in
- iets anders dan bepaalde recente takken van het basissysteem op te
- lossen, dus leidt het insturen van een bug-rapport over een oudere
- versie waarschijnlijk alleen tot het advies van een ontwikkelaar
- om naar een ondersteunde versie bij te werken om te kijken of het
- probleem nog steeds voorkomt. Het Security Officer Team
- onderhoudt de <link xlink:href="&url.base;/security/">lijst van
- ondersteunde versies</link>.</para>
-
- <para>Als het probleem in een port zit, moet u uw Portscollectie
- eerst naar de laatste versie bijwerken en kijken of het probleem
- nog steeds van toepassing is. Wegens de hoge snelheid waarmee
- deze applicaties veranderen, is het onhaalbaar voor &os; om iets
- anders dan de allernieuwste versies te ondersteunen, problemen met
- oudere versies van applicaties kunnen simpelweg niet worden
- opgelost.</para>
- </section>
-
- <section xml:id="pr-prep">
- <title>Voorbereidingen</title>
-
- <para>Een goede regel is om altijd een vooronderzoek te doen voordat
- u een probleemrapport ingestuurd. Misschien is uw probleem reeds
- gerapporteerd; misschien wordt het besproken op de mailinglijsten,
- of gebeurde dat recentelijk; misschien is het al gerepareerd in
- een nieuwere versie dan die u draait. Om deze redenen dient u
- alle voor de hand liggende plaatsen te controleren voordat u uw
- probleemrapport instuurt. Voor &os; betekent dit:</para>
-
- <itemizedlist>
- <listitem>
- <para>De &os;-lijst van
- <link xlink:href="&url.books.faq.en;/index.html">Veelgestelde
- Vragen</link> (FAQ). De FAQ probeert antwoord te geven op
- een breed scala aan vragen, zoals vragen die betrekking hebben op
- <link xlink:href="&url.books.faq.en;/hardware.html">compatibiliteit van
- hardware</link>,
- <link xlink:href="&url.books.faq.en;/applications.html">
- gebruikersapplicaties</link>, en
- <link xlink:href="&url.books.faq.en;/kernelconfig.html">
- kernelconfiguratie</link>.</para>
- </listitem>
-
- <listitem>
- <para>De
- <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">
- mailinglijsten</link>&mdash;als u niet geabonneerd bent,
- gebruik dan <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">
- de doorzoekbare archieven</link> op de &os;-website. Als
- uw probleem niet op de lijsten bediscussieerd is, kunt u
- proberen om er een bericht over te posten en enkele dagen
- wachten om te zien of iemand iets kan zien wat u misschien
- over het hoofd heeft gezien.</para>
- </listitem>
-
- <listitem>
- <para>Optioneel, het gehele web&mdash;gebruik uw favoriete
- zoekmachine om referenties naar uw probleem te vinden. U kunt
- zelfs hits krijgen van gearchiveerde mailinglijsten of
- nieuwsgroepen die u niet kende of waarvan u er niet aan had
- gedacht om die te doorzoeken.</para>
- </listitem>
-
- <listitem>
- <para>Vervolgens, de doorzoekbare
- <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
- &os; PR-database</link> (GNATS). Tenzij uw probleem recent
- of obscuur is, bestaat er een redelijke kans dat het reeds
- gerapporteerd is.</para>
- </listitem>
-
- <listitem>
- <para>Het belangrijkste is dat u probeert te controleren of
- bestaande documentatie in de bronnen uw probleem
- bespreekt.</para>
-
- <para>Voor de basis-&os;-code dient u zorgvuldig de inhoud van
- het bestand <filename>/usr/src/UPDATING</filename> op uw
- systeem of de laatste versie ervan op <uri xlink:href="http://svnweb.freebsd.org/base/head/UPDATING?view=log">http://svnweb.freebsd.org/base/head/UPDATING?view=log</uri>
- te bestuderen. (Dit is essentiŽle informatie als u van
- de ene naar een andere versie bijwerkt&mdash;in het bijzonder
- als u naar de tak &os.current; bijwerkt.)</para>
-
- <para>Als het probleem echter zit in iets wat als deel van de
- &os; Portscollectie was geÔnstalleerd, dan dient u
- <filename>/usr/ports/UPDATING</filename> (voor individuele
- ports) of <filename>/usr/ports/CHANGES</filename> (voor
- veranderingen die de gehele Portscollectie beÔnvloeden)
- te raadplegen. <uri xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING?view=log">http://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri>
- en <uri xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES?view=log">http://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri>
- zijn ook beschikbaar via svnweb.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section xml:id="pr-writing">
- <title>Het probleemrapport schrijven</title>
-
- <para>Nu u besloten heeft dat uw probleem een probleemrapport
- verdiend, en het een probleem met &os; is, is het tijd om het
- eigenlijke probleemrapport te schrijven. Voordat het mechanisme
- van het programma dat gebruikt wordt om PR's aan te maken en in te
- sturen wordt behandeld, zijn hier wat tips en trucs die ervoor
- zorgen dat uw PR het meest effectief is.</para>
-
- <section>
- <title>Tips en trucs voor het schrijven van een goed
- probleemrapport</title>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Laat de regel <quote>Synopsis</quote> niet
- leeg.</emphasis> De PR's gaan zowel naar een mailinglijst
- die over de gehele wereld wordt verspreid (waar de
- <quote>Synopsis</quote> wordt gebruikt voor de
- <literal>Onderwerp:</literal>-regel), als in een database.
- Iedereen die later de database op samenvatting doorzoekt, en
- een PR met een lege onderwerpsregel aantreft, zal het
- waarschijnlijk gewoon overslaan. Onthoud dat PR's in deze
- database blijven staan totdat iemand ze sluit; een anoniem
- PR zal slechts in de massa opgaan.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Voorkom het gebruik van een zwakke
- <quote>Synopsis</quote>-regel.</emphasis> U mag niet
- aannemen dat iemand die uw PR leest enige achtergrondkennis
- van uw inzending heeft, dus des meer u biedt, des te beter.
- Op welk deel van het systeem heeft het probleem betrekking?
- Ziet u het probleem alleen tijdens het installeren, of
- tijdens het draaien? Ter illustratie, in plaats van
- <literal>Synopsis: portupgrade is broken</literal>, zie
- hoeveel informatiever dit lijkt: <literal>Synopsis: port
- pors-mgmt/portupgrade coredumps on -current</literal>.
- (In het geval van ports is het bijzonder behulpzaam om zowel
- de categorie als de portnaam in de
- <quote>Synopsis</quote>-regel te vermelden.)</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Als u een patch heeft, zeg dat dan.</emphasis>
- Het is veel waarschijnlijker dat een PR met daarin een patch
- bekeken wordt dan een PR zonder patch. Als u een patch
- bijsluit, plaats dan de tekst <literal>[patch]</literal>
- (inclusief de haken) aan het begin van de
- <quote>Synopsis</quote>. (Alhoewel het niet verplicht is om
- die exacte tekst te gebruiken, is dat per conventie degene
- die gebruikt wordt.)</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Als u een onderhouder bent, zeg dat
- dan.</emphasis> Als u een deel van de broncode onderhoudt
- (bijvoorbeeld een port), kunt u overwegen om de tekst
- <literal>[maintainer update]</literal> (inclusief de haken)
- aan het begin van de onderwerpsregel te plaatsen, en dient u
- zeker de <quote>Class</quote> van uw PR op
- <literal>maintainer-update</literal> te zetten. Op deze
- manier hoeft de committer die uw PR behandelt dit niet te
- controleren.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Ben specifiek.</emphasis> Des te meer
- informatie u aanlevert over wat voor probleem u heeft, des
- te groter is de kans dat u een antwoord krijgt.</para>
-
- <itemizedlist>
- <listitem>
- <para>Vermeld de versie van &os; die u draait (hier is een
- plaats voor, zie hieronder) en op welke architectuur dat
- is. U dient aan te geven of u een uitgave draait
- (bijvoorbeeld een CD-ROM of een download), of een
- systeem dat met Subversion wordt onderhouden (en
- zo ja, op welk revisienummer u zit). Als u
- de tak &os.current; volgt, is dat het allereerste wat
- iemand zal vragen, omdat reparaties (in het bijzonder
- voor opvallende problemen) de neiging hebben om snel
- gecommit te worden, en gebruikers van &os.current;
- worden geacht om hun zaken bij te houden.</para>
- </listitem>
-
- <listitem>
- <para>Vermeld welke globale opties u in uw
- <filename>make.conf</filename> heeft gespecificeerd.
- Noot: het specificeren van <literal>-O2</literal> en
- hoger aan &man.gcc.1; staat in veel situaties als
- bug-gevoelig bekend. Hoewel de &os;-ontwikkelaars
- patches zullen accepteren, zijn ze over het algemeen
- niet bereid om zulke gevallen te onderzoeken vanwege een
- simpel gebrek aan tijd en vrijwilligers, en zullen ze in
- plaats hiervan antwoorden met dat dit gewoon niet
- ondersteund is.</para>
- </listitem>
-
- <listitem>
- <para>Als het probleem eenvoudig gereproduceerd kan
- worden, neem dan informatie op die een ontwikkelaar
- helpt om het probleem zelf te reproduceren. Al een
- probleem kan worden gedemonstreerd met specifieke
- invoer, neem dan een voorbeeld van die invoer op indien
- mogelijk, en neem zowel de eigenlijke als de verwachte
- uitvoer op. Als deze gegevens groot zijn of niet
- gepubliceerd kunnen worden, probeer dan om een minimaal
- bestand te maken dat hetzelfde probleem vertoont en dat
- in het PR kan worden opgenomen.</para>
- </listitem>
-
- <listitem>
- <para>Als het een probleem met de kernel betreft, reken er
- dan op om de volgende informatie aan te leveren. (U
- hoeft deze niet standaard bij te sluiten, wat alleen de
- database opvult, maar u dient uittreksel bij te sluiten
- die u relevant acht):</para>
-
- <itemizedlist>
- <listitem>
- <para>uw kernelconfiguratie (inclusief welke
- hardware-apparaten u heeft
- geÔnstalleerd)</para>
- </listitem>
- <listitem>
- <para>of u wel of niet debug-opties aan heeft staan
- (zoals <literal>WITNESS</literal>), en zo ja, of het
- probleem zich blijft voordoen als u de optie
- omkeert</para>
- </listitem>
-
- <listitem>
- <para>de volledige tekst van elke backtrace, panic of
- andere console-uitvoer, of regels in
- <filename>/var/log/messages</filename> als die waren
- gegenereerd</para>
- </listitem>
-
- <listitem>
- <para>De uitvoer van <command>pciconf -l</command> en
- relevante gedeelten van uw uitvoer van
- <command>dmesg</command> als uw probleem te maken
- heeft met een bepaald stuk hardware.</para>
- </listitem>
-
- <listitem>
- <para>het feit dat u
- <filename>/usr/src/UPDATING</filename> heeft
- gelezen en dat uw probleem daar niet staat vermeld
- (iemand gaat er geheid naar vragen)</para>
- </listitem>
-
- <listitem>
- <para>of u wel of niet op het draaien van een andere
- kernel kunt terugvallen (dit is om problemen
- gerelateerd aan hardware zoals falende schijven en
- oververhitte CPU's uit te sluiten, welke zich als
- kernelprobleem kunnen vermommen)</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Als het een probleem met de ports betreft, reken er
- dan op om de volgende informatie aan te leveren. (U
- hoeft deze niet standaard bij te sluiten, wat alleen de
- database opvult, maar u dient uittreksels bij te sluiten
- die u relevant acht):</para>
-
- <itemizedlist>
- <listitem>
- <para>welke ports u heeft geÔnstalleerd</para>
- </listitem>
-
- <listitem>
- <para>alle omgevingsvariabelen die de standaardwaarden
- in <filename>bsd.port.mk</filename> overschrijven,
- zoals <varname>PORTSDIR</varname></para>
- </listitem>
-
- <listitem>
- <para>het feit dat u
- <filename>/usr/ports/UPDATING</filename> heeft
- gelezen en dat uw probleem daar niet staat vermeld
- (iemand gaat er geheid naar vragen)</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><emphasis>Voorkom vage verzoeken voor
- mogelijkheden.</emphasis> PR's van de vorm <quote>iemand
- moet echt iets dat zus-en-zo doet implementeren</quote>
- leveren minder waarschijnlijk resultaat op dan zeer
- specifieke verzoeken. Onthoud dat de broncode voor iedereen
- beschikbaar is, dus als u een mogelijkheid wilt is de beste
- manier om het erin te krijgen aan het werk te gaan! Neem
- ook het feit in overweging dat veel van dit soort dingen
- beter op <literal>freebsd-questions</literal> besproken
- kunnen worden dan als een regel in de PR-database, zoals
- hierboven besproken.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Verzeker u ervan dat niemand anders reeds een
- soortgelijk PR heeft ingestuurd.</emphasis> Alhoewel dit al
- hierboven genoemd is, is het het herhalen hier waard. Het
- duurt slechts een minuut of twee om de webgebaseerde
- zoekmachine op <uri xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri> te gebruiken. (Natuurlijk vergeet iedereen dit zo
- nu en dan.)</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Rapporteer slechts ťťn zaak per
- Probleemrapport.</emphasis> Voorkom het bijsluiten van
- twee of meer problemen in hetzelfde rapport tenzij ze
- gerelateerd zijn. Voorkom, wanneer patches worden
- bijgevoegd, het toevoegen van meerdere mogelijkheden of het
- repareren van meerdere bugs in hetzelfde PR tenzij ze sterk
- gerelateerd zijn&mdash;het oplossen van zulke PR's duurt
- vaak langer.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Voorkom controversiŽle
- verzoeken.</emphasis> Als uw PR een gebied behandelt dat in
- het verleden controversieel was, dient u waarschijnlijk
- bereid te zijn om niet alleen patches, maar ook een
- verklaring waarom de patches <quote>Het Juiste Ding Om Te
- Doen</quote> zijn aan te leveren. Zoals hierboven
- vermeld, is het zorgvuldig doorzoeken van de mailinglijsten
- door gebruik te maken van de archieven op <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
- altijd een goede voorbereiding.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Ben beleefd.</emphasis> Bijna iedereen die aan
- uw PR zal werken is een vrijwilliger. Niemand houdt ervan
- om te horen dat ze iets moeten doen wat ze al aan het doen
- zijn voor een andere motivatie dan geld. Dit is iets goeds
- om altijd in de gaten te houden bij Open Source
- projecten.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Voordat u begint</title>
-
- <para>Als u het programma &man.send-pr.1; gebruikt, zorg er dan
- voor dat uw omgevingsvariabele <envar>VISUAL</envar> (of
- <envar>EDITOR</envar> als <envar>VISUAL</envar> niet is
- ingesteld) op iets zinnigs is ingesteld.</para>
-
- <para>U dient er ook zeker van te zijn dat het afleveren van mail
- goed werkt. &man.send-pr.1; gebruikt mailberichten voor het
- insturen en volgen van probleemrapporten. Als u geen
- mailberichten kunt posten op de machine waarop u &man.send-pr.1;
- draait, zal uw probleemrapport de GNATS-database niet bereiken.
- Zie voor details over het opzetten van mail op &os; het
- hoofdstuk <quote>Elektronische post</quote> van het &os;
- Handboek op <uri xlink:href="http://www.FreeBSD.org/doc/nl_NL.ISO8859-1/books/handbook/mail.html">http://www.FreeBSD.org/doc/nl_NL.ISO8859-1/books/handbook/mail.html</uri>.</para>
-
- <para>Verzeker u ervan dat uw mailprogramma het bericht onderweg
- naar GNATS niet vermangelt. In het bijzonder zal elke patch die
- u instuurt onbruikbaar worden, als uw mailer automatisch regels
- afbreekt, tabs in spaties verandert, of nieuwe-regel-tekens
- escapet. Voor de tekstgedeelten vragen wij u echter om
- handmatig regels rond de 70 tekens af te breken, zodat de
- webversie van het PR leesbaar is.</para>
-
- <para>Dezelfde soort overwegingen gelden als u het <link xlink:href="&url.base;/send-pr.html">webgebaseerde
- PR-instuurformulier</link> in plaats van &man.send-pr.1;
- gebruikt. Merk op dat knip-en-plakbewerkingen hun eigen
- bijwerkingen op tekstopmaak kunnen hebben. In bepaalde gevallen
- kan het nodig zijn om &man.uuencode.1; te gebruiken om er zeker
- van te zijn dat patches ongewijzigd aankomen.</para>
-
- <para>Ten slotte, als uw inzending lang is, dient u uw werk
- offline voor te bereiden zodat er niets verloren gaat indien er
- zich een probleem met het inzenden ervan voordoet. Dit kan in
- het bijzonder een probleem zijn met het <link xlink:href="&url.base;/send-pr.html">webformulier</link>.</para>
- </section>
-
- <section>
- <title>Patches of bestanden bijvoegen</title>
-
- <para>Het volgende geldt voor het versturen van PR's via
- email:</para>
-
- <para>Het programma &man.send-pr.1; heeft voorzieningen voor het
- bijvoegen van bestanden aan een probleemrapport. U kunt zoveel
- bestanden bijvoegen als u wilt op voorwaarde dat elk bestand een
- unieke basisnaam (i.e., de naam van het bestand zelf, zonder het
- pad) heeft. Gebruik de opdrachtregeloptie <option>-a</option>
- om de namen van de bij te voegen bestanden te
- specificeren:</para>
-
-<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/fouten</userinput></screen>
-
- <para>Maakt u zich geen zorgen over binaire bestanden, deze worden
- automatisch gecodeerd zodat ze de mail-agent niet
- verontrusten.</para>
-
- <para>Als u een patch bijvoegt, gebruik dan de optie
- <option>-c</option> of <option>-u</option> van &man.diff.1; om
- een context- of verenigde diff (verenigd is geprefereerd) aan te
- maken, en zorg ervoor dat u de exacte revisienummers uit SVN
- specificeert van de bestanden die u heeft gewijzigd zodat de
- ontwikkelaars die uw rapport lezen ze gemakkelijk kunnen
- toepassen. Voor problemen met de kernel of de
- basisgereedschappen is een patch tegen &os.current; (de Subversion-tak
- HEAD) geprefereerd aangezien alle nieuwe code eerst daar
- toegepast en getest dient te worden. Nadat het voldoende of
- substantieel is getest, wordt de code samengevoegd of gemigreerd
- naar de tak &os.stable;.</para>
-
- <para>Als u een patch inline in plaats van als bijlage bijvoegt,
- merk dan op dat het meest voorkomende probleem de neiging is van
- sommige email-programma's om tabs als spaties weer te geven, wat
- alles dat bedoeld was als deel van een Makefile volledig
- ruineert.</para>
-
- <para>Stuur geen patches als bijlagen door gebruik te maken van
- <command>Content-Transfer-Encoding: quoted-printable</command>.
- Dit zal karakter-escaping uitvoeren en de gehele patch
- waardeloos maken.</para>
-
- <para>Merk ook op dat hoewel het over het algemeen goed is om
- kleine patches in een PR op te nemen&mdash;in het bijzonder als
- ze het probleem dat in het PR beschreven is oplossen&mdash;grote
- patches en in het bijzonder nieuwe code waarvoor
- substantiŽle review nodig kan zijn voordat het gecommit
- wordt op een web- of FTP-server geplaatst dient te worden, en de
- URL in plaats van de patch bij het PR gevoegd dient te worden.
- Patches in email hebben de neiging om gemangeld te worden, in
- het bijzonder wanneer GNATS erbij betrokken is, en hoe groter de
- patch, des te moeilijker het is voor geÔnteresseerde
- partijen om het te ontrafelen. Ook stelt het posten van een
- patch op het web u in staat om het te wijzigen zonder dat het
- nodig is om de gehele patch opnieuw in te zenden als een
- vervolgbericht op het originele PR. Ten slotte vergroten grote
- patches simpelweg de omvang van de database, aangezien gesloten
- PR's niet worden verwijderd maar in plaats daarvan worden
- bewaard en simpelweg als <literal>closed</literal> worden
- gemarkeerd.</para>
-
- <para>U dient ook te weten dat tenzij u het expliciet in uw PR of
- in de patch zelf vermeld, dat van alle patches die u instuurt
- wordt aangenomen dat ze onder dezelfde licentietermen vallen als
- het originele bestand dat u heeft gewijzigd.</para>
- </section>
-
- <section>
- <title>Het sjabloon invullen</title>
-
- <para>De volgende sectie heeft alleen betrekking op de
- email-methode:</para>
-
- <para>Wanneer u &man.send-pr.1; draait, wordt er een sjabloon aan
- u gepresenteerd. Het sjabloon bestaat uit een lijst met velden,
- waarvan sommige al zijn ingevuld, en waarvan bij anderen staat
- uitgelegd wat de bedoeling is of wat acceptabele waarden zijn.
- Maakt u zich geen zorgen over het commentaar, deze worden
- automatisch verwijderd wanneer u ze niet wijzigt of ze zelf
- verwijdert.</para>
-
- <para>Bovenaan het sjabloon, onder de regels met
- <literal>SEND-PR:</literal>, staan de email-koppen. U hoeft
- deze normaalgesproken niet te wijzigen, tenzij u het
- probleemrapport vanaf een machine of account verstuurt die wel
- mail kan versturen maar niet kan ontvangen; in dat geval wilt u
- waarschijnlijk de velden <literal>From:</literal> en
- <literal>Reply-To:</literal> op uw echte emailadres instellen.
- U kunt uzelf (of iemand anders) een carbonkopie van het
- probleemrapport versturen door ťťn of meer
- emailadressen aan de kop <literal>Cc:</literal> toe te
- voegen.</para>
-
- <para>Alleen in het email-sjabloon vindt u de volgende velden van
- ťťn regel:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Submitter-Id:</emphasis> Verander dit niet.
- De standaardwaarde <literal>current-users</literal> is
- juist, zelfs als u &os.stable; draait.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Confidential:</emphasis> Dit is vooraf
- ingevuld met <literal>no</literal>. Het heeft geen zin om
- dit te veranderen aangezien er geen vertrouwelijk &os;
- probleemrapport bestaat&mdash;de PR-database wordt
- wereldwijd gedistribueerd.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Severity:</emphasis> Eťn van
- <literal>non-critical</literal>,
- <literal>serious</literal> of
- <literal>critical</literal>. Overdrijf niet, bestempel uw
- probleem niet als <literal>critical</literal> tenzij het
- dat echt is (bijvoorbeeld gevallen van gegevenscorruptie,
- serieuze functionele regressie ten opzichte van een vorige
- -CURRENT) of als <literal>serious</literal> tenzij het
- iets is dat vele gebruikers aangaat (kernelpanics of
- bevroren computers; problemen met bepaalde
- apparaatstuurprogramma's of systeemgereedschappen).
- &os;-ontwikkelaars zullen niet noodzakelijk sneller aan uw
- probleem werken als u de belangrijkheid ervan opblaast
- aangezien er vele anderen zijn die precies hetzelfde
- gedaan hebben &mdash; in feite schenken sommige
- ontwikkelaars weinig aandacht aan dit veld vanwege deze
- redenen.</para>
-
- <note>
- <para>Beveiligingsproblemen dienen
- <emphasis>niet</emphasis> naar GNATS gestuurd te worden,
- omdat alle GNATS-informatie publieke kennis is. Stuur
- zulke problemen alstublieft volgens onze <link xlink:href="http://security.freebsd.org/#how">richtlijnen voor
- beveilingsrapportages.</link>.</para>
- </note>
- </listitem>
-
- <listitem>
- <para><emphasis>Priority:</emphasis> Eťn van
- <literal>low</literal>, <literal>medium</literal> of
- <literal>high</literal>. <literal>high</literal> dient te
- worden gereserveerd voor problemen die bijna iedere
- gebruiker van &os; aangaan en <literal>medium</literal> voor
- iets dat vele gebruikers aangaat.</para>
-
- <note>
- <para>Dit veld is zo vaak misbruikt dat het bijna volledig
- betekenisloos is geworden.</para>
- </note>
- </listitem>
- </itemizedlist>
-
- <para>De volgende sectie beschrijft velden die zowel in de
- email-interface als in de <link xlink:href="&url.base;/send-pr.html">webinterface</link>
- voorkomen:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Originator:</emphasis>
- Specificeer hier alstublieft uw echte naam, eventueel
- gevolgd door uw emailadres in punthaken. In de
- email-interface wordt dit normaalgesproken vooraf ingevuld
- met het <literal>gecos</literal>-veld van de huidige
- aangemelde gebruiker.</para>
-
- <note>
- <para>Het emailadres dat u gebruikt wordt publieke
- informatie en kan in de handen van spammers vallen. U
- dient Úfwel maatregelen te treffen om spam af te
- handelen, Úf een tijdelijk emailaccount te
- gebruiken. Merk op dat als u een in het geheel ongeldig
- emailaccount gebruikt, wij u geen vragen over uw PR kunnen
- stellen.</para>
- </note>
-
- </listitem>
-
- <listitem>
- <para><emphasis>Organization:</emphasis> Alles waarvan u
- vrolijk wordt. Dit veld wordt niet voor iets significants
- gebruikt.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Synopsis:</emphasis> Vul hier een korte en
- accurate beschrijving van het probleem in. De samenvatting
- wordt gebruikt als het onderwerp van de email van het
- probleemrapport, en wordt gebruikt in lijsten en
- samenvattingen van probleemrapporten; probleemrapporten met
- een obscure samenvatting hebben de neiging om genegeerd te
- worden.</para>
-
- <para>Zoals hierboven vermeld, als uw probleemrapport een
- patch bevat, begin dan alstublieft de samenvatting met
- <literal>[patch]</literal> (inclusief de haken); als het een
- ports-PR is en u de port onderhoudt, overweeg dan om
- <literal>[maintainer update]</literal> (inclusief de haken)
- toe te voegen en de <quote>Class</quote> van uw PR op
- <literal>maintainer-update</literal> te zetten.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Category:</emphasis> Kies een geschikte
- categorie.</para>
-
- <para>Het eerste wat u moet doen is beslissen in welk gebied
- van het systeem uw probleem ligt. Onthoud dat &os; een
- compleet besturingssysteem is, dat zowel een kernel, de
- standaardbibliotheken, vele hulpstuurprogramma's, en een
- groot aantal gereedschappen (het
- <quote>basissysteem</quote>) installeert. Er zijn echter
- duizenden aanvullende applicaties in de Portscollectie. U
- dient eerst te beslissen of het probleem in het basissysteem
- zit of dat het in iets dat via de Portscollectie
- geÔnstalleerd is zit.</para>
-
- <para>Hier volgt een beschrijving van de grote
- categoriŽn:</para>
-
- <itemizedlist>
- <listitem>
- <para>Als er een probleem met de kernel, de bibliotheken
- (zoals de standaard C-bibliotheek
- <literal>libc</literal>), of een hulpstuurprogramma is,
- gebruikt u in het algemeen de categorie
- <literal>kern</literal>. (Er zijn enkele uitzonderingen
- die hieronder vermeld staan). In het algemeen zijn dat
- dingen die in sectie 2, 3, of 4 van de
- handleidingpagina's staan beschreven.</para>
- </listitem>
-
- <listitem>
- <para>Als er een probleem met een binair programma zoals
- &man.sh.1; of &man.mount.8; is, dient u eerst te bepalen
- of deze programma's deel zijn van het basissysteem of
- dat ze via de Portscollectie zijn toegevoegd. Als u het
- niet zeker weet, kunt u <command>whereis
- programmanaam</command>
- uitvoeren. De conventie van &os; voor de Portscollectie
- is om alles onder <filename>/usr/local</filename> te
- installeren, alhoewel dit door een systeembeheerder
- veranderd kan worden. Voor dezen gebruikt u de
- categorie <literal>ports</literal> (zelfs als de
- categorie van de port <literal>www</literal> is; zie
- hieronder). Als de locatie
- <filename>/bin</filename>,
- <filename>/usr/bin</filename>,
- <filename>/sbin</filename>, of
- <filename>/usr/sbin</filename> is,
- dan is het een onderdeel van het basissysteem, en dient
- u de categorie <literal>bin</literal> te gebruiken.
- (Enkele programma's, zoals &man.gcc.1;, gebruiken
- eigenlijk de categorie <literal>gnu</literal>, maar
- daarover hoeft u zich nu geen zorgen te maken.) Dit
- zijn allemaal programma's die in sectie 1 of 8 van de
- handleidingpagina's worden beschreven.</para>
- </listitem>
-
- <listitem>
- <para>Als u denkt dat de fout in de opstartscripts
- <literal>(rc)</literal> zit, of in een ander type
- onuitvoerbaar configuratiebestand, dan is de juiste
- categorie <literal>conf</literal> (configuratie). Deze
- dingen worden in sectie 5 van de handleidingpagina's
- beschreven.</para>
- </listitem>
-
- <listitem>
- <para>Als u een probleem in de documentatie (artikelen,
- boeken, handleidingpagina's) heeft gevonden, dan is de
- juiste keuze <literal>docs</literal>.</para>
- </listitem>
-
- <listitem>
- <para>Als u een probleem heeft met de
- <link xlink:href="&url.base;">&os; webpagina's</link>, dan is
- de juiste <literal>www</literal>.</para>
-
- <note>
- <para>Als u problemen heeft met iets dat van een port genaamd
- <literal>www/portnaam</literal>
- afkomt, dan hoort dit desalniettemin in de categorie
- <literal>ports</literal> thuis.</para>
- </note>
- </listitem>
- </itemizedlist>
-
- <para>Er zijn nog enkele gespecialiseerde categoriŽn:</para>
-
- <itemizedlist>
- <listitem>
- <para>Als het probleem in <literal>kern</literal> gestopt
- zou worden maar met het USB-subsysteem te maken heeft,
- dan is de juiste keuze <literal>usb</literal>.</para>
- </listitem>
-
- <listitem>
- <para>Als het probleem in <literal>kern</literal> gestopt
- zou worden maar het met de threading-bibliotheken te
- maken heeft, dan is de juiste keuze
- <literal>threads</literal>.</para>
- </listitem>
-
- <listitem>
- <para>Als het probleem in het basissysteem zit, maar het
- met onze naleving van standaarden zoals &posix; te maken
- heeft, dan is de juiste keuze
- <literal>standards</literal>.</para>
- </listitem>
-
- <listitem>
- <para>Als het probleem te maken heeft met interne fouten
- van de &java.virtual.machine; (&jvm;), dan dient u de
- categorie <literal>java</literal> te kiezen, zelfs als
- was &java; vanuit de Portscollectie geÔnstalleerd.
- Meer algemene problemen met &java;-ports horen nog
- steeds onder <literal>ports</literal> thuis.</para>
- </listitem>
- </itemizedlist>
-
- <para>Dit laat al het andere achter.</para>
-
- <itemizedlist>
- <listitem>
- <para>Als u ervan overtuigd bent dat het probleem zich
- alleen voordoet onder de processorarchitectuur die u
- gebruikt, kies dan ťťn van de
- architectuurspecifieke categoriŽn: gewoonlijk
- <literal>i386</literal> voor Intel-compatibele machines
- in 32-bit-modus; <literal>amd64</literal> voor
- AMD-machines die in 64-bit-modus draaien (dit omvat ook
- Intel-compatibele machines die in EMT64-modus draaien);
- en minder gewoonlijk <literal>arm</literal>,
- <literal>ia64</literal>, <literal>powerpc</literal>, en
- <literal>sparc64</literal>.</para>
-
- <note>
- <para>Deze categoriŽn worden vaak misbruikt voor
- <quote>Ik weet het niet</quote>-problemen. Gebruik
- alstublieft <literal>misc</literal>, in plaats van te
- raden.</para>
- </note>
-
- <example>
- <title>Correct gebruik van een arch-specifieke
- categorie</title>
-
- <para>U heeft een gewone PC-gebaseerde machine, en denkt
- dat u een probleem bent tegengekomen dat specifiek is
- voor een bepaalde chipset of een bepaald moederbord:
- <literal>i386</literal> is de juiste categorie.</para>
- </example>
-
- <example>
- <title>Onjuist gebruik van een arch-specifieke
- categorie</title>
-
- <para>U heeft een probleem met een insteekkaart op een
- veelvoorkomende bus, of een probleem met een bepaald
- type harde schijfstation: in dit geval is het
- waarschijnlijk op meer dan ťťn
- architectuur van toepassing, en is
- <literal>kern</literal> de juiste categorie.</para>
- </example>
- </listitem>
-
- <listitem>
- <para>Als u echt niet weet waar het probleem zich bevindt
- (of als de uitleg niet bij een van de bovenstaanden
- lijkt te passen), gebruik dan de categorie
- <literal>misc</literal>. Voordat u dit doet, kunt u
- eerst hulp vragen aan de &a.questions;. U krijgt dan
- misschien het advies dat een bestaande categorie echt
- een betere keuze is.</para>
- </listitem>
- </itemizedlist>
-
- <para>Hier is een actuele lijst van categoriŽn (van <uri xlink:href="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories">http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories</uri>):</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>advocacy:</literal> problemen gerelateerd
- aan het publieke imago van &os;. Overbodig.</para>
- </listitem>
-
- <listitem>
- <para><literal>amd64:</literal> problemen specifiek aan
- het platform AMD64.</para>
- </listitem>
-
- <listitem>
- <para><literal>arm:</literal> problemen specifiek aan het
- platform ARM.</para>
- </listitem>
-
- <listitem>
- <para><literal>bin:</literal> problemen met
- gebruikersprogramma's in het basissysteem.</para>
- </listitem>
-
- <listitem>
- <para><literal>conf:</literal> problemen met
- configuratiebestanden, standaardwaarden,
- enzovoorts.</para>
- </listitem>
-
- <listitem>
- <para><literal>docs:</literal> problemen met
- handleidingpagina's of online documentatie.</para>
- </listitem>
-
- <listitem>
- <para><literal>gnu:</literal> problemen met
- geÔmporteerde GNU-software zoals &man.gcc.1; of
- &man.grep.1;.</para>
- </listitem>
-
- <listitem>
- <para><literal>i386:</literal> problemen specifiek aan het
- &i386;-platform.</para>
- </listitem>
-
- <listitem>
- <para><literal>ia64:</literal> problemen specifiek aan het
- ia64-platform.</para>
- </listitem>
-
- <listitem>
- <para><literal>java:</literal> problemen gerelateerd aan
- de &java; Virtual Machine.</para>
- </listitem>
-
- <listitem>
- <para><literal>kern:</literal> problemen met de kernel,
- (platforminspecifieke) apparaatstuurprogramma's, of
- de basisbibliotheken.</para>
- </listitem>
-
- <listitem>
- <para><literal>misc:</literal> alles wat niet in een van
- de andere categoriŽn past. (Merk op dat er bijna
- niets is wat echt in deze categorie past, behalve
- problemen met de uitgave- en bouwinfrastructuur.
- Tijdelijke bouwfouten op <literal>HEAD</literal> horen
- hier niet thuis. Merk ook op dat dingen in deze
- categorie gemakkelijk kwijtraken).</para>
- </listitem>
-
- <listitem>
- <para><literal>ports:</literal> problemen gerelateerd aan
- de Portscollectie.</para>
- </listitem>
-
- <listitem>
- <para><literal>powerpc:</literal> problemen specifiek voor
- het &powerpc;-platform.</para>
- </listitem>
-
- <listitem>
- <para><literal>sparc64:</literal> problemen specifiek voor
- het &sparc64;-platform.</para>
- </listitem>
-
- <listitem>
- <para><literal>standards:</literal> Zaken met betrekking
- tot conformatie aan standaarden.</para>
- </listitem>
-
- <listitem>
- <para><literal>threads:</literal> problemen gerelateerd
- aan de implementatie van threads op &os; (in het
- bijzonder op &os.current;).</para>
- </listitem>
-
- <listitem>
- <para><literal>usb:</literal> problemen gerelateerd aan de
- implementatie van USB op &os;.</para>
- </listitem>
-
- <listitem>
- <para><literal>www:</literal> Veranderingen of
- verbeteringen aan de website van &os;.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><emphasis>Class:</emphasis> Kies ťťn van
- de volgenden:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>sw-bug:</literal> softwarebugs.</para>
- </listitem>
-
- <listitem>
- <para><literal>doc-bug:</literal> fouten in
- documentatie.</para>
- </listitem>
-
- <listitem>
- <para><literal>change-request:</literal> verzoeken voor
- aanvullende mogelijkheden of veranderingen in bestaande
- mogelijkheden.</para>
- </listitem>
-
- <listitem>
- <para><literal>update:</literal> updates aan ports of
- andere bijgedragen software.</para>
- </listitem>
-
- <listitem>
- <para><literal>maintainer-update:</literal> updates aan
- ports die u onderhoudt.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><emphasis>Release:</emphasis> De versie van &os; die u
- draait. Dit wordt automatisch ingevuld als u
- &man.send-pr.1; gebruikt en hoeft alleen veranderd te worden
- als u een probleemrapport verstuurt vanaf een ander systeem
- dan van hetgene waarop het probleem zich voordoet.</para>
- </listitem>
- </itemizedlist>
-
- <para>Ten slotte zijn er een aantal meerregelige velden:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Environment:</emphasis> Dit dient zou
- nauwkeurig mogelijk de omgeving te beschrijven waarin het
- probleem is waargenomen. Dit omvat de versie van het
- besturingssysteem, de versie van het specifieke programma of
- bestand dat het probleem bevat, en alle andere relevante
- zaken zoals systeemconfiguratie, andere geÔnstalleerde
- software dat het probleem beÔnvloedt, enzovoorts&mdash;
- eigenlijk alles wat een ontwikkelaar moet weten om de
- omgeving te reconstrueren waarin het probleem
- optreedt.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Description:</emphasis> Een complete en
- nauwkeurige beschrijving van het probleem dat u ondervindt.
- Probeer speculaties over de oorzaken van het probleem te
- vermijden tenzij u zeker weet dat u op het juiste spoor zit,
- aangezien een ontwikkelaar hierdoor onjuiste aannames over
- het probleem kan maken.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>How-To-Repeat:</emphasis> Een samenvatting van
- de acties die nodig waren om het probleem te
- reproduceren.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Fix:</emphasis> Bij voorkeur een patch, of op
- zijn minst een tijdelijke oplossing (wat niet alleen andere
- mensen helpt om het probleem te omzeilen, maar
- mogelijk ook een ontwikkelaar de oorzaak van het probleem
- helpt te begrijpen), maar als u hier ook geen echte
- ideŽen over heeft is het beter om dit veld open te
- laten dan om te speculeren.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Het probleemrapport versturen</title>
-
- <para>Als u &man.send-pr.1; gebruikt:</para>
-
- <para>Als u klaar bent met het invullen van het sjabloon, het
- heeft opgeslagen, en uw tekstverwerker verlaten heeft, zal
- &man.send-pr.1; u de prompt <prompt>s)end, e)dit or
- a)bort?</prompt> tonen. U kunt dan <userinput>s</userinput>
- aanslaan om het probleemrapport in te sturen,
- <userinput>e</userinput> aanslaan om de tekstverwerker te
- herstarten en verdere wijzigingen te maken, of
- <userinput>a</userinput> aanslaan om te stoppen. Als u het
- laatste kiest, blijft uw probleemrapport bewaard op schijf
- (&man.send-pr.1; vertelt u de bestandsnaam voordat het eindigt),
- zodat u het rustig kunt bewerken, of het misschien over kunt
- plaatsen naar een systeem met een betere netverbinding, voordat
- u het met de optie <option>-f</option> van &man.send-pr.1;
- verstuurt:</para>
-
-<screen>&prompt.user; <userinput>send-pr -f ~/mijn-probleemrapport</userinput></screen>
-
- <para>Dit leest het gespecificeerde bestand, controleert de
- geldigheid van de inhoud, verwijdert commentaar en verstuurt
- het.</para>
-
- <para>Als u het <link xlink:href="&url.base;/send-pr.html">webformulier</link>
- gebruikt:</para>
-
- <para>Voordat u op <literal>submit</literal> drukt, moet u een
- veld invullen waarin tekst staat dat als afbeelding op de pagina
- wordt weergegeven. Deze ongelukkige maatregel moest worden
- genomen vanwege het misbruik door geautomatiseerde systemen en
- enkele kwaadwillige gebruikers. Het is noodzakelijk kwaad dat
- niemand leuk vindt; vraag ons alstublieft niet om het te
- verwijderen.</para>
-
- <para>Merk op dat u <literal>ten zeerste wordt
- aangeraden</literal> om uw werk ergens op te slaan voordat u
- op <literal>submit</literal> drukt. Een veelvoorkomend probleem
- voor gebruikers is dat hun webbrowser een verouderde afbeelding
- uit de cache laat zien. Als u dit overkomt, wordt uw inzending
- geweigerd en kan u uw werk verliezen.</para>
-
- <para>Als u om een bepaalde reden geen afbeeldingen kunt bekijken,
- en u ook &man.send-pr.1; niet kunt gebruiken, accepteer dan
- alstublieft onze verontschuldigingen voor het ongemak en email
- uw probleemrapport naar het bugbuster-team op
- <email>freebsd-bugbusters@FreeBSD.org</email>.</para>
- </section>
- </section>
-
- <section xml:id="pr-followup">
- <title>Vervolg</title>
-
- <para>Als uw probleemrapport eenmaal is ingestuurd, ontvangt u een
- bevestiging per email waarin het volgnummer dat aan uw
- probleemrapport was toegewezen en een URL dat u kunt gebruiken om
- de status te controleren zijn opgenomen. Met een beetje geluk zal
- iemand interesse in uw probleem tonen en proberen het op te
- lossen, of, wat het geval kan zijn, uitleggen waarom het geen
- probleem is. U wordt automatisch op de hoogte gehouden van alle
- toestandsveranderingen, en u ontvangt kopiŽn van al het
- commentaar en patches die iemand aan het controletraject van uw
- probleemrapport kan koppelen.</para>
-
- <para>Als iemand aanvullende informatie van u vraagt, of als u zich
- iets herinnert of iets ontdekt dat u niet in het initiŽle
- rapport noemde, gebruik dan alstublieft ťťn van de
- twee methoden om uw vervolg in te sturen:</para>
-
- <itemizedlist>
- <listitem>
- <para>De gemakkelijkste manier is om de vervolgkoppeling op de
- webpagina van het individuele PR te gebruiken, welke u kunt
- bereiken vanuit de <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
- PR-zoekpagina</link>. Het klikken op deze koppeling brengt
- een email-venster naar voren met daarin de juiste regels voor
- Aan: en Onderwerp: ingevuld (als uw browser is ingesteld om
- dit te doen).</para>
- </listitem>
-
- <listitem>
- <para>Als alternatief kunt u het naar &a.bugfollowup; mailen,
- waarbij het volgnummer in het onderwerp is opgenomen zodat het
- foutenvolgsysteem weet aan welk probleemrapport het vervolg
- gekoppeld moet worden.</para>
-
- <note>
- <para>Als u het volgnummer <emphasis>niet</emphasis> opgeeft,
- raakt GNATS in de war en maakt het een geheel nieuw PR aan
- welke het vervolgens aan de GNATS-beheerder toekent, en
- vervolgens raakt uw PR kwijt totdat iemand de rommel
- opruimt, wat dagen of weken later kan zijn.</para>
-
- <para>Verkeerde manier:</para>
-
- <programlisting>Onderwerp: that PR I sent</programlisting>
-
- <para>Juiste manier:</para>
-
- <programlisting>Onderwerp: Re: ports/12345: compilation problem with foo/bar</programlisting>
- </note>
- </listitem>
- </itemizedlist>
-
- <para>Als het probleemrapport open blijft nadat het probleem is
- opgelost, stuur dan een vervolg (op de bovenstaande manier) waarin
- u vertelt dat het probleemrapport gesloten kan worden, en indien
- mogelijk, uitlegt hoe of wanneer het probleem was opgelost.</para>
- </section>
-
- <section xml:id="pr-problems">
- <title>Als u problemen heeft</title>
-
- <para>De meeste PR's gaan door het systeem en worden snel
- geaccepteerd; soms loopt GNATS echter achter en kan het zijn dat u
- uw email-bevestiging pas na 10 minuten of zelfs later ontvangt.
- Wees alstublieft geduldig.</para>
-
- <para>Tevens geldt, omdat GNATS alle invoer via email ontvangt, dat
- het absoluut noodzakelijk is dat &os; alle inzendingen door
- spam-filters haalt. Als u binnen een uur of twee geen antwoord
- krijgt, kan uw PR misschien zijn opgeslokt; als dit zo is, neem
- dan alstublieft contact op met de GNATS-beheerders op
- <email>bugmeister@FreeBSD.org</email> en vraag om hulp.</para>
-
- <note>
- <para>Een veelvoorkomende anti-spam-maatregel is het vergelijken
- met vele vormen van misbruik die in HTML-gebaseerde email
- voorkomen (alhoewel niet noodzakelijk het slechts opnemen van
- HTML in een PR). We raden het gebruik van HTML-gebaseerde email
- voor het versturen van PR's sterk af: niet alleen is het
- waarschijnlijker dat het niet door de filters komt, het heeft
- ook de neiging om de database te verstoppen. Oude platte email
- wordt sterk geprefereerd.</para>
- </note>
-
- <para>In zeldzame gevallen zult een bug in GNATS tegenkomen waarbij
- een PR geaccepteerd is en een volgnummer toegewezen heeft gekregen
- maar waarbij het niet op de lijst van PR's van een van de
- opvraag-webpagina's staat. Het kan zijn gebeurd dat de index van
- database niet meer met de database zelf is gesynchroniseerd. De
- manier waarop u dit kunt testen is door de webpagina <link xlink:href="http://www.FreeBSD.org/cgi/query-pr.cgi">bekijk een enkel
- PR</link> op te roepen en te kijken of het PR wordt vermeld.
- Als dat zo is, stel dan alstublieft de GNATS-beheerders op
- <email>bugmeister@FreeBSD.org</email> op de hoogte. Merk op dat
- er een <literal>cron</literal>-taak is die de database periodiek
- herbouwt, dus u hoeft geen actie te ondernemen tenzij u haast
- heeft.</para>
- </section>
-
- <section xml:id="pr-further">
- <title>Verdere literatuur</title>
-
- <para>Er is een lijst met bronnen die relevant is voor het juist
- schrijven en verwerken van probleemrapporten. Het is in geen
- geval compleet.</para>
-
- <itemizedlist>
- <listitem>
- <para><link xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs-nl.html">
- Effectief softwarestoringen melden</link>&mdash;een uitstekend
- essay door Simon G. Tatham over het samenstellen van nuttige
- (niet-&os;-specifieke) probleemrapporten.</para>
- </listitem>
-
- <listitem>
- <para><link xlink:href="&url.articles.pr-guidelines.en;/article.html">Problem
- Report Handling Guidelines</link>&mdash;waardevolle inzichten
- in hoe probleemrapporten worden afgehandeld door de
- &os;-ontwikkelaars.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <index/>
-</article>
diff --git a/nl_NL.ISO8859-1/articles/solid-state/Makefile b/nl_NL.ISO8859-1/articles/solid-state/Makefile
deleted file mode 100644
index d9e24fe386..0000000000
--- a/nl_NL.ISO8859-1/articles/solid-state/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-#
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/articles/solid-state/Makefile
-# %SRCID% 39631
-#
-# Article: FreeBSD and Solid State Devices
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-DOC_PREFIX?= ${.CURDIR}/../../..
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/articles/solid-state/article.xml b/nl_NL.ISO8859-1/articles/solid-state/article.xml
deleted file mode 100644
index 1f338e277f..0000000000
--- a/nl_NL.ISO8859-1/articles/solid-state/article.xml
+++ /dev/null
@@ -1,509 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
-<!-- Copyright (c) 2001 The FreeBSD Documentation Project
-
- 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 FREEBSD DOCUMENTATION PROJECT "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$
-
- %SOURCE% en_US.ISO8859-1/articles/solid-state/article.xml
- %SRCID% 41645
--->
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="nl">
- <info><title>&os; en Solid State Apparaten</title>
-
-
- <authorgroup>
- <author><personname><firstname>John</firstname><surname>Kozubik</surname></personname><affiliation>
- <address><email>john@kozubik.com</email></address>
- </affiliation></author>
- </authorgroup>
-
- <copyright>
- <year>2001</year>
- <year>2009</year>
- <holder>The &os; Documentation Project</holder>
- </copyright>
-
- <pubdate>$FreeBSD$</pubdate>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
- <legalnotice xml:id="trademarks" role="trademarks">
- &tm-attrib.freebsd;
- &tm-attrib.general;
- </legalnotice>
-
- &legalnotice;
-
- <abstract>
- <para>Dit artikel behandelt het gebruik van solid state
- disk-apparaten in &os; voor het maken van embedded
- systemen.</para>
-
- <para>Embedded systemen hebben het voordeel van verhoogde
- stabiliteit wegens het ontbreken van bewegende delen (harde
- schijven). Er moet echter rekening worden gehouden met de over
- het algemeen weinig beschikbare schijfruimte in het systeem en
- de duurzaamheid van het opslagmedium.</para>
-
- <para>Specifieke onderwerpen die aan bod komen omvatten de typen
- en attributen van solid state-media die geschikt zijn om in &os;
- als schijf te gebruiken, kernelopties die interessant zijn in
- zo'n omgeving, de mechanismen van
- <filename>rc.initdiskless</filename> die de initialisatie van zulke
- systemen automatiseren en de noodzaak voor alleen-lezen
- bestandssystemen, en het van voor af aan bouwen van
- bestandssystemen. Het artikel zal afsluiten met wat algemene
- strategiŽn voor kleine en alleen-lezen
- &os;-omgevingen.</para>
-
- <para><emphasis>Vertaald door Renť Ladan</emphasis>.</para>
- </abstract>
- </info>
-
- <sect1 xml:id="intro">
- <title>Solid State Disk-apparaten</title>
-
- <para>Het bereik van dit artikel zal beperkt zijn tot solid state
- disk-apparaten die gemaakt zijn met flash-geheugen.
- Flash-geheugen is een solid state-geheugen (geen bewegende
- onderdelen) dat niet-vluchtig is (het geheugen blijft gegevens
- behouden zelf nadat alle stroombronnen zijn ontkoppeld).
- Flash-geheugen kan enorme fysieke schokken weerstaan en is
- redelijk snel (de oplossingen met flash-geheugens die in dit
- artikel worden behandeld zijn iets langzamer dan een EIDE-harde
- schijf voor schrijfbewerkingen, en veel sneller voor
- leesbewerkingen). Een heel belangrijk aspect van flash-geheugen,
- waarvan de ramnificaties later in dit artikel besproken zullen
- worden, is dat elke sector een beperkte herschrijfcapaciteit heeft.
- Een sector flash-geheugen kan maar een bepaald aantal keren
- beschreven, gewist, en herschreven worden voordat de sector
- permanent onbruikbaar wordt. Hoewel veel flash-geheugenproducten
- automatisch slechte blokken in kaart brengen, en hoewel sommigen
- zelfs schrijfoperaties gelijkmatig over de eenheid distribueren,
- blijft het een feit dat er een limiet bestaat aan de hoeveelheid
- waarmee het apparaat kan worden beschreven. Concurrerende
- apparaten hebben tussen de 1.000.000 en 10.000.000
- schrijfbewerkingen per sector in hun specificaties staan. Dit
- getal varieert vanwege de omgevingstemperatuur.</para>
-
- <para>In het bijzonder worden ATA-compatibele compact-flash-eenheden
- besproken, welke vrij populair zijn als opslagmedium voor digitale
- camera's. Bijzonder interessant is het feit dat de pinnen ervan
- precies met die van de IDE-bus overeenkomen en dat ze compatibel
- zijn met de ATA-commandoverzameling. Daarom kunnen deze apparaten
- direct aan een IDE-bus in een computer gekoppeld worden met een
- zeer eenvoudige en goedkope adapter. Eenmaal op deze wijze
- geÔmplementeerd zien besturingssystemen zoals &os; het
- apparaat als een normale harde schijf (doch klein).</para>
-
- <para>Er bestaan nog andere solid state disk-oplossingen, maar hun
- kosten, zeldzaamheid, en relatieve gebruiksongemak plaatst ze
- buiten het bereik van dit artikel.</para>
- </sect1>
-
- <sect1 xml:id="kernel">
- <title>Kernelopties</title>
-
- <para>Enkele kernelopties zijn specifiek interessant voor degenen
- die een embedded &os;-systeem creŽren.</para>
-
- <para>Alle embedded &os;-systemen die flash-geheugen als
- systeemschijf gebruiken zullen geÔntereseerd zijn
- in geheugenschijven en geheugenbestandssystemen. Vanwege het
- beperkt aantal keren dat het flash-geheugen kan worden beschreven,
- is het het waarschijnlijkst dat de schijf en de bestandssystemen
- op de schijf als alleen-lezen worden aangekoppeld. In deze
- omgeving zullen bestandssystemen zoals <filename>/tmp</filename>
- en <filename>/var</filename> als geheugenbestandssystemen worden
- aangekoppeld zodat het systeem logs kan creŽren en tellers en
- tijdelijke bestanden kan bijwerken. Geheugenbestandssystemen zijn
- een kritiek station naar een succesvolle implementatie van solid
- state &os;.</para>
-
- <para>De volgende regels dienen in uw kernelinstellingenbestand te
- staan:</para>
-
- <programlisting>options MFS # Geheugenbestandssysteem
-options MD_ROOT # md-apparaat bruikbaar als een potentieel root-apparaat
-pseudo-device md # geheugenschijf</programlisting>
- </sect1>
-
- <sect1 xml:id="ro-fs">
- <title>Het <literal>rc</literal>-deelsysteem en alleen-lezen
- bestandssystemen</title>
-
- <para>De post-boot-initialisatie van een embedded &os;-systeem wordt
- beheerd door <filename>/etc/rc.initdiskless</filename>.</para>
-
- <para><filename>/etc/rc.d/var</filename> koppelt
- <filename>/var</filename> als een geheugenbestandssysteem aan,
- maakt een instelbare lijst van mappen in <filename>/var</filename>
- aan met het commando &man.mkdir.1;, en verandert de modus van sommige
- van deze mappen. Tijdens het uitvoeren van
- <filename>/etc/rc.d/var</filename> is er nog een
- <filename>rc.conf</filename>-variabele in het spel &ndash;
- <literal>varsize</literal>. Het bestand
- <filename>/etc/rc.d/var</filename> maakt een partitie
- <filename>/var</filename> aan gebaseerd op de waarde van deze
- variabele in <filename>rc.conf</filename>:</para>
-
- <programlisting>varsize=8192</programlisting>
-
- <para>Onthoud dat deze waarde standaard in sectoren is.</para>
-
- <para>Het feit dat <filename>/var</filename> een bestandssysteem is
- dat zowel gelezen als geschreven wordt is
- een belangrijk verschil, aangezien de partitie
- <filename>/</filename> (en alle andere partities die op uw
- flash-medium kunnen staan) als alleen-lezen aangekoppeld dienen te
- worden. In <xref linkend="intro"/> hebben we de beperkingen van
- flash-geheugen uiteen gelegd - in bijzonder de beperkte
- herschrijfcapaciteit. Het belang van het niet als lezen-schrijven
- aankoppelen van flash-media en het belang van het niet gebruiken
- van een wisselbestand kunnen niet genoeg benadrukt worden. Een
- wisselbestand op een druk systeem kan binnen een jaar een
- flash-medium opmaken. Het uitgebreid loggen of aanmaken en
- vernietigen van tijdelijke bestanden kan hetzelfde doen. Daarom
- dient u, naast het verwijderen van de regel <literal>swap</literal>
- uit het bestand <filename>/etc/fstab</filename>, ook de Options
- van elk bestandssysteem als volgt op <literal>ro</literal> te
- zetten:</para>
-
- <programlisting># Device Mountpoint FStype Options Dump Pass#
-/dev/ad0s1a / ufs ro 1 1</programlisting>
-
- <para>Op een gemiddeld systeem zullen enkele applicaties het
- onmiddellijk niet meer doen als gevolg van deze verandering.
- cron zal niet correct draaien vanwege ontbrekende cron-tabellen in
- het <filename>/var</filename> dat door
- <filename>/etc/rc.d/var</filename> is aangemaakt, en syslog en
- DHCP zullen problemen ondervinden als gevolg van het alleen-lezen
- bestandssysteem en ontbrekende items in het
- <filename>/var</filename> dat
- <filename>/etc/rc.d/var</filename> heeft aangemaakt. Dit zijn
- slechts tijdelijke problemen, en worden tezamen met oplossingen
- voor het uitvoeren van andere veelgebruikte softwarepakketten
- behandeld in <xref linkend="strategies"/>.</para>
-
- <para>Een belangrijk ding om te onthouden is dat een bestandssysteem
- dat met <filename>/etc/fstab</filename> als alleen-lezen was
- aangekoppeld ten alle tijden lezen-schrijven kan worden gemaakt
- door dit commando te geven:</para>
-
- <screen>&prompt.root; <userinput>/sbin/mount -uw partitie</userinput></screen>
-
- <para>en kan op alleen-lezen worden teruggezet met het
- commando:</para>
-
- <screen>&prompt.root; <userinput>/sbin/mount -ur partitie</userinput></screen>
- </sect1>
-
- <sect1>
- <title>Een bestandssysteem uit het niets opbouwen</title>
-
- <para>Omdat ATA-compatibele compact-flash-kaarten door &os; als
- normale IDE harde schijven worden gezien, kunt u theoretisch &os;
- vanaf het netwerk installeren door de floppies kern en mfsroot of
- een CD te gebruiken.</para>
-
- <para>Zelfs een kleine installatie van &os; die normale
- installatieprocedures gebruikt kan echter een systeem produceren
- met een omvang van meer dan 200 MB. Omdat de meeste mensen
- kleinere flash-geheugenapparaten zullen gebruiken (128 MB wordt als
- redelijk groot gezien - 32 of zelfs 16 MB is gebruikelijk) is een
- installatie dat de normale mechanismen gebruikt niet
- mogelijk&nbsp;er is simpelweg niet genoeg schijfruimte voor zelfs
- de kleinste van de conventionele installaties.</para>
-
- <para>De gemakkelijkste manier om over deze beperking heen te komen
- is om &os; met conventionele middelen naar een normale harde
- schijf te installeren. Kleedt, nadat de installatie voltooid is,
- het besturingssysteem uit tot een grootte die op uw flash-medium
- past, en pak vervolgens het gehele bestandssysteem in. De volgende
- stappen leiden u door het proces heen van een normaal flash-geheugen
- voorbereiden op uw ingepakte bestandssysteem. Omdat er geen normale
- installatie wordt uitgevoerd, moeten bewerkingen zoals partitioneren,
- labelen, het aanmaken van bestandssystemen, etcetera met de hand
- uitgevoerd worden. Naast de floppies kern en mfsroot heeft u ook
- de floppy fixit nodig.</para>
-
- <procedure>
- <step>
- <title>Het flash-media-apparaat partitioneren</title>
-
- <para>Kies nadat er met de floppies kern en mfsroot is opgestart
- <literal>custom</literal> uit het installatiemenu. Kies
- <literal>partition</literal> in het aangepaste
- installatiemenu. In het partitiemenu dient u alle bestaande
- partities te wissen met de toets <keycap>d</keycap>. Maak
- nadat alle bestaande partities gewist zijn een partitie aan
- met de toets <keycap>c</keycap> en accepteer de
- standaardwaarde voor de grootte van de partitie. Zorg ervoor
- dat het type van de partitie op <literal>165</literal> is
- ingesteld wanneer daar naar wordt gevraagd. Schrijf nu deze
- partitietabel naar schijf door op de toets <keycap>w</keycap>
- te drukken (dit is een verborgen optie op dit scherm). Wanneer
- u een ATA-compatibele flash-kaart gebruikt, dient u de
- opstartbeheerder van &os; te gebruiken. Druk nu op de toets
- <keycap>q</keycap> om het partitiemenu te verlaten. Het menu
- van de opstartbeheerder wordt nog een keer aan u getoond -
- herhaal de keuze die u eerder heeft gemaakt.</para>
- </step>
-
- <step>
- <title>De bestandssystemen op uw flash-geheugenapparaat
- aanmaken</title>
-
- <para>Verlaat het aangepaste installatiemenu, en kies van het
- hoofdinstallatiemenu de optie <literal>fixit</literal>. Geef
- na het binnengaan van de fixit-omgeving het volgende
- commando:</para>
-
- <screen>&prompt.root; <userinput>disklabel -e /dev/ad0c</userinput></screen>
-
- <para>Op dit punt bent u de tekstverwerker vi binnengegaan onder
- toezien van het commando disklabel. Vervolgens dient u een
- regel met <literal>a:</literal> aan het einde van het
- bestand toe te voegen. Deze regel dient er als volgt uit te
- zien:</para>
-
- <programlisting>a: <replaceable>123456</replaceable> 0 4.2BSD 0 0</programlisting>
-
- <para>Hierbij is <replaceable>123456</replaceable> een getal dat
- exact gelijk is aan het getal in de bestaande regel met
- <literal>c:</literal> voor de grootte. In feite dupliceert u
- de bestaande regel met <literal>c:</literal> als een regel met
- <literal>a:</literal>, met daarbij <literal>4.2BSD</literal>
- als type van het bestandssysteem. Sla het bestand op en
- verlaat de tekstverwerker.</para>
-
- <screen>&prompt.root; <userinput>disklabel -B -r /dev/ad0c</userinput>
-&prompt.root; <userinput>newfs /dev/ad0a</userinput></screen>
- </step>
-
- <step>
- <title>Uw bestandssysteem op het flash-medium plaatsen</title>
-
- <para>Koppel het nieuw voorbereide flash-medium aan:</para>
-
- <screen>&prompt.root; <userinput>mount /dev/ad0a /flash</userinput></screen>
-
- <para>Activeer deze machine in het netwerk zodat we ons
- tar-bestand kunnen overzenden en het op het bestandssysteem
- van het flash-medium kunnen uitpakken. Een manier om dit te
- doen is:</para>
-
- <screen>&prompt.root; <userinput>ifconfig xl0 192.168.0.10 netmask 255.255.255.0</userinput>
-&prompt.root; <userinput>route add default 192.168.0.1</userinput></screen>
-
- <para>Nu de machine op het netwerk is, kan het tar-bestand
- worden overgezonden. U kunt nu tegen een dilemma aanlopen -
- als bijvoorbeeld uw flash-geheugen 128 MB groot is, en uw
- tar-bestand groter is dan 64 MB, kan uw tar-bestand niet op
- het zelfde moment op het flash-medium staan als dan wanneer u
- het uitpakt - u zult schijfruimte tekort komen. Een oplossing
- voor dit probleem is, wanneer u FTP gebruikt, om het bestand
- uitpakt terwijl u het over FTP verzendt. Als u de overdracht
- op deze manier aanpakt, zult u nooit het tar-bestand en de
- inhoud ervan op hetzelfde moment op uw schijf hebben:</para>
-
- <screen><prompt>ftp&gt;</prompt> <userinput>get tar-bestand.tar "| tar xvf -"</userinput></screen>
-
- <para>Als uw tar-bestand met gzip is ingepakt, kunt u dit ook
- voor elkaar krijgen:</para>
-
- <screen><prompt>ftp&gt;</prompt> <userinput>get tar-bestand.tar "| zcat | tar xvf -"</userinput></screen>
-
- <para>Nadat de inhoud van uw ge-tar-de bestandssysteem op het
- bestandssysteem van uw flash-geheugen staan, kunt u het
- flash-geheugen afkoppelen en opnieuw opstarten:</para>
-
- <screen>&prompt.root; <userinput>cd /</userinput>
-&prompt.root; <userinput>umount /flash</userinput>
-&prompt.root; <userinput>exit</userinput></screen>
-
- <para>Aangenomen dat u uw bestandssysteem correct heeft
- geconfigureerd toen het gebouwd werd op de normale harde
- schijf (met uw bestandssystemen als alleen-lezen aangekoppeld
- en met de nodige opties in de kernel gecompileerd) zou u nu
- succesvol uw embedded &os;-systeem moeten kunnen
- opstarten.</para>
- </step>
- </procedure>
- </sect1>
-
- <sect1 xml:id="strategies">
- <title>SysteemstragiŽn voor kleine en alleen-lezen
- omgevingen.</title>
-
- <para>In <xref linkend="ro-fs"/> werd erop gewezen dat het
- bestandssysteem <filename>/var</filename> zoals geconstrueerd
- door <filename>/etc/rc.d/var</filename> en de aanwezigheid van
- een hoofdbestandssysteem dat alleen gelezen kan worden problemen
- veroorzaakt met veel alledaagse softwarepakketten die door &os;
- gebruikt worden. In dit artikel zullen suggesties voor het
- succesvol draaien van cron, syslog, ports-installaties en de
- webserver Apache worden gegeven.</para>
-
- <sect2>
- <title>cron</title>
-
- <para>Tijdens het opstarten wordt <filename>/var</filename> bevolkt door
- <filename>/etc/rc.d/var</filename> dat de lijst van
- <filename>/etc/mtree/BSD.var.dist</filename> gebruikt, dus
- <filename>cron</filename>, <filename>cron/tabs</filename>, <filename>at</filename>, en nog wat andere
- standaardmappen worden aangemaakt.</para>
-
- <para>Dit lost echter nog niet het probleem van het
- behouden van cron-tabellen na het opnieuw opstarten op. Wanneer
- het systeem opnieuw opstart, zal het bestandssysteem
- <filename>/var</filename> dat in het geheugen staat verdwijnen
- en zullen alle cron-tabellen die er in stonden ook verdwijnen.
- Daarom is een oplossing hiervoor het aanmaken van cron-tabellen
- voor de gebruikers die ze nodig hebben, uw bestandssysteem
- <filename>/</filename> als lezen-schrijven aan te koppelen en
- die cron-tabellen naar een veilige plaats zoals
- <filename>/etc/tabs</filename> te kopiŽren en een regel aan
- het einde van <filename>/etc/rc.initdiskless</filename> toe te
- voegen die deze cron-tabellen naar
- <filename>/var/cron/tabs</filename> kopieert nadat die map is
- aangemaakt tijdens de syseeminitialisatie. U moet misschien ook
- een regel toevoegen die de modi en toestemmingen van de mappen
- die u aanmaakt en de bestanden die u met
- <filename>etc/rc.initdiskless</filename> kopieert verandert.</para>
- </sect2>
-
- <sect2>
- <title>syslog</title>
-
- <para><filename>syslog.conf</filename> specificeert de plaats van
- bepaalde logbestanden die in <filename>/var/log</filename>
- bestaan. Deze bestanden worden niet door
- <filename>/etc/rc.d/var</filename> tijdens de
- systeeminitialisatie aangemaakt. Daarom dient u ergens na de
- sectie die de mappen in <filename>/var</filename> aanmaakt in
- <filename>/etc/rc.d/var</filename> iets als het volgende
- toevoegen:</para>
-
- <screen>&prompt.root; <userinput>touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages</userinput>
-&prompt.root; <userinput>chmod 0644 /var/log/*</userinput></screen>
- </sect2>
-
- <sect2>
- <title>Ports installeren</title>
-
- <para>Voordat de veranderingen die nodig zijn om succesvol de
- portsboom te gebruiken besproken worden, is een herinnering ten
- aanzien van de alleen-lezen-natuur van uw bestandssystemen op
- het flash-medium op zijn plaats. Aangezien ze alleen-lezen zijn,
- dient u ze tijdelijk als lezen-schrijven aan te koppelen waarbij
- de koppelsyntaxis zoals getoond in <xref linkend="ro-fs"/> wordt
- gebruikt. U dient deze bestandssystemen altijd als alleen-lezen
- te herkoppelen als u klaar bent met enig onderhoud - onnodige
- schrijfacties naar het flash-medium kunnen de levensduur ervan
- aanzienlijk verkorten.</para>
-
- <para>Om het mogelijk te maken om een portsmap binnen te gaan en
- succesvol <command>make</command> <buildtarget>install</buildtarget>
- uit te voeren, moeten we een pakketmap op een bestandssysteem
- aanmaken dat niet geheugengebaseerd is en dat onze pakketten
- tussen herstarts bijhoudt. Omdat het toch nodig is om uw
- bestandssystemen als lezen-schrijven te koppelen voor het
- installeren van een pakket, is het zinnig om aan te nemen dat
- een gebied op het flash-medium ook gebruikt kan worden om
- pakketinformatie naar te schrijven.</para>
-
- <para>Maak als eerste een map aan voor de pakketdatabase. Dit is
- normaliter <filename>/var/db/pkg</filename>, maar we kunnen het
- daar niet plaatsen aangezien het telkens als het systeem wordt
- opgestart zal verdwijnen.</para>
-
- <screen>&prompt.root; <userinput>mkdir /etc/pkg</userinput></screen>
-
- <para>Voeg nu een regel aan <filename>/etc/rc.d/var</filename>
- toe die de map <filename>/etc/pkg</filename> aan
- <filename>/var/db/pkg</filename> koppelt. Een voorbeeld:</para>
-
- <screen>&prompt.root; <userinput>ln -s /etc/pkg /var/db/pkg</userinput></screen>
-
- <para>Nu zal telkens wanneer u uw bestandssystemen als
- lezen-schrijven aankoppelt en een pakket installeert,
- <command>make</command> <buildtarget>install</buildtarget> werken,
- en zal de pakketinformatie succesvol naar
- <filename>/etc/pkg</filename> worden geschreven (omdat het
- bestandssysteem op dat moment als lezen-schrijven is aangekoppeld)
- wat altijd als <filename>/var/db/pkg</filename> beschikbaar is
- voor het besturingssysteem.</para>
- </sect2>
-
- <sect2>
- <title>Apache Web Server</title>
-
- <note>
- <para>De stappen in deze sectie zijn alleen nodig indien Apache
- is ingesteld om de pid- of loginformatie buiten <filename>/var</filename> te schrijven. Standaard
- houdt Apache het pid-bestand in <filename>/var/run/httpd.pid</filename> en de
- logbestanden in <filename>/var/log</filename>.</para>
- </note>
-
- <para>Er wordt nu aangenomen dat Apache de logbestanden in een map
- <filename>apache_log_map</filename>
- buiten <filename>/var</filename> bewaart.
- Wanneer deze map op een alleen-lezen bestandssysteem staat, zal
- Apache geen logbestanden kunnen opslaan, en kan het werkproblemen
- hebben. Indien dit zo is, is het noodzakelijk om een nieuwe map
- aan de lijst met mappen in <filename>/etc/rc.d/var</filename> die
- in <filename>/var</filename> worden aangemaakt toe te voegen, en om
- <filename>apache_log_map</filename>
- aan <filename>/var/log/apache</filename> te koppelen. Het is
- ook nodig om de toestemmingen en eigenaarschappen van deze
- nieuwe map in te stellen.</para>
-
- <para>Voeg eerst de map <literal>log/apache</literal> toe aan de
- lijst van mappen die in <filename>/etc/rc.d/var</filename>
- aangemaakt moeten worden.</para>
-
- <para>Voeg ten tweede deze commando's toe aan
- <filename>/etc/rc.d/var</filename> na de sectie die mappen
- aanmaakt:</para>
-
- <screen>&prompt.root; <userinput>chmod 0774 /var/log/apache</userinput>
-&prompt.root; <userinput>chown nobody:nobody /var/log/apache</userinput></screen>
-
- <para>Verwijder als laatste de bestaande map
- <filename>apache_log_map</filename>
- en vervang het door een koppeling:</para>
-
- <screen>&prompt.root; <userinput>rm -rf apache_log_map</userinput>
-&prompt.root; <userinput>ln -s /var/log/apache apache_log_map</userinput></screen>
- </sect2>
- </sect1>
-</article>
diff --git a/nl_NL.ISO8859-1/articles/solid-state/nl_NL.po b/nl_NL.ISO8859-1/articles/solid-state/nl_NL.po
deleted file mode 100644
index 55d387696a..0000000000
--- a/nl_NL.ISO8859-1/articles/solid-state/nl_NL.po
+++ /dev/null
@@ -1,510 +0,0 @@
-# $FreeBSD$
-msgid ""
-msgstr ""
-"Project-Id-Version: \n"
-"POT-Creation-Date: 2017-03-23 13:22+0100\n"
-"PO-Revision-Date: 2017-03-23 16:05+0100\n"
-"Language: nl_NL\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=UTF-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-"Last-Translator: Remko Lodder <remko@FreeBSD.org>\n"
-"Language-Team: \n"
-"X-Generator: Poedit 2.0beta5\n"
-
-#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
-msgctxt "_"
-msgid "translator-credits"
-msgstr "Remko Lodder <remko@FreeBSD.org> 2017"
-
-#. (itstool) path: info/title
-#: article.translate.xml:35
-msgid "FreeBSD and Solid State Devices"
-msgstr "FreeBSD en Solid State apparaten"
-
-#. (itstool) path: affiliation/address
-#: article.translate.xml:44
-#, no-wrap
-msgid ""
-"\n"
-"\t <email>john@kozubik.com</email>\n"
-"\t "
-msgstr ""
-"\n"
-"\t <email>john@kozubik.com</email>\n"
-"\t "
-
-#. (itstool) path: authorgroup/author
-#: article.translate.xml:38
-msgid "<personname> <firstname>John</firstname> <surname>Kozubik</surname> </personname> <affiliation> <_:address-1/> </affiliation>"
-msgstr "<personname> <firstname>John</firstname> <surname>Kozubik</surname> </personname> <affiliation> <_:address-1/> </affiliation>"
-
-#. (itstool) path: info/copyright
-#: article.translate.xml:51
-msgid "<year>2001</year> <year>2009</year> <holder>The FreeBSD Documentation Project</holder>"
-msgstr "<year>2001</year> <year>2009</year> <holder>The FreeBSD Documentation Project</holder>"
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:58
-msgid "FreeBSD is a registered trademark of the FreeBSD Foundation."
-msgstr "FreeBSD is een geregistreerd trademark van de FreeBSD Foundation."
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:60
-msgid "Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the <quote>√ʬĄ¬Ę</quote> or the <quote>√ā¬ģ</quote> symbol."
-msgstr "Veel van de benamingen gebruikt door fabrikanten en verkopers om hun producten te onderscheiden, zijn geclaimed als handelsmerken. Waar deze onderscheidingen voorkomen in dit document, en het FreeBSD project op de hoogte was van de vordering op de handelsmerken, worden deze onderscheidingen gevolgd door een <quote>‚ĄĘ</quote> of het <quote>¬ģ</quote> -symbool."
-
-#. (itstool) path: legalnotice/title
-#: article.translate.xml:70
-msgid "Copyright"
-msgstr "Copyright"
-
-#. (itstool) path: legalnotice/para
-#: article.translate.xml:72
-msgid "Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:"
-msgstr "Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:"
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:79
-msgid "Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified."
-msgstr "Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified."
-
-#. (itstool) path: listitem/para
-#: article.translate.xml:85
-msgid "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."
-msgstr "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."
-
-#. (itstool) path: important/para
-#: article.translate.xml:94
-msgid "THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT \"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 FREEBSD DOCUMENTATION PROJECT 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."
-msgstr "THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT \"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 FREEBSD DOCUMENTATION PROJECT 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."
-
-#. (itstool) path: info/pubdate
-#. (itstool) path: info/releaseinfo
-#: article.translate.xml:110 article.translate.xml:112
-msgid "$FreeBSD$"
-msgstr "$FreeBSD$"
-
-#. (itstool) path: abstract/para
-#: article.translate.xml:115
-msgid "This article covers the use of solid state disk devices in FreeBSD to create embedded systems."
-msgstr "Dit artikel behandelt het gebruik van solid state disk-apparaten in FreeBSD voor het maken van embedded systemen."
-
-#. (itstool) path: abstract/para
-#: article.translate.xml:118
-msgid "Embedded systems have the advantage of increased stability due to the lack of integral moving parts (hard drives). Account must be taken, however, for the generally low disk space available in the system and the durability of the storage medium."
-msgstr "Embedded systemen hebben het voordeel van verhoogde stabiliteit wegens het ontbreken van bewegende delen (harde schijven). Er moet echter rekening worden gehouden met de over het algemeen weinig beschikbare schijfruimte in het systeem en de duurzaamheid van het opslagmedium."
-
-#. (itstool) path: abstract/para
-#: article.translate.xml:124
-msgid "Specific topics to be covered include the types and attributes of solid state media suitable for disk use in FreeBSD, kernel options that are of interest in such an environment, the <filename>rc.initdiskless</filename> mechanisms that automate the initialization of such systems and the need for read-only filesystems, and building filesystems from scratch. The article will conclude with some general strategies for small and read-only FreeBSD environments."
-msgstr "Specifieke onderwerpen die aan bod komen omvatten de typen en attributen van solid state-media die geschikt zijn om in FreeBSD als schijf te gebruiken, kernelopties die interessant zijn in zo'n omgeving, de mechanismen van <filename>rc.initdiskless</filename> die de initialisatie van zulke systemen automatiseren en de noodzaak voor alleen-lezen bestandssystemen, en het van voor af aan bouwen van bestandssystemen. Het artikel zal afsluiten met wat algemene strategi√ęn voor kleine en alleen-lezen FreeBSD-omgevingen."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:136
-msgid "Solid State Disk Devices"
-msgstr "Solid State Disk-apparaten"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:138
-msgid "The scope of this article will be limited to solid state disk devices made from flash memory. Flash memory is a solid state memory (no moving parts) that is non-volatile (the memory maintains data even after all power sources have been disconnected). Flash memory can withstand tremendous physical shock and is reasonably fast (the flash memory solutions covered in this article are slightly slower than a EIDE hard disk for write operations, and much faster for read operations). One very important aspect of flash memory, the ramifications of which will be discussed later in this article, is that each sector has a limited rewrite capacity. You can only write, erase, and write again to a sector of flash memory a certain number of times before the sector becomes permanently unusable. Although many flash memory products automatically map bad blocks, and although some even distribute write operations evenly throughout the unit, the fact remains that there exists a limit to the amount of writing that can be done to the device. Competitive units have between 1,000,000 and 10,000,000 writes per sector in their specification. This figure varies due to the temperature of the environment."
-msgstr "Het bereik van dit artikel zal beperkt zijn tot solid state disk-apparaten die gemaakt zijn met flash-geheugen. Flash-geheugen is een solid state-geheugen (geen bewegende onderdelen) dat niet-vluchtig is (het geheugen blijft gegevens behouden zelf nadat alle stroombronnen zijn ontkoppeld). Flash-geheugen kan enorme fysieke schokken weerstaan en is redelijk snel (de oplossingen met flash-geheugens die in dit artikel worden behandeld zijn iets langzamer dan een EIDE-harde schijf voor schrijfbewerkingen, en veel sneller voor leesbewerkingen). Een heel belangrijk aspect van flash-geheugen, waarvan de ramnificaties later in dit artikel besproken zullen worden, is dat elke sector een beperkte herschrijfcapaciteit heeft. Een sector flash-geheugen kan maar een bepaald aantal keren beschreven, gewist, en herschreven worden voordat de sector permanent onbruikbaar wordt. Hoewel veel flash-geheugenproducten automatisch slechte blokken in kaart brengen, en hoewel sommigen zelfs schrijfoperaties gelijkmatig over de eenheid distribueren, blijft het een feit dat er een limiet bestaat aan de hoeveelheid waarmee het apparaat kan worden beschreven. Concurrerende apparaten hebben tussen de 1.000.000 en 10.000.000 schrijfbewerkingen per sector in hun specificaties staan. Dit getal varieert vanwege de omgevingstemperatuur."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:159
-msgid "Specifically, we will be discussing ATA compatible compact-flash units, which are quite popular as storage media for digital cameras. Of particular interest is the fact that they pin out directly to the IDE bus and are compatible with the ATA command set. Therefore, with a very simple and low-cost adaptor, these devices can be attached directly to an IDE bus in a computer. Once implemented in this manner, operating systems such as FreeBSD see the device as a normal hard disk (albeit small)."
-msgstr "In het bijzonder worden ATA-compatibele compact-flash-eenheden besproken, welke vrij populair zijn als opslagmedium voor digitale camera's. Bijzonder interessant is het feit dat de pinnen ervan precies met die van de IDE-bus overeenkomen en dat ze compatibel zijn met de ATA-commandoverzameling. Daarom kunnen deze apparaten direct aan een IDE-bus in een computer gekoppeld worden met een zeer eenvoudige en goedkope adapter. Eenmaal op deze wijze ge√Įmplementeerd zien besturingssystemen zoals FreeBSD het apparaat als een normale harde schijf (doch klein)."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:169
-msgid "Other solid state disk solutions do exist, but their expense, obscurity, and relative unease of use places them beyond the scope of this article."
-msgstr "Er bestaan nog andere solid state disk-oplossingen, maar hun kosten, zeldzaamheid, en relatieve gebruiksongemak plaatst ze buiten het bereik van dit artikel."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:175
-msgid "Kernel Options"
-msgstr "Kernelopties"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:177
-msgid "A few kernel options are of specific interest to those creating an embedded FreeBSD system."
-msgstr "Enkele kernelopties zijn specifiek interessant voor degenen die een embedded FreeBSD-systeem cre√ęren."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:180
-msgid "All embedded FreeBSD systems that use flash memory as system disk will be interested in memory disks and memory filesystems. Because of the limited number of writes that can be done to flash memory, the disk and the filesystems on the disk will most likely be mounted read-only. In this environment, filesystems such as <filename>/tmp</filename> and <filename>/var</filename> are mounted as memory filesystems to allow the system to create logs and update counters and temporary files. Memory filesystems are a critical component to a successful solid state FreeBSD implementation."
-msgstr "Alle embedded FreeBSD-systemen die flash-geheugen als systeemschijf gebruiken zullen ge√Įntereseerd zijn in geheugenschijven en geheugenbestandssystemen. Vanwege het beperkt aantal keren dat het flash-geheugen kan worden beschreven, is het het waarschijnlijkst dat de schijf en de bestandssystemen op de schijf als alleen-lezen worden aangekoppeld. In deze omgeving zullen bestandssystemen zoals <filename>/tmp</filename> en <filename>/var</filename> als geheugenbestandssystemen worden aangekoppeld zodat het systeem logs kan cre√ęren en tellers en tijdelijke bestanden kan bijwerken. Geheugenbestandssystemen zijn een kritiek station naar een succesvolle implementatie van solid state FreeBSD."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:191
-msgid "You should make sure the following lines exist in your kernel configuration file:"
-msgstr "De volgende regels dienen in uw kernelinstellingenbestand te staan:"
-
-#. (itstool) path: sect1/programlisting
-#: article.translate.xml:194
-#, no-wrap
-msgid ""
-"options MFS # Memory Filesystem\n"
-"options MD_ROOT # md device usable as a potential root device\n"
-"pseudo-device md # memory disk"
-msgstr ""
-"options MFS # Memory Filesystem\n"
-"options MD_ROOT # md device usable as a potential root device\n"
-"pseudo-device md # memory disk"
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:200
-msgid "The <literal>rc</literal> Subsystem and Read-Only Filesystems"
-msgstr "Het <literal>rc</literal> -deelsysteem en alleen-lezen bestandssystemen"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:203
-msgid "The post-boot initialization of an embedded FreeBSD system is controlled by <filename>/etc/rc.initdiskless</filename>."
-msgstr "De post-boot-initialisatie van een embedded FreeBSD-systeem wordt beheerd door <filename>/etc/rc.initdiskless</filename>."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:206
-msgid "<filename>/etc/rc.d/var</filename> mounts <filename>/var</filename> as a memory filesystem, makes a configurable list of directories in <filename>/var</filename> with the <citerefentry><refentrytitle>mkdir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command, and changes modes on some of those directories. In the execution of <filename>/etc/rc.d/var</filename>, one other <filename>rc.conf</filename> variable comes into play √ʬĬď <literal>varsize</literal>. A <filename>/var</filename> partition is created by <filename>/etc/rc.d/var</filename> based on the value of this variable in <filename>rc.conf</filename>:"
-msgstr "<filename>/etc/rc.d/var</filename> koppelt <filename>/var</filename> als een geheugenbestandssysteem aan, maakt een instelbare lijst van mappen in /var aan met het commando <citerefentry><refentrytitle>mkdir</refentrytitle><manvolnum>1</manvolnum></citerefentry>, en verandert de modus van sommige van deze mappen. Tijdens het uitvoeren van <filename>/etc/rc.d/var</filename> is er nog een <filename>rc.conf</filename>-variabele in het spel ‚Äď <literal>varsize</literal>. Het bestand <filename>/etc/rc.d/var</filename> maakt een partitie <filename>/var</filename> aan gebaseerd op de waarde van deze variabele in <filename>rc.conf</filename>:"
-
-#. (itstool) path: sect1/programlisting
-#: article.translate.xml:218
-#, no-wrap
-msgid "varsize=8192"
-msgstr "varsize=8192"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:220
-msgid "Remember that this value is in sectors by default."
-msgstr "Onthoud dat deze waarde standaard in sectoren is."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:222
-msgid "The fact that <filename>/var</filename> is a read-write filesystem is an important distinction, as the <filename>/</filename> partition (and any other partitions you may have on your flash media) should be mounted read-only. Remember that in <xref linkend=\"intro\"/> we detailed the limitations of flash memory - specifically the limited write capability. The importance of not mounting filesystems on flash media read-write, and the importance of not using a swap file, cannot be overstated. A swap file on a busy system can burn through a piece of flash media in less than one year. Heavy logging or temporary file creation and destruction can do the same. Therefore, in addition to removing the <literal>swap</literal> entry from your <filename>/etc/fstab</filename>, you should also change the Options field for each filesystem to <literal>ro</literal> as follows:"
-msgstr "Het feit dat <filename>/var</filename> een bestandssysteem is dat zowel gelezen als geschreven wordt is een belangrijk verschil, aangezien de partitie <filename>/</filename> (en alle andere partities die op uw flash-medium kunnen staan) als alleen-lezen aangekoppeld dienen te worden. In <xref linkend=\"intro\"/> hebben we de beperkingen van flash-geheugen uiteen gelegd - in bijzonder de beperkte herschrijfcapaciteit. Het belang van het niet als lezen-schrijven aankoppelen van flash-media en het belang van het niet gebruiken van een wisselbestand kunnen niet genoeg benadrukt worden. Een wisselbestand op een druk systeem kan binnen een jaar een flash-medium opmaken. Het uitgebreid loggen of aanmaken en vernietigen van tijdelijke bestanden kan hetzelfde doen. Daarom dient u, naast het verwijderen van de regel <literal>swap</literal> uit het bestand <filename>/etc/fstab</filename>, ook de Options van elk bestandssysteem als volgt op <literal>ro</literal> te zetten:"
-
-#. (itstool) path: sect1/programlisting
-#: article.translate.xml:239
-#, no-wrap
-msgid ""
-"# Device Mountpoint FStype Options Dump Pass#\n"
-"/dev/ad0s1a / ufs ro 1 1"
-msgstr ""
-"# Device Mountpoint FStype Options Dump Pass#\n"
-"/dev/ad0s1a / ufs ro 1 1"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:242
-msgid "A few applications in the average system will immediately begin to fail as a result of this change. For instance, cron will not run properly as a result of missing cron tabs in the <filename>/var</filename> created by <filename>/etc/rc.d/var</filename>, and syslog and dhcp will encounter problems as well as a result of the read-only filesystem and missing items in the <filename>/var</filename> that <filename>/etc/rc.d/var</filename> has created. These are only temporary problems though, and are addressed, along with solutions to the execution of other common software packages in <xref linkend=\"strategies\"/>."
-msgstr "Op een gemiddeld systeem zullen enkele applicaties het onmiddellijk niet meer doen als gevolg van deze verandering. cron zal niet correct draaien vanwege ontbrekende cron-tabellen in het <filename>/var</filename> dat door <filename>/etc/rc.d/var</filename> is aangemaakt, en syslog en DHCP zullen problemen ondervinden als gevolg van het alleen-lezen bestandssysteem en ontbrekende items in het <filename>/var</filename> dat <filename>/etc/rc.d/var</filename> heeft aangemaakt. Dit zijn slechts tijdelijke problemen, en worden tezamen met oplossingen voor het uitvoeren van andere veelgebruikte softwarepakketten behandeld in <xref linkend=\"strategies\"/>."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:254
-msgid "An important thing to remember is that a filesystem that was mounted read-only with <filename>/etc/fstab</filename> can be made read-write at any time by issuing the command:"
-msgstr "Een belangrijk ding om te onthouden is dat een bestandssysteem dat met <filename>/etc/fstab</filename> als alleen-lezen was aangekoppeld ten alle tijden lezen-schrijven kan worden gemaakt door dit commando te geven:"
-
-#. (itstool) path: sect1/screen
-#: article.translate.xml:258
-#, no-wrap
-msgid "<prompt>#</prompt> <userinput>/sbin/mount -uw <replaceable>partition</replaceable></userinput>"
-msgstr "<prompt>#</prompt> <userinput>/sbin/mount -uw <replaceable>partition</replaceable></userinput>"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:260
-msgid "and can be toggled back to read-only with the command:"
-msgstr "en kan op alleen-lezen worden teruggezet met het commando:"
-
-#. (itstool) path: sect1/screen
-#: article.translate.xml:263
-#, no-wrap
-msgid "<prompt>#</prompt> <userinput>/sbin/mount -ur <replaceable>partition</replaceable></userinput>"
-msgstr "<prompt>#</prompt> <userinput>/sbin/mount -ur <replaceable>partition</replaceable></userinput>"
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:267
-msgid "Building a File System from Scratch"
-msgstr "Een bestandssysteem uit het niets opbouwen"
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:269
-msgid "Because ATA compatible compact-flash cards are seen by FreeBSD as normal IDE hard drives, you could theoretically install FreeBSD from the network using the kern and mfsroot floppies or from a CD."
-msgstr "Omdat ATA-compatibele compact-flash-kaarten door FreeBSD als normale IDE harde schijven worden gezien, kunt u theoretisch FreeBSD vanaf het netwerk installeren door de floppies kern en mfsroot of een CD te gebruiken."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:274
-msgid "However, even a small installation of FreeBSD using normal installation procedures can produce a system in size of greater than 200 megabytes. Because most people will be using smaller flash memory devices (128 megabytes is considered fairly large - 32 or even 16 megabytes is common) an installation using normal mechanisms is not possible√ʬĬĒthere is simply not enough disk space for even the smallest of conventional installations."
-msgstr "Zelfs een kleine installatie van FreeBSD die normale installatieprocedures gebruikt kan echter een systeem produceren met een omvang van meer dan 200 MB. Omdat de meeste mensen kleinere flash-geheugenapparaten zullen gebruiken (128 MB wordt als redelijk groot gezien - 32 of zelfs 16 MB is gebruikelijk) is een installatie dat de normale mechanismen gebruikt niet mogelijk er is simpelweg niet genoeg schijfruimte voor zelfs de kleinste van de conventionele installaties."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:283
-msgid "The easiest way to overcome this space limitation is to install FreeBSD using conventional means to a normal hard disk. After the installation is complete, pare down the operating system to a size that will fit onto your flash media, then tar the entire filesystem. The following steps will guide you through the process of preparing a piece of flash memory for your tarred filesystem. Remember, because a normal installation is not being performed, operations such as partitioning, labeling, file-system creation, etc. need to be performed by hand. In addition to the kern and mfsroot floppy disks, you will also need to use the fixit floppy."
-msgstr "De gemakkelijkste manier om over deze beperking heen te komen is om FreeBSD met conventionele middelen naar een normale harde schijf te installeren. Kleedt, nadat de installatie voltooid is, het besturingssysteem uit tot een grootte die op uw flash-medium past, en pak vervolgens het gehele bestandssysteem in. De volgende stappen leiden u door het proces heen van een normaal flash-geheugen voorbereiden op uw ingepakte bestandssysteem. Omdat er geen normale installatie wordt uitgevoerd, moeten bewerkingen zoals partitioneren, labelen, het aanmaken van bestandssystemen, etcetera met de hand uitgevoerd worden. Naast de floppies kern en mfsroot heeft u ook de floppy fixit nodig."
-
-#. (itstool) path: step/title
-#: article.translate.xml:297
-msgid "Partitioning Your Flash Media Device"
-msgstr "Het flash-media-apparaat partitioneren"
-
-#. (itstool) path: step/para
-#: article.translate.xml:299
-msgid "After booting with the kern and mfsroot floppies, choose <literal>custom</literal> from the installation menu. In the custom installation menu, choose <literal>partition</literal>. In the partition menu, you should delete all existing partitions using <keycap>d</keycap>. After deleting all existing partitions, create a partition using <keycap>c</keycap> and accept the default value for the size of the partition. When asked for the type of the partition, make sure the value is set to <literal>165</literal>. Now write this partition table to the disk by pressing <keycap>w</keycap> (this is a hidden option on this screen). If you are using an ATA compatible compact flash card, you should choose the FreeBSD Boot Manager. Now press <keycap>q</keycap> to quit the partition menu. You will be shown the boot manager menu once more - repeat the choice you made earlier."
-msgstr "Kies nadat er met de floppies kern en mfsroot is opgestart <literal>custom</literal> uit het installatiemenu. Kies <literal>partition</literal> in het aangepaste installatiemenu. In het partitiemenu dient u alle bestaande partities te wissen met de toets <keycap>d</keycap>. Maak nadat alle bestaande partities gewist zijn een partitie aan met de toets <keycap>c</keycap> en accepteer de standaardwaarde voor de grootte van de partitie. Zorg ervoor dat het type van de partitie op <literal>165</literal> is ingesteld wanneer daar naar wordt gevraagd. Schrijf nu deze partitietabel naar schijf door op de toets <keycap>w</keycap> te drukken (dit is een verborgen optie op dit scherm). Wanneer u een ATA-compatibele flash-kaart gebruikt, dient u de opstartbeheerder van FreeBSD te gebruiken. Druk nu op de toets <keycap>q</keycap> om het partitiemenu te verlaten. Het menu van de opstartbeheerder wordt nog een keer aan u getoond - herhaal de keuze die u eerder heeft gemaakt."
-
-#. (itstool) path: step/title
-#: article.translate.xml:319
-msgid "Creating Filesystems on Your Flash Memory Device"
-msgstr "De bestandssystemen op uw flash-geheugenapparaat aanmaken"
-
-#. (itstool) path: step/para
-#: article.translate.xml:322
-msgid "Exit the custom installation menu, and from the main installation menu choose the <literal>fixit</literal> option. After entering the fixit environment, enter the following command:"
-msgstr "Verlaat het aangepaste installatiemenu, en kies van het hoofdinstallatiemenu de optie <literal>fixit</literal>. Geef na het binnengaan van de fixit-omgeving het volgende commando:"
-
-#. (itstool) path: step/screen
-#: article.translate.xml:327
-#, no-wrap
-msgid "<prompt>#</prompt> <userinput>disklabel -e /dev/ad0c</userinput>"
-msgstr "<prompt>#</prompt> <userinput>disklabel -e /dev/ad0c</userinput>"
-
-#. (itstool) path: step/para
-#: article.translate.xml:329
-msgid "At this point you will have entered the vi editor under the auspices of the disklabel command. Next, you need to add an <literal>a:</literal> line at the end of the file. This <literal>a:</literal> line should look like:"
-msgstr "Op dit punt bent u de tekstverwerker vi binnengegaan onder toezien van het commando disklabel. Vervolgens dient u een regel met <literal>a:</literal> aan het einde van het bestand toe te voegen. Deze regel dient er als volgt uit te zien:"
-
-#. (itstool) path: step/programlisting
-#: article.translate.xml:334
-#, no-wrap
-msgid "a: <replaceable>123456</replaceable> 0 4.2BSD 0 0"
-msgstr "a: <replaceable>123456</replaceable> 0 4.2BSD 0 0"
-
-#. (itstool) path: step/para
-#: article.translate.xml:336
-msgid "Where <replaceable>123456</replaceable> is a number that is exactly the same as the number in the existing <literal>c:</literal> entry for size. Basically you are duplicating the existing <literal>c:</literal> line as an <literal>a:</literal> line, making sure that fstype is <literal>4.2BSD</literal>. Save the file and exit."
-msgstr "Hierbij is <replaceable>123456</replaceable> een getal dat exact gelijk is aan het getal in de bestaande regel met <literal>c:</literal> voor de grootte. In feite dupliceert u de bestaande regel met <literal>c:</literal> als een regel met <literal>a:</literal>, met daarbij <literal>4.2BSD</literal> als type van het bestandssysteem. Sla het bestand op en verlaat de tekstverwerker."
-
-#. (itstool) path: step/screen
-#: article.translate.xml:343
-#, no-wrap
-msgid ""
-"<prompt>#</prompt> <userinput>disklabel -B -r /dev/ad0c</userinput>\n"
-"<prompt>#</prompt> <userinput>newfs /dev/ad0a</userinput>"
-msgstr ""
-"<prompt>#</prompt> <userinput>disklabel -B -r /dev/ad0c</userinput>\n"
-"<prompt>#</prompt> <userinput>newfs /dev/ad0a</userinput>"
-
-#. (itstool) path: step/title
-#: article.translate.xml:348
-msgid "Placing Your Filesystem on the Flash Media"
-msgstr "Uw bestandssysteem op het flash-medium plaatsen"
-
-#. (itstool) path: step/para
-#: article.translate.xml:350
-msgid "Mount the newly prepared flash media:"
-msgstr "Koppel het nieuw voorbereide flash-medium aan:"
-
-#. (itstool) path: step/screen
-#: article.translate.xml:352
-#, no-wrap
-msgid "<prompt>#</prompt> <userinput>mount /dev/ad0a /flash</userinput>"
-msgstr "<prompt>#</prompt> <userinput>mount /dev/ad0a /flash</userinput>"
-
-#. (itstool) path: step/para
-#: article.translate.xml:354
-msgid "Bring this machine up on the network so we may transfer our tar file and explode it onto our flash media filesystem. One example of how to do this is:"
-msgstr "Activeer deze machine in het netwerk zodat we ons tar-bestand kunnen overzenden en het op het bestandssysteem van het flash-medium kunnen uitpakken. Een manier om dit te doen is:"
-
-#. (itstool) path: step/screen
-#: article.translate.xml:358
-#, no-wrap
-msgid ""
-"<prompt>#</prompt> <userinput>ifconfig xl0 192.168.0.10 netmask 255.255.255.0</userinput>\n"
-"<prompt>#</prompt> <userinput>route add default 192.168.0.1</userinput>"
-msgstr ""
-"<prompt>#</prompt> <userinput>ifconfig xl0 192.168.0.10 netmask 255.255.255.0</userinput>\n"
-"<prompt>#</prompt> <userinput>route add default 192.168.0.1</userinput>"
-
-#. (itstool) path: step/para
-#: article.translate.xml:361
-msgid "Now that the machine is on the network, transfer your tar file. You may be faced with a bit of a dilemma at this point - if your flash memory part is 128 megabytes, for instance, and your tar file is larger than 64 megabytes, you cannot have your tar file on the flash media at the same time as you explode it - you will run out of space. One solution to this problem, if you are using FTP, is to untar the file while it is transferred over FTP. If you perform your transfer in this manner, you will never have the tar file and the tar contents on your disk at the same time:"
-msgstr "Nu de machine op het netwerk is, kan het tar-bestand worden overgezonden. U kunt nu tegen een dilemma aanlopen - als bijvoorbeeld uw flash-geheugen 128 MB groot is, en uw tar-bestand groter is dan 64 MB, kan uw tar-bestand niet op het zelfde moment op het flash-medium staan als dan wanneer u het uitpakt - u zult schijfruimte tekort komen. Een oplossing voor dit probleem is, wanneer u FTP gebruikt, om het bestand uitpakt terwijl u het over FTP verzendt. Als u de overdracht op deze manier aanpakt, zult u nooit het tar-bestand en de inhoud ervan op hetzelfde moment op uw schijf hebben:"
-
-#. (itstool) path: step/screen
-#: article.translate.xml:373
-#, no-wrap
-msgid "<prompt>ftp&gt;</prompt> <userinput>get tarfile.tar \"| tar xvf -\"</userinput>"
-msgstr "<prompt>ftp&gt;</prompt> <userinput>get tarfile.tar \"| tar xvf -\"</userinput>"
-
-#. (itstool) path: step/para
-#: article.translate.xml:375
-msgid "If your tarfile is gzipped, you can accomplish this as well:"
-msgstr "Als uw tar-bestand met gzip is ingepakt, kunt u dit ook voor elkaar krijgen:"
-
-#. (itstool) path: step/screen
-#: article.translate.xml:378
-#, no-wrap
-msgid "<prompt>ftp&gt;</prompt> <userinput>get tarfile.tar \"| zcat | tar xvf -\"</userinput>"
-msgstr "<prompt>ftp&gt;</prompt> <userinput>get tarfile.tar \"| zcat | tar xvf -\"</userinput>"
-
-#. (itstool) path: step/para
-#: article.translate.xml:380
-msgid "After the contents of your tarred filesystem are on your flash memory filesystem, you can unmount the flash memory and reboot:"
-msgstr "Nadat de inhoud van uw ge-tar-de bestandssysteem op het bestandssysteem van uw flash-geheugen staan, kunt u het flash-geheugen afkoppelen en opnieuw opstarten:"
-
-#. (itstool) path: step/screen
-#: article.translate.xml:384
-#, no-wrap
-msgid ""
-"<prompt>#</prompt> <userinput>cd /</userinput>\n"
-"<prompt>#</prompt> <userinput>umount /flash</userinput>\n"
-"<prompt>#</prompt> <userinput>exit</userinput>"
-msgstr ""
-"<prompt>#</prompt> <userinput>cd /</userinput>\n"
-"<prompt>#</prompt> <userinput>umount /flash</userinput>\n"
-"<prompt>#</prompt> <userinput>exit</userinput>"
-
-#. (itstool) path: step/para
-#: article.translate.xml:388
-msgid "Assuming that you configured your filesystem correctly when it was built on the normal hard disk (with your filesystems mounted read-only, and with the necessary options compiled into the kernel) you should now be successfully booting your FreeBSD embedded system."
-msgstr "Aangenomen dat u uw bestandssysteem correct heeft geconfigureerd toen het gebouwd werd op de normale harde schijf (met uw bestandssystemen als alleen-lezen aangekoppeld en met de nodige opties in de kernel gecompileerd) zou u nu succesvol uw embedded FreeBSD-systeem moeten kunnen opstarten."
-
-#. (itstool) path: sect1/title
-#: article.translate.xml:398
-msgid "System Strategies for Small and Read Only Environments"
-msgstr "Systeemstragi√ęn voor kleine en alleen-lezen omgevingen."
-
-#. (itstool) path: sect1/para
-#: article.translate.xml:401
-msgid "In <xref linkend=\"ro-fs\"/>, it was pointed out that the <filename>/var</filename> filesystem constructed by <filename>/etc/rc.d/var</filename> and the presence of a read-only root filesystem causes problems with many common software packages used with FreeBSD. In this article, suggestions for successfully running cron, syslog, ports installations, and the Apache web server will be provided."
-msgstr "In <xref linkend=\"ro-fs\"/> werd erop gewezen dat het bestandssysteem <xref linkend=\"ro-fs\"/> zoals geconstrueerd door <filename>/etc/rc.d/var</filename> en de aanwezigheid van een hoofdbestandssysteem dat alleen gelezen kan worden problemen veroorzaakt met veel alledaagse softwarepakketten die door FreeBSD gebruikt worden. In dit artikel zullen suggesties voor het succesvol draaien van cron, syslog, ports-installaties en de webserver Apache worden gegeven."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:410
-msgid "Cron"
-msgstr "Cron"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:412
-msgid "Upon boot, <filename>/var</filename> gets populated by <filename>/etc/rc.d/var</filename> using the list from <filename>/etc/mtree/BSD.var.dist</filename>, so the <filename>cron</filename>, <filename>cron/tabs</filename>, <filename>at</filename>, and a few other standard directories get created."
-msgstr "Tijdens het opstarten wordt <filename>/var</filename>bevolkt door <filename>/etc/rc.d/var</filename> dat de lijst van <filename>/etc/mtree/BSD.var.dist</filename> gebruikt, dus <filename>cron</filename>, <filename>cron/tabs</filename>, <filename>at</filename>, en nog wat andere standaardmappen worden aangemaakt."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:419
-msgid "However, this does not solve the problem of maintaining cron tabs across reboots. When the system reboots, the <filename>/var</filename> filesystem that is in memory will disappear and any cron tabs you may have had in it will also disappear. Therefore, one solution would be to create cron tabs for the users that need them, mount your <filename>/</filename> filesystem as read-write and copy those cron tabs to somewhere safe, like <filename>/etc/tabs</filename>, then add a line to the end of <filename>/etc/rc.initdiskless</filename> that copies those crontabs into <filename>/var/cron/tabs</filename> after that directory has been created during system initialization. You may also need to add a line that changes modes and permissions on the directories you create and the files you copy with <filename>/etc/rc.initdiskless</filename>."
-msgstr "Dit lost echter nog niet het probleem van het behouden van cron-tabellen na het opnieuw opstarten op. Wanneer het systeem opnieuw opstart, zal het bestandssysteem <filename>/var</filename> dat in het geheugen staat verdwijnen en zullen alle cron-tabellen die er in stonden ook verdwijnen. Daarom is een oplossing hiervoor het aanmaken van cron-tabellen voor de gebruikers die ze nodig hebben, uw bestandssysteem <filename>/</filename> als lezen-schrijven aan te koppelen en die cron-tabellen naar een veilige plaats zoals <filename>/etc/tabs</filename> te kopi√ęren en een regel aan het einde van <filename>/etc/rc.initdiskless</filename> toe te voegen die deze cron-tabellen naar <filename>/var/cron/tabs</filename> kopieert nadat die map is aangemaakt tijdens de syseeminitialisatie. U moet misschien ook een regel toevoegen die de modi en toestemmingen van de mappen die u aanmaakt en de bestanden die u met <filename>/etc/rc.initdiskless</filename> kopieert verandert."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:437
-msgid "Syslog"
-msgstr "Syslog"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:439
-msgid "<filename>syslog.conf</filename> specifies the locations of certain log files that exist in <filename>/var/log</filename>. These files are not created by <filename>/etc/rc.d/var</filename> upon system initialization. Therefore, somewhere in <filename>/etc/rc.d/var</filename>, after the section that creates the directories in <filename>/var</filename>, you will need to add something like this:"
-msgstr "<filename>syslog.conf</filename> specificeert de plaats van bepaalde logbestanden die in <filename>/var/log</filename> bestaan. Deze bestanden worden niet door <filename>/etc/rc.d/var</filename> tijdens de systeeminitialisatie aangemaakt. Daarom dient u ergens na de sectie die de mappen in <filename>/var</filename> aanmaakt in <filename>/etc/rc.d/var</filename> iets als het volgende toevoegen:"
-
-#. (itstool) path: sect2/screen
-#: article.translate.xml:448
-#, no-wrap
-msgid ""
-"<prompt>#</prompt> <userinput>touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages</userinput>\n"
-"<prompt>#</prompt> <userinput>chmod 0644 /var/log/*</userinput>"
-msgstr ""
-"<prompt>#</prompt> <userinput>touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages</userinput>\n"
-"<prompt>#</prompt> <userinput>chmod 0644 /var/log/*</userinput>"
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:453
-msgid "Ports Installation"
-msgstr "Ports installeren"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:455
-msgid "Before discussing the changes necessary to successfully use the ports tree, a reminder is necessary regarding the read-only nature of your filesystems on the flash media. Since they are read-only, you will need to temporarily mount them read-write using the mount syntax shown in <xref linkend=\"ro-fs\"/>. You should always remount those filesystems read-only when you are done with any maintenance - unnecessary writes to the flash media could considerably shorten its lifespan."
-msgstr "Voordat de veranderingen die nodig zijn om succesvol de portsboom te gebruiken besproken worden, is een herinnering ten aanzien van de alleen-lezen-natuur van uw bestandssystemen op het flash-medium op zijn plaats. Aangezien ze alleen-lezen zijn, dient u ze tijdelijk als lezen-schrijven aan te koppelen waarbij de koppelsyntaxis zoals getoond in <xref linkend=\"ro-fs\"/> wordt gebruikt. U dient deze bestandssystemen altijd als alleen-lezen te herkoppelen als u klaar bent met enig onderhoud - onnodige schrijfacties naar het flash-medium kunnen de levensduur ervan aanzienlijk verkorten."
-
-#. (itstool) path: para/buildtarget
-#: article.translate.xml:466 article.translate.xml:489
-msgid "install"
-msgstr "install"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:464
-msgid "To make it possible to enter a ports directory and successfully run <command>make</command> <_:buildtarget-1/>, we must create a packages directory on a non-memory filesystem that will keep track of our packages across reboots. Because it is necessary to mount your filesystems as read-write for the installation of a package anyway, it is sensible to assume that an area on the flash media can also be used for package information to be written to."
-msgstr "Om het mogelijk te maken om een portsmap binnen te gaan en succesvol <command>make</command> <_:buildtarget-1/> uit te voeren, moeten we een pakketmap op een bestandssysteem aanmaken dat niet geheugengebaseerd is en dat onze pakketten tussen herstarts bijhoudt. Omdat het toch nodig is om uw bestandssystemen als lezen-schrijven te koppelen voor het installeren van een pakket, is het zinnig om aan te nemen dat een gebied op het flash-medium ook gebruikt kan worden om pakketinformatie naar te schrijven."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:474
-msgid "First, create a package database directory. This is normally in <filename>/var/db/pkg</filename>, but we cannot place it there as it will disappear every time the system is booted."
-msgstr "Maak als eerste een map aan voor de pakketdatabase. Dit is normaliter <filename>/var/db/pkg</filename>, maar we kunnen het daar niet plaatsen aangezien het telkens als het systeem wordt opgestart zal verdwijnen."
-
-#. (itstool) path: sect2/screen
-#: article.translate.xml:479
-#, no-wrap
-msgid "<prompt>#</prompt> <userinput>mkdir /etc/pkg</userinput>"
-msgstr "<prompt>#</prompt> <userinput>mkdir /etc/pkg</userinput>"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:481
-msgid "Now, add a line to <filename>/etc/rc.d/var</filename> that links the <filename>/etc/pkg</filename> directory to <filename>/var/db/pkg</filename>. An example:"
-msgstr "Voeg nu een regel aan <filename>/etc/rc.d/var</filename> toe die de map <filename>/etc/pkg</filename> aan <filename>/var/db/pkg</filename> koppelt. Een voorbeeld:"
-
-#. (itstool) path: sect2/screen
-#: article.translate.xml:485
-#, no-wrap
-msgid "<prompt>#</prompt> <userinput>ln -s /etc/pkg /var/db/pkg</userinput>"
-msgstr "<prompt>#</prompt> <userinput>ln -s /etc/pkg /var/db/pkg</userinput>"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:487
-msgid "Now, any time that you mount your filesystems as read-write and install a package, the <command>make</command> <_:buildtarget-1/> will work, and package information will be written successfully to <filename>/etc/pkg</filename> (because the filesystem will, at that time, be mounted read-write) which will always be available to the operating system as <filename>/var/db/pkg</filename>."
-msgstr "Nu zal telkens wanneer u uw bestandssystemen als lezen-schrijven aankoppelt en een pakket installeert, <command>make</command> <_:buildtarget-1/> werken, en zal de pakketinformatie succesvol naar <filename>/etc/pkg</filename> worden geschreven (omdat het bestandssysteem op dat moment als lezen-schrijven is aangekoppeld) wat altijd als <filename>/var/db/pkg</filename> beschikbaar is voor het besturingssysteem."
-
-#. (itstool) path: sect2/title
-#: article.translate.xml:498
-msgid "Apache Web Server"
-msgstr "Apache Web Server"
-
-#. (itstool) path: note/para
-#: article.translate.xml:501
-msgid "The steps in this section are only necessary if Apache is set up to write its pid or log information outside of <filename>/var</filename>. By default, Apache keeps its pid file in <filename>/var/run/httpd.pid</filename> and its log files in <filename>/var/log</filename>."
-msgstr "De stappen in deze sectie zijn alleen nodig indien Apache is ingesteld om de pid- of loginformatie buiten <filename>/var</filename> te schrijven. Standaard houdt Apache het pid-bestand in <filename>/var/run/httpd.pid</filename> en de logbestanden in <filename>/var/log</filename>."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:508
-msgid "It is now assumed that Apache keeps its log files in a directory <filename><replaceable>apache_log_dir</replaceable></filename> outside of <filename>/var</filename>. When this directory lives on a read-only filesystem, Apache will not be able to save any log files, and may have problems working. If so, it is necessary to add a new directory to the list of directories in <filename>/etc/rc.d/var</filename> to create in <filename>/var</filename>, and to link <filename><replaceable>apache_log_dir</replaceable></filename> to <filename>/var/log/apache</filename>. It is also necessary to set permissions and ownership on this new directory."
-msgstr "Er wordt nu aangenomen dat Apache de logbestanden in een map <filename><replaceable>apache_log_map</replaceable></filename> buiten <filename>/var</filename> bewaart. Wanneer deze map op een alleen-lezen bestandssysteem staat, zal Apache geen logbestanden kunnen opslaan, en kan het werkproblemen hebben. Indien dit zo is, is het noodzakelijk om een nieuwe map aan de lijst met mappen in <filename>/etc/rc.d/var</filename> die in <filename>/var</filename> worden aangemaakt toe te voegen, en om <filename><replaceable>apache_log_map</replaceable></filename> aan <filename>/var/log/apache</filename> te koppelen. Het is ook nodig om de toestemmingen en eigenaarschappen van deze nieuwe map in te stellen."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:521
-msgid "First, add the directory <literal>log/apache</literal> to the list of directories to be created in <filename>/etc/rc.d/var</filename>."
-msgstr "Voeg eerst de map <literal>log/apache</literal> toe aan de lijst van mappen die in <filename>/etc/rc.d/var</filename> aangemaakt moeten worden."
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:525
-msgid "Second, add these commands to <filename>/etc/rc.d/var</filename> after the directory creation section:"
-msgstr "Voeg ten tweede deze commando's toe aan <filename>/etc/rc.d/var</filename> na de sectie die mappen aanmaakt:"
-
-#. (itstool) path: sect2/screen
-#: article.translate.xml:529
-#, no-wrap
-msgid ""
-"<prompt>#</prompt> <userinput>chmod 0774 /var/log/apache</userinput>\n"
-"<prompt>#</prompt> <userinput>chown nobody:nobody /var/log/apache</userinput>"
-msgstr ""
-"<prompt>#</prompt> <userinput>chmod 0774 /var/log/apache</userinput>\n"
-"<prompt>#</prompt> <userinput>chown nobody:nobody /var/log/apache</userinput>"
-
-#. (itstool) path: sect2/para
-#: article.translate.xml:532
-msgid "Finally, remove the existing <filename><replaceable>apache_log_dir</replaceable></filename> directory, and replace it with a link:"
-msgstr "Verwijder als laatste de bestaande map <filename><replaceable>apache_log_map</replaceable></filename> en vervang het door een koppeling:"
-
-#. (itstool) path: sect2/screen
-#: article.translate.xml:536
-#, no-wrap
-msgid ""
-"<prompt>#</prompt> <userinput>rm -rf <replaceable>apache_log_dir</replaceable></userinput>\n"
-"<prompt>#</prompt> <userinput>ln -s /var/log/apache <replaceable>apache_log_dir</replaceable></userinput>"
-msgstr ""
-"<prompt>#</prompt> <userinput>rm -rf <replaceable>apache_log_dir</replaceable></userinput>\n"
-"<prompt>#</prompt> <userinput>ln -s /var/log/apache <replaceable>apache_log_dir</replaceable></userinput>"
diff --git a/nl_NL.ISO8859-1/books/Makefile b/nl_NL.ISO8859-1/books/Makefile
deleted file mode 100644
index b70d8cf4fb..0000000000
--- a/nl_NL.ISO8859-1/books/Makefile
+++ /dev/null
@@ -1,12 +0,0 @@
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/books/Makefile
-# %SRCID% 40258
-#
-
-SUBDIR = handbook
-
-ROOT_SYMLINKS= handbook
-
-DOC_PREFIX?= ${.CURDIR}/../..
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/books/Makefile.inc b/nl_NL.ISO8859-1/books/Makefile.inc
deleted file mode 100644
index 253e764133..0000000000
--- a/nl_NL.ISO8859-1/books/Makefile.inc
+++ /dev/null
@@ -1,8 +0,0 @@
-#
-# $FreeBSD$
-#
-# %SOURCE% en_US.ISO8859-1/books/Makefile.inc
-# %SRCID% 39534
-#
-
-DESTDIR?= ${DOCDIR}/nl_NL.ISO8859-1/books/${.CURDIR:T}
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/Makefile b/nl_NL.ISO8859-1/books/fdp-primer/Makefile
deleted file mode 100644
index eea6e02405..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/Makefile
+++ /dev/null
@@ -1,27 +0,0 @@
-#
-# $FreeBSD$
-#
-# Build the FreeBSD Documentation Project Primer.
-#
-
-MAINTAINER=doc@FreeBSD.org
-
-DOC?= book
-
-FORMATS?= html-split html
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-#
-# SRCS lists the individual XML files that make up the document. Changes
-# to any of these files will force a rebuild
-#
-
-# XML content
-SRCS= book.xml
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/book.xml b/nl_NL.ISO8859-1/books/fdp-primer/book.xml
deleted file mode 100644
index f176bba16c..0000000000
--- a/nl_NL.ISO8859-1/books/fdp-primer/book.xml
+++ /dev/null
@@ -1,9003 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
-<!ENTITY % chapters SYSTEM "chapters.ent">
-<!--
- 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">
-<!-- ENTITY index SYSTEM "index.xml" -->]>
-<!-- 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$
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="nl_NL">
- <info><title>Overzicht van het FreeBSD Documentatieproject voor nieuwe bijdragers</title>
-
-
- <author><orgname>Het FreeBSD Documentatieproject</orgname></author>
-
- <copyright><year>1998</year> <year>1999</year> <year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <holder role="mailto:doceng@FreeBSD.org">DocEng</holder></copyright>
-
- <pubdate role="rcs">$FreeBSD$</pubdate>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
-
-<legalnotice xml:id="legalnotice">
- <title>Copyright</title>
-
- <para>Herdistributiie en gebruik in bron- (XML DocBook) en 'gecompileerde' vormen (XML, HTML, PDF, PostScript, RTF enzovoorts) met of zonder aanpassingen, is toegestaan gegeven dat aan de volgende voorwaarden is voldaan:</para>
-
- <orderedlist>
- <listitem>
- <para>Herdistributies van broncode (XML DocBook) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer onveranderd als de eerste regels van dit bestand behouden.</para>
- </listitem>
-
- <listitem>
- <para>Herdistributies in gecompileerde vorm (getransformeerd naar andere DTDs, omgezet naar PDF, PostScript, RTF en andere formaten) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer in de documentatie en/of andere materialen geleverd met de distributie herproduceren.</para>
- </listitem>
- </orderedlist>
-
- <important>
- <para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "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 FREEBSD DOCUMENTATION PROJECT 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.</para>
- </important>
-</legalnotice>
-
-
- <abstract>
- <para>Dank u dat u deel bent geworden van het FreeBSD Documentatieproject. Uw bijdrage is zeer waardevol, en we stellen het op prijs.</para>
-
- <para>Deze handleidng behandelt details die nodig zijn om te beginnen met bij te dragen aan het FreeBSD Documentatieproject, of <acronym>FDP</acronym>, inclusief gereedschappen, softare en de gedachten achter het Documentatieproject.</para>
-
- <para>Dit is werk in uitvoering. Correcties en aanvullingen zijn altijd welkom.</para>
- </abstract>
- </info>
-
- <preface xml:id="preface">
- <title>Inleiding</title>
-
- <sect1 xml:id="preface-prompts">
- <title>Shellprompts</title>
-
- <para>Deze tabel laat de standaard systeemprompt en de prompt van de supergebruiker zien. Deze voorbeelden gebruiken deze prompts om aan te geven welk soort gebruiker het voorbeeld draait.</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Gebruiker</entry>
- <entry>Prompt</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Gewone gebruiker</entry>
- <entry><prompt>%</prompt></entry>
- </row>
-
- <row>
- <entry><systemitem class="username">root</systemitem></entry>
- <entry><prompt>#</prompt></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-
- <sect1 xml:id="preface-conventions">
- <title>Typografische aannames</title>
-
- <para>Deze tabel beschrijft de typografische aannames die in dit boek gebruikt worden.</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Betekenis</entry>
- <entry>Voorbeelden</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>De naam van commando's.</entry>
- <entry>Gebruik <command>ls -l</command> voor een lijst van alle bestanden.</entry>
- </row>
-
- <row>
- <entry>De namen van bestanden.</entry>
- <entry>Bewerk <filename>.login</filename>.</entry>
- </row>
-
- <row>
- <entry>Uitvoer op het computerscherm.</entry>
- <entry><screen>You have mail.</screen></entry>
- </row>
-
- <row>
- <entry>Wat de gebruiker typt, in contrast met uitvoer op het computerscherm.</entry>
-
- <entry><screen><prompt>%</prompt> <userinput>date +"De tijd is %H:%M"</userinput>
-De tijd is 09:18</screen></entry>
- </row>
-
- <row>
- <entry>Verwijzing naar handleidingspagina's.</entry>
- <entry>Gebruik <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> om van gebruikersidentiteit te veranderen.</entry>
- </row>
-
- <row>
- <entry>Gebruiker- en groepnamen.</entry>
- <entry>Alleen <systemitem class="username">root</systemitem> kan dit doen.</entry>
- </row>
-
- <row>
- <entry>Nadruk.</entry>
- <entry>De gebruiker <emphasis>moet</emphasis> dit doen.</entry>
- </row>
-
- <row>
- <entry>Tekst die de gebruiker door de eigenlijke tekst dient te vervangen.</entry>
-
- <entry>Gebruik <command>man -k<replaceable>sleutelwoord</replaceable></command> om naar een sleutelwoord in handleidingspagina's te zoeken.</entry>
- </row>
-
- <row>
- <entry>Omgevingsvariabelen.</entry>
- <entry><envar>$HOME</envar> is ingesteld op de thuismap van de gebruiker.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-
- <sect1 xml:id="preface-notes">
- <title>Opmerkingen, tips, belangrijke informatie, waarschuwingen en voorbeelden</title>
-
- <para>Opmerkingen, waarschuwingen en voorbeelden verschijnen in de tekst.</para>
-
- <note>
- <para>Opmerkingen worden zo weergegeven en bevatten informatie waarvan kennis genomen moet worden, aangezien ze kunne be√Įnvloeden wat de gebruiker doet.</para>
- </note>
-
- <tip>
- <para>Tips worden zo weergegeven en bevatten behulpzame informatie voor de gebruiker, zoals een eenvoudigere manier laten zien om iets te doen.</para>
- </tip>
-
- <important>
- <para>Belangrijke informatie wordt zo weergegeven. Typisch laat het extra stappen zien die de gebruiker kan moeten nemen.</para>
- </important>
-
- <warning>
- <para>Waarschuwingen worden zo weergegeven en bevatten informatie die waarschuuwt over mogelijke schade indien de instructies niet worden opgevolgd. Deze schade kan fysiek zijn, aan de hardware of de gebruiker, of het kan niet-fysiek zijn, zoals het onbedoeld verwijderen van belangrijke bestanden.</para>
- </warning>
-
- <example>
- <title>Een voorbeeld van een voorbeeld</title>
-
- <para>Voorbeelden worden zo weergegeven en bevatten typisch een voorbeeld dat een stappenplan of het resultaat van een bepaalde actie laat zien.</para>
- </example>
- </sect1>
-
- <sect1 xml:id="preface-acknowledgements">
- <title>Erkenningen</title>
-
- <para>Veel dank aan Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, en Christopher Maden. die te tijd hebben genomen om vroege kladversies van dit document te lezen en veel waardevol commentaar en kritiek hebben geboden.</para>
- </sect1>
- </preface>
-
-
-<!-- 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 version="5.0" xml:id="overview">
- <title>Overzicht</title>
-
- <para>Welkom bij het FreeBSD Documentatieproject (<acronym>FDP</acronym>). Kwaliteitsdocumentatie is cruciaal voor het succes van FreeBSD en we stellen uw bijdragen zeer op prijs.</para>
-
- <para>Dit document beschrijft hoe het <acronym>FDP</acronym> is georganiseerd, hoe documentatie te schrijven en op te sturen, en hoe effectief van de beschikbare gereedschappen gebruik te maken.</para>
-
- <para>Iedereen is welkom om aan het <acronym>FDP</acronym> bij te dragen. Bereidheid om bij te dragen is de enige eis voor lidmaatschap.</para>
-
- <para>Deze handleiding laat zien hoe:</para>
-
- <itemizedlist>
- <listitem>
- <para>Te identificeren welke gedeelten van FreeBSD door het <acronym>FDP</acronym> worden onderhouden.</para>
- </listitem>
-
- <listitem>
- <para>De benodigde gereedschappen en bestanden te installeren.</para>
- </listitem>
-
- <listitem>
- <para>Veranderingen aan de documentatie te maken.</para>
- </listitem>
-
- <listitem>
- <para>Veranderingen terug te sturen voor bespreking en opname in de documentatie van FreeBSD.</para>
- </listitem>
- </itemizedlist>
-
- <sect1 xml:id="overview-doc">
- <title>De FreeBSD Documentatieverzameling </title>
-
- <para>Het <acronym>FDP</acronym> is verantwoordelijk voor vier categori√ęn van documentatie van FreeBSD.</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Handboek</emphasis>: Het Handboek is de uitgebreide online bron en referentie voor gebruikers van FreeBSD.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>FAQ</emphasis>: De <acronym>FAQ</acronym> gebruikt een kort vraag-en-antwoord-formaat om vragen te bespreken die vaak worden gesteld op de verschillende mailinglijsten en fora gewijd aan FreeBSD.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Handleidingspagina's</emphasis>: De Engelstalige handleidingspagina's van het systeem worden gewoonlijk niet geschreven door het <acronym>FDP</acronym>, aangezien ze onderdeel zijn van het basissysteem zijn. Het <acronym>FDP</acronym> kan echter delen van bestaande handleidingspagina's hershrijven om ze te verduidelijken of om onjuistheden te corrigeren.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Website</emphasis>: Dit is de voornaamste aanwezigheid van FreeBSD op het web, zichtbaar op <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link> en vele spiegels over de wereld. De website is typisch de eerste blootstelling van een nieuwe gebruiker aan FreeBSD. </para>
- </listitem>
- </itemizedlist>
-
- <para>Vertaalteams zijn verantwoordelijk voor de vertaling van het Handboek en de website in verschillende talen. Handleidingpagina's worden momenteel niet vertaald.</para>
-
- <para>Bronnen van de documentatie voor de website, het Handboek en de <acronym>FAQ</acronym> van FreeBSD zijn beschikbaar in het documentatie-reservoir op <literal>https://svn.FreeBSD.org/doc/</literal>.</para>
-
- <para>Bronnen voor handleidingspagina's zijn beschikbaar in een apart broncode-reservoir op <literal>https://svn.FreeBSD.org/base/</literal>.</para>
-
- <para>Commit-berichten over de documentatie zijn zichtbaar met <command>svn log</command>. Commit-berichten zijn ook gearchiveerd op <uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>.</para>
-
- <para>Web-frontends voor deze beide reservoirs zijn beschikbaar op <link xlink:href="https://svnweb.FreeBSD.org/doc/"/> en <link xlink:href="https://svnweb.FreeBSD.org/base/"/>.</para>
-
- <para>Vele mensen hebben tutorials of stappenplannen over FreeBSD geschreven. Sommigen worden opgeslagen als deel van het <acronym>FDP</acronym>. In andere gevallen heeft de auteur besloten om de documentatie apart te houden. Het <acronym>FDP</acronym> tracht om verwijzigingen naar zoveel mogelijk van deze externe documentatie te bieden.</para>
- </sect1>
-
- <sect1 xml:id="overview-quick-start">
- <title xml:lang="en">Quick Start</title>
-
- <para xml:lang="en">Some preparatory steps must be taken before editing the FreeBSD
- documentation. First, subscribe to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>. 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 xml:lang="en">Install the
- <package>textproc/docproj</package>
- package or port. This meta-port installs all of the
- software needed to edit and build FreeBSD documentation.</para>
- </step>
-
- <step>
- <para xml:lang="en">Install a local working copy of the documentation from
- the FreeBSD repository in
- <filename>~/doc</filename> (see
- <xref linkend="working-copy"/>).</para>
-
- <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">Configure the text editor:</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en">Word wrap set to 70 characters.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Tab stops set to 2.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Replace each group of 8 leading spaces with a
- single tab.</para>
- </listitem>
- </itemizedlist>
-
- <para xml:lang="en">Specific editor configurations are listed in
- <xref linkend="editor-config"/>.</para>
- </step>
-
- <step>
- <para xml:lang="en">Update the local working copy:</para>
-
- <screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">Edit the documentation files that require changes. If a
- file needs major changes, consult the mailing list for
- input.</para>
-
- <para xml:lang="en">References to tag and entity usage can be found in
- <xref linkend="xhtml-markup"/> and
- <xref linkend="docbook-markup"/>.</para>
- </step>
-
- <step>
- <para xml:lang="en">After editing, check for problems by running:</para>
-
- <screen><prompt>%</prompt> <userinput>igor -R bestandsnaam.xml | less -RS</userinput></screen>
-
- <para xml:lang="en">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 xml:lang="en"><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 xml:lang="en">When changes are complete and tested, generate a
- <quote>diff file</quote>:</para>
-
- <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput>
-<prompt>%</prompt> <userinput>svn diff &gt; <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
-
- <para xml:lang="en">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 xml:lang="en">Submit the diff file using the web-based
- <link xlink:href="@@URL_RELPREFIX@@/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>[ Browse... ]</guibutton> button to
- attach the diff file.</para>
- </step>
- </procedure>
- </sect1>
-</chapter>
-
-
-<!-- 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 version="5.0" xml:id="tools">
- <title>Gereedschappen</title>
-
- <para xml:lang="en">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>Benodigde gereedschappen</title>
-
- <para xml:lang="en">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 FreeBSD
- documentation. Some further notes on particular components are
- given below.</para>
-
- <sect2>
- <title><acronym>DTD</acronym>s en <acronym>entiteiten</acronym></title>
-
- <para xml:lang="en">FreeBSD 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 xml:lang="en"><acronym>XHTML</acronym> <acronym>DTD</acronym>
- (<package>textproc/xhtml</package>)</term>
-
- <listitem>
- <para xml:lang="en"><acronym>XHTML</acronym> is the markup language of
- choice for the World Wide Web, and is used throughout
- the FreeBSD web site.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term>
-
- <listitem>
- <para xml:lang="en">DocBook is designed for marking up technical
- documentation. Most of the FreeBSD documentation is
- written in DocBook.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en">ISO 8879 entities
- (<package>textproc/iso8879</package>)</term>
-
- <listitem>
- <para xml:lang="en">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 xml:lang="en">Optional Tools</title>
-
- <para xml:lang="en">These applications are not required, but can make working on
- the documentation easier or add capabilities.</para>
-
- <sect2>
- <title>Software</title>
-
- <variablelist>
-
- <varlistentry>
- <term xml:lang="en"><application>Vim</application>
- (<package>editors/vim</package>)</term>
-
- <listitem>
- <para xml:lang="en">A popular editor for working with
- <acronym>XML</acronym> and derived documents, like
- DocBook <acronym>XML</acronym>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><application>Emacs</application> or
- <application>XEmacs</application>
- (<package>editors/emacs</package> or
- <package>editors/xemacs</package>)</term>
-
- <listitem>
- <para xml:lang="en">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>
-
-
-<!-- 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 version="5.0" xml:id="working-copy">
- <title xml:lang="en">The Working Copy</title>
-
- <para xml:lang="en">The <emphasis>working copy</emphasis> is a copy of the FreeBSD
- 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 xml:lang="en">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 xml:lang="en"><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link>
- is used to manage the FreeBSD 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 xml:lang="en">Documentation and Manual Pages</title>
-
- <para xml:lang="en">FreeBSD 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 xml:lang="en">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 xml:lang="en">Choosing a Directory</title>
-
- <para xml:lang="en">FreeBSD 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 xml:lang="en">Checking Out a Copy</title>
-
- <para xml:lang="en">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>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
-
- <para xml:lang="en">A checkout of the source code to work on manual pages is
- very similar:</para>
-
- <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
- </sect1>
-
- <sect1 xml:id="working-copy-updating">
- <title xml:lang="en">Updating a Working Copy</title>
-
- <para xml:lang="en">The documents and files in the FreeBSD 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 FreeBSD
- 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>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>
-
- <para xml:lang="en">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 xml:lang="en">Reverting Changes</title>
-
- <para xml:lang="en">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>%</prompt> <userinput>svn revert chapter.xml</userinput></screen>
- </sect1>
-
- <sect1 xml:id="working-copy-making-diff">
- <title xml:lang="en">Making a Diff</title>
-
- <para xml:lang="en">After edits to a file or group of files are completed, the
- differences between the local working copy and the version on
- the FreeBSD 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 xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>
-<prompt>%</prompt> <userinput>svn diff &gt; <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen>
-
- <para xml:lang="en">Give the file a meaningful name that identifies the
- contents. The example above is for spelling fixes to the whole
- documentation tree.</para>
-
- <para xml:lang="en">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 FreeBSD
- 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 xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput>
-<prompt>%</prompt> <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 xml:lang="en"><application>Subversion</application> References</title>
-
- <para xml:lang="en">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>
-
-
-<!-- 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 version="5.0" xml:id="structure">
- <title xml:lang="en">Documentation Directory Structure</title>
-
- <para xml:lang="en">Files and directories in the
- <filename>doc/</filename> tree follow a
- structure meant to:</para>
-
- <orderedlist>
- <listitem>
- <para xml:lang="en">Make it easy to automate converting the document to other
- formats.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Promote consistency between the different documentation
- organizations, to make it easier to switch between working on
- different documents.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Make it easy to decide where in the tree new documentation
- should be placed.</para>
- </listitem>
- </orderedlist>
-
- <para xml:lang="en">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 xml:lang="en">The Top Level,
- <filename>doc/</filename></title>
-
- <para xml:lang="en">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 xml:lang="en">Directory</entry>
- <entry xml:lang="en">Usage</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry valign="top"><filename>share</filename></entry>
-
- <entry xml:lang="en">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
- <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> infrastructure are in
- <filename>share/mk</filename>, while
- the additional <acronym>XML</acronym> support files
- (such as the FreeBSD extended DocBook
- <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry>
- </row>
-
- <row>
- <entry valign="top" xml:lang="en">
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
-
- <entry xml:lang="en">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 xml:lang="en">The
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename>
- Directories</title>
-
- <para xml:lang="en">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 xml:lang="en">Directory</entry>
- <entry xml:lang="en">Usage</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry valign="top"><filename>articles</filename></entry>
-
- <entry xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">Document-Specific Information</title>
-
- <para xml:lang="en">This section contains specific notes about particular
- documents managed by the FDP.</para>
-
- <sect2>
- <title>Het Handboek</title>
-
- <subtitle><filename>books/handbook/</filename></subtitle>
-
- <para xml:lang="en">The Handbook is written in DocBook <acronym>XML</acronym>
- using the FreeBSD DocBook extended <acronym>DTD</acronym>.</para>
-
- <para xml:lang="en">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 xml:lang="en">Physical Organization</title>
-
- <para xml:lang="en">There are a number of files and directories within the
- <filename>handbook</filename> directory.</para>
-
- <note>
- <para xml:lang="en">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
- <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
- </note>
-
- <sect4>
- <title><filename>Makefile</filename></title>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en"><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 xml:lang="en"><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
-
- <para xml:lang="en">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 xml:lang="en">For example, if one of the chapter files
- contains:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">chapter id="kernelconfig"</tag>
-...
-<tag class="endtag">chapter</tag></programlisting>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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>
-
-
-<!-- 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 version="5.0" xml:id="doc-build">
- <title xml:lang="en">The Documentation Build Process</title>
-
- <para xml:lang="en">This chapter covers organization of the documentation build
- process and how <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to control it.</para>
-
- <sect1 xml:id="doc-build-rendering">
- <title xml:lang="en">Rendering DocBook into Output</title>
-
- <para xml:lang="en">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" xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-<prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput></screen>
-
- <table xml:id="doc-build-rendering-common-formats" frame="none">
- <title xml:lang="en">Common Output Formats</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry xml:lang="en"><varname>FORMATS</varname> Value</entry>
- <entry xml:lang="en">File Type</entry>
- <entry>Beschrijving</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>html</literal></entry>
- <entry xml:lang="en"><acronym>HTML</acronym>, one file</entry>
- <entry xml:lang="en">A single <filename>book.html</filename> or
- <filename>article.html</filename>.</entry>
- </row>
-
- <row>
- <entry><literal>html-split</literal></entry>
- <entry xml:lang="en"><acronym>HTML</acronym>, multiple files</entry>
- <entry xml:lang="en">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 xml:lang="en">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 xml:lang="en">Build a Single HTML Output File</title>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-<prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen>
- </example>
-
- <example xml:id="doc-build-formats-example-html-split-pdf">
- <title xml:lang="en">Build HTML-Split and <acronym>PDF</acronym> Output
- Files</title>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-<prompt>%</prompt> <userinput>make FORMATS="html-split pdf"</userinput></screen>
- </example>
- </sect1>
-
- <sect1 xml:id="doc-build-toolset">
- <title xml:lang="en">The FreeBSD Documentation Build Toolset</title>
-
- <para xml:lang="en">These are the tools used to build and install the
- <acronym>FDP</acronym> documentation.</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en">The primary build tool is <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, specifically
- <application>Berkeley Make</application>.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Package building is handled by FreeBSD's
- <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to create compressed versions of
- the document. <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> archives are also supported.
- <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used for package building.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to install the
- documentation.</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 xml:id="doc-build-makefiles">
-
- <title xml:lang="en">Understanding <filename>Makefile</filename>s in the
- Documentation Tree</title>
-
- <para xml:lang="en">There are three main types of <filename>Makefile</filename>s
- in the FreeBSD Documentation Project tree.</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en"><link linkend="sub-make">Subdirectory
- <filename>Makefile</filename>s</link> simply pass
- commands to those directories below them.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><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 xml:lang="en"><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 xml:lang="en">Subdirectory <filename>Makefile</filename>s</title>
-
- <para xml:lang="en">These <filename>Makefile</filename>s usually take the form
- of:</para>
-
- <programlisting xml:lang="en">SUBDIR =articles
-SUBDIR+=books
-
-COMPAT_SYMLINK = en
-
-DOC_PREFIX?= ${.CURDIR}/..
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
-
- <para xml:lang="en">The first four non-empty lines define the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- variables <varname>SUBDIR</varname>,
- <varname>COMPAT_SYMLINK</varname>, and
- <varname>DOC_PREFIX</varname>.</para>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en"><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 xml:lang="en"><varname>DOC_PREFIX</varname> is the path to the root of
- the FreeBSD Document Project tree. This is not always that easy
- to find, and is also easily overridden, to allow for
- flexibility. <varname>.CURDIR</varname> is a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- builtin variable with the path to the current
- directory.</para>
-
- <para xml:lang="en">The final line includes the FreeBSD Documentation Project's
- project-wide <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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 xml:lang="en">Documentation <filename>Makefile</filename>s</title>
-
- <para xml:lang="en">These <filename>Makefile</filename>s set <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- variables that describe how to build the documentation
- contained in that directory.</para>
-
- <para xml:lang="en">Here is an example:</para>
-
- <programlisting xml:lang="en">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 xml:lang="en">The <varname>MAINTAINER</varname> variable allows
- committers to claim ownership of a document in the FreeBSD
- Documentation Project, and take responsibility for maintaining
- it.</para>
-
- <para xml:lang="en"><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 xml:lang="en"><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 xml:lang="en">The <varname>DOC_PREFIX</varname> and include statements
- should be familiar already.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="make-includes">
- <title xml:lang="en">FreeBSD Documentation Project
- <application>Make</application> Includes</title>
-
- <para xml:lang="en"><citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes are best explained by inspection of
- the code. Here are the system include files:</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en"><filename>doc.project.mk</filename> is the main project
- include file, which includes all the following include
- files, as necessary.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><filename>doc.subdir.mk</filename> handles traversing of
- the document tree during the build and install
- processes.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><filename>doc.install.mk</filename> provides variables
- that affect ownership and installation of documents.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><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 xml:lang="en"><filename>doc.project.mk</filename></title>
-
- <para xml:lang="en">By inspection:</para>
-
- <programlisting xml:lang="en">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 xml:lang="en">Variables</title>
-
- <para xml:lang="en"><varname>DOCFORMAT</varname> and
- <varname>MAINTAINER</varname> are assigned default values,
- if these are not set by the document make file.</para>
-
- <para xml:lang="en"><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 xml:lang="en"><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 xml:lang="en"><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
- FreeBSD documentation install root.</para>
- </note>
- </sect3>
-
- <sect3>
- <title xml:lang="en">Conditionals</title>
-
- <para xml:lang="en">The <literal>.if defined(DOC)</literal> line is an
- example of a <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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 xml:lang="en"><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 xml:lang="en">The two <literal>.endif</literal>s close the two above
- conditionals, marking the end of their application.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title xml:lang="en"><filename>doc.subdir.mk</filename></title>
-
- <para xml:lang="en">This file is too long to explain in detail. These notes
- describe the most important features.</para>
-
- <sect3>
- <title xml:lang="en">Variables</title>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en"><varname>SUBDIR</varname> is a list of
- subdirectories that the build process should go further
- down into.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><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 xml:lang="en"><varname>COMPAT_SYMLINK</varname> is described in
- the
- <link linkend="sub-make">Subdirectory Makefile</link>
- section.</para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title xml:lang="en">Targets and Macros</title>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">A special dependency <literal>.USE</literal> defines
- the equivalent of a macro.</para>
-
- <programlisting xml:lang="en">_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 xml:lang="en">In the above, <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> is now
- a macro which will execute the given commands when it is
- listed as a dependency.</para>
-
- <para xml:lang="en">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 xml:lang="en">clean: _SUBDIRUSE
- rm -f ${CLEANFILES}</programlisting>
-
- <para xml:lang="en">In the above, <buildtarget xml:lang="en">clean</buildtarget> will use
- the <buildtarget xml:lang="en">_SUBDIRUSE</buildtarget> macro after it has
- executed the instruction
- <command>rm -f ${CLEANFILES}</command>. In effect, this
- causes <buildtarget xml:lang="en">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 xml:lang="en">Provided Targets</title>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en"><buildtarget xml:lang="en">install</buildtarget> and
- <buildtarget xml:lang="en">package</buildtarget> both go down the
- directory tree calling the real versions of themselves
- in the subdirectories
- (<buildtarget xml:lang="en">realinstall</buildtarget> and
- <buildtarget xml:lang="en">realpackage</buildtarget>
- respectively).</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> removes files
- created by the build process (and goes down the
- directory tree too).
- <buildtarget xml:lang="en">cleandir</buildtarget> does the same, and
- also removes the object directory, if any.</para>
- </listitem>
- </itemizedlist>
- </sect4>
- </sect3>
-
- <sect3>
- <title xml:lang="en">More on Conditionals</title>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en"><literal>exists</literal> is another condition
- function which returns true if the given file
- exists.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><literal>empty</literal> returns true if the given
- variable is empty.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><literal>target</literal> returns true if the given
- target does not already exist.</para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title xml:lang="en">Looping Constructs in <command>make
- (.for)</command></title>
-
- <para xml:lang="en"><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 xml:lang="en">_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 xml:lang="en">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>
-
-
-<!-- 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 version="5.0" xml:id="the-website">
- <title xml:lang="en">The Website</title>
-
- <para xml:lang="en">The FreeBSD web site is part of the FreeBSD 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 xml:lang="en">Environment Variables</title>
-
- <para xml:lang="en">Several environment variables control which parts of the the
- web site are built or installed, and to which
- directories.</para>
-
- <tip>
- <para xml:lang="en">The web build system uses <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 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 xml:lang="en"><varname>DESTDIR</varname></term>
-
- <listitem>
- <para xml:lang="en">DESTDIR specifies the path where the web site files
- are to be installed.</para>
-
- <para xml:lang="en">This variable is best set with <citerefentry><refentrytitle>env</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the user
- shell's method of setting environment variables,
- <command>setenv</command> for <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
- <command>export</command> for <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry xml:id="the-website-env-englishonly">
- <term xml:lang="en"><varname>ENGLISH_ONLY</varname></term>
-
- <listitem>
- <para xml:lang="en">Default: undefined. Build and include all
- translations.</para>
-
- <para xml:lang="en"><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 xml:lang="en"><varname>WEB_ONLY</varname></term>
-
- <listitem>
- <para xml:lang="en">Default: undefined. Build both the web site
- and all the books and articles.</para>
-
- <para xml:lang="en"><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 xml:lang="en"><varname>WEB_LANG</varname></term>
-
- <listitem>
- <para xml:lang="en">Default: undefined. Build and include all the
- available languages on the web site.</para>
-
- <para xml:lang="en">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 xml:lang="en"><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para xml:lang="en"><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
- and <varname>ENGLISH_ONLY</varname> are <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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 xml:lang="en">Building and Installing the Web Pages</title>
-
- <para xml:lang="en">Having obtained the documentation and web site source files,
- the web site can be built.</para>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">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_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/ports.html#ports-tree">Ports
- Collection</link>.</para>
- </tip>
-
- <example xml:id="the-website-examples-build">
- <title xml:lang="en">Build the Full Web Site and All Documents</title>
-
- <para xml:lang="en">Build the web site and all documents. The resulting files
- are left in the document tree:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
-<prompt>%</prompt> <userinput>make all</userinput></screen>
- </example>
-
- <example xml:id="the-website-examples-buildinstall-englishonly">
- <title xml:lang="en">Build Only the Web Site in English</title>
-
- <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
-<prompt>%</prompt> <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 xml:lang="en">Build and Install the Web Site</title>
-
- <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
-<prompt>%</prompt> <userinput>make all</userinput>
-<prompt>%</prompt> <userinput>su -</userinput>
-Password:
-<prompt>#</prompt> <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
-<prompt>#</prompt> <userinput>make install</userinput></screen>
- </example>
-
- <para xml:lang="en">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 xml:lang="en"><prompt>#</prompt> <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
- </sect1>
-</chapter>
-
-
-<!-- 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 version="5.0" xml:id="xml-primer">
- <title xml:lang="en">XML Primer</title>
-
- <para xml:lang="en">Most <acronym>FDP</acronym> documentation is written with
- markup languages based on <acronym>XML</acronym>. This chapter
- explains what that means, how to read and understand the
- documentation source, and the <acronym>XML</acronym> techniques
- used.</para>
-
- <para xml:lang="en">Portions of this section were inspired by Mark Galassi's
- <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
- Going With DocBook</link>.</para>
-
- <sect1 xml:id="xml-primer-overview">
- <title>Overzicht</title>
-
- <para xml:lang="en">In the original days of computers, electronic text was
- simple. There were a few character sets like
- <acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, but that
- was about it. Text was text, and what you saw really was what
- you got. No frills, no formatting, no intelligence.</para>
-
- <para xml:lang="en">Inevitably, this was not enough. When text is in a
- machine-usable format, machines are expected to be able to use
- and manipulate it intelligently. Authors want to indicate that
- certain phrases should be emphasized, or added to a glossary, or
- made into hyperlinks. Filenames could be shown in a
- <quote>typewriter</quote> style font for viewing on screen, but
- as <quote>italics</quote> when printed, or any of a myriad of
- other options for presentation.</para>
-
- <para xml:lang="en">It was once hoped that Artificial Intelligence (AI) would
- make this easy. The computer would read the document and
- automatically identify key phrases, filenames, text that the
- reader should type in, examples, and more. Unfortunately, real
- life has not happened quite like that, and computers still
- require assistance before they can meaningfully process
- text.</para>
-
- <para xml:lang="en">More precisely, they need help identifying what is what.
- Consider this text:</para>
-
- <blockquote>
- <para xml:lang="en">To remove <filename>/tmp/foo</filename>, use
- <citerefentry><refentrytitle>rm</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>rm /tmp/foo</userinput></screen>
- </blockquote>
-
- <para xml:lang="en">It is easy to see which parts are filenames, which are
- commands to be typed in, which parts are references to manual
- pages, and so on. But the computer processing the document
- cannot. For this we need markup.</para>
-
- <para xml:lang="en"><quote>Markup</quote> is commonly used to describe
- <quote>adding value</quote> or <quote>increasing cost</quote>.
- The term takes on both these meanings when applied to text.
- Markup is additional text included in the document,
- distinguished from the document's content in some way, so that
- programs that process the document can read the markup and use
- it when making decisions about the document. Editors can hide
- the markup from the user, so the user is not distracted by
- it.</para>
-
- <para xml:lang="en">The extra information stored in the markup
- <emphasis>adds value</emphasis> to the document. Adding the
- markup to the document must typically be done by a
- person‚ÄĒafter all, if computers could recognize the text
- sufficiently well to add the markup then there would be no need
- to add it in the first place. This
- <emphasis>increases the cost</emphasis> (the effort required) to
- create the document.</para>
-
- <para xml:lang="en">The previous example is actually represented in this
- document like this:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &amp;man.rm.1;.<tag class="endtag">para</tag>
-
-<tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>
-
- <para xml:lang="en">The markup is clearly separate from the content.</para>
-
- <para xml:lang="en">Markup languages define what the markup means and how it
- should be interpreted.</para>
-
- <para xml:lang="en">Of course, one markup language might not be enough. A
- markup language for technical documentation has very different
- requirements than a markup language that is intended for cookery
- recipes. This, in turn, would be very different from a markup
- language used to describe poetry. What is really needed is a
- first language used to write these other markup languages. A
- <emphasis>meta markup language</emphasis>.</para>
-
- <para xml:lang="en">This is exactly what the eXtensible Markup
- Language (<acronym>XML</acronym>) is. Many markup languages
- have been written in <acronym>XML</acronym>, including the two
- most used by the <acronym>FDP</acronym>,
- <acronym>XHTML</acronym> and DocBook.</para>
-
- <para xml:lang="en">Each language definition is more properly called a grammar,
- vocabulary, schema or Document Type Definition
- (<acronym>DTD</acronym>). There are various languages to
- specify an <acronym>XML</acronym> grammar, or
- <emphasis>schema</emphasis>.</para>
-
- <para xml:id="xml-primer-validating" xml:lang="en">A schema is a
- <emphasis>complete</emphasis> specification of all the elements
- that are allowed to appear, the order in which they should
- appear, which elements are mandatory, which are optional, and so
- forth. This makes it possible to write an
- <acronym>XML</acronym> <emphasis>parser</emphasis> which reads
- in both the schema and a document which claims to conform to the
- schema. The parser can then confirm whether or not all the
- elements required by the vocabulary are in the document in the
- right order, and whether there are any errors in the markup.
- This is normally referred to as
- <quote>validating the document</quote>.</para>
-
- <note>
- <para xml:lang="en">Validation confirms that the choice of
- elements, their ordering, and so on, conforms to that listed
- in the grammar. It does <emphasis>not</emphasis> check
- whether <emphasis>appropriate</emphasis> markup has been used
- for the content. If all the filenames in a document were
- marked up as function names, the parser would not flag this as
- an error (assuming, of course, that the schema defines
- elements for filenames and functions, and that they are
- allowed to appear in the same place).</para>
- </note>
-
- <para xml:lang="en">Most contributions to the Documentation
- Project will be content marked up in either
- <acronym>XHTML</acronym> or DocBook, rather than alterations to
- the schemas. For this reason, this book will not touch on how
- to write a vocabulary.</para>
- </sect1>
-
- <sect1 xml:id="xml-primer-elements">
- <title xml:lang="en">Elements, Tags, and Attributes</title>
-
- <para xml:lang="en">All the vocabularies written in <acronym>XML</acronym> share
- certain characteristics. This is hardly surprising, as the
- philosophy behind <acronym>XML</acronym> will inevitably show
- through. One of the most obvious manifestations of this
- philosophy is that of <emphasis>content</emphasis> and
- <emphasis>elements</emphasis>.</para>
-
- <para xml:lang="en">Documentation, whether it is a single web page, or a lengthy
- book, is considered to consist of content. This content is then
- divided and further subdivided into elements. The purpose of
- adding markup is to name and identify the boundaries of these
- elements for further processing.</para>
-
- <para xml:lang="en">For example, consider a typical book. At the very top
- level, the book is itself an element. This <quote>book</quote>
- element obviously contains chapters, which can be considered to
- be elements in their own right. Each chapter will contain more
- elements, such as paragraphs, quotations, and footnotes. Each
- paragraph might contain further elements, identifying content
- that was direct speech, or the name of a character in the
- story.</para>
-
- <para xml:lang="en">It may be helpful to think of this as
- <quote>chunking</quote> content. At the very top level is one
- chunk, the book. Look a little deeper, and there are more
- chunks, the individual chapters. These are chunked further into
- paragraphs, footnotes, character names, and so on.</para>
-
- <para xml:lang="en">Notice how this differentiation between different elements
- of the content can be made without resorting to any
- <acronym>XML</acronym> terms. It really is surprisingly
- straightforward. This could be done with a highlighter pen and
- a printout of the book, using different colors to indicate
- different chunks of content.</para>
-
- <para xml:lang="en">Of course, we do not have an electronic highlighter pen, so
- we need some other way of indicating which element each piece of
- content belongs to. In languages written in
- <acronym>XML</acronym> (<acronym>XHTML</acronym>, DocBook, et
- al) this is done by means of <emphasis>tags</emphasis>.</para>
-
- <para xml:lang="en">A tag is used to identify where a particular element starts,
- and where the element ends. <emphasis>The tag is not part of
- the element itself</emphasis>. Because each grammar was
- normally written to mark up specific types of information, each
- one will recognize different elements, and will therefore have
- different names for the tags.</para>
-
- <para xml:lang="en">For an element called
- <replaceable>element-name</replaceable> the start tag will
- normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>.
- The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para>
-
- <example>
- <title xml:lang="en">Using an Element (Start and End Tags)</title>
-
- <para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating
- that the content enclosed by the element is a paragraph,
- called <tag>p</tag>.</para>
-
- <programlisting xml:lang="en"><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for
- the 'p' element, and it will end with the end tag for the 'p'
- element.<tag class="endtag">p</tag>
-
-<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para xml:lang="en">Some elements have no content. For example, in
- <acronym>XHTML</acronym>, a horizontal line can be included in
- the document. For these <quote>empty</quote> elements,
- <acronym>XML</acronym> introduced a shorthand form that is
- completely equivalent to the two-tag version:</para>
-
- <example>
- <title xml:lang="en">Using an Element Without Content</title>
-
- <para xml:lang="en"><acronym>XHTML</acronym> has an element for indicating a
- horizontal rule, called <tag>hr</tag>. This element
- does not wrap content, so it looks like this:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
-<tag class="starttag">hr</tag><tag class="endtag">hr</tag>
-
-<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
- from the previous paragraph.<tag class="endtag">p</tag></programlisting>
-
- <para xml:lang="en">The shorthand version consists of a single tag:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
-<tag class="emptytag">hr</tag>
-
-<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this
- from the previous paragraph.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para xml:lang="en">As shown above, elements can contain other elements. In the
- book example earlier, the book element contained all the chapter
- elements, which in turn contained all the paragraph elements,
- and so on.</para>
-
- <example>
- <title xml:lang="en">Elements Within Elements; <tag>em</tag></title>
-
- <programlisting xml:lang="en"><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some
- of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para xml:lang="en">The grammar consists of rules that describe which elements
- can contain other elements, and exactly what they can
- contain.</para>
-
- <important>
- <para xml:lang="en">People often confuse the terms tags and elements, and use
- the terms as if they were interchangeable. They are
- not.</para>
-
- <para xml:lang="en">An element is a conceptual part of your document. An
- element has a defined start and end. The tags mark where the
- element starts and ends.</para>
-
- <para xml:lang="en">When this document (or anyone else knowledgeable about
- <acronym>XML</acronym>) refers to
- <quote>the <tag class="starttag">p</tag> tag</quote>
- they mean the literal text consisting of the three characters
- <literal>&lt;</literal>, <literal>p</literal>, and
- <literal>&gt;</literal>. But the phrase
- <quote>the <tag>p</tag> element</quote> refers to the
- whole element.</para>
-
- <para xml:lang="en">This distinction <emphasis>is</emphasis> very subtle. But
- keep it in mind.</para>
- </important>
-
- <para xml:lang="en">Elements can have attributes. An attribute has a name and a
- value, and is used for adding extra information to the element.
- This might be information that indicates how the content should
- be rendered, or might be something that uniquely identifies that
- occurrence of the element, or it might be something else.</para>
-
- <para xml:lang="en">An element's attributes are written
- <emphasis>inside</emphasis> the start tag for that element, and
- take the form
- <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
-
- <para xml:lang="en">In <acronym>XHTML</acronym>, the <tag>p</tag>
- element has an attribute called
- <tag class="attribute">align</tag>, which suggests an
- alignment (justification) for the paragraph to the program
- displaying the <acronym>XHTML</acronym>.</para>
-
- <para xml:lang="en">The <tag class="attribute">align</tag> attribute can
- take one of four defined values, <literal>left</literal>,
- <literal>center</literal>, <literal>right</literal> and
- <literal>justify</literal>. If the attribute is not specified
- then the default is <literal>left</literal>.</para>
-
- <example>
- <title xml:lang="en">Using an Element with an Attribute</title>
-
- <programlisting xml:lang="en"><tag class="starttag">p align="left"</tag>The inclusion of the align attribute
- on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag>
-
-<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para xml:lang="en">Some attributes only take specific values, such as
- <literal>left</literal> or <literal>justify</literal>. Others
- allow any value.</para>
-
- <example>
- <title xml:lang="en">Single Quotes Around Attributes</title>
-
- <programlisting xml:lang="en"><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting>
- </example>
-
- <para xml:lang="en">Attribute values in <acronym>XML</acronym> must be enclosed
- in either single or double quotes. Double quotes are
- traditional. Single quotes are useful when the attribute value
- contains double quotes.</para>
-
- <para xml:lang="en">Information about attributes, elements, and tags is stored
- in catalog files. The Documentation Project uses standard
- DocBook catalogs and includes additional catalogs for
- FreeBSD-specific features. Paths to the catalog files are defined
- in an environment variable so they can be found by the document
- build tools.</para>
-
- <sect2>
- <title xml:lang="en">To Do…</title>
-
- <para xml:lang="en">Before running the examples in this document, install
- <package>textproc/docproj</package> from
- the FreeBSD Ports Collection. This is a
- <emphasis>meta-port</emphasis> that downloads and installs
- the standard programs and supporting files needed by the
- Documentation Project. <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> users must use
- <command>rehash</command> for the shell to recognize new
- programs after they have been installed, or log out
- and then log back in again.</para>
-
- <procedure>
- <step>
- <para xml:lang="en">Create <filename>example.xml</filename>, and enter
- this text:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag>
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para xml:lang="en">Try to validate this file using an
- <acronym>XML</acronym> parser.</para>
-
- <para xml:lang="en"><package>textproc/docproj</package>
- includes the <command>xmllint</command>
- <link linkend="xml-primer-validating">validating
- parser</link>.</para>
-
- <para xml:lang="en">Use <command>xmllint</command> to validate the
- document:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput></screen>
-
- <para xml:lang="en"><command>xmllint</command> returns without displaying
- any output, showing that the document validated
- successfully.</para>
- </step>
-
- <step>
- <para xml:lang="en">See what happens when required elements are omitted.
- Delete the line with the
- <tag class="starttag">title</tag> and
- <tag class="endtag">title</tag> tags, and re-run
- the validation.</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput>
-example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen>
-
- <para xml:lang="en">This shows that the validation error comes from the
- <replaceable>fifth</replaceable> line of the
- <replaceable>example.xml</replaceable> file and that the
- content of the <tag class="starttag">head</tag> is
- the part which does not follow the rules of the
- <acronym>XHTML</acronym> grammar.</para>
-
- <para xml:lang="en">Then <command>xmllint</command> shows the line where
- the error was found and marks the exact character position
- with a <literal>^</literal> sign.</para>
- </step>
-
- <step>
- <para xml:lang="en">Replace the <tag>title</tag> element.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-doctype-declaration">
- <title xml:lang="en">The DOCTYPE Declaration</title>
-
- <para xml:lang="en">The beginning of each document can specify the name of the
- <acronym>DTD</acronym> to which the document conforms. This
- DOCTYPE declaration is used by <acronym>XML</acronym> parsers to
- identify the <acronym>DTD</acronym> and ensure that the document
- does conform to it.</para>
-
- <para xml:lang="en">A typical declaration for a document written to conform with
- version 1.0 of the <acronym>XHTML</acronym>
- <acronym>DTD</acronym> looks like this:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting>
-
- <para xml:lang="en">That line contains a number of different components.</para>
-
- <variablelist>
- <varlistentry>
- <term xml:lang="en"><literal>&lt;!</literal></term>
-
- <listitem>
- <para xml:lang="en">The <emphasis>indicator</emphasis> shows
- this is an <acronym>XML</acronym> declaration.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>DOCTYPE</literal></term>
-
- <listitem>
- <para xml:lang="en">Shows that this is an <acronym>XML</acronym>
- declaration of the document type.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>html</literal></term>
-
- <listitem>
- <para xml:lang="en">Names the first
- <link linkend="xml-primer-elements">element</link> that
- will appear in the document.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
-
- <listitem>
- <para xml:lang="en">Lists the Formal Public Identifier
- (<acronym>FPI</acronym>)
- <indexterm xml:lang="en">
- <primary>Formal Public Identifier</primary>
- </indexterm>
- for the <acronym>DTD</acronym> to which this document
- conforms. The <acronym>XML</acronym> parser uses this to
- find the correct <acronym>DTD</acronym> when processing
- this document.</para>
-
- <para xml:lang="en"><literal>PUBLIC</literal> is not a part of the
- <acronym>FPI</acronym>, but indicates to the
- <acronym>XML</acronym> processor how to find the
- <acronym>DTD</acronym> referenced in the
- <acronym>FPI</acronym>. Other ways of telling the
- <acronym>XML</acronym> parser how to find the
- <acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
-
- <listitem>
- <para xml:lang="en">A local filename or a <acronym>URL</acronym> to find
- the <acronym>DTD</acronym>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>&gt;</literal></term>
-
- <listitem>
- <para xml:lang="en">Ends the declaration and returns to the
- document.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <sect2>
- <title xml:lang="en">Formal Public Identifiers
- (<acronym>FPI</acronym>s)</title>
-
- <indexterm significance="preferred" xml:lang="en">
- <primary>Formal Public Identifier</primary>
- </indexterm>
-
- <note>
- <para xml:lang="en">It is not necessary to know this, but it is useful
- background, and might help debug problems when the
- <acronym>XML</acronym> processor can not locate the
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para xml:lang="en"><acronym>FPI</acronym>s must follow a specific
- syntax:</para>
-
- <programlisting xml:lang="en">"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
-
- <variablelist>
- <varlistentry>
- <term xml:lang="en"><replaceable>Owner</replaceable></term>
-
- <listitem>
- <para xml:lang="en">The owner of the <acronym>FPI</acronym>.</para>
-
- <para xml:lang="en">The beginning of the string identifies the owner of
- the <acronym>FPI</acronym>. For example, the
- <acronym>FPI</acronym>
- <literal>"ISO 8879:1986//ENTITIES Greek
- Symbols//EN"</literal> lists
- <literal>ISO 8879:1986</literal> as being the owner for
- the set of entities for Greek symbols.
- <acronym>ISO</acronym> 8879:1986 is the International
- Organization for Standardization
- (<acronym>ISO</acronym>) number for the
- <acronym>SGML</acronym> standard, the predecessor (and a
- superset) of <acronym>XML</acronym>.</para>
-
- <para xml:lang="en">Otherwise, this string will either look like
- <literal>-//<replaceable>Owner</replaceable></literal>
- or
- <literal>+//<replaceable>Owner</replaceable></literal>
- (notice the only difference is the leading
- <literal>+</literal> or <literal>-</literal>).</para>
-
- <para xml:lang="en">If the string starts with <literal>-</literal> then
- the owner information is unregistered, with a
- <literal>+</literal> identifying it as
- registered.</para>
-
- <para xml:lang="en"><acronym>ISO</acronym> 9070:1991 defines how
- registered names are generated. It might be derived
- from the number of an <acronym>ISO</acronym>
- publication, an <acronym>ISBN</acronym> code, or an
- organization code assigned according to
- <acronym>ISO</acronym> 6523. Additionally, a
- registration authority could be created in order to
- assign registered names. The <acronym>ISO</acronym>
- council delegated this to the American National
- Standards Institute (<acronym>ANSI</acronym>).</para>
-
- <para xml:lang="en">Because the FreeBSD Project has not been registered,
- the owner string is <literal>-//FreeBSD</literal>. As seen
- in the example, the <acronym>W3C</acronym> are not a
- registered owner either.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><replaceable>Keyword</replaceable></term>
-
- <listitem>
- <para xml:lang="en">There are several keywords that indicate the type of
- information in the file. Some of the most common
- keywords are <literal>DTD</literal>,
- <literal>ELEMENT</literal>, <literal>ENTITIES</literal>,
- and <literal>TEXT</literal>. <literal>DTD</literal> is
- used only for <acronym>DTD</acronym> files,
- <literal>ELEMENT</literal> is usually used for
- <acronym>DTD</acronym> fragments that contain only
- entity or element declarations. <literal>TEXT</literal>
- is used for <acronym>XML</acronym> content (text and
- tags).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><replaceable>Description</replaceable></term>
-
- <listitem>
- <para xml:lang="en">Any description can be given for the contents
- of this file. This may include version numbers or any
- short text that is meaningful and unique for the
- <acronym>XML</acronym> system.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><replaceable>Language</replaceable></term>
-
- <listitem>
- <para xml:lang="en">An <acronym>ISO</acronym> two-character code that
- identifies the native language for the file.
- <literal>EN</literal> is used for English.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <sect3>
- <title xml:lang="en"><filename>catalog</filename> Files</title>
-
- <para xml:lang="en">With the syntax above, an <acronym>XML</acronym>
- processor needs to have some way of turning the
- <acronym>FPI</acronym> into the name of the file containing
- the <acronym>DTD</acronym>. A catalog file (typically
- called <filename>catalog</filename>) contains lines that map
- <acronym>FPI</acronym>s to filenames. For example, if the
- catalog file contained the line:</para>
-
-<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog -->
-
- <programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting>
-
- <para xml:lang="en">The <acronym>XML</acronym> processor knows that the
- <acronym>DTD</acronym> is called
- <filename>transitional.dtd</filename> in the
- <filename>1.0</filename> subdirectory of the directory that
- held <filename>catalog</filename>.</para>
-
- <para xml:lang="en">Examine the contents of
- <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
- This is the catalog file for the <acronym>XHTML</acronym>
- <acronym>DTD</acronym>s that were installed as part of the
- <package>textproc/docproj</package> port.</para>
- </sect3>
- </sect2>
-
- <sect2 xml:id="xml-primer-fpi-alternatives">
- <title xml:lang="en">Alternatives to <acronym>FPI</acronym>s</title>
-
- <para xml:lang="en">Instead of using an <acronym>FPI</acronym> to indicate the
- <acronym>DTD</acronym> to which the document conforms (and
- therefore, which file on the system contains the
- <acronym>DTD</acronym>), the filename can be explicitly
- specified.</para>
-
- <para xml:lang="en">The syntax is slightly different:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting>
-
- <para xml:lang="en">The <literal>SYSTEM</literal> keyword indicates that the
- <acronym>XML</acronym> processor should locate the
- <acronym>DTD</acronym> in a system specific fashion. This
- typically (but not always) means the <acronym>DTD</acronym>
- will be provided as a filename.</para>
-
- <para xml:lang="en">Using <acronym>FPI</acronym>s is preferred for reasons of
- portability. If the <literal>SYSTEM</literal> identifier is
- used, then the <acronym>DTD</acronym> must be provided and
- kept in the same location for everyone.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-xml-escape">
- <title xml:lang="en">Escaping Back to <acronym>XML</acronym></title>
-
- <para xml:lang="en">Some of the underlying <acronym>XML</acronym> syntax can be
- useful within documents. For example, comments can be included
- in the document, and will be ignored by the parser. Comments
- are entered using <acronym>XML</acronym> syntax. Other uses for
- <acronym>XML</acronym> syntax will be shown later.</para>
-
- <para xml:lang="en"><acronym>XML</acronym> sections begin with a
- <literal>&lt;!</literal> tag and end with a
- <literal>&gt;</literal>. These sections contain instructions
- for the parser rather than elements of the document. Everything
- between these tags is <acronym>XML</acronym> syntax. The
- <link linkend="xml-primer-doctype-declaration">DOCTYPE
- declaration</link> shown earlier is an example of
- <acronym>XML</acronym> syntax included in the document.</para>
-
- </sect1>
-
- <sect1 xml:id="xml-primer-comments">
- <title xml:lang="en">Comments</title>
-
- <para xml:lang="en">Comments are an <acronym>XML</acronym> construct, and are
- normally only valid inside a <acronym>DTD</acronym>. However,
- as <xref linkend="xml-primer-xml-escape"/> shows, it is possible
- to use <acronym>XML</acronym> syntax within the document.</para>
-
- <para xml:lang="en">The delimiter for XML comments is the string
- <quote><literal>--</literal></quote>. The first occurrence of
- this string opens a comment, and the second closes it.</para>
-
- <example>
- <title xml:lang="en"><acronym>XML</acronym> Generic Comment</title>
-
- <programlisting xml:lang="en">&lt;!-- This is inside the comment --&gt;
-
-&lt;!-- This is another comment --&gt;
-
-&lt;!-- This is one way
- of doing multiline comments --&gt;
-
-&lt;!-- This is another way of --
- -- doing multiline comments --&gt;</programlisting>
- </example>
-
- <para xml:lang="en"><acronym>XHTML</acronym> users may be familiar with different
- rules for comments. In particular, it is often believed that
- the string <literal>&lt;!--</literal> opens a comment, and it is
- only closed by <literal>--&gt;</literal>.</para>
-
- <para xml:lang="en">This is <emphasis>not</emphasis> correct. Many web browsers
- have broken <acronym>XHTML</acronym> parsers, and will accept
- incorrect input as valid. However, the <acronym>XML</acronym>
- parsers used by the Documentation Project are more strict, and
- will reject documents with that error.</para>
-
- <example>
- <title xml:lang="en">Erroneous <acronym>XML</acronym> Comments</title>
-
- <programlisting xml:lang="en">&lt;!-- This is in the comment --
-
- THIS IS OUTSIDE THE COMMENT!
-
- -- back inside the comment --&gt;</programlisting>
-
- <para xml:lang="en">The <acronym>XML</acronym> parser will treat this as
- though it were actually:</para>
-
- <programlisting xml:lang="en">&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
-
- <para xml:lang="en">That is not valid <acronym>XML</acronym>, and may give
- confusing error messages.</para>
- </example>
-
- <sect2>
- <title xml:lang="en">To Do…</title>
-
- <procedure>
- <step>
- <para xml:lang="en">Add some comments to
- <filename>example.xml</filename>, and check that the file
- still validates using <command>xmllint</command>.</para>
- </step>
-
- <step>
- <para xml:lang="en">Add some invalid comments to
- <filename>example.xml</filename>, and see the error
- messages that <command>xmllint</command> gives when it
- encounters an invalid comment.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-entities">
- <title xml:lang="en">Entities</title>
-
- <para xml:lang="en">Entities are a mechanism for assigning names to chunks of
- content. As an <acronym>XML</acronym> parser processes a
- document, any entities it finds are replaced by the content of
- the entity.</para>
-
- <para xml:lang="en">This is a good way to have re-usable, easily changeable
- chunks of content in <acronym>XML</acronym> documents. It is
- also the only way to include one marked up file inside another
- using <acronym>XML</acronym>.</para>
-
- <para xml:lang="en">There are two types of entities for two different
- situations: <emphasis>general entities</emphasis> and
- <emphasis>parameter entities</emphasis>.</para>
-
- <sect2 xml:id="xml-primer-general-entities">
- <title xml:lang="en">General Entities</title>
-
- <para xml:lang="en">General entities are used to assign names to reusable
- chunks of text. These entities can only be used in the
- document. They cannot be used in an
- <acronym>XML</acronym> context.</para>
-
- <para xml:lang="en">To include the text of a general entity in the document,
- include
- <literal>&amp;<replaceable>entity-name</replaceable>;</literal>
- in the text. For example, consider a general entity called
- <literal>current.version</literal> which expands to the
- current version number of a product. To use it in the
- document, write:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>The current version of our product is
- &amp;current.version;.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">When the version number changes, edit the definition of
- the general entity, replacing the value. Then reprocess the
- document.</para>
-
- <para xml:lang="en">General entities can also be used to enter characters that
- could not otherwise be included in an <acronym>XML</acronym>
- document. For example, <literal>&lt;</literal> and
- <literal>&amp;</literal> cannot normally appear in an
- <acronym>XML</acronym> document. The <acronym>XML</acronym>
- parser sees the <literal>&lt;</literal> symbol as the start of
- a tag. Likewise, when the <literal>&amp;</literal> symbol is
- seen, the next text is expected to be an entity name.</para>
-
- <para xml:lang="en">These symbols can be included by using two predefined
- general entities: <literal>&amp;lt;</literal> and
- <literal>&amp;amp;</literal>.</para>
-
- <para xml:lang="en">General entities can only be defined within an
- <acronym>XML</acronym> context. Such definitions are usually
- done immediately after the DOCTYPE declaration.</para>
-
- <example>
- <title xml:lang="en">Defining General Entities</title>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY current.version "3.0-RELEASE"&gt;
-&lt;!ENTITY last.version "2.2.7-RELEASE"&gt;
-]&gt;</programlisting>
-
- <para xml:lang="en">The DOCTYPE declaration has been extended by adding a
- square bracket at the end of the first line. The two
- entities are then defined over the next two lines, the
- square bracket is closed, and then the DOCTYPE declaration
- is closed.</para>
-
- <para xml:lang="en">The square brackets are necessary to indicate that the
- DTD indicated by the DOCTYPE declaration is being
- extended.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="xml-primer-parameter-entities">
- <title xml:lang="en">Parameter Entities</title>
-
- <para xml:lang="en">Parameter entities, like
- <link linkend="xml-primer-general-entities">general
- entities</link>, are used to assign names to reusable chunks
- of text. But parameter entities can only be used within an
- <link linkend="xml-primer-xml-escape">XML
- context</link>.</para>
-
- <para xml:lang="en">Parameter entity definitions are similar to those for
- general entities. However, parameter entries are included
- with
- <literal>%<replaceable>entity-name</replaceable>;</literal>.
- The definition also includes the <literal>%</literal> between
- the <literal>ENTITY</literal> keyword and the name of the
- entity.</para>
-
- <para xml:lang="en">For a mnemonic, think
- <quote><emphasis>P</emphasis>arameter entities use the
- <emphasis>P</emphasis>ercent symbol</quote>.</para>
-
- <example>
- <title xml:lang="en">Defining Parameter Entities</title>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY % param.some "some"&gt;
-&lt;!ENTITY % param.text "text"&gt;
-&lt;!ENTITY % param.new "%param.some more %param.text"&gt;
-
-&lt;!-- %param.new now contains "some more text" --&gt;
-]&gt;</programlisting>
- </example>
- </sect2>
-
- <sect2>
- <title xml:lang="en">To Do…</title>
-
- <procedure>
- <step>
- <para xml:lang="en">Add a general entity to
- <filename>example.xml</filename>.</para>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY version "1.1"&gt;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- &lt;!-- There may be some comments in here as well --&gt;
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
-
- <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
-
- <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para xml:lang="en">Validate the document using
- <command>xmllint</command>.</para>
- </step>
-
- <step>
- <para xml:lang="en">Load <filename>example.xml</filename> into a web
- browser. It may have to be copied to
- <filename>example.html</filename> before the browser
- recognizes it as an <acronym>XHTML</acronym>
- document.</para>
-
- <para xml:lang="en">Older browsers with simple parsers may not render this
- file as expected. The entity reference
- <literal>&amp;version;</literal> may not be replaced by
- the version number, or the <acronym>XML</acronym> context
- closing <literal>]&gt;</literal> may not be recognized and
- instead shown in the output.</para>
- </step>
-
- <step>
- <para xml:lang="en">The solution is to <emphasis>normalize</emphasis> the
- document with an <acronym>XML</acronym> normalizer. The
- normalizer reads valid <acronym>XML</acronym> and writes
- equally valid <acronym>XML</acronym> which has been
- transformed in some way. One way the normalizer
- transforms the input is by expanding all the entity
- references in the document, replacing the entities with
- the text that they represent.</para>
-
- <para xml:lang="en"><command>xmllint</command> can be used for this. It
- also has an option to drop the initial
- <acronym>DTD</acronym> section so that the closing
- <literal>]&gt;</literal> does not confuse browsers:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --noent --dropdtd example.xml &gt; example.html</userinput></screen>
-
- <para xml:lang="en">A normalized copy of the document with entities
- expanded is produced in <filename>example.html</filename>,
- ready to load into a web browser.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-include">
- <title xml:lang="en">Using Entities to Include Files</title>
-
- <para xml:lang="en">Both
- <link linkend="xml-primer-general-entities">general</link> and
- <link linkend="xml-primer-parameter-entities">parameter</link>
- entities are particularly useful for including one file inside
- another.</para>
-
- <sect2 xml:id="xml-primer-include-using-gen-entities">
- <title xml:lang="en">Using General Entities to Include Files</title>
-
- <para xml:lang="en">Consider some content for an <acronym>XML</acronym> book
- organized into files, one file per chapter, called
- <filename>chapter1.xml</filename>,
- <filename>chapter2.xml</filename>, and so forth, with a
- <filename>book.xml</filename> that will contain these
- chapters.</para>
-
- <para xml:lang="en">In order to use the contents of these files as the values
- for entities, they are declared with the
- <literal>SYSTEM</literal> keyword. This directs the
- <acronym>XML</acronym> parser to include the contents of the
- named file as the value of the entity.</para>
-
- <example>
- <title xml:lang="en">Using General Entities to Include Files</title>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY chapter.1 SYSTEM "chapter1.xml"&gt;
-&lt;!ENTITY chapter.2 SYSTEM "chapter2.xml"&gt;
-&lt;!ENTITY chapter.3 SYSTEM "chapter3.xml"&gt;
-&lt;!-- And so forth --&gt;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- &lt;!-- Use the entities to load in the chapters --&gt;
-
- &amp;chapter.1;
- &amp;chapter.2;
- &amp;chapter.3;
-<tag class="endtag">html</tag></programlisting>
- </example>
-
- <warning>
- <para xml:lang="en">When using general entities to include other files
- within a document, the files being included
- (<filename>chapter1.xml</filename>,
- <filename>chapter2.xml</filename>, and so on)
- <emphasis>must not</emphasis> start with a DOCTYPE
- declaration. This is a syntax error because entities are
- low-level constructs and they are resolved before any
- parsing happens.</para>
- </warning>
- </sect2>
-
- <sect2>
- <title xml:lang="en">Using Parameter Entities to Include Files</title>
-
- <para xml:lang="en">Parameter entities can only be used inside an
- <acronym>XML</acronym> context. Including a file in an
- <acronym>XML</acronym> context can be used
- to ensure that general entities are reusable.</para>
-
- <para xml:lang="en">Suppose that there are many chapters in the document, and
- these chapters were reused in two different books, each book
- organizing the chapters in a different fashion.</para>
-
- <para xml:lang="en">The entities could be listed at the top of each book, but
- that quickly becomes cumbersome to manage.</para>
-
- <para xml:lang="en">Instead, place the general entity definitions inside one
- file, and use a parameter entity to include that file within
- the document.</para>
-
- <example>
- <title xml:lang="en">Using Parameter Entities to Include Files</title>
-
- <para xml:lang="en">Place the entity definitions in a separate file
- called <filename>chapters.ent</filename> and
- containing this text:</para>
-
- <programlisting xml:lang="en">&lt;!ENTITY chapter.1 SYSTEM "chapter1.xml"&gt;
-&lt;!ENTITY chapter.2 SYSTEM "chapter2.xml"&gt;
-&lt;!ENTITY chapter.3 SYSTEM "chapter3.xml"&gt;</programlisting>
-
- <para xml:lang="en">Create a parameter entity to refer to the contents
- of the file. Then use the parameter entity to load the file
- into the document, which will then make all the general
- entities available for use. Then use the general entities
- as before:</para>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!-- Define a parameter entity to load in the chapter general entities --&gt;
-&lt;!ENTITY % chapters SYSTEM "chapters.ent"&gt;
-
-&lt;!-- Now use the parameter entity to load in this file --&gt;
-%chapters;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- &amp;chapter.1;
- &amp;chapter.2;
- &amp;chapter.3;
-<tag class="endtag">html</tag></programlisting>
- </example>
- </sect2>
-
- <sect2>
- <title xml:lang="en">To Do…</title>
-
- <sect3>
- <title xml:lang="en">Use General Entities to Include Files</title>
-
- <procedure>
- <step>
- <para xml:lang="en">Create three files, <filename>para1.xml</filename>,
- <filename>para2.xml</filename>, and
- <filename>para3.xml</filename>.</para>
-
- <para xml:lang="en">Put content like this in each file:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting>
- </step>
-
- <step>
- <para xml:lang="en">Edit <filename>example.xml</filename> so that it
- looks like this:</para>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY version "1.1"&gt;
-&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
-&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
-&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
-
- &amp;para1;
- &amp;para2;
- &amp;para3;
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para xml:lang="en">Produce <filename>example.html</filename> by
- normalizing <filename>example.xml</filename>.</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">Load <filename>example.html</filename> into the web
- browser and confirm that the
- <filename>para<replaceable>n</replaceable>.xml</filename>
- files have been included in
- <filename>example.html</filename>.</para>
- </step>
- </procedure>
- </sect3>
-
- <sect3>
- <title xml:lang="en">Use Parameter Entities to Include Files</title>
-
- <note>
- <para xml:lang="en">The previous steps must have completed before this
- step.</para>
- </note>
-
- <procedure>
- <step>
- <para xml:lang="en">Edit <filename>example.xml</filename> so that it
- looks like this:</para>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
-&lt;!ENTITY % entities SYSTEM "entities.ent"&gt; %entities;
-]&gt;
-
-<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
- <tag class="starttag">head</tag>
- <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
- <tag class="endtag">head</tag>
-
- <tag class="starttag">body</tag>
- <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
-
- &amp;para1;
- &amp;para2;
- &amp;para3;
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </step>
-
- <step>
- <para xml:lang="en">Create a new file called
- <filename>entities.ent</filename> with this
- content:</para>
-
- <programlisting xml:lang="en">&lt;!ENTITY version "1.1"&gt;
-&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
-&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
-&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;</programlisting>
- </step>
-
- <step>
- <para xml:lang="en">Produce <filename>example.html</filename> by
- normalizing <filename>example.xml</filename>.</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">Load <filename>example.html</filename> into the web
- browser and confirm that the
- <filename>para<replaceable>n</replaceable>.xml</filename>
- files have been included in
- <filename>example.html</filename>.</para>
- </step>
- </procedure>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-marked-sections">
- <title xml:lang="en">Marked Sections</title>
-
- <para xml:lang="en"><acronym>XML</acronym> provides a mechanism to indicate that
- particular pieces of the document should be processed in a
- special way. These are called
- <quote>marked sections</quote>.</para>
-
- <example>
- <title xml:lang="en">Structure of a Marked Section</title>
-
- <programlisting xml:lang="en">&lt;![<replaceable>KEYWORD</replaceable>[
- Contents of marked section
-]]&gt;</programlisting>
- </example>
-
- <para xml:lang="en">As expected of an <acronym>XML</acronym> construct, a marked
- section starts with <literal>&lt;!</literal>.</para>
-
- <para xml:lang="en">The first square bracket begins the marked section.</para>
-
- <para xml:lang="en"><replaceable>KEYWORD</replaceable> describes how this marked
- section is to be processed by the parser.</para>
-
- <para xml:lang="en">The second square bracket indicates the start of the
- marked section's content.</para>
-
- <para xml:lang="en">The marked section is finished by closing the two square
- brackets, and then returning to the document context from the
- <acronym>XML</acronym> context with
- <literal>&gt;</literal>.</para>
-
- <sect2 xml:id="xml-primer-marked-section-keywords">
- <title xml:lang="en">Marked Section Keywords</title>
-
- <sect3 xml:id="xml-primer-cdata">
- <title xml:lang="en"><literal>CDATA</literal></title>
-
- <para xml:lang="en">These keywords denote the marked sections
- <emphasis>content model</emphasis>, and allow you to change
- it from the default.</para>
-
- <para xml:lang="en">When an <acronym>XML</acronym> parser is processing a
- document, it keeps track of the
- <quote>content model</quote>.</para>
-
- <para xml:lang="en">The content model describes the
- content the parser is expecting to see and what it will do
- with that content.</para>
-
- <para xml:lang="en">The <literal>CDATA</literal> content model is one of the
- most useful.</para>
-
- <para xml:lang="en"><literal>CDATA</literal> is for
- <quote>Character Data</quote>. When the parser is in this
- content model, it expects to see only characters. In this
- model the <literal>&lt;</literal> and
- <literal>&amp;</literal> symbols lose their special status,
- and will be treated as ordinary characters.</para>
-
- <note>
- <para xml:lang="en">When using <literal>CDATA</literal> in examples of
- text marked up in <acronym>XML</acronym>, remember that
- the content of <literal>CDATA</literal> is not validated.
- The included text must be check with other means. For
- example, the content could be written in another document,
- validated, and then pasted into the
- <literal>CDATA</literal> section.</para>
- </note>
-
- <example>
- <title xml:lang="en">Using a <literal>CDATA</literal> Marked
- Section</title>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Here is an example of how to include some text that contains
- many <tag class="starttag">literal</tag>&amp;lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;amp;<tag class="endtag">literal</tag>
- symbols. The sample text is a fragment of
- <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and
- <tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag>
-
-<tag class="starttag">programlisting</tag>&lt;![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the
- elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle
- brackets are used so many times, it is simpler to say the whole
- example is a CDATA marked section than to use the entity names for
- the left and right angle brackets throughout.<tag class="endtag">p</tag>
-
- <tag class="starttag">ul</tag>
- <tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag>
- <tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag>
- <tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag>
- <tag class="endtag">ul</tag>
-
- <tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]&gt;<tag class="endtag">programlisting</tag></programlisting>
- </example>
- </sect3>
-
- <sect3 xml:id="xml-primer-include-ignore">
- <title xml:lang="en"><literal>INCLUDE</literal> and
- <literal>IGNORE</literal></title>
-
- <para xml:lang="en">When the keyword is <literal>INCLUDE</literal>, then the
- contents of the marked section will be processed. When the
- keyword is <literal>IGNORE</literal>, the marked section
- is ignored and will not be processed. It will not appear in
- the output.</para>
-
- <example>
- <title xml:lang="en">Using <literal>INCLUDE</literal> and
- <literal>IGNORE</literal> in Marked Sections</title>
-
- <programlisting xml:lang="en">&lt;![INCLUDE[
- This text will be processed and included.
-]]&gt;
-
-&lt;![IGNORE[
- This text will not be processed or included.
-]]&gt;</programlisting>
- </example>
-
- <para xml:lang="en">By itself, this is not too useful. Text to be
- removed from the document could be cut out, or wrapped
- in comments.</para>
-
- <para xml:lang="en">It becomes more useful when controlled by
- <link linkend="xml-primer-parameter-entities">parameter
- entities</link>, yet this usage is limited
- to entity files.</para>
-
- <para xml:lang="en">For example, suppose that documentation was produced in
- a hard-copy version and an electronic version. Some extra
- text is desired in the electronic version content that was
- not to appear in the hard-copy.</para>
-
- <para xml:lang="en">Create an entity file that defines general entities to
- include each chapter and guard these definitions with a
- parameter entity that can be set to either
- <literal>INCLUDE</literal> or <literal>IGNORE</literal> to
- control whether the entity is defined. After these
- conditional general entity definitions, place one more
- definition for each general entity to set them to an empty
- value. This technique makes use of the fact that entity
- definitions cannot be overridden but the first definition
- always takes effect. So the inclusion of the chapter is
- controlled with the corresponding parameter entity. Set to
- <literal>INCLUDE</literal>, the first general entity
- definition will be read and the second one will be ignored.
- Set to <literal>IGNORE</literal>, the first definition will
- be ignored and the second one will take effect.</para>
-
- <example>
- <title xml:lang="en">Using a Parameter Entity to Control a Marked
- Section</title>
-
- <programlisting xml:lang="en">&lt;!ENTITY % electronic.copy "INCLUDE"&gt;
-
-&lt;![%electronic.copy;[
-&lt;!ENTITY chap.preface SYSTEM "preface.xml"&gt;
-]]&gt;
-
-&lt;!ENTITY chap.preface ""&gt;</programlisting>
-
- <para xml:lang="en">When producing the hard-copy version, change the
- parameter entity's definition to:</para>
-
- <programlisting xml:lang="en">&lt;!ENTITY % electronic.copy "IGNORE"&gt;</programlisting>
- </example>
- </sect3>
- </sect2>
-
- <sect2>
- <title xml:lang="en">To Do…</title>
-
- <procedure>
- <step>
- <para xml:lang="en">Modify <filename>entities.ent</filename> to
- contain the following:</para>
-
- <programlisting xml:lang="en">&lt;!ENTITY version "1.1"&gt;
-&lt;!ENTITY % conditional.text "IGNORE"&gt;
-
-&lt;![%conditional.text;[
-&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
-]]&gt;
-
-&lt;!ENTITY para1 ""&gt;
-
-&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
-&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;</programlisting>
- </step>
-
- <step>
- <para xml:lang="en">Normalize <filename>example.xml</filename>
- and notice that the conditional text is not present in the
- output document. Set the parameter entity
- guard to <literal>INCLUDE</literal> and regenerate the
- normalized document and the text will appear again.
- This method makes sense if there are more
- conditional chunks depending on the same condition. For
- example, to control generating printed or online
- text.</para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-
- <sect1 xml:id="xml-primer-conclusion">
- <title xml:lang="en">Conclusion</title>
-
- <para xml:lang="en">That is the conclusion of this <acronym>XML</acronym>
- primer. For reasons of space and complexity, several things
- have not been covered in depth (or at all). However, the
- previous sections cover enough <acronym>XML</acronym> to
- introduce the organization of the <acronym>FDP</acronym>
- documentation.</para>
- </sect1>
-</chapter>
-
-
-<!-- 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 version="5.0" xml:id="xhtml-markup">
- <title xml:lang="en"><acronym>XHTML</acronym> Markup</title>
-
- <sect1 xml:id="xhtml-markup-introduction">
- <title xml:lang="en">Introduction</title>
-
- <para xml:lang="en">This chapter describes usage of the <acronym>XHTML</acronym>
- markup language used for the FreeBSD web site.</para>
-
- <para xml:lang="en"><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 xml:lang="en"><acronym>XHTML</acronym> is used to mark up pages on the
- FreeBSD 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 xml:lang="en"><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 xml:lang="en">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 xml:lang="en">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 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
- </note>
-
- <note>
- <title xml:lang="en">Inline Versus Block</title>
-
- <para xml:lang="en">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 xml:lang="en">Formal Public Identifier (<acronym>FPI</acronym>)</title>
-
- <para xml:lang="en">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 FreeBSD web site comply with the transitional version of
- <acronym>XHTML</acronym> 1.0.</para>
-
- <programlisting xml:lang="en">PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
- </sect1>
-
- <sect1 xml:id="xhtml-markup-sectional-elements">
- <title xml:lang="en">Sectional Elements</title>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">Normal <acronym>XHTML</acronym> Document
- Structure</title>
-
- <programlisting xml:lang="en"><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>
-
- …
-
- <tag class="endtag">body</tag>
-<tag class="endtag">html</tag></programlisting>
- </example>
- </sect1>
-
- <sect1 xml:id="xhtml-markup-block-elements">
- <title xml:lang="en">Block Elements</title>
-
- <sect2 xml:id="xhtml-markup-block-elements-headings">
- <title xml:lang="en">Headings</title>
-
- <para xml:lang="en"><acronym>XHTML</acronym> has tags to denote headings in
- the document at up to six different levels.</para>
-
- <para xml:lang="en">The largest and most prominent heading is
- <tag>h1</tag>, then <tag>h2</tag>,
- continuing down to <tag>h6</tag>.</para>
-
- <para xml:lang="en">The element's content is the text of the heading.</para>
-
- <example>
- <title xml:lang="en"><tag>h1</tag>, <tag>h2</tag>,
- and Other Header Tags</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">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 xml:lang="en">Paragraphs</title>
-
- <para xml:lang="en"><acronym>XHTML</acronym> supports a single paragraph
- element, <tag>p</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>p</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Block Quotations</title>
-
- <para xml:lang="en">A block quotation is an extended quotation from another
- document that will appear in a separate paragraph.</para>
-
- <example>
- <title xml:lang="en"><tag>blockquote</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Lists</title>
-
- <para xml:lang="en"><acronym>XHTML</acronym> can present the user with three
- types of lists: ordered, unordered, and definition.</para>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en"><tag>ul</tag> and
- <tag>ol</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Definition Lists with <tag>dl</tag></title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Pre-formatted Text</title>
-
- <para xml:lang="en">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 xml:lang="en">Wrap pre-formatted text in the <tag>pre</tag>
- element.</para>
-
- <example>
- <title xml:lang="en"><tag>pre</tag> Example</title>
-
- <para xml:lang="en">For example, the <tag>pre</tag> tags could be
- used to mark up an email message:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">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 xml:lang="en">Tables</title>
-
- <para xml:lang="en">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 xml:lang="en">Simple Use of <tag>table</tag></title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">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 xml:lang="en">Using
- <tag class="attribute">rowspan</tag></title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Using
- <tag class="attribute">colspan</tag></title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Using <tag class="attribute">rowspan</tag> and
- <tag class="attribute">colspan</tag>
- Together</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">In-line Elements</title>
-
- <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">
- <title xml:lang="en">Emphasizing Information</title>
-
- <para xml:lang="en">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 xml:lang="en"><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 xml:lang="en"><tag>em</tag> and
- <tag>strong</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Indicating Fixed-Pitch Text</title>
-
- <para xml:lang="en">Content that should be rendered in a fixed pitch
- (typewriter) typeface is tagged with <tag>tt</tag>
- (for <quote>teletype</quote>).</para>
-
- <example>
- <title xml:lang="en"><tag>tt</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">Links</title>
-
- <note>
- <para xml:lang="en">Links are also inline elements.</para>
- </note>
-
- <sect3 xml:id="xhtml-markup-inline-elements-linking">
- <title xml:lang="en">Linking to Other Documents on the Web</title>
-
- <para xml:lang="en">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 xml:lang="en">Using
- <tag class="starttag">a href="..."</tag></title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">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 xml:lang="en">Linking to Specific Parts of Documents</title>
-
- <para xml:lang="en">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 xml:lang="en">Creating an Anchor</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><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 xml:lang="en">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 xml:lang="en">Linking to a Named Part of a Different
- Document</title>
-
- <para xml:lang="en">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 xml:lang="en"><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 xml:lang="en">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 xml:lang="en">Linking to a Named Part of the Same Document</title>
-
- <para xml:lang="en">The <literal>samplepara</literal> example
- resides in this document. To link to it:</para>
-
- <programlisting xml:lang="en"><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>
-
-
-<!-- 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 version="5.0" xml:id="docbook-markup">
-
- <title xml:lang="en">DocBook Markup</title>
-
- <sect1 xml:id="docbook-markup-introduction">
- <title xml:lang="en">Introduction</title>
-
- <para xml:lang="en">This chapter is an introduction to DocBook as it is used for
- FreeBSD documentation. DocBook is a large and complex markup
- system, but the subset described here covers the parts that are
- most widely used for FreeBSD documentation. While a moderate
- subset is covered, it is impossible to anticipate every
- situation. Please post questions that this document does
- not answer to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>.</para>
-
- <para xml:lang="en">DocBook was originally developed by HaL Computer Systems and
- O'Reilly &amp; Associates to be a Document Type Definition
- (<acronym>DTD</acronym>) for writing technical documentation
- <footnote><para xml:lang="en">A short history can be found under <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>.
- Since 1998 it is maintained by the <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
- DocBook Technical Committee</link>. As such, and unlike
- LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily
- oriented towards markup that describes <emphasis>what</emphasis>
- something is, rather than describing <emphasis>how</emphasis> it
- should be presented.</para>
-
- <para xml:lang="en">The DocBook <acronym>DTD</acronym> is available from the
- Ports Collection in the
- <package>textproc/docbook-xml</package>
- port. It is automatically installed as part of the
- <package>textproc/docproj</package>
- port.</para>
-
- <note>
- <title xml:lang="en">Formal Versus Informal</title>
-
- <para xml:lang="en">Some elements may exist in two forms,
- <emphasis>formal</emphasis> and <emphasis>informal</emphasis>.
- Typically, the formal version of the element will consist of a
- title followed by the informal version of the element. The
- informal version will not have a title.</para>
- </note>
-
- <note>
- <title xml:lang="en">Inline Versus Block</title>
-
- <para xml:lang="en">In the remainder of this document, when describing
- elements, <emphasis>inline</emphasis> means that the element
- can occur within a block element, and does not cause a line
- break. A <emphasis>block</emphasis> element, by comparison,
- will cause a line break (and other processing) when it is
- encountered.</para>
- </note>
- </sect1>
-
- <sect1 xml:id="docbook-markup-freebsd-extensions">
- <title xml:lang="en">FreeBSD Extensions</title>
-
- <para xml:lang="en">The FreeBSD Documentation Project has extended the DocBook
- <acronym>DTD</acronym> with additional elements and entities.
- These additions serve to make some of the markup easier or more
- precise.</para>
-
- <para xml:lang="en">Throughout the rest of this document, the term
- <quote>DocBook</quote> is used to mean the FreeBSD-extended
- DocBook <acronym>DTD</acronym>.</para>
-
- <note>
- <para xml:lang="en">Most of these extensions are not unique to FreeBSD, it was
- just felt that they were useful enhancements for this
- particular project. Should anyone from any of the other *nix
- camps (NetBSD, OpenBSD, Linux, …) be interested in
- collaborating on a standard DocBook extension set, please
- contact Documentation Engineering Team <email>doceng@FreeBSD.org</email>.</para>
- </note>
-
- <sect2 xml:id="docbook-markup-freebsd-extensions-elements">
- <title xml:lang="en">FreeBSD Elements</title>
-
- <para xml:lang="en">The additional FreeBSD elements are not (currently) in the
- Ports Collection. They are stored in the FreeBSD Subversion
- tree, as <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para>
-
- <para xml:lang="en">FreeBSD-specific elements used in the examples below are
- clearly marked.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-freebsd-extensions-entities">
- <title xml:lang="en">FreeBSD Entities</title>
-
- <para xml:lang="en">This table shows some of the most useful entities
- available in the <acronym>FDP</acronym>. For a complete list,
- see the <filename>*.ent</filename> files in
- <filename>doc/share/xml</filename>.</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="3">
- <colspec colname="entity"/>
- <colspec colname="expandsto"/>
- <colspec colname="notes"/>
- <thead>
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
- </thead>
-
- <tbody valign="top">
- <row>
- <entry namest="entity" nameend="notes" xml:lang="en"><emphasis>FreeBSD
- Name Entities</emphasis></entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;os;</literal></entry>
- <entry><literal>FreeBSD</literal></entry>
- <entry/>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;os.stable;</literal></entry>
- <entry xml:lang="en"><literal>FreeBSD-STABLE</literal></entry>
- <entry/>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;os.current;</literal></entry>
- <entry xml:lang="en"><literal>FreeBSD-CURRENT</literal></entry>
- <entry/>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes" xml:lang="en">Manual Page
- Entities</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;man.ls.1;</literal></entry>
- <entry xml:lang="en"><citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry>
- <entry xml:lang="en">Usage: <literal>&amp;man.ls.1; is the manual page
- for
- &lt;command&gt;ls&lt;/command&gt;.</literal></entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;man.cp.1;</literal></entry>
- <entry xml:lang="en"><citerefentry><refentrytitle>cp</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry>
- <entry xml:lang="en">Usage: <literal>The manual page for
- &lt;command&gt;cp&lt;/command&gt; is
- &amp;man.cp.1;.</literal></entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry>
- <entry xml:lang="en"><emphasis>link to
- <replaceable>command</replaceable> manual page in
- section
- <replaceable>sectionnumber</replaceable></emphasis></entry>
- <entry xml:lang="en">Entities are defined for all the
- <link xlink:href="@@URL_RELPREFIX@@/cgi/man.cgi">FreeBSD manual
- pages</link>.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes" xml:lang="en">FreeBSD Mailing List
- Entities</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;a.doc;</literal></entry>
- <entry xml:lang="en"><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link></literal></entry>
- <entry xml:lang="en">Usage: <literal>A link to the
- &amp;a.doc;.</literal></entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;a.questions;</literal></entry>
- <entry xml:lang="en"><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions">FreeBSD general questions mailing list</link></literal></entry>
- <entry xml:lang="en">Usage: <literal>A link to the
- &amp;a.questions;.</literal></entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;a.<replaceable>listname</replaceable>;</literal></entry>
- <entry xml:lang="en"><emphasis>link to
- <replaceable>listname</replaceable></emphasis></entry>
- <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/eresources.html#eresources-mail">FreeBSD
- mailing lists</link>.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes" xml:lang="en">FreeBSD Document
- Link Entities</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;url.books.handbook;</literal></entry>
- <entry xml:lang="en"><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook</literal></entry>
- <entry xml:lang="en">Usage: <literal>A link to the &lt;link
- xlink:href="&amp;url.books.handbook;/advanced-networking.html"&gt;Advanced
- Networking&lt;/link&gt; chapter of the
- Handbook.</literal></entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;url.books.<replaceable>bookname</replaceable>;</literal></entry>
- <entry xml:lang="en"><emphasis>relative path to
- <replaceable>bookname</replaceable></emphasis></entry>
- <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/">FreeBSD
- books</link>.</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;url.articles.committers-guide;</literal></entry>
- <entry xml:lang="en"><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide</literal></entry>
- <entry xml:lang="en">Usage: <literal>A link to the &lt;link
- xlink:href="&amp;url.articles.committers-guide;"&gt;Committer's
- Guide&lt;/link&gt;
- article.</literal></entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;url.articles.<replaceable>articlename</replaceable>;</literal></entry>
- <entry xml:lang="en"><emphasis>relative path to
- <replaceable>articlename</replaceable></emphasis></entry>
- <entry xml:lang="en">Entities are defined for all the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/">FreeBSD
- articles</link>.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes" xml:lang="en">Other Operating
- System Name Entities</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;linux;</literal></entry>
- <entry><trademark class="registered">Linux</trademark></entry>
- <entry xml:lang="en">The <trademark class="registered">Linux</trademark> operating system.</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;unix;</literal></entry>
- <entry><trademark class="registered">UNIX</trademark></entry>
- <entry>Het <trademark class="registered">UNIX</trademark> besturingssysteem.</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;windows;</literal></entry>
- <entry><trademark class="registered">Windows</trademark></entry>
- <entry xml:lang="en">The <trademark class="registered">Windows</trademark> operating system.</entry>
- </row>
-
- <row>
- <entry/>
- <entry/>
- <entry/>
- </row>
-
- <row>
- <entry namest="entity" nameend="notes" xml:lang="en">Miscellaneous
- Entities</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;prompt.root;</literal></entry>
- <entry><prompt>#</prompt></entry>
- <entry xml:lang="en">The <systemitem class="username">root</systemitem> user
- prompt.</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;prompt.user;</literal></entry>
- <entry><prompt>%</prompt></entry>
- <entry xml:lang="en">A prompt for an unprivileged user.</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;postscript;</literal></entry>
- <entry><trademark class="registered">PostScript</trademark></entry>
- <entry xml:lang="en">The
- <trademark class="registered">PostScript</trademark> programming language.</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;tex;</literal></entry>
- <entry xml:lang="en"><application>TeX</application></entry>
- <entry xml:lang="en">The
- <application>TeX</application> typesetting language.</entry>
- </row>
-
- <row>
- <entry xml:lang="en"><literal>&amp;xorg;</literal></entry>
- <entry xml:lang="en">Xorg</entry>
- <entry xml:lang="en">The Xorg open source X
- Window System.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-fpi">
- <title xml:lang="en">Formal Public Identifier (FPI)</title>
-
- <para xml:lang="en">In compliance with the DocBook guidelines for writing
- <acronym>FPI</acronym>s for DocBook customizations, the
- <acronym>FPI</acronym> for the FreeBSD extended DocBook
- <acronym>DTD</acronym> is:</para>
-
- <programlisting xml:lang="en">PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
- </sect1>
-
- <sect1 xml:id="docbook-markup-document-structure">
- <title xml:lang="en">Document Structure</title>
-
- <para xml:lang="en">DocBook allows structuring documentation in several ways.
- The FreeBSD Documentation Project uses two primary types of DocBook
- document: the book and the article.</para>
-
- <para xml:lang="en">Books are organized into <tag>chapter</tag>s.
- This is a mandatory requirement. There may be
- <tag>part</tag>s between the book and the chapter to
- provide another layer of organization. For example, the
- Handbook is arranged in this way.</para>
-
- <para xml:lang="en">A chapter may (or may not) contain one or more sections.
- These are indicated with the <tag>sect1</tag> element.
- If a section contains another section then use the
- <tag>sect2</tag> element, and so on, up to
- <tag>sect5</tag>.</para>
-
- <para xml:lang="en">Chapters and sections contain the remainder of the
- content.</para>
-
- <para xml:lang="en">An article is simpler than a book, and does not use
- chapters. Instead, the content of an article is organized into
- one or more sections, using the same <tag>sect1</tag>
- (and <tag>sect2</tag> and so on) elements that are used
- in books.</para>
-
- <para xml:lang="en">The nature of the document being written should be used to
- determine whether it is best marked up as a book or an article.
- Articles are well suited to information that does not need to be
- broken down into several chapters, and that is, relatively
- speaking, quite short, at up to 20-25 pages of content. Books
- are best suited to information that can be broken up into
- several chapters, possibly with appendices and similar content
- as well.</para>
-
- <para xml:lang="en">The <link xlink:href="@@URL_RELPREFIX@@/docs.html">FreeBSD
- tutorials</link> are all marked up as articles, while this
- document, the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/index.html">FAQ</link>,
- and the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">Handbook</link> are all marked up as books, for
- example.</para>
-
- <sect2 xml:id="docbook-markup-starting-a-book">
- <title xml:lang="en">Starting a Book</title>
-
- <para xml:lang="en">The content of a book is contained within the
- <tag>book</tag> element. As well as containing
- structural markup, this element can contain elements that
- include additional information about the book. This is either
- meta-information, used for reference purposes, or additional
- content used to produce a title page.</para>
-
- <para xml:lang="en">This additional information is contained within
- <tag>info</tag>.</para>
-
- <example>
- <title xml:lang="en">Boilerplate <tag>book</tag> with
- <tag>info</tag></title>
-
- <!-- Cannot put this in a marked section because of the
- replaceable elements -->
-
- <programlisting xml:lang="en"><tag class="starttag">book</tag>
- <tag class="starttag">info</tag>
- <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag>
-
- <tag class="starttag">author</tag>
- <tag class="starttag">personname</tag>
- <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
- <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
- <tag class="endtag">personname</tag>
-
- <tag class="starttag">affiliation</tag>
- <tag class="starttag">address</tag>
- <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag>
- <tag class="endtag">address</tag>
- <tag class="endtag">affiliation</tag>
- <tag class="endtag">author</tag>
-
- <tag class="starttag">copyright</tag>
- <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag>
- <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag>
- <tag class="endtag">copyright</tag>
-
- <tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">info</tag>
-
- …
-
-<tag class="endtag">book</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-starting-an-article">
- <title xml:lang="en">Starting an Article</title>
-
- <para xml:lang="en">The content of the article is contained within the
- <tag>article</tag> element. As well as containing
- structural markup, this element can contain elements that
- include additional information about the article. This is
- either meta-information, used for reference purposes, or
- additional content used to produce a title page.</para>
-
- <para xml:lang="en">This additional information is contained within
- <tag>info</tag>.</para>
-
- <example>
- <title xml:lang="en">Boilerplate <tag>article</tag> with
- <tag>info</tag></title>
-
- <!-- Cannot put this in a marked section because of the
- replaceable elements -->
-
- <programlisting xml:lang="en"><tag class="starttag">article</tag>
- <tag class="starttag">info</tag>
- <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag>
-
- <tag class="starttag">author</tag>
- <tag class="starttag">personname</tag>
- <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag>
- <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag>
- <tag class="endtag">personname</tag>
-
- <tag class="starttag">affiliation</tag>
- <tag class="starttag">address</tag>
- <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag>
- <tag class="endtag">address</tag>
- <tag class="endtag">affiliation</tag>
- <tag class="endtag">author</tag>
-
- <tag class="starttag">copyright</tag>
- <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag>
- <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag>
- <tag class="endtag">copyright</tag>
-
- <tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">info</tag>
-
- …
-
-<tag class="endtag">article</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-indicating-chapters">
- <title xml:lang="en">Indicating Chapters</title>
-
- <para xml:lang="en">Use <tag>chapter</tag> to mark up your chapters.
- Each chapter has a mandatory <tag>title</tag>.
- Articles do not contain chapters, they are reserved for
- books.</para>
-
- <example>
- <title xml:lang="en">A Simple Chapter</title>
-
- <programlisting xml:lang="en"><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag>
-
- ...
-<tag class="endtag">chapter</tag></programlisting>
- </example>
-
- <para xml:lang="en">A chapter cannot be empty; it must contain elements in
- addition to <tag>title</tag>. If you need to
- include an empty chapter then just use an empty
- paragraph.</para>
-
- <example>
- <title xml:lang="en">Empty Chapters</title>
-
- <programlisting xml:lang="en"><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag><tag class="endtag">para</tag>
-<tag class="endtag">chapter</tag></programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-sections-below-chapters">
- <title xml:lang="en">Sections Below Chapters</title>
-
- <para xml:lang="en">In books, chapters may (but do not need to) be broken up
- into sections, subsections, and so on. In articles, sections
- are the main structural element, and each article must contain
- at least one section. Use the
- <tag>sect<replaceable>n</replaceable></tag> element.
- The <replaceable>n</replaceable> indicates the section number,
- which identifies the section level.</para>
-
- <para xml:lang="en">The first
- <tag>sect<replaceable>n</replaceable></tag> is
- <tag>sect1</tag>. You can have one or more of these
- in a chapter. They can contain one or more
- <tag>sect2</tag> elements, and so on, down to
- <tag>sect5</tag>.</para>
-
- <example>
- <title xml:lang="en">Sections in Chapters</title>
-
- <programlisting xml:lang="en"><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag>
-
- …
- <tag class="endtag">sect1</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag>
-
- <tag class="starttag">sect2</tag>
- <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag>
-
- <tag class="starttag">sect3</tag>
- <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag>
-
- …
- <tag class="endtag">sect3</tag>
- <tag class="endtag">sect2</tag>
-
- <tag class="starttag">sect2</tag>
- <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag>
-
- …
- <tag class="endtag">sect2</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">chapter</tag></programlisting>
- </example>
-
- <note>
- <para xml:lang="en">Section numbers are automatically generated and
- prepended to titles when the document is rendered to an
- output format. The generated section numbers and titles
- from the example above will be:</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en">1.1. First Section</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">1.2. Second Section</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">1.2.1. First Sub-Section</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">1.2.1.1. First Sub-Sub-Section</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">1.2.2. Second Sub-Section</para>
- </listitem>
- </itemizedlist>
- </note>
- </sect2>
-
- <sect2 xml:id="docbook-markup-subdividing-part">
- <title xml:lang="en">Subdividing Using <tag>part</tag>
- Elements</title>
-
- <para xml:lang="en"><tag>part</tag>s introduce another level of
- organization between <tag>book</tag> and
- <tag>chapter</tag> with one or more
- <tag>part</tag>s. This cannot be done in an
- <tag>article</tag>.</para>
-
- <programlisting xml:lang="en"><tag class="starttag">part</tag>
- <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag>
-
- <tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag>
-
- ...
- <tag class="endtag">chapter</tag>
-
- <tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag>
-
- ...
- <tag class="endtag">chapter</tag>
-
- <tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>History<tag class="endtag">title</tag>
-
- ...
- <tag class="endtag">chapter</tag>
-<tag class="endtag">part</tag></programlisting>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-block-elements">
- <title xml:lang="en">Block Elements</title>
-
- <sect2 xml:id="docbook-markup-paragraphs">
- <title xml:lang="en">Paragraphs</title>
-
- <para xml:lang="en">DocBook supports three types of paragraphs:
- <tag>formalpara</tag>, <tag>para</tag>, and
- <tag>simpara</tag>.</para>
-
- <para xml:lang="en">Almost all paragraphs in FreeBSD documentation use
- <tag>para</tag>. <tag>formalpara</tag>
- includes a <tag>title</tag> element, and
- <tag>simpara</tag> disallows some elements from
- within <tag>para</tag>. Stick with
- <tag>para</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>para</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>This is a paragraph. It can contain just about any
- other element.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">This is a paragraph. It can contain just about any
- other element.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-block-quotations">
- <title xml:lang="en">Block Quotations</title>
-
- <para xml:lang="en">A block quotation is an extended quotation from another
- document that should not appear within the current paragraph.
- These are rarely needed.</para>
-
- <para xml:lang="en">Blockquotes can optionally contain a title and an
- attribution (or they can be left untitled and
- unattributed).</para>
-
- <example>
- <title xml:lang="en"><tag>blockquote</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag>
-
-<tag class="starttag">blockquote</tag>
- <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag>
-
- <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag>
-
- <tag class="starttag">para</tag>We the People of the United States, in Order to form a more
- perfect Union, establish Justice, insure domestic Tranquility,
- provide for the common defence, promote the general Welfare, and
- secure the Blessings of Liberty to ourselves and our Posterity, do
- ordain and establish this Constitution for the United States of
- America.<tag class="endtag">para</tag>
-<tag class="endtag">blockquote</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">A small excerpt from the US Constitution:</para>
-
- <blockquote>
- <title xml:lang="en">Preamble to the Constitution of the United
- States</title>
-
- <attribution xml:lang="en">Copied from a web site
- somewhere</attribution>
-
- <para xml:lang="en">We the People of the United States, in Order to form
- a more perfect Union, establish Justice, insure domestic
- Tranquility, provide for the common defence, promote the
- general Welfare, and secure the Blessings of Liberty to
- ourselves and our Posterity, do ordain and establish
- this Constitution for the United States of
- America.</para>
- </blockquote>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-tips-notes">
- <title xml:lang="en">Tips, Notes, Warnings, Cautions, and Important
- Information</title>
-
- <para xml:lang="en">Extra information may need to be separated from
- the main body of the text. Typically this is
- <quote>meta</quote> information of which the user should be
- aware.</para>
-
- <para xml:lang="en">Several types of admonitions are available:
- <tag>tip</tag>, <tag>note</tag>,
- <tag>warning</tag>, <tag>caution</tag>, and
- <tag>important</tag>.</para>
-
- <para xml:lang="en">Which admonition to choose depends on the situation.
- The DocBook
- documentation suggests:</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en">Note is for information that should be heeded by
- all readers.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Important is a variation on Note.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Caution is for information regarding possible data
- loss or software damage.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Warning is for information regarding possible
- hardware damage or injury to life or limb.</para>
- </listitem>
- </itemizedlist>
-
- <example>
- <title xml:lang="en"><tag>tip</tag> and <tag>important</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">tip</tag>
- <tag class="starttag">para</tag>&amp;os; may reduce stress.<tag class="endtag">para</tag>
-<tag class="endtag">tip</tag>
-
-<tag class="starttag">important</tag>
- <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions
- are visually jarring and can have the opposite of the
- intended effect.<tag class="endtag">para</tag>
-<tag class="endtag">important</tag></programlisting>
- </example>
-
- <para xml:lang="en">Appearance:</para>
- <!-- Need to do this outside of the example -->
- <tip>
- <para xml:lang="en">FreeBSD may reduce stress.</para>
- </tip>
-
- <important>
- <para xml:lang="en">Please use admonitions sparingly. Too many admonitions
- are visually jarring and can have the opposite of the
- intended effect.</para>
- </important>
- </sect2>
-
- <sect2 xml:id="docbook-markup-example">
- <title>Voorbeelden</title>
-
- <para xml:lang="en">Examples can be shown with <tag>example</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>example</tag> Source</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">example</tag>
- <tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag>
-
- <tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag>
-<tag class="endtag">example</tag></programlisting>
- </example>
-
- <!-- Need to do this outside of the example -->
- <para xml:lang="en">Appearance:</para>
-
- <example>
- <title xml:lang="en">Rendered <tag>example</tag></title>
-
- <para xml:lang="en">Empty files can be created easily:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>touch file1 file2 file3</userinput></screen>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-lists-and-procedures">
- <title xml:lang="en">Lists and Procedures</title>
-
- <para xml:lang="en">Information often needs to be presented as lists, or as a
- number of steps that must be carried out in order to
- accomplish a particular goal.</para>
-
- <para xml:lang="en">To do this, use <tag>itemizedlist</tag>,
- <tag>orderedlist</tag>, <tag>variablelist</tag>, or
- <tag>procedure</tag>. There are other types of list
- elements in DocBook, but we will not cover them here.</para>
-
- <para xml:lang="en"><tag>itemizedlist</tag> and
- <tag>orderedlist</tag> are similar to their
- counterparts in <acronym>HTML</acronym>, <tag>ul</tag>
- and <tag>ol</tag>. Each one consists of one or more
- <tag>listitem</tag> elements, and each
- <tag>listitem</tag> contains one or more block
- elements. The <tag>listitem</tag> elements are
- analogous to <acronym>HTML</acronym>'s <tag>li</tag>
- tags. However, unlike HTML, they are required.</para>
-
- <example>
- <title xml:lang="en"><tag>itemizedlist</tag> and
- <tag>orderedlist</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">itemizedlist</tag>
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-<tag class="endtag">itemizedlist</tag>
-
-<tag class="starttag">orderedlist</tag>
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
-<tag class="endtag">orderedlist</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en">This is the first itemized item.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">This is the second itemized item.</para>
- </listitem>
- </itemizedlist>
-
- <orderedlist>
- <listitem>
- <para xml:lang="en">This is the first ordered item.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">This is the second ordered item.</para>
- </listitem>
- </orderedlist>
- </example>
-
- <para xml:id="docbook-markup-varlist" xml:lang="en">An alternate and often
- useful way of presenting information is the
- <tag>variablelist</tag>. These are lists where each entry has
- a term and a description. They are well suited for many types
- of descriptions, and present information in a form that is
- often easier for the reader than sections and
- subsections.</para>
-
- <para xml:lang="en">A <tag>variablelist</tag> has a <tag>title</tag>, and then
- pairs of <tag>term</tag> and <tag>listitem</tag>
- entries.</para>
-
- <example xml:id="docbook-markup-variablelist-example">
- <title xml:lang="en"><tag>variablelist</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">variablelist</tag>
- <tag class="starttag">varlistentry</tag>
- <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>In parallel communications, groups of bits arrive
- at the same time over multiple communications
- channels.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
- <tag class="endtag">varlistentry</tag>
-
- <tag class="starttag">varlistentry</tag>
- <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag>
-
- <tag class="starttag">listitem</tag>
- <tag class="starttag">para</tag>In serial communications, bits arrive one at a
- time over a single communications
- channel.<tag class="endtag">para</tag>
- <tag class="endtag">listitem</tag>
- <tag class="endtag">varlistentry</tag>
-<tag class="endtag">variablelist</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <variablelist>
- <varlistentry>
- <term xml:lang="en">Parallel</term>
-
- <listitem>
- <para xml:lang="en">In parallel communications, groups of bits arrive
- at the same time over multiple communications
- channels.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en">Serial</term>
-
- <listitem>
- <para xml:lang="en">In serial communications, bits arrive one at a
- time over a single communications channel.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </example>
-
- <para xml:lang="en">A <tag>procedure</tag> shows a series of
- <tag>step</tag>s, which may in turn
- consist of more <tag>step</tag>s or
- <tag>substep</tag>s. Each <tag>step</tag>
- contains block elements and may include an optional title.</para>
-
- <para xml:lang="en">Sometimes, steps are not sequential, but present a choice:
- do <emphasis>this</emphasis> or do <emphasis>that</emphasis>,
- but not both. For these alternative choices, use
- <tag>stepalternatives</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>procedure</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">procedure</tag>
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Finally, do one of these.<tag class="endtag">para</tag>
-
- <tag class="starttag">stepalternatives</tag>
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
-
- <tag class="starttag">step</tag>
- <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag>
- <tag class="endtag">step</tag>
- <tag class="endtag">stepalternatives</tag>
- <tag class="endtag">step</tag>
-<tag class="endtag">procedure</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <procedure>
- <step>
- <para xml:lang="en">Do this.</para>
- </step>
-
- <step>
- <para xml:lang="en">Then do this.</para>
- </step>
-
- <step>
- <para xml:lang="en">And now do this.</para>
- </step>
-
- <step>
- <para xml:lang="en">Finally, do one of these:</para>
-
- <stepalternatives>
- <step>
- <para xml:lang="en">Go left.</para>
- </step>
-
- <step>
- <para xml:lang="en">Go right.</para>
- </step>
- </stepalternatives>
- </step>
- </procedure>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-showing-file-samples">
- <title xml:lang="en">Showing File Samples</title>
-
- <para xml:lang="en">Fragments of a file (or perhaps a complete file) are shown
- by wrapping them in the <tag>programlisting</tag>
- element.</para>
-
- <para xml:lang="en">White space and line breaks within
- <tag>programlisting</tag> <emphasis>are</emphasis>
- significant. In particular, this means that the opening tag
- should appear on the same line as the first line of the
- output, and the closing tag should appear on the same line
- as the last line of the output, otherwise spurious blank
- lines may be included.</para>
-
- <example>
- <title xml:lang="en"><tag>programlisting</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like
- this:<tag class="endtag">para</tag>
-
-<tag class="starttag">programlisting</tag>#include &amp;lt;stdio.h&amp;gt;
-
-int
-main(void)
-{
- printf("hello, world\n");
-}<tag class="endtag">programlisting</tag></programlisting>
-
- <para xml:lang="en">Notice how the angle brackets in the
- <literal>#include</literal> line need to be referenced by
- their entities instead of being included literally.</para>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">When finished, the program will look like this:</para>
-
- <programlisting xml:lang="en">#include &lt;stdio.h&gt;
-
-int
-main(void)
-{
- printf("hello, world\n");
-}</programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-callouts">
- <title xml:lang="en">Callouts</title>
-
- <para xml:lang="en">A callout is a visual marker for referring to a
- piece of text or specific position within an
- example.</para>
-
- <para xml:lang="en">Callouts are marked with the <tag>co</tag>
- element. Each element must have a unique
- <literal>id</literal> assigned to it. After the example,
- include a <tag>calloutlist</tag> that describes each
- callout.</para>
-
- <example>
- <title xml:lang="en"><tag>co</tag> and
- <tag>calloutlist</tag> Example</title>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>When finished, the program will look like
- this:<tag class="endtag">para</tag>
-
-<tag class="starttag">programlisting</tag>#include &amp;lt;stdio.h&amp;gt; <tag class="emptytag">co xml:id="co-ex-include"</tag>
-
-int <tag class="emptytag">co xml:id="co-ex-return"</tag>
-main(void)
-{
- printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag>
-}<tag class="endtag">programlisting</tag>
-
-<tag class="starttag">calloutlist</tag>
- <tag class="starttag">callout arearefs="co-ex-include"</tag>
- <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag>
- <tag class="endtag">callout</tag>
-
- <tag class="starttag">callout arearefs="co-ex-return"</tag>
- <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an
- int.<tag class="endtag">para</tag>
- <tag class="endtag">callout</tag>
-
- <tag class="starttag">callout arearefs="co-ex-printf"</tag>
- <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes
- <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag>
- <tag class="endtag">callout</tag>
-<tag class="endtag">calloutlist</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">When finished, the program will look like this:</para>
-
- <programlisting xml:lang="en">#include &lt;stdio.h&gt; <co xml:id="co-ex-include"/>
-
-int <co xml:id="co-ex-return"/>
-main(void)
-{
- printf("hello, world\n"); <co xml:id="co-ex-printf"/>
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="co-ex-include">
- <para xml:lang="en">Includes the standard IO header file.</para>
- </callout>
-
- <callout arearefs="co-ex-return">
- <para xml:lang="en">Specifies that <function>main()</function> returns
- an int.</para>
- </callout>
-
- <callout arearefs="co-ex-printf">
- <para xml:lang="en">The <function>printf()</function> call that writes
- <literal>hello, world</literal> to standard
- output.</para>
- </callout>
- </calloutlist>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-tables">
- <title xml:lang="en">Tables</title>
-
- <para xml:lang="en">Unlike <acronym>HTML</acronym>, DocBook does not need
- tables for layout purposes, as the stylesheet handles those
- issues. Instead, just use tables for marking up tabular
- data.</para>
-
- <para xml:lang="en">In general terms (and see the DocBook documentation for
- more detail) a table (which can be either formal or informal)
- consists of a <tag>table</tag> element. This contains
- at least one <tag>tgroup</tag> element, which
- specifies (as an attribute) the number of columns in this
- table group. Within the tablegroup there is one
- <tag>thead</tag> element, which contains elements for
- the table headings (column headings), and one
- <tag>tbody</tag> which contains the body of the
- table.</para>
-
- <para xml:lang="en">Both <tag>tgroup</tag> and
- <tag>thead</tag> contain <tag>row</tag>
- elements, which in turn contain <tag>entry</tag>
- elements. Each <tag>entry</tag> element specifies
- one cell in the table.</para>
-
- <example>
- <title xml:lang="en"><tag>informaltable</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">informaltable pgwide="1"</tag>
- <tag class="starttag">tgroup cols="2"</tag>
- <tag class="starttag">thead</tag>
- <tag class="starttag">row</tag>
- <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag>
- <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag>
- <tag class="endtag">row</tag>
- <tag class="endtag">thead</tag>
-
- <tag class="starttag">tbody</tag>
- <tag class="starttag">row</tag>
- <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag>
- <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag>
- <tag class="endtag">row</tag>
-
- <tag class="starttag">row</tag>
- <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag>
- <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag>
- <tag class="endtag">row</tag>
- <tag class="endtag">tbody</tag>
- <tag class="endtag">tgroup</tag>
-<tag class="endtag">informaltable</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <informaltable pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry xml:lang="en">This is Column Head 1</entry>
- <entry xml:lang="en">This is Column Head 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry xml:lang="en">Row 1, column 1</entry>
- <entry xml:lang="en">Row 1, column 2</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Row 2, column 1</entry>
- <entry xml:lang="en">Row 2, column 2</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </example>
-
- <para xml:lang="en">Always use the <literal>pgwide</literal> attribute with
- a value of <literal>1</literal> with the
- <tag>informaltable</tag> element. A bug in Internet
- Explorer can cause the table to render incorrectly if this
- is omitted.</para>
-
- <para xml:lang="en">Table borders can be suppressed by setting the
- <literal>frame</literal> attribute to <literal>none</literal>
- in the <tag>informaltable</tag> element. For example,
- <literal>informaltable frame="none"</literal>.</para>
-
- <example>
- <title xml:lang="en">Table with <literal>frame="none"</literal> Example</title>
-
- <para xml:lang="en">Appearance:</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry xml:lang="en">This is Column Head 1</entry>
- <entry xml:lang="en">This is Column Head 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry xml:lang="en">Row 1, column 1</entry>
- <entry xml:lang="en">Row 1, column 2</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Row 2, column 1</entry>
- <entry xml:lang="en">Row 2, column 2</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-examples">
- <title xml:lang="en">Examples for the User to Follow</title>
-
- <para xml:lang="en">Examples for the user to follow are often necessary.
- Typically, these will consist of dialogs with the computer;
- the user types in a command, the user gets a response back,
- the user types another command, and so on.</para>
-
- <para xml:lang="en">A number of distinct elements and entities come into
- play here.</para>
-
- <variablelist>
- <varlistentry>
- <term xml:lang="en"><tag>screen</tag></term>
-
- <listitem>
- <para xml:lang="en">Everything the user sees in this example will be
- on the computer screen, so the next element is
- <tag>screen</tag>.</para>
-
- <para xml:lang="en">Within <tag>screen</tag>, white space is
- significant.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><tag>prompt</tag>,
- <literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal></term>
-
- <listitem>
- <para xml:lang="en">Some of the things the user will be seeing on the
- screen are prompts from the computer (either from the
- operating system, command shell, or application). These
- should be marked up using
- <tag>prompt</tag>.</para>
-
- <para xml:lang="en">As a special case, the two shell prompts for the
- normal user and the root user have been provided as
- entities. To indicate the user is at a shell prompt,
- use one of <literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal> as necessary. They
- do not need to be inside
- <tag>prompt</tag>.</para>
-
- <note>
- <para xml:lang="en"><literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal> are FreeBSD
- extensions to DocBook, and are not part of the
- original <acronym>DTD</acronym>.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><tag>userinput</tag></term>
-
- <listitem>
- <para xml:lang="en">When displaying text that the user should type in,
- wrap it in <tag>userinput</tag> tags. It will
- be displayed differently than system output text.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title xml:lang="en"><tag>screen</tag>, <tag>prompt</tag>,
- and <tag>userinput</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag>
-foo1
-foo2
-foo3
-&amp;prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag>
-foo2
-&amp;prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag>
-<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag>
-&amp;prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag>
-This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>ls -1</userinput>
-foo1
-foo2
-foo3
-<prompt>%</prompt> <userinput>ls -1 | grep foo2</userinput>
-foo2
-<prompt>%</prompt> <userinput>su</userinput>
-<prompt>Password: </prompt>
-<prompt>#</prompt> <userinput>cat foo2</userinput>
-This is the file called 'foo2'</screen>
- </example>
-
- <note>
- <para xml:lang="en">Even though we are displaying the contents of the file
- <filename>foo2</filename>, it is <emphasis>not</emphasis>
- marked up as <tag>programlisting</tag>. Reserve
- <tag>programlisting</tag> for showing fragments of
- files outside the context of user actions.</para>
- </note>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-inline-elements">
- <title xml:lang="en">In-line Elements</title>
-
- <sect2 xml:id="docbook-markup-inline-emphasizing">
- <title xml:lang="en">Emphasizing Information</title>
-
- <para xml:lang="en">To emphasize a particular word or phrase, use
- <tag>emphasis</tag>. This may be presented as
- italic, or bold, or might be spoken differently with a
- text-to-speech system.</para>
-
- <para xml:lang="en">There is no way to change the presentation of the
- emphasis within the document, no equivalent of
- <acronym>HTML</acronym>'s <tag>b</tag> and
- <tag>i</tag>. If the information being presented is
- important, then consider presenting it in
- <tag>important</tag> rather than
- <tag>emphasis</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>emphasis</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>&amp;os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag>
- premiere &amp;unix;-like operating system for the Intel
- architecture.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">FreeBSD is without doubt <emphasis>the</emphasis>
- premiere <trademark class="registered">UNIX</trademark>-like operating system for the Intel
- architecture.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-acronyms">
- <title xml:lang="en">Acronyms</title>
-
- <para xml:lang="en">Many computer terms are <emphasis>acronyms</emphasis>,
- words formed from the first letter of each word in a
- phrase. Acronyms are marked up into
- <tag>acronym</tag> elements. It is helpful to the
- reader when an acronym is defined on the first use, as shown
- in the example below.</para>
-
- <example>
- <title xml:lang="en"><tag>acronym</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149
- defined the use of avian carriers for transmission of
- Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The
- quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently
- transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Request For Comments (<acronym>RFC</acronym>) 1149
- defined the use of avian carriers for transmission of
- Internet Protocol (<acronym>IP</acronym>) data. The
- quantity of <acronym>IP</acronym> data currently
- transmitted in that manner is unknown.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-quotations">
- <title xml:lang="en">Quotations</title>
-
- <para xml:lang="en">To quote text from another document or source, or to
- denote a phrase that is used figuratively, use
- <tag>quote</tag>. Most of the markup tags available
- for normal text are also available from within a
- <tag>quote</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>quote</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>However, make sure that the search does not go beyond the
- <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>,
- as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">However, make sure that the search does not go beyond
- the <quote>boundary between local and public
- administration</quote>, as <acronym>RFC</acronym> 1535
- calls it.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-keys">
- <title xml:lang="en">Keys, Mouse Buttons, and Combinations</title>
-
- <para xml:lang="en">To refer to a specific key on the keyboard, use
- <tag>keycap</tag>. To refer to a mouse button, use
- <tag>mousebutton</tag>. And to refer to
- combinations of key presses or mouse clicks, wrap them all
- in <tag>keycombo</tag>.</para>
-
- <para xml:lang="en"><tag>keycombo</tag> has an attribute called
- <literal>action</literal>, which may be one of
- <literal>click</literal>, <literal>double-click</literal>,
- <literal>other</literal>, <literal>press</literal>,
- <literal>seq</literal>, or <literal>simul</literal>. The
- last two values denote whether the keys or buttons should be
- pressed in sequence, or simultaneously.</para>
-
- <para xml:lang="en">The stylesheets automatically add any connecting
- symbols, such as <literal>+</literal>, between the key
- names, when wrapped in <tag>keycombo</tag>.</para>
-
- <example>
- <title xml:lang="en">Keys, Mouse Buttons, and Combinations Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>To switch to the second virtual terminal, press
- <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>
- <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type
- <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag>
- <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>My window manager is configured so that
- <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag>
- <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag>
- <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">To switch to the second virtual terminal, press
- <keycombo action="simul"><keycap>Alt</keycap>
- <keycap>F1</keycap></keycombo>.</para>
-
- <para xml:lang="en">To exit <command>vi</command> without saving changes,
- type <keycombo action="seq">
- <keycap>Esc</keycap>
- <keycap>:</keycap>
- <keycap>q</keycap>
- <keycap>!</keycap></keycombo>.</para>
-
- <para xml:lang="en">My window manager is configured so that
- <keycombo action="simul">
- <keycap>Alt</keycap>
- <mousebutton>right</mousebutton></keycombo> mouse button
- is used to move windows.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-applications">
- <title xml:lang="en">Applications, Commands, Options, and Cites</title>
-
- <para xml:lang="en">Both applications and commands are frequently referred to
- when writing documentation. The distinction between them is
- that an application is the name of a program or suite of
- programs that fulfill a particular task. A command is the
- filename of a program that the user can type and run at a
- command line.</para>
-
- <para xml:lang="en">It is often necessary to show some of the options that a
- command might take.</para>
-
- <para xml:lang="en">Finally, it is often useful to list a command with its
- manual section number, in the <quote>command(number)</quote>
- format so common in Unix manuals.</para>
-
- <para xml:lang="en">Mark up application names with
- <tag>application</tag>.</para>
-
- <para xml:lang="en">To list a command with its manual section
- number (which should be most of the time) the DocBook
- element is <tag>citerefentry</tag>. This will
- contain a further two elements,
- <tag>refentrytitle</tag> and
- <tag>manvolnum</tag>. The content of
- <tag>refentrytitle</tag> is the name of the command,
- and the content of <tag>manvolnum</tag> is the
- manual page section.</para>
-
- <para xml:lang="en">This can be cumbersome to write, and so a series of
- <link linkend="xml-primer-general-entities">general
- entities</link> have been created to make this easier.
- Each entity takes the form
- <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
-
- <para xml:lang="en">The file that contains these entities is in
- <filename>doc/share/xml/man-refs.ent</filename>, and can be
- referred to using this <acronym>FPI</acronym>:</para>
-
- <programlisting xml:lang="en">PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
-
- <para xml:lang="en">Therefore, the introduction to FreeBSD documentation will
- usually include this:</para>
-
- <programlisting xml:lang="en">&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
-
-&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
-%man;
-
-…
-
-]&gt;</programlisting>
-
- <para xml:lang="en">Use <tag>command</tag> to include a command
- name <quote>in-line</quote> but present it as something the
- user should type.</para>
-
- <para xml:lang="en">Use <tag>option</tag> to mark up the options
- which will be passed to a command.</para>
-
- <para xml:lang="en">When referring to the same command multiple times in
- close proximity, it is preferred to use the
- <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
- notation to markup the first reference and use
- <tag>command</tag> to markup subsequent references.
- This makes the generated output, especially
- <acronym>HTML</acronym>, appear visually better.</para>
-
- <example>
- <title xml:lang="en">Applications, Commands, and Options Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most
- widely used Unix mail application.<tag class="starttag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the
- <tag class="starttag">citerefentry</tag>
- <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>
- <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>
- <tag class="endtag">citerefentry</tag>, &amp;man.mailq.1;, and &amp;man.newaliases.1;
- programs.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag>
- <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag>
- <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag>
- <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current
- status of messages in the mail queue. Check this on the command
- line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en"><application>Sendmail</application> is the most widely
- used Unix mail application.</para>
-
- <para xml:lang="en"><application>Sendmail</application> includes the
- <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, <citerefentry><refentrytitle>mailq</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and <citerefentry><refentrytitle>newaliases</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- programs.</para>
-
- <para xml:lang="en">One of the command line parameters to
- <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, <option>-bp</option>, will display the
- current status of messages in the mail queue. Check this
- on the command line by running
- <command>sendmail -bp</command>.</para>
- </example>
-
- <note>
- <para xml:lang="en">Notice how the
- <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
- notation is easier to follow.</para>
- </note>
- </sect2>
-
- <sect2 xml:id="docbook-markup-files">
- <title xml:lang="en">Files, Directories, Extensions, Device Names</title>
-
- <para xml:lang="en">To refer to the name of a file, a directory, a file
- extension, or a device name, use <tag>filename</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>filename</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>The source for the Handbook in English is found in
- <tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>.
- The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>.
- There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a
- number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected
- by the system, and appears in
- <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">The source for the Handbook in English is found in
- <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
- The main file is called <filename>book.xml</filename>.
- There is also a <filename>Makefile</filename> and a number
- of files with a <filename>.ent</filename> extension.</para>
-
- <para xml:lang="en"><filename>kbd0</filename> is the first keyboard detected
- by the system, and appears in
- <filename>/dev</filename>.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-name-of-ports">
- <title xml:lang="en">The Name of Ports</title>
-
- <note>
- <title xml:lang="en">FreeBSD Extension</title>
-
- <para xml:lang="en">These elements are part of the FreeBSD extension to
- DocBook, and do not exist in the original DocBook
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para xml:lang="en">To include the name of a program from the FreeBSD
- Ports Collection in the document, use the <tag>package</tag>
- tag. Since the Ports Collection can be installed in any
- number of locations, only include the category and the port
- name; do not include <filename>/usr/ports</filename>.</para>
-
- <para xml:lang="en">By default, <tag>package</tag> refers to a binary package.
- To refer to a port that will be built from source, set the
- <literal>role</literal> attribute to
- <literal>port</literal>.</para>
-
- <example>
- <title xml:lang="en"><tag>package</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary
- package to view network traffic.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be
- built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Install the <package>net/wireshark</package> binary
- package to view network traffic.</para>
-
- <para xml:lang="en"><package role="port">net/wireshark</package> can also be
- built and installed from the Ports Collection.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-hosts">
- <title xml:lang="en">Hosts, Domains, IP Addresses, User Names, Group Names,
- and Other System Items</title>
-
- <note>
- <title xml:lang="en">FreeBSD Extension</title>
-
- <para xml:lang="en">These elements are part of the FreeBSD extension to
- DocBook, and do not exist in the original DocBook
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para xml:lang="en">Information for <quote>system items</quote> is marked up
- with <tag>systemitem</tag>. The <literal>class</literal>
- attribute is used to identify the particular type of
- information shown.</para>
-
- <variablelist>
- <varlistentry>
- <term xml:lang="en"><literal>class="domainname"</literal></term>
-
- <listitem>
- <para xml:lang="en">The text is a domain name, such as
- <literal>FreeBSD.org</literal> or
- <literal>ngo.org.uk</literal>. There is no hostname
- component.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>class="etheraddress"</literal></term>
-
- <listitem>
- <para xml:lang="en">The text is an Ethernet <acronym>MAC</acronym>
- address, expressed as a series of 2 digit hexadecimal
- numbers separated by colons.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>class="fqdomainname"</literal></term>
-
- <listitem>
- <para xml:lang="en">The text is a Fully Qualified Domain Name, with
- both hostname and domain name parts.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>class="ipaddress"</literal></term>
-
- <listitem>
- <para xml:lang="en">The text is an <acronym>IP</acronym> address,
- probably expressed as a dotted quad.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>class="netmask"</literal></term>
-
- <listitem>
- <para xml:lang="en">The text is a network mask, which might be
- expressed as a dotted quad, a hexadecimal string, or as
- a <literal>/</literal> followed by a number
- (<acronym>CIDR</acronym> notation).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>class="systemname"</literal></term>
-
- <listitem>
- <para xml:lang="en">With <literal>class="systemname"</literal>
- the marked up information is the simple hostname, such
- as <literal>freefall</literal> or
- <literal>wcarchive</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>class="username"</literal></term>
-
- <listitem>
- <para xml:lang="en">The text is a username, like
- <literal>root</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><literal>class="groupname"</literal></term>
-
- <listitem>
- <para xml:lang="en">The text is a groupname, like
- <literal>wheel</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title xml:lang="en"><tag>systemitem</tag> and Classes Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>The local machine can always be referred to by the
- name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP
- address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag>
- domain contains a number of different hosts, including
- <tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and
- <tag class="starttag">systemitem class="fqdomainname"</tag>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an
- interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>)
- <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of
- <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can
- also be expressed as
- <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies
- every network card in existence. A typical
- <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like
- <tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>To carry out most system administration functions
- requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">The local machine can always be referred to by the name
- <systemitem>localhost</systemitem>, which will have the IP
- address
- <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>
-
- <para xml:lang="en">The
- <systemitem class="fqdomainname">FreeBSD.org</systemitem>
- domain contains a number of different hosts, including
- <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
- <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>
-
- <para xml:lang="en">When adding an <acronym>IP</acronym> alias to an
- interface (using <command>ifconfig</command>)
- <emphasis>always</emphasis> use a netmask of
- <systemitem class="netmask">255.255.255.255</systemitem>
- (which can also be expressed as
- <systemitem class="netmask">0xffffffff</systemitem>).</para>
-
- <para xml:lang="en">The <acronym>MAC</acronym> address uniquely identifies
- every network card in existence. A typical
- <acronym>MAC</acronym> address looks like <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>
-
- <para xml:lang="en">To carry out most system administration functions
- requires logging in as
- <systemitem class="username">root</systemitem>.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-uri">
- <title xml:lang="en">Uniform Resource Identifiers
- (<acronym>URI</acronym>s)</title>
-
- <para xml:lang="en">Occasionally it is useful to show a
- Uniform Resource Identifier (<acronym>URI</acronym>) without
- making it an active hyperlink. The <tag>uri</tag> element
- makes this possible:</para>
-
- <example>
- <title xml:lang="en"><tag>uri</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text:
- <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not
- create a link.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">This <acronym>URL</acronym> shows only as text:
- <uri>https://www.FreeBSD.org</uri>. It does not
- create a link.</para>
- </example>
-
- <para xml:lang="en">To create links, see
- <xref linkend="docbook-markup-links"/>.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-email-addresses">
- <title>E-mail-adressen</title>
-
- <para xml:lang="en">Email addresses are marked up as <tag>email</tag>
- elements. In the <acronym>HTML</acronym> output format, the
- wrapped text becomes a hyperlink to the email address. Other
- output formats that support hyperlinks may also make the email
- address into a link.</para>
-
- <example>
- <title xml:lang="en"><tag>email</tag> with a Hyperlink Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>An email address that does not actually exist, like
- <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an
- example.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">An email address that does not actually exist, like
- <email>notreal@example.com</email>, can be used as an
- example.</para>
- </example>
-
- <para xml:lang="en">A FreeBSD-specific extension allows setting the
- <literal>role</literal> attribute to <literal>nolink</literal>
- to prevent the creation of the hyperlink to the email
- address.</para>
-
- <example>
- <title xml:lang="en"><tag>email</tag> Without a Hyperlink Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Sometimes a link to an email address like
- <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not
- desired.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Sometimes a link to an email address like
- <email role="nolink">notreal@example.com</email> is not
- desired.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-describing-makefiles">
- <title xml:lang="en">Describing <filename>Makefile</filename>s</title>
-
- <note>
- <title xml:lang="en">FreeBSD Extension</title>
-
- <para xml:lang="en">These elements are part of the FreeBSD extension to
- DocBook, and do not exist in the original DocBook
- <acronym>DTD</acronym>.</para>
- </note>
-
- <para xml:lang="en">Two elements exist to describe parts of
- <filename>Makefile</filename>s, <tag>buildtarget</tag>
- and <tag>varname</tag>.</para>
-
- <para xml:lang="en"><tag>buildtarget</tag> identifies a build target
- exported by a <filename>Makefile</filename> that can be
- given as a parameter to <command>make</command>.
- <tag>varname</tag> identifies a variable that can be
- set (in the environment, on the command line with
- <command>make</command>, or within the
- <filename>Makefile</filename>) to influence the
- process.</para>
-
- <example>
- <title xml:lang="en"><tag>buildtarget</tag> and
- <tag>varname</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag>
- are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and
- <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will
- rebuild the application, and invoking
- <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary
- files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the
- build process.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a
- number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag>
- and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Two common targets in a <filename>Makefile</filename>
- are <buildtarget xml:lang="en">all</buildtarget> and
- <buildtarget xml:lang="en">clean</buildtarget>.</para>
-
- <para xml:lang="en">Typically, invoking <buildtarget xml:lang="en">all</buildtarget> will
- rebuild the application, and invoking
- <buildtarget xml:lang="en">clean</buildtarget> will remove the temporary
- files (<filename>.o</filename> for example) created by the
- build process.</para>
-
- <para xml:lang="en"><buildtarget xml:lang="en">clean</buildtarget> may be controlled by a
- number of variables, including <varname>CLOBBER</varname>
- and <varname>RECURSE</varname>.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-literal-text">
- <title xml:lang="en">Literal Text</title>
-
- <para xml:lang="en">Literal text, or text which should be entered verbatim, is
- often needed in documentation. This is text that is excerpted
- from another file, or which should be copied exactly as shown
- from the documentation into another file.</para>
-
- <para xml:lang="en">Some of the time, <tag>programlisting</tag> will
- be sufficient to denote this text. But
- <tag>programlisting</tag> is not always appropriate,
- particularly when you want to include a portion of a file
- <quote>in-line</quote> with the rest of the
- paragraph.</para>
-
- <para xml:lang="en">On these occasions, use
- <tag>literal</tag>.</para>
-
- <example>
- <title xml:lang="en"><tag>literal</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel
- configuration file determines the size of many system tables, and is
- a rough guide to how many simultaneous logins the system will
- support.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">The <literal>maxusers 10</literal> line in the kernel
- configuration file determines the size of many system
- tables, and is a rough guide to how many simultaneous
- logins the system will support.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-replaceable">
- <title xml:lang="en">Showing Items That the User <emphasis>Must</emphasis>
- Fill In</title>
-
- <para xml:lang="en">There will often be times when the user is shown
- what to do, or referred to a file or command line, but
- cannot simply copy the example provided. Instead, they
- must supply some information themselves.</para>
-
- <para xml:lang="en"><tag>replaceable</tag> is designed for this
- eventuality. Use it <emphasis>inside</emphasis> other
- elements to indicate parts of that element's content that
- the user must replace.</para>
-
- <example>
- <title xml:lang="en"><tag>replaceable</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <informalexample>
- <screen xml:lang="en"><prompt>%</prompt> <userinput>man <replaceable>command</replaceable></userinput></screen>
- </informalexample>
-
- <para xml:lang="en"><tag>replaceable</tag> can be used in many
- different elements, including <tag>literal</tag>.
- This example also shows that <tag>replaceable</tag>
- should only be wrapped around the content that the user
- <emphasis>is</emphasis> meant to provide. The other content
- should be left alone.</para>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag>
- line in the kernel configuration file determines the size of many system
- tables, and is a rough guide to how many simultaneous logins the system will
- support.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value
- for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">The
- <literal>maxusers <replaceable>n</replaceable></literal>
- line in the kernel configuration file determines the size
- of many system tables, and is a rough guide to how many
- simultaneous logins the system will support.</para>
-
- <para xml:lang="en">For a desktop workstation, <literal>32</literal> is a
- good value for <replaceable>n</replaceable>.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-gui-buttons">
- <title xml:lang="en">Showing <acronym>GUI</acronym> Buttons</title>
-
- <para xml:lang="en">Buttons presented by a graphical user interface are marked
- with <tag>guibutton</tag>. To make the text look more
- like a graphical button, brackets and non-breaking spaces are
- added surrounding the text.</para>
-
- <example>
- <title xml:lang="en"><tag>guibutton</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Edit the file, then click
- <tag class="starttag">guibutton</tag>[&amp;nbsp;Save&amp;nbsp;]<tag class="endtag">guibutton</tag> to save the
- changes.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Edit the file, then click
- <guibutton>[ Save ]</guibutton> to save the
- changes.</para>
- </example>
- </sect2>
-
- <sect2 xml:id="docbook-markup-system-errors">
- <title>Systeemfouten aanhalen</title>
-
- <para xml:lang="en">System errors generated by FreeBSD are marked with
- <tag>errorname</tag>. This indicates the exact error
- that appears.</para>
-
- <example>
- <title xml:lang="en"><tag>errorname</tag> Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <informalexample>
- <screen xml:lang="en"><errorname>Panic: cannot mount root</errorname></screen>
- </informalexample>
- </example>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-images">
- <title xml:lang="en">Images</title>
-
- <important>
- <para xml:lang="en">Image support in the documentation is somewhat
- experimental. The mechanisms described here are unlikely to
- change, but that is not guaranteed.</para>
-
- <para xml:lang="en">To provide conversion between different image formats, the
- <package>graphics/ImageMagick</package>
- port must be installed. This port is not included in the
- <package>textproc/docproj</package> meta
- port, and must be installed separately.</para>
-
- <para xml:lang="en">A good example of the use of images is the
- <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
- document. Examine the files in that directory to see how
- these elements are used together. Build different output
- formats to see how the format determines what images are shown
- in the rendered document.</para>
- </important>
-
- <sect2 xml:id="docbook-markup-image-formats">
- <title xml:lang="en">Image Formats</title>
-
- <para xml:lang="en">The following image formats are currently supported. An
- image file will automatically be converted to bitmap or vector
- image depending on the output document format.</para>
-
- <para xml:lang="en">These are the <emphasis>only</emphasis> formats in which
- images should be committed to the documentation
- repository.</para>
-
- <variablelist>
- <varlistentry>
- <term xml:lang="en"><acronym>EPS</acronym> (Encapsulated
- Postscript)</term>
-
- <listitem>
- <para xml:lang="en">Images that are primarily vector based, such as
- network diagrams, time lines, and similar, should be in
- this format. These images have a
- <filename>.eps</filename> extension.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><acronym>PNG</acronym> (Portable Network
- Graphic)</term>
-
- <listitem>
- <para xml:lang="en">For bitmaps, such as screen captures, use this
- format. These images have the <filename>.png</filename>
- extension.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><acronym>PIC</acronym> (PIC graphics language)</term>
-
- <listitem>
- <para xml:lang="en"><acronym>PIC</acronym> is a language for drawing
- simple vector-based figures used in the <citerefentry><refentrytitle>pic</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- utility. These images have the
- <filename>.pic</filename> extension.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:lang="en"><acronym>SCR</acronym> (SCReen capture)</term>
-
- <listitem>
- <para xml:lang="en">This format is specific to screenshots of console
- output. The following command generates an SCR file
- <filename>shot.scr</filename> from video buffer of
- <filename>/dev/ttyv0</filename>:</para>
-
- <screen xml:lang="en"><prompt>#</prompt> <userinput><command>vidcontrol -p</command> &lt; <filename><replaceable>/dev/ttyv0</replaceable></filename> &gt; <filename><replaceable>shot.scr</replaceable></filename></userinput></screen>
-
- <para xml:lang="en">This is preferable to <acronym>PNG</acronym> format
- for screenshots because the <acronym>SCR</acronym> file
- contains plain text of the command lines so that it can
- be converted to a <acronym>PNG</acronym> image or a
- plain text depending on the output document
- format.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para xml:lang="en">Use the appropriate format for each image. Documentation
- will often have a mix of <acronym>EPS</acronym> and
- <acronym>PNG</acronym> images. The
- <filename>Makefile</filename>s ensure that the correct format
- image is chosen depending on the output format used.
- <emphasis>Do not commit the same image to the repository in
- two different formats</emphasis>.</para>
-
- <important>
- <para xml:lang="en">The Documentation Project may eventually switch to using
- the <acronym>SVG</acronym> (Scalable Vector Graphic) format
- for vector images. However, the current state of
- <acronym>SVG</acronym> capable editing tools makes this
- impractical.</para>
- </important>
- </sect2>
-
- <sect2 xml:id="docbook-markup-image-file-locations">
- <title xml:lang="en">Image File Locations</title>
-
- <para xml:lang="en">Image files can be stored in one of several locations,
- depending on the document and image:</para>
-
- <itemizedlist>
- <listitem>
- <para xml:lang="en">In the same directory as the document itself, usually
- done for articles and small books that keep all their
- files in a single directory.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">In a subdirectory of the main document. Typically
- done when a large book uses separate subdirectories to
- organize individual chapters.</para>
-
- <para xml:lang="en">When images are stored in a subdirectory of the
- main document directory, the subdirectory name must be
- included in their paths in the
- <filename>Makefile</filename> and the
- <tag>imagedata</tag> element.</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">In a subdirectory of
- <filename>doc/share/images</filename> named after the
- document. For example, images for the Handbook are stored
- in <filename>doc/share/images/books/handbook</filename>.
- Images that work for multiple translations are stored in
- this upper level of the documentation file tree.
- Generally, these are images that can be used unchanged in
- non-English translations of the document.</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 xml:id="docbook-markup-image-markup">
- <title xml:lang="en">Image Markup</title>
-
- <para xml:lang="en">Images are included as part of a <tag>mediaobject</tag>.
- The <tag>mediaobject</tag> can contain other, more specific
- objects. We are concerned with two, the
- <tag>imageobject</tag> and the <tag>textobject</tag>.</para>
-
- <para xml:lang="en">Include one <tag>imageobject</tag>, and two
- <tag>textobject</tag> elements. The <tag>imageobject</tag>
- will point to the name of the image file without the
- extension. The <tag>textobject</tag> elements contain
- information that will be presented to the user as well as, or
- instead of, the image itself.</para>
-
- <para xml:lang="en">Text elements are shown to the reader in several
- situations. When the document is viewed in
- <acronym>HTML</acronym>, text elements are shown while the
- image is loading, or if the mouse pointer is hovered over the
- image, or if a text-only browser is being used. In formats
- like plain text where graphics are not possible, the text
- elements are shown instead of the graphical ones.</para>
-
- <para xml:lang="en">This example shows how to include an image called
- <filename>fig1.png</filename> in a document. The image is a
- rectangle with an A inside it:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">mediaobject</tag>
- <tag class="starttag">imageobject</tag>
- <tag class="starttag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/>
- <tag class="endtag">imageobject</tag>
-
- <tag class="starttag">textobject</tag>
- <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/>
-| A |
-+---------------+<tag class="endtag">literallayout</tag>
- <tag class="endtag">textobject</tag>
-
- <tag class="starttag">textobject</tag>
- <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/>
- <tag class="endtag">textobject</tag>
-<tag class="endtag">mediaobject</tag></programlisting>
-
- <calloutlist>
- <callout arearefs="co-image-ext">
- <para xml:lang="en">Include an <tag>imagedata</tag> element
- inside the <tag>imageobject</tag> element. The
- <literal>fileref</literal> attribute should contain the
- filename of the image to include, without the extension.
- The stylesheets will work out which extension should be
- added to the filename automatically.</para>
- </callout>
-
- <callout arearefs="co-image-literal">
-
- <para xml:lang="en">The first <tag>textobject</tag> contains a
- <tag>literallayout</tag> element, where the
- <literal>class</literal> attribute is set to
- <literal>monospaced</literal>. This is an opportunity to
- demonstrate <acronym>ASCII</acronym> art skills. This
- content will be used if the document is converted to plain
- text.</para>
-
- <para xml:lang="en">Notice how the first and last lines of the content
- of the <tag>literallayout</tag> element butt up
- next to the element's tags. This ensures no extraneous
- white space is included.</para>
- </callout>
-
- <callout arearefs="co-image-phrase">
- <para xml:lang="en">The second <tag>textobject</tag> contains a
- single <tag>phrase</tag> element. The contents of
- this phrase will become the <literal>alt</literal>
- attribute for the image when this document is converted to
- <acronym>HTML</acronym>.</para>
- </callout>
- </calloutlist>
- </sect2>
-
- <sect2 xml:id="docbook-markup-image-makefile-entries">
- <title xml:lang="en">Image <filename>Makefile</filename> Entries</title>
-
- <para xml:lang="en">Images must be listed in the <filename>Makefile</filename>
- in the <varname>IMAGES</varname> variable. This variable must
- contain the names of all the <emphasis>source</emphasis>
- images. For example, if there are three figures,
- <filename>fig1.eps</filename>, <filename>fig2.png</filename>,
- <filename>fig3.png</filename>, then the
- <filename>Makefile</filename> should have lines like this in
- it.</para>
-
- <programlisting xml:lang="en">…
-IMAGES= fig1.eps fig2.png fig3.png
-…</programlisting>
-
- <para xml:lang="en">or</para>
-
- <programlisting xml:lang="en">…
-IMAGES= fig1.eps
-IMAGES+= fig2.png
-IMAGES+= fig3.png
-…</programlisting>
-
- <para xml:lang="en">Again, the <filename>Makefile</filename> will work out the
- complete list of images it needs to build the source document,
- you only need to list the image files <emphasis>you</emphasis>
- provided.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-images-in-subdirectories">
- <title xml:lang="en">Images and Chapters in Subdirectories</title>
-
- <para xml:lang="en">Be careful when separating documentation into smaller
- files in different directories (see <xref linkend="xml-primer-include-using-gen-entities"/>).</para>
-
- <para xml:lang="en">Suppose there is a book with three chapters, and the
- chapters are stored in their own directories, called
- <filename>chapter1/chapter.xml</filename>,
- <filename>chapter2/chapter.xml</filename>, and
- <filename>chapter3/chapter.xml</filename>. If each chapter
- has images associated with it, place those images in each
- chapter's subdirectory (<filename>chapter1/</filename>,
- <filename>chapter2/</filename>, and
- <filename>chapter3/</filename>).</para>
-
- <para xml:lang="en">However, doing this requires including the directory
- names in the <varname>IMAGES</varname> variable in the
- <filename>Makefile</filename>, <emphasis>and</emphasis>
- including the directory name in the <tag>imagedata</tag>
- element in the document.</para>
-
- <para xml:lang="en">For example, if the book has
- <filename>chapter1/fig1.png</filename>, then
- <filename>chapter1/chapter.xml</filename> should
- contain:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">mediaobject</tag>
- <tag class="starttag">imageobject</tag>
- <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/>
- <tag class="endtag">imageobject</tag>
-
- …
-
-<tag class="endtag">mediaobject</tag></programlisting>
-
- <calloutlist>
- <callout arearefs="co-image-dir">
- <para xml:lang="en">The directory name must be included in the
- <literal>fileref</literal> attribute.</para>
- </callout>
- </calloutlist>
-
- <para xml:lang="en">The <filename>Makefile</filename> must contain:</para>
-
- <programlisting xml:lang="en">…
-IMAGES= chapter1/fig1.png
-…</programlisting>
- </sect2>
- </sect1>
-
- <sect1 xml:id="docbook-markup-links">
- <title xml:lang="en">Links</title>
-
- <note>
- <para xml:lang="en">Links are also in-line elements. To show a
- <acronym>URI</acronym> without creating a link, see
- <xref linkend="docbook-markup-uri"/>.</para>
- </note>
-
- <sect2 xml:id="docbook-markup-links-ids">
- <title xml:lang="en"><literal>xml:id</literal> Attributes</title>
-
- <para xml:lang="en">Most DocBook elements accept an <literal>xml:id</literal>
- attribute to give that part of the document a unique name.
- The <literal>xml:id</literal> can be used as a target for a
- crossreference or link.</para>
-
- <para xml:lang="en">Any portion of the document that will be a link target
- must have an <literal>xml:id</literal> attribute. Assigning
- an <literal>xml:id</literal> to all chapters and sections,
- even if there are no current plans to link to them, is a good
- idea. These <literal>xml:id</literal>s can be used as unique
- reference points by anyone referring to the
- <acronym>HTML</acronym> version of the document.</para>
-
- <example>
- <title xml:lang="en"><literal>xml:id</literal> on Chapters and
- Sections Example</title>
-
- <programlisting xml:lang="en"><tag class="starttag">chapter xml:id="introduction"</tag>
- <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is the introduction. It contains a subsection,
- which is identified as well.<tag class="endtag">para</tag>
-
- <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag>
- <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">chapter</tag></programlisting>
- </example>
-
- <para xml:lang="en">Use descriptive values for <literal>xml:id</literal>
- names. The values must be unique within the entire document,
- not just in a single file. In the example, the subsection
- <literal>xml:id</literal> is constructed by appending text to
- the chapter <literal>xml:id</literal>. This ensures that the
- <literal>xml:id</literal>s are unique. It also helps both
- reader and anyone editing the document to see where the link
- is located within the document, similar to a directory path to
- a file.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-links-crossreferences">
- <title xml:lang="en">Crossreferences with <literal>xref</literal></title>
-
- <para xml:lang="en"><tag>xref</tag> provides the reader with a link to jump to
- another section of the document. The target
- <literal>xml:id</literal> is specified in the
- <literal>linkend</literal> attribute, and <tag>xref</tag>
- generates the link text automatically.</para>
-
- <example>
- <title xml:lang="en"><tag>xref</tag> Example</title>
-
- <para xml:lang="en">Assume that this fragment appears somewhere in a
- document that includes the <literal>xml:id</literal>
- example shown above:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>More information can be found
- in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>More specific information can be found
- in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">The link text will be generated automatically, looking
- like (<emphasis>emphasized</emphasis> text indicates the
- link text):</para>
-
- <blockquote>
- <para xml:lang="en">More information can be found in <emphasis>Chapter
- 1, Introduction</emphasis>.</para>
-
- <para xml:lang="en">More specific information can be found in
- <emphasis>Section 1.1,
- <quote>More Details</quote></emphasis>.</para>
- </blockquote>
- </example>
-
- <para xml:lang="en">The link text is generated automatically from the chapter
- and section number and <literal>title</literal>
- elements.</para>
- </sect2>
-
- <sect2 xml:id="docbook-markup-links-to-web-documents">
- <title xml:lang="en">Linking to Other Documents on the
- Web</title>
-
- <para xml:lang="en">The link element described here allows the writer to
- define the link text. When link text is used, it is very important to be descriptive
- to give the reader an idea of where the link goes.
- Remember that DocBook can be rendered to multiple
- types of media. The reader might be looking at a printed book
- or other form of media where there are no links. If the link
- text is not descriptive enough, the reader might not be able to
- locate the linked section.</para>
-
- <para xml:lang="en">The <literal>xlink:href</literal> attribute
- is the <acronym>URL</acronym> of the page,
- and the content of the element is the text that
- will be displayed for the user to activate.</para>
-
- <para xml:lang="en">In many situations, it is preferable to show the actual
- <acronym>URL</acronym> rather than text. This can be done by
- leaving out the element text entirely.</para>
-
- <example>
- <title xml:lang="en"><tag>link</tag> to a FreeBSD Documentation Web
- Page Example</title>
-
- <para xml:lang="en">Link to the book or article <acronym>URL</acronym>
- entity. To link to a specific chapter in a book, add a
- slash and the chapter file name, followed by an optional
- anchor within the chapter. For articles, link to the
- article <acronym>URL</acronym> entity, followed by an
- optional anchor within the article.
- <acronym>URL</acronym> entities can be found in
- <filename>doc/share/xml/urls.ent</filename>.</para>
-
- <para xml:lang="en">Usage for FreeBSD book links:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Read the <tag class="starttag">link
- xlink:href="&amp;url.books.handbook;/svn.html#svn-intro"</tag>SVN
- introduction<tag class="endtag">link</tag>, then pick the nearest mirror from
- the list of <tag class="starttag">link
- xlink:href="&amp;url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion
- mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Read the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-intro">SVN
- introduction</link>, then pick the nearest mirror from
- the list of <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion
- mirror sites</link>.</para>
-
- <para xml:lang="en">Usage for FreeBSD article links:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Read this
- <tag class="starttag">link xlink:href="&amp;url.articles.bsdl-gpl;"</tag>article
- about the BSD license<tag class="endtag">link</tag>, or just the
- <tag class="starttag">link xlink:href="&amp;url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Read this
- <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl">article
- about the BSD license</link>, or just the <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl#intro">introduction</link>.</para>
- </example>
-
- <example>
- <title xml:lang="en"><tag>link</tag> to a FreeBSD Web Page Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the
- <tag class="starttag">link xlink:href="&amp;url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Of course, you could stop reading this document and go
- to the <link xlink:href="@@URL_RELPREFIX@@/index.html">FreeBSD
- home page</link> instead.</para>
- </example>
-
- <example>
- <title xml:lang="en"><tag>link</tag> to an External Web
- Page Example</title>
-
- <para xml:lang="en">Usage:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
- <tag class="starttag">link
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID
- Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">Appearance:</para>
-
- <para xml:lang="en">Wikipedia has an excellent reference on <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
- Partition Tables</link>.</para>
-
- <para xml:lang="en">The link text can be omitted to show the actual
- URL:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
- GUID Partition Tables: <tag class="starttag">link
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">The same link can be entered using shorter
- notation instead of a separate ending tag:</para>
-
- <programlisting xml:lang="en"><tag class="starttag">para</tag>Wikipedia has an excellent reference on
- GUID Partition Tables: <tag class="emptytag">link
- xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting>
-
- <para xml:lang="en">The two methods are equivalent. Appearance:</para>
-
- <para xml:lang="en">Wikipedia has an excellent reference on GUID Partition
- Tables: <uri xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para>
- </example>
- </sect2>
- </sect1>
-</chapter>
-
-
-<!-- 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 version="5.0" xml:id="stylesheets">
- <title xml:lang="en">Style Sheets</title>
-
- <para xml:lang="en"><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 xml:lang="en">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 xml:lang="en"><acronym>CSS</acronym></title>
-
- <para xml:lang="en">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 xml:lang="en">The DocBook Documents</title>
-
- <para xml:lang="en">The FreeBSD <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>
-
-
-<!-- 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 version="5.0" xml:id="translations">
- <title xml:lang="en">Translations</title>
-
- <para xml:lang="en">This is the FAQ for people translating the FreeBSD
- documentation (FAQ, Handbook, tutorials, manual pages, and others)
- to different languages.</para>
-
- <para xml:lang="en">It is <emphasis>very</emphasis> heavily based on the
- translation FAQ from the FreeBSD German Documentation Project,
- originally written by Frank Gr√ľnder
- <email>elwood@mc5sys.in-berlin.de</email> and translated back to
- English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
-
- <para xml:lang="en">The FAQ is maintained by the Documentation Engineering Team <email>doceng@FreeBSD.org</email>.</para>
-
- <qandaset>
- <qandaentry>
- <question>
- <para xml:lang="en">What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
- mean?</para>
- </question>
-
- <answer>
- <para xml:lang="en"><phrase>i18n</phrase> means
- <phrase>internationalization</phrase> and
- <phrase>l10n</phrase> means <phrase>localization</phrase>.
- They are just a convenient shorthand.</para>
-
- <para xml:lang="en"><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 xml:lang="en">Is there a mailing list for translators?</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en">Are more translators needed?</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en">You do not have to be a professional translator to be
- able to help.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para xml:lang="en">What languages do I need to know?</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">What software do I need to know?</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen>
-
- <para xml:lang="en"><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_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Subversion
- mirror sites</link>.</para>
-
- <note>
- <para xml:lang="en">This will require the <package>devel/subversion</package> package to
- be installed.</para>
- </note>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <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 xml:lang="en">How do I find out who else might be translating to the
- same language?</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en">If no one is listed on that page as translating for your
- language, then send a message to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link> in case someone
- else is thinking of doing a translation, but has not
- announced it yet.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para xml:lang="en">No one else is translating to my language. What do I
- do?</para>
- </question>
-
- <answer>
- <para xml:lang="en">Congratulations, you have just started the
- <quote>FreeBSD <replaceable>your-language-here</replaceable>
- Documentation Translation Project</quote>. Welcome
- aboard.</para>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">Then pick a document and start translating. It is best
- to start with something fairly small‚ÄĒeither the FAQ,
- or one of the tutorials.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para xml:lang="en">I have translated some documentation, where do I send
- it?</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">I am the only person working on translating to this
- language, how do I submit my translation?</para>
-
- <para xml:lang="en">or</para>
-
- <para xml:lang="en">We are a translation team, and want to submit
- documentation that our members have translated for
- us.</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">Finally, you should have directories for each
- document.</para>
-
- <para xml:lang="en">For example, a hypothetical Swedish translation might
- look like:</para>
-
- <programlisting xml:lang="en">head/
- sv_SE.ISO8859-1/
- Makefile
- htdocs/
- docproj/
- books/
- faq/
- Makefile
- book.xml</programlisting>
-
- <para xml:lang="en"><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 xml:lang="en">Use <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> to compress up your
- documentation, and send it to the project.</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd doc</userinput>
-<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
-<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput></screen>
-
- <para xml:lang="en">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
- Documentation Engineering Team <email>doceng@FreeBSD.org</email>, and arrange to email the files when it is
- convenient.</para>
-
- <para xml:lang="en">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 xml:lang="en">Someone (probably the Documentation Project Manager,
- currently Documentation Engineering Team <email>doceng@FreeBSD.org</email>) will then take your translation and
- confirm that it builds. In particular, the following things
- will be looked at:</para>
-
- <orderedlist>
- <listitem>
- <para xml:lang="en">Do all your files use RCS strings (such as
- "ID")?</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Does <command>make all</command> in the
- <filename>sv_SE.ISO8859-1</filename> directory work
- correctly?</para>
- </listitem>
-
- <listitem>
- <para xml:lang="en">Does <command>make install</command> work
- correctly?</para>
- </listitem>
- </orderedlist>
-
- <para xml:lang="en">If there are any problems then whoever is looking at the
- submission will get back to you to work them out.</para>
-
- <para xml:lang="en">If there are no problems your translation will be
- committed as soon as possible.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para xml:lang="en">Can I include language or country specific text in my
- translation?</para>
- </question>
-
- <answer>
- <para xml:lang="en">We would prefer that you did not.</para>
-
- <para xml:lang="en">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 xml:lang="en">There is no real reason why that information should not
- be in the English (or German, or Spanish, or Japanese, or
- …) 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 xml:lang="en">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 xml:lang="en">Thanks.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para xml:lang="en">How should language specific characters be
- included?</para>
- </question>
-
- <answer>
- <para xml:lang="en">Non-ASCII characters in the documentation should be
- included using SGML entities.</para>
-
- <para xml:lang="en">Briefly, these look like an ampersand (&amp;), the name
- of the entity, and a semi-colon (;).</para>
-
- <para xml:lang="en">The entity names are defined in ISO8879, which is in the
- ports tree as <package>textproc/iso8879</package>.</para>
-
- <para xml:lang="en">A few examples include:</para>
-
- <segmentedlist>
- <segtitle xml:lang="en">Entity</segtitle>
-
- <segtitle xml:lang="en">Appearance</segtitle>
-
- <segtitle>Beschrijving</segtitle>
-
- <seglistitem>
- <seg xml:lang="en">&amp;eacute;</seg>
- <seg xml:lang="en">é</seg>
- <seg xml:lang="en">Small <quote>e</quote> with an acute accent</seg>
- </seglistitem>
-
- <seglistitem>
- <seg xml:lang="en">&amp;Eacute;</seg>
- <seg xml:lang="en">√Č</seg>
- <seg xml:lang="en">Large <quote>E</quote> with an acute accent</seg>
- </seglistitem>
-
- <seglistitem>
- <seg xml:lang="en">&amp;uuml;</seg>
- <seg xml:lang="en">√ľ</seg>
- <seg xml:lang="en">Small <quote>u</quote> with an umlaut</seg>
- </seglistitem>
- </segmentedlist>
-
- <para xml:lang="en">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 xml:lang="en">Addressing the reader</para>
- </question>
-
- <answer>
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">Do I need to include any additional information in my
- translations?</para>
- </question>
-
- <answer>
- <para xml:lang="en">Yes.</para>
-
- <para xml:lang="en">The header of the English version of each document will
- look something like this:</para>
-
- <programlisting xml:lang="en">&lt;!--
- The FreeBSD Documentation Project
-
- $FreeBSD$
---&gt;</programlisting>
-
- <para xml:lang="en">The exact boilerplate may change, but it will always
- include a $FreeBSD$ line and the phrase
- <literal>The FreeBSD Documentation Project</literal>.
- Note that the $FreeBSD part is expanded automatically
- by Subversion, so it should be empty (just
- <literal>$FreeBSD$</literal>) for new
- files.</para>
-
- <para xml:lang="en">Your translated documents should include their own
- $FreeBSD$ line, and change the
- <literal>FreeBSD Documentation Project</literal> line to
- <literal>The FreeBSD <replaceable>language</replaceable>
- Documentation Project</literal>.</para>
-
- <para xml:lang="en">In addition, you should add a third line which indicates
- which revision of the English text this is based on.</para>
-
- <para xml:lang="en">So, the Spanish version of this file might start:</para>
-
- <programlisting xml:lang="en">&lt;!--
- The FreeBSD Spanish Documentation Project
-
- $FreeBSD$
- Original revision: r38674
---&gt;</programlisting>
- </answer>
- </qandaentry>
- </qandaset>
-</chapter>
-
-
-<!--
- The FreeBSD Documentation Project
- $FreeBSD$
--->
-<chapter version="5.0" xml:id="po-translations">
-
- <title xml:lang="en"><acronym>PO</acronym> Translations</title>
-
- <sect1 xml:id="po-translations-introduction">
- <title xml:lang="en">Introduction</title>
-
- <para xml:lang="en">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 xml:lang="en">Quick Start</title>
-
- <para xml:lang="en">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 xml:lang="en"><prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput>
-<prompt>#</prompt> <userinput>make config</userinput>
-<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput></screen>
-
- <para xml:lang="en">This example shows the creation of a Spanish translation of
- the short <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds">Leap
- Seconds</link> article.</para>
-
- <procedure xml:id="po-translations-quick-start-install-po-editor">
- <title xml:lang="en">Install a <acronym>PO</acronym> Editor</title>
-
- <step>
- <para xml:lang="en">A <acronym>PO</acronym> editor is needed to edit
- translation files. This example uses
- <package role="ports">editors/poedit</package>.</para>
-
- <screen xml:lang="en"><prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput>
-<prompt>#</prompt> <userinput>make install clean</userinput></screen>
- </step>
- </procedure>
-
- <procedure xml:id="po-translations-quick-start-initial-setup">
- <title xml:lang="en">Initial Setup</title>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">Copy the <filename>Makefile</filename> from the original
- document into the translation directory:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <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 xml:lang="en">Translation</title>
-
- <para xml:lang="en">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 xml:lang="en">Extract the translatable strings from the original
- English version into a <acronym>PO</acronym> file:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
-<prompt>%</prompt> <userinput>make po</userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen>
- </step>
- </procedure>
-
- <procedure xml:id="po-translations-quick-generating-a-translated-document">
- <title xml:lang="en">Generating a Translated Document</title>
-
- <step>
- <para xml:lang="en">Generate the translated document:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
-<prompt>%</prompt> <userinput>make tran</userinput></screen>
-
- <para xml:lang="en">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 xml:lang="en">Check the generated file by rendering it to
- <acronym>HTML</acronym> and viewing it with a
- web browser:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>make FORMATS=html</userinput>
-<prompt>%</prompt> <userinput>firefox article.html</userinput></screen>
- </step>
- </procedure>
- </sect1>
-
- <sect1 xml:id="po-translations-creating">
- <title xml:lang="en">Creating New Translations</title>
-
- <para xml:lang="en">The first step to creating a new translated document is
- locating or creating a directory to hold it. FreeBSD 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 xml:lang="en">Language Names</title>
-
- <tgroup cols="5">
- <thead>
- <row>
- <entry xml:lang="en">Language</entry>
- <entry xml:lang="en">Region</entry>
- <entry xml:lang="en">Translated Directory Name</entry>
- <entry xml:lang="en"><acronym>PO</acronym> File Name</entry>
- <entry xml:lang="en">Character Set</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry xml:lang="en">English</entry>
- <entry>Verenigde Staten</entry>
- <entry xml:lang="en"><filename>en_US.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>en_US.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Bengali</entry>
- <entry xml:lang="en">Bangladesh</entry>
- <entry xml:lang="en"><filename>bn_BD.UTF-8</filename></entry>
- <entry xml:lang="en"><filename>bn_BD.po</filename></entry>
- <entry xml:lang="en"><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Danish</entry>
- <entry xml:lang="en">Denmark</entry>
- <entry xml:lang="en"><filename>da_DK.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>da_DK.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">German</entry>
- <entry xml:lang="en">Germany</entry>
- <entry xml:lang="en"><filename>de_DE.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>de_DE.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Greek</entry>
- <entry xml:lang="en">Greece</entry>
- <entry xml:lang="en"><filename>el_GR.ISO8859-7</filename></entry>
- <entry xml:lang="en"><filename>el_GR.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-7</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Spanish</entry>
- <entry xml:lang="en">Spain</entry>
- <entry xml:lang="en"><filename>es_ES.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>es_ES.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">French</entry>
- <entry xml:lang="en">France</entry>
- <entry xml:lang="en"><filename>fr_FR.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>fr_FR.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Hungarian</entry>
- <entry xml:lang="en">Hungary</entry>
- <entry xml:lang="en"><filename>hu_HU.ISO8859-2</filename></entry>
- <entry xml:lang="en"><filename>hu_HU.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Italian</entry>
- <entry xml:lang="en">Italy</entry>
- <entry xml:lang="en"><filename>it_IT.ISO8859-15</filename></entry>
- <entry xml:lang="en"><filename>it_IT.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-15</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Japanese</entry>
- <entry xml:lang="en">Japan</entry>
- <entry xml:lang="en"><filename>ja_JP.eucJP</filename></entry>
- <entry xml:lang="en"><filename>ja_JP.po</filename></entry>
- <entry xml:lang="en"><acronym>EUC</acronym> JP</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Korean</entry>
- <entry xml:lang="en">Korea</entry>
- <entry xml:lang="en"><filename>ko_KR.UTF-8</filename></entry>
- <entry xml:lang="en"><filename>ko_KR.po</filename></entry>
- <entry xml:lang="en"><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Mongolian</entry>
- <entry xml:lang="en">Mongolia</entry>
- <entry xml:lang="en"><filename>mn_MN.UTF-8</filename></entry>
- <entry xml:lang="en"><filename>mn_MN.po</filename></entry>
- <entry xml:lang="en"><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Dutch</entry>
- <entry xml:lang="en">Netherlands</entry>
- <entry xml:lang="en"><filename>nl_NL.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>nl_NL.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Norwegian</entry>
- <entry xml:lang="en">Norway</entry>
- <entry xml:lang="en"><filename>no_NO.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>no_NO.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Polish</entry>
- <entry xml:lang="en">Poland</entry>
- <entry xml:lang="en"><filename>pl_PL.ISO8859-2</filename></entry>
- <entry xml:lang="en"><filename>pl_PL.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Portuguese</entry>
- <entry xml:lang="en">Brazil</entry>
- <entry xml:lang="en"><filename>pt_BR.ISO8859-1</filename></entry>
- <entry xml:lang="en"><filename>pt_BR.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Russian</entry>
- <entry xml:lang="en">Russia</entry>
- <entry xml:lang="en"><filename>ru_RU.KOI8-R</filename></entry>
- <entry xml:lang="en"><filename>ru_RU.po</filename></entry>
- <entry xml:lang="en"><acronym>KOI</acronym>8-R</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Serbian</entry>
- <entry xml:lang="en">Serbia</entry>
- <entry xml:lang="en"><filename>sr_YU.ISO8859-2</filename></entry>
- <entry xml:lang="en"><filename>sr_YU.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Turkish</entry>
- <entry xml:lang="en">Turkey</entry>
- <entry xml:lang="en"><filename>tr_TR.ISO8859-9</filename></entry>
- <entry xml:lang="en"><filename>tr_TR.po</filename></entry>
- <entry xml:lang="en"><acronym>ISO</acronym> 8859-9</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Chinese</entry>
- <entry xml:lang="en">China</entry>
- <entry xml:lang="en"><filename>zh_CN.UTF-8</filename></entry>
- <entry xml:lang="en"><filename>zh_CN.po</filename></entry>
- <entry xml:lang="en"><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry xml:lang="en">Chinese</entry>
- <entry xml:lang="en">Taiwan</entry>
- <entry xml:lang="en"><filename>zh_TW.UTF-8</filename></entry>
- <entry xml:lang="en"><filename>zh_TW.po</filename></entry>
- <entry xml:lang="en"><acronym>UTF</acronym>-8</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para xml:lang="en">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 xml:lang="en">Each language directory contains separate subdirectories
- named for the type of documents, usually
- <filename>articles/</filename> and
- <filename>books/</filename>.</para>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">FreeBSD 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 xml:lang="en">Creating a Spanish Translation of the Porter's
- Handbook</title>
-
- <para xml:lang="en">Create a new Spanish translation of the
- <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook">Porter's
- Handbook</link>. The original is a book in
- <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename>.</para>
-
- <procedure>
- <step>
- <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>
-<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput>
-A porters-handbook</screen>
- </step>
-
- <step>
- <para xml:lang="en">Copy the <filename>Makefile</filename> from the
- original book:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>
-A Makefile</screen>
-
- <para xml:lang="en">Modify the contents of the
- <filename>Makefile</filename> to only expect a single
- <filename>book.xml</filename>:</para>
-
- <programlisting xml:lang="en">#
-# $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 xml:lang="en">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 xml:lang="en">Creating a French Translation of the
- <acronym>PGP</acronym> Keys Article</title>
-
- <para xml:lang="en">Create a new French translation of the
- <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/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 xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>
-<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput>
-A pgpkeys</screen>
- </step>
-
- <step>
- <para xml:lang="en">Copy the <filename>Makefile</filename> from the
- original article:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>
-<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>
-A Makefile</screen>
-
- <para xml:lang="en">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>$FreeBSD...$</literal>
- version string on the third line will be replaced by the
- version control system when this file is committed.</para>
-
- <programlisting xml:lang="en">#
-# $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 xml:lang="en">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 xml:lang="en">Translating</title>
-
- <para xml:lang="en">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 xml:lang="en">The FreeBSD <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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">Translating the Porter's Handbook to Spanish</title>
-
- <para xml:lang="en">Enter Spanish translations of the contents of the Porter's
- Handbook.</para>
-
- <procedure>
- <step>
- <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-<prompt>%</prompt> <userinput>make po</userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">Enter translations using a <acronym>PO</acronym>
- editor:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-tips">
- <title xml:lang="en">Tips for Translators</title>
-
- <sect2 xml:id="po-translations-tips-xmltags">
- <title xml:lang="en">Preserving <acronym>XML</acronym> Tags</title>
-
- <para xml:lang="en">Preserve <acronym>XML</acronym> tags that are shown in
- the English original.</para>
-
- <example>
- <title xml:lang="en">Preserving <acronym>XML</acronym> Tags</title>
-
- <para xml:lang="en">English original:</para>
-
- <programlisting xml:lang="en">If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting>
-
- <para xml:lang="en">Spanish translation:</para>
-
- <programlisting xml:lang="en">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 xml:lang="en">Preserving Spaces</title>
-
- <para xml:lang="en">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 xml:lang="en">Verbatim Tags</title>
-
- <para xml:lang="en">The contents of some tags should be copied verbatim, not
- translated:</para>
-
- <itemizedlist xml:id="po-translations-tips-verbatim-list">
- <listitem>
- <para xml:lang="en"><tag class="starttag">citerefentry</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">command</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">filename</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">literal</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">manvolnum</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">orgname</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">package</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">programlisting</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">prompt</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">refentrytitle</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">screen</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">userinput</tag></para>
- </listitem>
-
- <listitem>
- <para xml:lang="en"><tag class="starttag">varname</tag></para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 xml:id="po-translations-literal-dollar">
- <title xml:lang="en"><literal>$FreeBSD$</literal>
- Strings</title>
-
- <para xml:lang="en">The $FreeBSD$ version strings used in
- files require special handling. In examples like
- <xref linkend="po-translations-creating-example"/>, these
- strings are not meant to be expanded. The English documents
- use <literal>&amp;dollar;</literal> entities to avoid
- including actual literal dollar signs in the file:</para>
-
- <programlisting xml:lang="en">&amp;dollar;FreeBSD&amp;dollar;</programlisting>
-
- <para xml:lang="en">The <literal>&amp;dollar;</literal> entities are not seen
- as dollar signs by the version control system and so the
- string is not expanded into a version string.</para>
-
- <para xml:lang="en">When a <acronym>PO</acronym> file is created, the
- <literal>&amp;dollar;</literal> entities used in examples are
- replaced with actual dollar signs. The resulting literal
- <literal>$FreeBSD$</literal> string will be
- wrongly expanded by the version control system when the file
- is committed.</para>
-
- <para xml:lang="en">The same technique as used in the English documents can be
- used in the translation. The <literal>&amp;dollar;</literal>
- is used to replace the dollar sign in the translation entered
- into the <acronym>PO</acronym> editor:</para>
-
- <programlisting xml:lang="en">&amp;dollar;FreeBSD&amp;dollar;</programlisting>
- </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 xml:lang="en">Building a Translated Document</title>
-
- <para xml:lang="en">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 xml:lang="en">Building the Spanish Porter's Handbook</title>
-
- <para xml:lang="en">Build and preview the Spanish version of the Porter's
- Handbook that was created in an earlier example.</para>
-
- <procedure>
- <step>
- <para xml:lang="en">Build the translated document. Because the original
- is a book, the generated document is
- <filename>book.xml</filename>.</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-<prompt>%</prompt> <userinput>make tran</userinput></screen>
- </step>
-
- <step>
- <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>make FORMATS=html</userinput>
-<prompt>%</prompt> <userinput>firefox book.html</userinput></screen>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-submitting">
- <title xml:lang="en">Submitting the New Translation</title>
-
- <para xml:lang="en">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 xml:lang="en">The <acronym>PO</acronym> file must contain a FreeBSD
- version string comment on the first line:</para>
-
- <programlisting>#$FreeBSD$</programlisting>
- </step>
-
- <step>
- <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>
-<prompt>%</prompt> <userinput>ls</userinput>
-Makefile article.xml es_ES.po
-<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput>
-A Makefile
-A article.xml
-A es_ES.po</screen>
- </step>
-
- <step>
- <para xml:lang="en">These files must also have the
- <application>Subversion</application>
- <literal>svn:keywords</literal> property set to
- <literal>FreeBSD=%H</literal> so
- <literal>$FreeBSD$</literal> strings are expanded into
- the path, revision, date, and author when committed:</para>
-
- <screen xml:lang="en"><prompt>%</prompt> <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 xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc</userinput>
-<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ &gt; /tmp/es_nanobsd.diff</userinput></screen>
-
- <para xml:lang="en">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>
-
-
-<!-- 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 version="5.0" xml:id="writing-style">
- <title xml:lang="en">Writing Style</title>
-
- <sect1 xml:id="writing-style-tips">
- <title xml:lang="en">Tips</title>
-
- <para xml:lang="en">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>Ben duidelijk</title>
-
- <para xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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 xml:lang="en">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>, t