DocBook wurde ursprünglich von HaL Computer Systems und O'Reilly & Associates als DTD für das Erstellen von technischen Dokumenten entwickelt [12]. Seit 1998 wird es vom DocBook Technical Committee gewartet. DocBook ist sehr stark auf die Beschreibung von Inhalten, und nicht auf die Darstellung des Inhalts ausgerichtet. Damit steht es im Gegensatz zu LinuxDoc und XHTML.
Einige Elemente der DocBook DTD sind in zwei Varianten vorhanden: formell und informell. Üblicherweise besitzt die formelle Variante einen Titel, dem der eigentliche Elementinhalt folgt. Die informelle Variante hingegen hat keinen Titel.
Die DocBook DTD ist in der Ports-Sammlung im Port textproc/docbook
enthalten und wird
bei der Installation des Metaports textproc/docproj
automatisch
installiert.
Für das FDP wurde die DocBook DTD durch das FreeBSD-Dokumentationsproject um zusätzliche Elemente erweitert, um damit präzisiere Auszeichnungsmöglichkeiten zur Verfügung zu haben. Sofern im folgenden FreeBSD-spezifische Elemente genutzt werden, wird explizit darauf hingewiesen werden.
Wenn nachfolgend im Text der Begriff „DocBook“ verwendet wird, ist damit die durch das FDP erweiterte Version der DocBook DTD gemeint.
Die durch das FDP vorgenommenen Erweiterungen sind nicht
FreeBSD-spezifisch. Sie wurden lediglich vorgenommen, da sie
für die Arbeit des FDPs als nützlich erschienen.
Für den Fall, das in den anderen *nix-Lagern (NetBSD,
OpenBSD, Linux,…) Interesse daran besteht, gemeinsam
eine Standarderweiterung für die DocBook DTD zu
entwickeln, kann mit dem Documentation Engineering Team <doceng@FreeBSD.org>
Verbindung aufgenommen
werden.
Zum jetzigen Zeitpunkt sind die FreeBSD-Erweiterungen nicht Bestandteil der Ports-Sammlung. Sie werden im FreeBSD-Subversion-Repository (head/share/xml/freebsd.dtd) verwaltet.
In Übereinstimmung mir der DocBook-Richtlinie zur Erstellung von Bezeichnern für DocBook-Erweiterungen lautet der Bezeichner der erweiterten FreeBSD-Variante:
DocBook erlaubt es, Dokumente auf verschiedene Weise zu
strukturieren. Innerhalb des FDPs werden hauptsächlich zwei
Arten von DocBook-Dokumenten verwendet: Buch und Artikel.
Beide unterscheiden sich darin, dass ein Buch auf der obersten
Ebene durch chapter
-Elemente strukturiert
wird. Sollte das noch nicht ausreichend sein, können die
einzelnen Kapitel eines Buches mit Hilfe des Elementes
part
in Teile aufgespalten werden. Das
Handbuch ist beispielsweise auf diese Weise aufgebaut.
Kapitel (chapter
) können weiterhin in
Unterkapitel unterteilt werden. Diese werden durch die
Elemente sect1
ausgezeichnet. Soll ein
Unterkapitel selbst weitere Unterkapitel enthalten, kann das
über das Element sect2
geschehen. Diese
Unterteilung kann bis zur Tiefe von fünf Unterkapiteln –
über die Elemente sect3
,
sect4
und sect5
–
fortgeführt werden. Der eigentliche Inhalt, um den es ja in
dem Artikel oder Buch geht, wird unterhalb der hier genannten
Elemente eingefügt.
Vom Aufbau her ist ein Artikel einfacher strukturiert
als ein Buch. So kann ein Artikel beispielsweise keine Kapitel
(chapter
) enthalten. Stattdessen kann der
Inhalt eines Artikels nur durch die schon bekannten
sect
-Elemente
in einen oder mehrere Abschnitte gegliedert werden.
Überlegen Sie sich vor dem Schreiben eines Textes,
ob der zu schreibende Text am
besten als Buch oder als Artikel angelegt wird. Artikel eignen
sich besser für Texte, die nicht in mehrere Kapitel
aufgeteilt werden müssen und mit einem Umfang von
ungefähr 20 bis 25 Seiten vergleichsweise kurz sind.
Natürlich ist das nur eine Richtlinie. Bücher sind
dementsprechend am besten für lange Texte geeignet, die
sich sinnvoll in Kapitel unterteilen lassen und
möglichweiser noch Anhänge und ähnliches
enthalten können.N
Alle Tutorien von FreeBSD sind als Artikel verfasst, während hingegen die FreeBSD-FAQ und das FreeBSD-Handbuch als Bücher verfasst wurden.
Der Inhalt eines Buches wird in einem
book
-Element abgelegt. Neben dem
Textteil des Buches kann dieses Element weitergehende
Informationen über das Buch selbst,
wie Meta-Informationen zum Erstellen eines
Stichwortverzeichnisses oder zusätzliche
Inhalte zum Erstellen einer Titelei, enthalten. Diese
zusätzlichen Inhalte sollten in einem
bookinfo
-Element abgelegt werden.
book
mit
bookinfo
Titel
</title>
<author>
<firstname>Vorname
</firstname>
<surname>Nachname
</surname>
<affiliation>
<address><email>E-Mail-Adresse
</email></address>
</affiliation>
</author>
<copyright>
<year>1998
</year>
<holder role="mailto:E-Mail-Adresse
">Vollständiger Name
</holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>Kurze Zusammenfassung des Buchinhaltes.
</para>
</abstract>
</bookinfo>
…
</book>Der Inhalt eines Artikels wird in einem
article
-Element abgelegt. Neben
dem Textteil kann dieses Element weitere Teile,
wie Meta-Informationen zum Erstellen eines
Stichwortverzeichnisses oder zusätzliche
Inhalte zum Erstellen einer Titelei, enthalten.
Analog zu einem Buch, sollten diese Informationen in einem
articleinfo
-Element abgelegt
werden.
article
mit
articleinfo
Titel
</title>
<author>
<firstname>Vorname
</firstname>
<surname>Nachname
</surname>
<affiliation>
<address><email>E-Mail-Adresse
</email></address>
</affiliation>
</author>
<copyright>
<year>1998
</year>
<holder role="mailto:E-Mail-Adresse
">Vollständiger Name
</holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>Kurze Zusammenfassung des Artikelinhalts.
</para>
</abstract>
</articleinfo>
…
</article>Kapitel werden mit dem
chapter
-Element angelegt und müssen ein
title
-Element enthalten. Verwendet werden
können sie nur in Büchern.
Kapitel können nicht leer sein. Neben einem
title
-Element müssen sie weiteren Inhalt
beinhalten. Falls ein leeres Kapitel benötig wird, kann dies
durch das Einfügen eines leeren Absatzes
(para
) erreicht werden.
Bücher werden auf der obersten Gliederungsebene
durch chapter
-Elemente in Kapitel
unterteilt. Eine weitergehende Untergliederung kann durch
das Anlegen von Unterkapiteln erreicht werden. Im Gegensatz
zu Kapiteln, die durch chapter
-Elemente
ausgezeichnet werden, erfolgt die Auszeichnung von
Unterkapitel mit dem Element
sect
. Das
n
n
in Elementnamen trifft eine
Aussage über die Gliederungstiefe, auf der sich das
Unterkapitel befindet. Ein sect1
-Element
kann mehrere Elemente vom Typ sect2
enthalten, die die Unterkapitel der
nächsten Gliederungsebene darstellen.
sect5
ist das letzte Element, das auf
diese Art zur Gliederung eingesetzt werden kann.
Die Unterkapitel dieses Beispiels wurden zu Demonstrationszwecken manuell durchnummeriert. In „normalen“ Dokumenten wird diese Aufgabe von den Stylesheets übernommen.
In den Fällen, in denen die Unterteilung eines Buches in
Kapitel nicht ausreichend ist, können mehrere
Kapitel mit dem Element part
zu
einem Teil zusammengefasst werden.
DocBook kennt drei Arten von Absätzen: Absätze
mit Überschrift (formalpara
),
normale Absätze (para
) und einfache
Absätze (simpara
).
Normale Absätze und einfache Absätze
unterscheiden sich dadurch, dass innerhalb von
para
Blockelemente erlaubt sind,
innerhalb von simpara
hingegen nicht. Es
ist empfehlenswert, para
den Vorzug
zu geben.
para
Darstellung:
Das ist ein Absatz. Absätze können fast jedes andere Element aufnehmen.
Blockzitate sind textlich umfangreichere Zitate aus einem anderen Text, die nicht innerhalb des aktuellen Absatzes angezeigt werden sollen. Wahlweise können Blockzitate eine Überschrift haben und die Zitatquelle nennen.
blockquote
Darstellung:
Menschenwürde; Grundrechtsbindung der
staatlichen Gewalt
| ||
--Aus dem Grundgesetz |
In bestimmten Fällen kann es nützlich sein,
dem Leser zusätzliche Informationen zu geben, die sich
vom Haupttext abheben, damit der Leser sie besser wahrnimmt.
Abhängig von der Art der Information, können
solche Stellen mit einem der Elemente tip
(für Tipps), note
(für
Anmerkungen), warning
(für
Warnungen), caution
(für besonders
ernstzunehmende Warnungen) und important
(für wichtige Anmerkungen) ausgezeichnet werden. Trifft
keines dieser Elemente für die auszuzeichnende Stelle
zu, sollte diese mit dem Element sidebar
ausgezeichnet werden.
Da die richtige Einordnung einer auszuzeichnenden Textstelle nicht immer leicht zu treffen ist, werden in der DocBook-Dokumentation folgende Empfehlungen gegeben:
Eine Anmerkung (note
) ist eine
Information, die von jedem Leser beachtet werden
sollte.
Eine wichtige Anmerkung
(important
) eine Variation einer
Anmerkung.
Eine Warnung (warning
)
betrifft einen möglichen Hardwareschaden
oder weist auf eine Gefahr für Leib und Leben
hin.
Eine besonders ernstzunehmende Warnung
(caution
) betrifft einen möglichen
Datenverlust oder Softwareschaden.
warning
Eine Warnung wird wie folgt dargestellt:
Wenn Sie FreeBSD auf Ihrer Festplatte installieren, kann es sein, dass Sie Windows nie mehr benutzen wollen.
Listen sind ein oft gebrauchtes Hilfsmittel, wenn es
darum geht, Informationen für den Benutzer
übersichtlich darzustellen oder eine Abfolge von
Arbeitsschritten zu beschreiben, die notwendig sind, um ein
bestimmtes Ziel zu erreichen. Zur Auszeichnung von Listen
stellt DocBook die Elemente itemizedlist
,
orderedlist
und
procedure
zur Verfügung.[13].
itemizedlist
und
orderedlist
ähneln sehr stark ihren
HTML-Gegenstücken ul
und
ol
. Beide Listenarten müssen
mindestens ein Element listitem
enthalten. Das listitem
Element
muss mindestens ein weiteres Blockelement
enthalten.
procedure
unterscheidet sich ein
wenig von den vorhergehenden. Es enthält
step
-Elemente, die wiederum
step
- oder
substel
-Elemente enthalten können.
Ein step
-Element kann nur Blockelemente
aufnehmen.
itemizedlist
,
orderedlist
und
procedure
Darstellung:
Das ist das erste Listenelement.
Das ist das zweite Listenelement.
Das ist das erste Aufzählungselement.
Das ist das zweite Aufzählungselement.
Machen Sie zuerst dies.
Und dann machen Sie das..
Und jetzt noch das…
Technische Dokumente enthalten oft auch
Konfigurationsbeispiele oder Quellcodeschnipsel. Zur
Auszeichnung dieser Inhalte, stellt Docbook das Element
programmlisting
zur Verfügung. Im
Gegensatz zu anderen DocBook-Elementen wird der
Elementinhalt von programmlisting
nicht normalisiert, das heißt,
dass alle Leerzeichen, Tabulatoren und
Zeilenumbrüche unverändert übernommen werden.
Aus diesem Grund ist es unter anderem wichtig, dass
sich der öffende Tag in der selben Zeile wie der Anfang
des darzustellenden Textes befindet. Gleiches gilt für
den schließenden Tag: Er muss sich am Ende der
letzten Zeile befinden. Wird das nicht beachtet, kann es
sein, dass unerwartete Leerzeichen und Leerzeilen in
der Ausgabe auftauchen.
programlisting
Die spitzen Klammern der
#include
-Anweisung können nicht direkt
verwendet werden, sondern müssen über ihre Entitäten
eingebunden werden.
Darstellung:
Am Ende sollte Ihr Programm wie folgt aussehen:
Textanmerkungen[14] sind ein Mechanismus, um auf bestimmte Stellen in einem vorhergehenden Beispiel oder Text zu verweisen.
Um solche Verweise anzulegen, müssen die betreffenden
Stellen in den Beispielen
(programlisting
,
literallayout
, …) mit
co
-Elementen markiert werden, wobei jedes
Element ein eindeutiges id
-Attribut
besitzen muss. Anschließend sollte ein
calloutlist
-Element eingefügt werden,
dessen Elemente sich auf die co
-Elemente
des Beispiels beziehen und die jeweiligen Anmerkungen
enthalten.
co
- und das
calloutlist
-ElementDarstellung:
Am Ende sollte Ihr Programm wie folgt aussehen:
Im Gegensatz zu HTML ist es nicht notwendig, Tabellen zu Layoutzwecken einzusetzen, da die Layoutaufgabe von den Stylesheets übernommen wird. Stattdessen sollten Tabellen nur für die Auszeichnung von Daten in Tabellenform genutzt werden.
Vereinfacht betrachtet (für Details sollte die
DocBook-Dokumentation zu Rate gezogen werden) besteht eine
Tabelle, die entweder als formelle oder als informelle
Tabelle angelegt werden kann, aus einem
table
-Element. Dieses Element selbst
beinhaltet mindestens ein Element tgroup
,
das über ein Attribut die Spaltenanzahl der Tabelle
bestimmt. Innerhalb des Elementes tgroup
kann sich ein Element thead
mit den
Spaltenüberschriften und ein Element
tbody
mit dem eigentlichen Tabelleninhalt
befinden. Beide Elemente beinhalten
row
-Elemente, die wiederum
entry
-Elemente beinhalten. Jedes
entry
-Element stellt eine einzelne
Tabellenzelle dar.
informaltable
auszeichnenDarstellung:
Spaltenüberschrift 1 | Spaltenüberschrift 2 |
---|---|
Zeile 1, Spalte 1 | Zeile 1, Spalte 2 |
Zeile 2, Spalte 1 | Zeile 2, Spalte 2 |
Verwenden Sie stets das Attribut pgwide
mit dem Wert 1
, wenn Sie das Element
informaltable
benutzen. Ein Bug des
Internet Explorers verhindert ansonsten die korrekte
Darstellung dieser Tabellen.
Soll die Tabelle keinen Rand haben, kann das Attribut
frame
mit dem Wert
none
dem Element
informaltable
hinzugefügt werden
(<informaltable frame="none">
)).
frame="none"
Darstellung:
Spaltenüberschrift 1 | Spaltenüberschrift 2 |
---|---|
Zeile 1, Spalte 1 | Zeile 1, Spalte 2 |
Zeile 2, Spalte 1 | Zeile 2, Spalte 2 |
Oft gilt es, für dem Benutzer Beispiele zu geben, die er dann selber nachvollziehen soll. Meist handelt es sich dabei um interaktive Dialoge zwischen Mensch und Maschine: Der Benutzer gibt einen Befehl ein und erhält eine Antwort vom System. Ein Satz von speziellen Elementen und Entitäten unterstützt den Autor bei der Auszeichnung solcher Textstellen:
screen
Gedacht zur Auszeichnung von Bildschirminhalten.
Im Unterschied zu anderen Elementen werden Leerzeichen
innerhalb des Elementes screen
unverändert übernommen.
prompt
,
&prompt.root;
und
&prompt.user;
Eingabeaufforderungen des Rechners
(Betriebssystem, Shell oder Anwendung) sind ein häufig
auftretender Teil dessen, was der Benutzer auf dem
Bildschirm zu sehen bekommt. Sie sollten mit
prompt
ausgezeichnet werden.
Ein Spezialfall sind die beiden
Eingabeaufforderungen der Shell für normale
Benutzer und den Superuser root
.
Jedes mal wenn auf eine von diesen beiden Nutzerrollen
hingewiesen werden soll, sollte entweder
&prompt.root;
oder
&prompt.user;
eingesetzt
werden. Beide Entitäten können auch
außerhalb von screen
verwendet werden.
&prompt.root;
und
&prompt.user;
sind
FreeBSD-spezifische Erweiterungen der DocBook DTD
und nicht in der originalen DocBook DTD
enthalten.
userinput
Das Element userinput
ist
für die Auszeichnung von Benutzereingaben
gedacht.
screen
, prompt
und userinput
Darstellung:
%
ls -1
foo1
foo2
foo3
%
ls -1 | grep foo2
foo2
%
su
Password:
#
cat foo2
This is the file called 'foo2'Obgleich der Inhalt der Datei
foo2
in dem obigen Beispiel angezeigt
wird, sollte dieser nicht mit
programlisting
ausgezeichnet werden.
Vielmehr sollte programlisting
einzig
und allein für die Darstellung von Dateifragmenten
außerhalb von Benutzeraktionen gewählt
werden.
Wenn es darum geht bestimmte Wörter oder Textstellen
hervorzuheben, sollte dafür das Element
emphasis
verwendet werden. Das so
ausgezeichnete Text wird dann kursiv oder fett dargestellt;
im Falle einer Sprachausgabe würde es anders betont
werden.
Im Gegensatz zu den HTML mit seinen Elementen
b
und i
, kennt DocBook
keinen Weg, um diese Darstellung zu
ändern[15]. Handelt es sich bei
dem darzustellenden um eine wichtige Information, kann
alternativ important
verwendet
werden.
emphasis
Darstellung:
FreeBSD ist zweifelslos das führende Unix-artige Bestriebssystem für die Intel-Plattform.
Um einen Auszug aus einer anderen Quelle zu zitieren
oder kenntlich zu machen, dass eine bestimmte Wendung
im übertragenen Sinne zu verstehen ist, kann der
betreffende Text mit Hilfe des Elementes
quote
ausgezeichnet werden. Innerhalb von
quote
können die meisten der
normalerweise zur Verfügung stehenden Elemente genutzt
werden.
Darstellung:
Es sollte immer sichergestellt werden, das die Suche die Grenzen zwischen „lokaler und öffentlicher Administration“ (RFC 1535) einhält.
Das Element keycap
beschreibt
eine bestimmte Taste der Tastatur.
Für die Auszeichnung von Maustasten
steht analog das Element mousebutton
zur
Verfügung. Mit Hilfe von keycombo
können beliebige Tasten- und Maustastenkombinationen
beschrieben werden.
Das Element keycombo
besitzt ein
Attribut action
, dem einer der Werte
click
, double-click
,
other
, press
,
seq
oder simul
zugewiesen werden kann. Die letzten beiden Werte deuten an,
dass die genannte Kombination nacheinander oder
gleichzeitig gedrückt werden soll. Die Stylesheets
fügen zwischen die einzelnen Unterelemente von
keycombo
„+“-Zeichen
ein.
Diese Eingaben zeichnen Sie wie folgt aus:
Darstellung:
Mit der Tastenkombination Alt+F1 kann auf die zweite virtuelle Konsole umgeschaltet werden.
Um vi
zu beenden, ohne die
Änderungen zu speichern, muss Esc : q ! eingegeben werden.
Der Fenstermanager ist so konfiguriert, dass mittels Alt+ Fenster verschoben werden können.
Oft besteht die Notwendigkeit auf bestimmte Anwendungen und Befehle zu verweisen. Der Unterschied zwischen einer Anwendung und einem Befehl liegt darin, dass eine Anwendung ein einzelnes oder eine Gruppe von Programmen ist, mit denen eine bestimmte Aufgabe erledigt werden kann. Ein Befehl hingegen ist der Name eines Programmes, dass der Benutzer aufrufen kann[16].
Desweiteren kann es auch vorkommen, dass die von einem Programm (in einem bestimmten Fall) akzeptierten Optionen genannt werden müssen.
Schlussendlich ist es oft gewünscht, zu einem Befehl dessen Abschnitt der Manualseiten im Unix-üblichen Stil „Befehl(Zahl)“ anzugeben.
Anwendungsnamen können mit application
ausgezeichnet werden.
Befehle können zusammen mit der betreffenden
Hilfeseite über das DocBook-Element
citerefentry
ausgezeichnet werden.
citerefentry
muss zwei weitere
Elemente enthalten: refentrytitle
,
für den Befehlsnamen, und manvolnum
,
für die Kategorie der Hilfeseite.
Diese Art auf Befehle zu verweisen kann sehr
ermüdent sein. Daher gibt es einen Satz von
Allgemeinen
Entitäten, der diese Arbeit erleichtert. Er
ist in der Datei
doc/share/xml/man-refs.ent
enhalten
und kann über den folgenden Bezeichner eingebunden
werden:
Jede Entität in dieser Datei ist wie folgt aufgebaut:
&man.
.Hilfeseite
.Kategorie
;
Der Anfang eines Dokumentes, das diese Entitäten einbindet, könnte so aussehen:
Um Befehle innerhalb des Fließtextes auszuzeichnen,
kann das Element command
genutzt werden.
Die Optionen eines Befehles können mit Hilfe von
option
ausgezeichnet werden.
Wenn man sich mehrmals hintereinander auf den gleichen
Befehl bezieht, sollte man beim ersten Auftreten die Notation
&man.
verwenden. Für alle folgenden Referenzen sollte hingegen
command
.section
;command
verwendet werden. Dadurch
verbessert sich das Erscheinungsbild, insbesondere von HTML,
deutlich.
Die Unterscheidung zwischen command
und application
kann schwer sein, und
manchmal ist die Entscheidung, welches Element das richtige
ist, nicht leicht. Das folgende Beispiel soll diese
Unterscheidung erleichtern.
Darstellung:
Sendmail ist der verbreitetste UNIX-Mailserver.
Sendmail besteht aus den Programmen sendmail(8), mailq(1) sowie newaliases(1).
Mittels der Option -bp
kann
sendmail(8) den Status der Mailwarteschlange ausgeben.
Der Status der Mailwarteschlange kann durch den Befehl
sendmail -bp
überprüft
werden.
Die Schreibweise
&man.
ist leichter lesbar.Hilfeseite
.Kategorie
;
Immer wenn in einem Text der Name einer Datei, eines
Verzeichnisses oder eine Dateierweiterung vorkommt, sollte
die betreffende Stelle mit dem Element
filename
ausgezeichnet werden.
filename
Darstellung:
Die SGML-Quellen des englischen Handbuches befinden
sich im Verzeichnis
/usr/doc/en/handbook/
. In diesem
Verzeichnis befindet sich eine Datei
handbook.xml
. Desweiteren sollte
sich eine Datei mit dem Namen
Makefile
zusammen mit mehreren
Dateien mit der Endung .ent
in diesem
Verzeichnis befinden.
Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.
An einigen Stellen ist es notwendig, den Namen eines
Ports aus FreeBSDs Ports-Sammlung in Dokumenten zu verwenden.
In diesem Fall sollte ebenfalls das Element
filename
eingesetzt werden, dabei aber
dem Element das Attribut role
mit dem
Wert package
zugewiesen werden. Da die
Ports-Sammlung an jeder beliebigen Stelle im Dateisystem
installiert werden kann, sollte filename
nur die Kategorie und den Namen des Ports enthalten, aber
nicht das Verzeichnis
/usr/ports
.
filename
Darstellung:
Wenn Sie Ihr Netz und dessen Datenverkehr analysieren
möchten, dann installieren Sie bitte den Port net/ethereal
.
Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.
Wird in einem Dokument Bezug auf Gerätedateien
unterhalb von dev
genommen, dann gibt es zwei Möglichkeiten diese
auszuzeichnen. Zum einen kann man sich auf das Gerät
beziehen, so wie es unter /dev
zu
finden ist, und zum anderen kann man sich auf den
Gerätenamen beziehen, wie es innerhalb des Kerns
verwendet wird. Für letztere Möglichkeit sollte
das Element devicename
genutzt
werden.
Allerdings besteht nicht immer diese
Wahlmöglichkeit. Einige Geräte, wie zum Beispiel
Netzwerkkarten haben keinen Eintrag unter
/dev
oder werden anders
dargestellt.
devicename
auszeichnenDarstellung:
Unter FreeBSD wird die serielle Datenübertragung
über sio
abgewickelt, das
unterhalb von /dev
eine Reihe von
Einträgen anlegt. Zu diesen Einträgen
behören beispielsweise
/dev/ttyd0
und
/dev/cuaa0
.
Andererseits erscheinen Geräte wie beispielsweise
ed0
nicht unterhalb von
/dev
.
Unter MS-DOS wird das erste Diskettelaufwerk als
a:
bezeichnet. FreeBSD bezeichnet
es als /dev/fd0
.
Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.
Bezeichner für Rechner können in Abhängigkeit
der Bezeichnungsweise auf verschiedene Art und Weise
ausgezeichnet werden. Gemeinsam ist allen, dass sie
das Element hostid
benutzen. Über das
Attribut role
wird die Art des Bezeichners
genauer bestimmt.
role="hostname"
Ohne Rollenattribut stellt der umschlossene Text
einen normalen Rechnernamen wie
freefall
oder
wcarchive
dar. Wenn es
gewünscht ist, kann mittels
role="hostname"
explizit angegeben
werden, dass es sich um einen Rechnernamen
handelt.
role="domainname"
Ein Domainname wie FreeBSD.org
oder ngo.org.uk
. Er enthält keinen
Rechnernamen.
role="fqdn"
Vollqualifizierter Domainname wie
www.FreeBSD.org
. Enthält sowohl
einen Domainnamen als auch einen Rechnernamen.
role="ipaddr"
Eine IP-Adresse, meistens als durch Doppelpunkte getrenntes Tupel von vier Zahlen dargestellt.
role="ip6addr"
Eine IPv6-Adresse.
role="netmask"
Eine Netzwerkmaske, dargestellt als ein durch
Doppelpunkte getrenntes Vierzahlentupel, einer Hexzahl
oder als ein /
, dem eine Zahl
folgt.
role="mac"
Eine MAC-Adresse, dargestellt durch zweistellige Hexzahlen, die durch Doppelpunkte getrennt sind.
role
und
hostid
Darstellung:
Der lokale Rechner kann immer über den Namen
localhost
angesprochen werden, dem immer
die IP-Adresse 127.0.0.1
zugeordnet ist.
Zur Domain FreeBSD.org
gehören
verschieden Rechner, inklusive freefall.FreeBSD.org
und bento.FreeBSD.org
.
Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet
wird, was mit der Hilfe von ifconfig
geschieht, sollte immer die Netzmaske
255.255.255.255
, die auch
hexadezimal als 0xffffffff
abgegeben werden kann, benutzt werden.
Die MAC-Adresse ist für jede existierende
Netzwerkkarte auf der Welt eindeutig. Eine typische
MAC-Adresse ist beispielsweise 08:00:20:87:ef:d0
.
Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.
Namen von Benutzern, wie
root
oder bib
,
können mit dem Element username
ausgezeichnet werden.
username
Darstellung:
Für die meisten Administrationsaufgaben müssen Sie als
root
angemeldet sein.
Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.
Zur Beschreibung von Teilen einer Makedatei stehen die
beiden Elemente marketarget
und
makevar
zur Verfügung.
maketarget
bezeichnet ein Ziel eines
Makefile
s, das als Parameter beim
Aufruf von make
angegeben werden kann.
makevar
hingegen bezeichnet eine
Variable, die entweder in einem
Makefile
definiert oder
make
auf der Befehlszeile übergeben
werden kann, um so den Bauprozess zu beeinflussen.
maketarget
und
makevar
Darstellung:
Zwei übliche Ziele in einem
Makefile
sind
all
und
clean
.
Üblicherweise wird, wenn das Ziel
all
aufgerufen wird, die gesamte
Anwendung neu erstellt. Der Aufruf des Zieles
clean
veranlaßt das
Löschen aller temporären Dateien (zum Beispiel
.o
), die während der
Übersetzung erzeugt wurden.
Das genaue Verhalten von
clean
kann von einer Reihe von
Variablen beeinflusst werden. Stellvertretend seien
hier CLOBBER
und
RECURSE
genannt.
Für das Handbuch ist es oft notwendig, Textausschnitte buchstabengetreu darzustellen. Hierbei kann es sich um Texte handeln, die aus einer anderen Datei stammen oder die der Leser eins-zu-eins aus dem Handbuch kopieren können soll.
In einigen Fällen ist zu diesem Zwecke
programlisting
ausreichend, jedoch nicht
immer. So ist programlisting
zum Beispiel
nicht einsetzbar, wenn es darum geht, einen Auszug aus einer
Datei innerhalb eines Absatzes einzufügen. In solchen Fällen
sollte das Element literal
zum Einsatz
kommen.
literal
Darstellung:
Die Zeile maxusers 10
in der
Kernelkonfigurationsdatei beeinflußt die Größe vieler
Systemtabellen und kann als ungefähr als Richtwert dafür
gelten, wie viele paralle Anmeldungen das System handhaben
kann.
Es kommt oft vor, dass der Leser Beispiele,
Dateinamen oder Kommandozeilen verändern muss.
Für einen solchen Anwendungsfall
ist das Element replaceable
gedacht. Es
kann innerhalb von anderen Elementen
genutzt werden, um die Teile auszuzeichnen, die es zu
ersetzen gilt.
replaceable
Darstellung:
%
man command
Dieses Beispiel zeigt, dass nur der Text mit
replaceable
umschlossen werden soll,
den der Benutzer einzusetzen hat. Sämtlicher anderer
Text sollte wie üblich ausgezeichnet werden.
Darstellung:
Die Zeile maxusers
in der
Kernelkonfigurationsdatei bestimmt die Größe
vieler Systemtabellen und stellt einen groben Richtwert
dafür dar, wie viele gleichzeitige Anmeldungen das
System unterstützt.n
Für einen Arbeitsplatzrechner stellt
32
einen guten Wert für
n
dar.
Die Verwendung von Grafiken innerhalb der Dokumentation ist momentan noch in einem experimentellen Stadium. Es ist daher wahrscheinlich, dass sich die hier beschriebenen Mechanismen noch ändern werden.
Für die Verwendung von Grafiken ist es notwendig,
den Port graphics/ImageMagick
zusätzlich zu installieren, da er
nicht vom Port textproc/docproj
mitinstalliert
wird.
Das beste Beispiel für den Einsatz von Grafiken ist
der unter
doc/en_US.ISO8859-1/articles/vm-design/
zu findene Artikel „Design elements of the FreeBSD VM
system“. Falls beim Lesen der folgenden Kapitel
Fragen unbeantwortet oder unklar bleiben, empfiehlt es sich,
die unter dem genannten Verzeichnis befindlichen Dateien zu
studieren und anhand ihrer zu verstehen, wie alles
zusammenhängt. Es empfiehlt sich, den Artikel in
verschiedenen Ausgabeformaten zu erzeugen, da man so sehen
kann, wie die Grafiken in Abhängigkeit vom
Ausgabemedium angeordnet werden.
Zur Zeit werden nur zwei Grafikformate unterstützt. Welches von beiden Formaten zum Einsatz kommen sollte, hängt von der Art der Grafik ab.
Für Bilder, die vorrangig Vektorelemente wie
Netzwerkdiagramme, Zeitlinien und ähnliches beinhalten,
sollte Encapsulated Postscript als Format gewählt
werden. Wichtig ist es in diesem Fall, dass die
Grafikdatei die Endung .eps
hat.
Für Bitmapgrafiken, wie zum Beispiel Bildschirmfotos,
steht das Portable Network Grafic Format zur
Verfügung. In diesem Fall, sollte die Grafikdatei immer
die Endung .png
haben.
In das Subversion-Repository sollten nur Grafiken in diesen beiden Formaten übernommen werden.
Es sollte darauf sehr darauf geachtet werden, das richtige Format für das richtige Bild zu wählen. Erwartungsgemäß wird es Dokumente geben, die eine Mischung aus PNG- und EPS-Grafiken enthalten. In solchen Fällen, stellen die Makedateien die Verwendung des richtigen Formats in Abhängigkeit vom Ausgabeformat sicher. Deshalb sollte die gleiche Grafik niemals in zwei unterschiedlichen Formaten in das CVS-Archiv übernommen werden.
Es ist absehbar, dass das Dokumentationsprojekt in Zukunft das Scalable Vector Graphic-Format (SVG) als Standardformat für Vektorgrafiken übernehmen wird. Zum jetzigen Zeitpunkt ist dieser Wechsel noch nicht möglich, da der Stand der jetzigen SVG-Anwendungen noch nicht den dafür notwendigen Erfordernissen entspricht.
Das Auszeichnen von Bildern mittels DocBook ist relativ
einfach. Zuerst wird ein
mediaobject
-Element eingefügt, das
als Container für medienspezifische Elemente fungieren
kann. Für die Zwecke des FDPs sind das die Elemente
imageobject
und
textobject
.
In das mediaobject
-Element sollten
ein Element vom Typ imageobject
und zwei
textobject
-Elemente eingefügt
werden. Das imageobject
-Element verweist
auf die eigentliche Grafikdatei. Dabei ist allerdings nur
der Dateipfad ohne Erweiterung anzugegeben. Die
textobject
-Elemente werden dafür
genutzt, Texte aufzunehmen, die dem Leser anstelle des
Bildes oder zusammen mit dem Bild angezeigt werden.
Dies kann unter zwei Umständen geschehen:
Wenn ein Dokument als HTML-Datei durch einem Browser angezeigt wird. In diesem Falle muss jeder Grafik ein Alternativtext zugeordnet werden, der dem Leser angezeigt werden kann. Meist ist das notwendig, wenn der Browser die Grafik noch nicht geladen hat oder wenn der Benutzer den Mauszeiger über die Grafik führt.
Wenn das Dokument als Textdatei gelesen wird. Da in einer Textdatei keine Grafiken angezeigt werden können, sollte es für die Grafik eine Textentsprechung geben, die alternativ angezeigt werden kann.
Das folgende Beispiel soll das bisher geschriebene
illustrieren. Angenommen es liegt eine einzubindende Grafik
in der Datei bild1.png
vor, die die
Darstellung eines As in einem Rechteck enthält. Die
ASCII-Alternative könnte so ausgezeichnet werden:
Innerhalb vom Element | |
Das erste Wichtig ist, dass die erste und die letzte Zeile sich gleichauf mit dem öffnenden und dem schließenden Tag befindet. Dadurch wird sichergestellt, dass keine unnötigen Leerzeichen in die Ausgabe aufgenommen werden. | |
Das zweite |
Alle in einem Dokument verwendeten Grafiken müssen in
dem zugehörigen Makefile in der Variable
IMAGES
enthalten sein.
IMAGES
sollte immer die Namen der
Quellgrafiken enthalten. Werden in
einem Dokument beispielsweise die drei Grafiken
bild1.eps
,
bild2.png
und
bild3.png
referenziert, sollte das
Makefile
die folgende Zeile
enthalten:
Eine andere Möglichkeit wäre:
Es kann nicht oft genug betont werden: Welche
Grafikdateien für das zu erzeugende Dokument benötigt
werden, wird von dem Makefiles bestimmt.
IMAGES
darf nur die Originaldateien
enthalten.
Wenn Sie Ihre Dokumentation in mehrere kleine Dateien aufspalten (siehe Abschnitt 3.7.1, „Dateien mit Allgemeinen Entitäten einbinden“), müssen Sie sorgfältig vorgehen.
Angenommen es handelt sich um ein Buch, dessen drei
Kapitel in separaten Verzeichnissen angelegt wurden
(kapitel1/kapitel.xml
,
kapitel2/kapitel.xml
und
kapitel3/kapitel.xml
). Enthalten die
Kapitel Grafiken, empfiehlt es sich, diese in den gleichen
Verzeichnisses abzulegen, wie die Kapitel selbst. In diesem
Falle gilt es jedoch zu beachten, dass die Pfade der
Grafikdateien in der Variable IMAGES
und
in den imagedata
-Elementen immer auch den
Verzeichnisnamen enthalten.
Soll beispielsweise die Datei
kapitel1/bild1.png
in das in
kapitel1/kapitel.xml
enthaltene
Kapitel eingebunden werden, sollte dies so erfolgen:
Das Makefile
muss dementsprechend
die Zeile
enthalten.
Wird dies beachtet, sollte es zu keinen Problemen kommen.
Querverweise sind auch Flußelemente.
Um innerhalb eines Dokumentes Verweise anzulegen, muss angegeben werden, von welcher Textstelle aus wohin verwiesen werden soll.
Jedes DocBook-Element besitzt ein Attribut
id
, über das seinem Element ein
eindeutiger Bezeichner zugewiesen werden kann.
In den meisten Fällen werden Querverweise nur zu
Kapiteln gesetzt. Die chaper
- und
sect*
-Elemente sollten aus diesem Grunde
ein gesetztes id
-Attribut
besitzen.
chapter
und section
mit dem Attribut id
Als Wert für das Attribut id
sollte immer ein selbsterklärender Bezeichner gewählt
werden. Zudem ist es notwendig, dass dieser Bezeichner
innerhalb des Dokumentes eindeutig ist. Im obigen Beispiel
wurde der Bezeichner für das Unterkapitel gebildet,
indem der Bezeichner des übergeordneten Kapitels um den
Titel des Unterkapitels erweitert wurde. Diese
Vorgehensweise hilft sicherzustellen, dass Bezeichner
eindeutig sind und bleiben.
Manchmal soll jedoch nicht auf den Anfang eines Kapitels
verwiesen werden, sondern zum Beispiel auf eine Stelle in
einem Absatz oder auf ein bestimmtes Beispiel. In solchen
Fällen kann an der Stelle, auf die verwiesen werden
soll, das Element anchor
mit gesetztem
Attribut id
eingefügt werden.
anchor
kann selber keinen weiteren Inhalt
aufnehmen.
anchor
Zum Anlegen des eigentlichen Querverweises selbst kann
eines der beiden Elemente xref
oder
link
genutzt werden. Beide besitzen das
Attribut linkend
, dem der
id
-Wert des Verweiszieles zugewiesen
wird. Ob sich das Ziel vor oder nach dem Verweis befindet,
spielt keine Rolle.
xref
und link
unterscheiden sich jedoch hinsichtlich der Art und Weise,
auf die der Text erzeugt wird, auf dem der Querverweis
liegt. Kommt xref
zum Einsatz, hat der
Autor keine Kontrolle darüber – der Text wird
automatisch für ihn erzeugt.
xref
Für dieses Beispiel wird davon ausgegangen, dass sich
folgendes Textfragment irgendwo innerhalb eines Dokumentes
auftaucht, dass das vorherige
id
-Beispiel enthält.
Der Verweistext wird automatisch von den Stylesheets erzeugt und so hervorgehoben, dass ersichtlich ist, dass es sich bei dem Text um einen Verweis handelt.
Weitere Informationen können in der Einführung gefunden werden.
Genauere Informationen können im Unterkapitel 1 gefunden werden.
Der Text, auf dem der HTML-Link für den Querverweis liegt, wurde von den Kapitelüberschriften übernommen.
Das bedeutet, dass es nicht
möglich ist, mit der Hilfe von
xref
einen Querverweis zu einer mit
anchor
gekennzeichneten Stelle
anzulegen. Da anchor
keinen Inhalt
aufnehmen kann, können die Stylesheets nicht
automatisch einen Text für den Verweis
erzeugen.
Möchte man selber den für den Verweis
benutzten Text bestimmen können, sollte das Element
link
verwendet werden. Im Gegensatz zu
xref
kann link
Inhalt
aufnehmen, der dann für den Verweis verwendet
wird.
link
beutzenFür dieses Beispiel wird davon ausgegangen, dass
es sich in dem Dokument befindet, das auch
das id
-Beispiel enthält.
Aus diesem SGML-Fragment würden die Stylesheets folgendes generieren (der hervorgehobene Text deutet den erzeugten Verweis an):
Weitere Informationen können im ersten Kapitel gefunden werden.
Genauere Informationen können in diesem Kapitel gefunden werden.
Das letzte Beispiel ist schlecht. Es sollten niemals Wörter wie „dieses“ oder „hier“ als Linktext benutzt werden. Solche Wörter zwingen den Leser dazu, den Kontext des Verweises zu lesen, um zu verstehen, wohin der Verweis führt.
Mit dem Element link
kann auf mit
anchor
gekennzeichnete Stellen im
Dokument verwiesen werden, da der Inhalt von
link
als Text für den Querverweise
genutzt wird.
Das Anlegen von Verweisen auf externe Dokumente ist
wesentlich einfacher – solange die URL des zu
referenzierenden Dokumentes bekannt ist. Um von einem
bestimmten Textabschnitt auf das gewünschte externe
Dokument zu verweisen, muss die jeweilige Stelle mit
dem Element ulink
ausgezeichnet werden.
Mittels des Attributes url
kann die
Adresse des Zieldokumentes angegeben werden. Bei der
Umformung des Quelldokumentes in die verschiedenen
Ausgabeformate wird der sich zwischen Start- und Endtag
befindliche Text für den Verweis übernommen, den
der Leser aufrufen kann.
ulink
Darstellung:
Natürlich ist es möglich, anstatt diesen Text weiterzulesen, sofort die FreeBSD-Homepage aufzurufen.
[12] Einen kurzen historischen Abriss finden Sie unter http://www.oasis-open.org/docbook/intro.shtml#d0e41.
[13] DocBook kennt noch andere Elemente für die Auszeichnung von Listen, die an dieser Stelle jedoch nicht behandelt werden.
[14] auf Englisch: callout
[15] Anmerkung des Übersetzers: Hier sollte man sich noch einmal ins Gedächtnis rufen, dass mittels der DocBook DTD nur Inhalte ausgezeichnet werden und nicht das Layout bestimmt wird.
[16] Der Befehl
mozilla
startet das Programm
mozilla.
Wenn Sie Fragen zu FreeBSD haben, schicken Sie eine E-Mail an
<de-bsd-questions@de.FreeBSD.org>.
Wenn Sie Fragen zu dieser Dokumentation haben, schicken Sie eine E-Mail an
<de-bsd-translators@de.FreeBSD.org>.