<!ELEMENT section (title, sectionid, preamble?, faq+)>
Eine Section beginnt immer mit einem Element section. Diese Element wird auch root-node (Wurzel-Knoten) genannt, da es die Wurzel einer Baumstruktur bildet.
<!ATTLIST section
date CDATA #REQUIRED
title CDATA #IMPLIED>
Damit das section Element nicht nur die Eigenschaft des root-nodes hat, transportiert es in den Attributen date und title Informationen über das Dokument. date enthält das Datum der letzten Änderung an der Datei und ist zwingend notwendig. title enthält den Titel des Dokumentes. Dieser Titel ist nicht derjenige, der später oben als Überschrift erscheint, sondern dient zur Identifizierung der Datei. Dieses Attribut ist nicht vorgeschrieben (#IMPLIED).
<!ELEMENT title (#PCDATA)>
<!ELEMENT sectionid (#PCDATA)>
<!ATTLIST sectionid
id ID #REQUIRED>
Das Element title bildet die Überschrift der Section (die, die später oben auf der Seite erscheint). Über das Element sectionid muss eine Section eindeutig identifizierbar sein. Die sectionid dient als Grundlage für Querverweise innerhalb und von außerhalb der FAQ und bildet gleichzeitig den Dateinamen der HTML Dateien (z.B. 1.html wäre das HTML Dokument, das aus der Section mit sectionid 1 erzeugt wurde).<sectionid id="secX">X</sectionid>
<!ELEMENT preamble ANY>
<!ATTLIST preamble
author IDREF #IMPLIED>
Das Element preamble dient dazu ein Vorwort zur Sektion zu verfassen. Es kann jeden möglichen Markup enthalten. Das Attribut author sollte der Autor des Vorwortes mit seiner ID füllen.
<!ELEMENT faq (question, answer, comment*)>
<!ATTLIST faq
id ID #REQUIRED>
Das Element faq bildet einen Container für eine Frage (question), die dazu gehörende Antwort (answer) und eventuelle Kommentare (comment). Frage und Antwort müssen jeweils genau einmal vorkommen, Kommentare können beliebig viele enthalten sein (beliebig schließt 0 mit ein!). Das Attribut id ist ein eindeutiger Bezeichner der FAQ, mittels dessen auf die FAQ referenziert werden kann.
<!ELEMENT question (#PCDATA)>
<!ELEMENT answer ANY>
<!ATTLIST answer
author IDREF #IMPLIED>
<!ELEMENT comment ANY>
<!ATTLIST comment
type (noprint|print) "noprint"
author IDREF #REQUIRED>
Das question Element enthält eine Frage, zu der das answer Element die Antwort gibt. Im author Attribut sollte sich der Autor der Antwort mit seiner ID verewigen. Wenn jemand diese kommentieren möchte, kann er dies mit Hilfe des comment Elementes tun. Das comment Element hat zwei Attribute: type gibt an, ob der Kommentar in der HTML Ausgabe erscheinen soll ("print") oder nicht ("noprint"). Standardmäßig wird "noprint" angenommen. Im author Attribut muss der Kommentator seine ID angeben.
<!ELEMENT authors (author+, user*)>
<!ATTLIST authors
date CDATA #REQUIRED
title CDATA #IMPLIED>
<!ELEMENT author ANY>
<!ATTLIST author
name CDATA #REQUIRED
job CDATA #REQUIRED
mail CDATA #IMPLIED
id ID #REQUIRED>
<!ELEMENT user ANY>
<!ATTLIST user
name CDATA #REQUIRED
mail CDATA #IMPLIED
id ID #REQUIRED>
Die Datei authors.xml enthält Informationen über alle Mitwirkenden an der FAQ. Aktive Mitglieder in der Mailingliste, die auch einen CVS Account haben, werden normalerweise als authors betrachtet, während Leser, die eine Kommentar, eine Korrektur oder einen neuen Vorschlag eingereicht haben, als user aufgeführt werden. Beide Elemente haben ähnliche Attribute. name enthält den Namen des Autoren/Users, mail die E-Mail Adresse (die Angabe ist optional). Über das Attribut id, kann der Autor referenziert werden. Der Wert der id muss FAQ-weit eindeutig sein! Für Autoren werden normalerweise die Initialen in Großbuchstaben, für User der volle Name in Kleinbuchstaben verwendet.
<!ELEMENT changesd (dummyhook?,changes+)>
<!ATTLIST changesd
date CDATA #REQUIRED
title CDATA #IMPLIED>
<!ELEMENT changes (change+)>
<!ATTLIST changes
date CDATA #REQUIRED>
<!ELEMENT change (#PCDATA)>
<!ATTLIST change
section CDATA #REQUIRED
faq IDREF #REQUIRED>
<!ELEMENT delete ANY>
<!ATTLIST delete
section CDATA #REQUIRED
faq CDATA #REQUIRED
rev CDATA #REQUIRED>
<!ELEMENT globchange ANY>
<!ELEMENT dummyhook EMPTY>
<!ATTLIST dummyhook
id ID #IMPLIED>
Die Datei changes.xml enthält alle inhaltlichen Änderungen an der FAQ zwischen zwei Builds/Releases. Dazu ist ein Container changes definiert, der im Attribut date das Datum des aktuellen Builds enthält. Dieses wird immer von demjenigen geändert, der ein neues Build macht (momentan ist das Thomas Nesges). Dieser setzt in date das Datum des Builds ein (das aktuelle Datum). Damit ist dieser changes Container abgeschlossen und er eröffnet darüber einen neuen Container. Für alle anderen Autoren gilt also, dass sie weder neue changes Container anlegen, noch sich an dem möglicherweise falschen Datum im date stören müssen. Es müssen einfach nur im obersten Container Element der changes.xml Datei neue change Elemente angelegt werden.
<!ELEMENT links (link+)>
<!ATTLIST links
date CDATA #REQUIRED
title CDATA #IMPLIED>
<!ELEMENT link (#PCDATA)>
<!ATTLIST link
href CDATA #REQUIRED
title CDATA #IMPLIED>
Die Datei links.xml enthält Links, die auf der Index-Seite der FAQ erscheinen sollen. Das Element link hat ein Attribut href, welches den URL enthält und ein optionales Attribut title, welches einen Titel für den Link definieren kann. Fehlt dieses Attribut, wird für den Linktitel automatisch der Wert aus href genommen.
<!ELEMENT preamble (title, text)>
<!ATTLIST preamble
date CDATA #REQUIRED
title CDATA #IMPLIED>
<!ELEMENT title (#PCDATA)>
<!ELEMENT text ANY>
Die Datei preamble.xml enthält ein Vorwort zur FAQ. Dieses Vorwort wird auf der Index-Seite angezeigt. Das Element title definiert einen Titel, das Element text Enthält den Text des Vorworts. Der Text kann aus gültigem Markup bestehen (dazu wird html.dtd eingebunden).
<!ELEMENT overview (intro, version+)>
<!ATTLIST overview
date CDATA #REQUIRED
title CDATA #IMPLIED>
<!ELEMENT intro (#PCDATA)>
<!ELEMENT version (title, browser?, files, text)>
<!ATTLIST version
type CDATA #IMPLIED
dir CDATA #REQUIRED>
<!ELEMENT title (#PCDATA)>
<!ELEMENT browser (#PCDATA)>
<!ELEMENT files (file*, tgz*)>
<!ELEMENT file (#PCDATA)>
<!ELEMENT tgz (#PCDATA)>
<!ELEMENT text (#PCDATA)>
Die Datei overview.xml enthält eine Übersicht über alle Ausgabeformate der FAQ und kann als Gesamtindex betrachtet werden. Das Element intro beinhaltet einen einleitenden Text, danach folgen mehrere version Elemente, von denen jedes für ein Ausgabeformat steht. Im type Attribut kann der Mime-Type des Formates angegeben werden (z.B. text/html, text/plain), das Attribut dir bestimmt das Unterverzeichnis, in dem die Version auf dem Webserver abgelegt ist. Das Element title gibt einen Titel für den Abschnitt der Version auf der Overview Seite an, im Element browser können empfohlene Browser angegeben werden, falls nötig. Das Containerelement files kann beliebig viele file und tgz Elemente enthalten. Für jede Datei der Version sollte ein file Element angelegt werden, das tgz Element enthält den Speicherplatz eines Tar Archives aller Files. Im Element text können noch nähere Erläuterungen zu der Version angegeben werden.
<!ELEMENT a (#PCDATA)>
<!ATTLIST a
href CDATA #REQUIRED>
<!ELEMENT br EMPTY>
<!ELEMENT hr EMPTY>
<!ELEMENT code ANY>
<!ELEMENT i ANY>
<!ELEMENT ul (li+)>
<!ELEMENT ol (li+)>
<!ELEMENT li ANY>
<!ELEMENT pre ANY>
<!ELEMENT h3 ANY>
<!ELEMENT h4 ANY>
Diese Tags sind genauso wie ihre HTML Äquivalente anzuwenden.
<!ELEMENT faqlink (#PCDATA)>
<!ATTLIST faqlink
sec CDATA #REQUIRED
id CDATA #REQUIRED
title CDATA #IMPLIED>
<!ELEMENT file (#PCDATA)>
<!ELEMENT dir (#PCDATA)>
<!ELEMENT attribute (#PCDATA)>
<!ELEMENT element (#PCDATA)>
<!ELEMENT authorref EMPTY>
<!ATTLIST authorref
id IDREF #REQUIRED>
<!ELEMENT insertauthors EMPTY>
<!ELEMENT codeblock (#PCDATA)>
<!ELEMENT man (#PCDATA)>
<!ATTLIST man
section CDATA #IMPLIED>
Das Element faqlink definiert einen Querverweis innerhalb der FAQ. Dazu kann kein normales <a> Tag verwendet werden, weil verschiedene Versionen der FAQ voneinander abweichende Dateistrukturen haben (z.B. DHTML Version). Im Attribut sec wird die Sektion, im Attribut id die ID der FAQ auf die Bezug genommen wird angegeben. Der Text der in den HTML Versionen angezeigt werden soll, wird entweder im Attribut title, oder im Content des Elementes angegeben.
Das file Element dient zur Auszeichnung von Dateinamen, dir für Verzeichnisnamen, attribute für Attribute und element markiert Elemente (und Tags). Die letztgenannten Elemente haben allesamt keine Attribute, sie dienen nur zur Visualisierung des Contents.
Das authorref dient dazu, um auf einen FAQ-Autoren zu referenzieren. Im Attribut id wird die ID des Autoren angegeben, per XSL wird ein Mailto-Link (<a href="mailto:..) erstellt.
Das insertauthors hat keine Attribute und keinen Content. Es veranlasst die XSL-Engine ein Template aufzurufen, welches alle Autoren aus authors.xml einzufügen.
Ein codeblock wird dazu eingesetzt Blöcke von Befehlen, Sourcecode oder ähnlichem darzustellen.
Das man definiert einen Verweis auf eine Manualseite. Siehe dazu Wie kann ich innerhalb der FAQ auf Manual Seiten (man pages) verweisen?.
$ export CVS_RSH=ssh
$ export CVSROOT=:ext:account@buug.de:/home/cvs
$ cvs -d $CVSROOT co linux-faq
Wer neugierig ist und sich mal den Quellcode anschauen will, kann über das Webinterface die ganze FAQ als Tararchiv oder auch nur einzelne Dateien herunterladen.
Cheatsheet für CVS Benutzer:
0. Ihr könnte ja mal am TODO üben.
1. $HOME/.cvsrc
Die Datei $HOME/.cvsrc enthält Default-Optionen für alle
CVS-Kommandos. Ich habe die folgende Datei installiert:
-----
cvs -q
update -dAP
diff -u
status -v
-----
Die erste Option bewirkt, dass alle CVS-Connects "-quiet" gemacht
werden.
Bei einem CVS update werden automatisch alle Unterverzeichnisse
mit aktualisiert (-d) und leere Unterverzeichnisse entfernt (-P,
prune). Außerdem werden sticky-Tags entfernt und es wird immer
die HEAD-Revision geholt (-A).
Ein diff wird automatisch mit der Option unified (-u)
aufgerufen.
Ein status wird immer verbose (-v) durchgeführt.
2. $HOME/.cvslist und automatisches Update
Ich habe eine Datei $HOME/.cvslist, die jeweils einen Workspace
pro Zeile bezeichnet:
/home/kris/Source/mysql-faq
/home/www/servers/kris.koehntopp.de/pages/php
/home/kris/Source/linux-faq
Das Script cvs-upall wird vom Cron einmal pro Nacht für kris
aufgerufen:
#! /bin/sh --
MAILTO=root
[ ! -f $HOME/.cvslist ] && exit 0
cat $HOME/.cvslist | while read line
do
echo "updating $line"
cd $line
cvs update
echo
done 2>&1 | mailx -s "cvs update `date +%Y-%m-%d`" $MAILTO
3. Die wichtigsten Kommandos:
- Begriffe:
- Repository: Zentrales Archiv auf dem Server
- Workspace: Deine Arbeitskopie
- Aktualisieren des Workspace
- Wechsle in die Wurzel des Workspace
- cvs update
- Aufruf nach Bedarf, zur Sicherheit einmal vor dem commit.
cvs update Legende:
- U update: Neue Datei
- P patched: Datei vom Repository in den Workspace aktualisiert
- M modified: Datei im Workspace ist modified, commit steht aus
- A added: Datei im Workspace ist neu, commit steht aus
- D deleted: Datei im Worksapce ist gelöscht, commit steht aus
- commit von Änderungen
- Immer direkt nach einem Update.
- Immer mit sinnvollem Kommentar. Der Kommentar wird Teil der
Mail.
- cvs commit
Commited alle M, A und D. Nicht immer sinnvoll.
- cvs commit file1 file2 dir1/file3
Commited die genannten Dateien, falls sie M, A oder D sind.
- Dateien zufügen und löschen
- Datei anlegen - Datei löschen
- cvs add file1 - cvs remove file1
- cvs commit - cvs commit
- Verzeichnisse anlegen
- NICHT MACHEN, außer es ist abgesprochen.
- Verzeichnisse können nicht gelöscht werden, weil ja bei einem
checkout der alten Version gelöschte Dateien wieder auftauchen
können.
- -P Option löscht leere Verzeichnisse, das ist als hätte
man es gelöscht.
- mkdir dir1; cvs add dir1; cvs commit
- Was haben die anderen gemacht?
- cvs diff
Listet die Änderungen im Repository gegen den Workspace.
- cvs annotate file1
Listet die Datei Zeile für Zeile, mit Änderungsdatum
- Alte Version bekommen
Für uns ist der Zugriff nach Datum wichtig, da wir keine
Releases taggen werden.
- cvs update -D 2000-12-29
Holt die Version vom 29. Dezember 2000 zurück.
Dies ist sticky, d.h. wird die Option -A nicht mit angegeben
beim "cvs update", bleibt das Repository auf diesem alten
Stand. Mit dem .cvsrc von oben ist "-A" immer mit angegeben.
Alte Versionen können nicht comitted werden, ohne zu
branchen. Branches sind unübersichtlich UND ZU VERMEIDEN!
Kristian
Um die FAQ zu bearbeiten, brauchst du die folgenden Tools und Programme:
Den CVS Client brauchst du um dir die Sourcen der FAQ aus dem Repository zu besorgen, und um deine Änderungen später wieder einzuchecken. Die Sourcen der FAQ liegen als ASCII-Text vor, also brauchst du einen Texteditor um sie zu bearbeiten.
Java wird zum Betrieb der Tools Xalan und FOP benötigt, wenn andere Tools als XSL-Engine und FO Prozessor eingesetzt werden ist Java also evtl. nicht nötig. Ein aktuelles JDK (Java Development Kit) ist unter http://java.sun.com/ erhältlich. Die meisten Distributionen liefern allerdings auch eine Java Version mit.
Die XSL-Engine brauchst du, um die XML Dateien in die verschiedenen Versionen zu konvertieren. Bisher hat sich gezeigt, dass die einzige XSL-Engine die weit genug implementiert ist um die FAQ zu übersetzen Xalan in der Java Version ist. Xalan kannst du von http://xml.apache.org/ beziehen.
"FO" steht für Formatting Objects, ein in XSL definierter Vorschlag des W3C für einen Standard zur Layoutbeschreibung (ähnlich zu CSS). Mit Hilfe von XSL-FO wird die PDF Version der FAQ formatiert, deshalb wird zur Erstellung dieser Version ein FO Prozessor benötigt. Auch hier hat das Apache-Project mit FOP sehr gute Arbeit geleistet, FOP ist wie Xalan von http://xml.apache.org/ zu beziehen.
css2fo.pl wird im bin Verzeichnis der FAQ mitgeliefert. Es ist ein Perlskript, welches CSS Files in XSL-FO konvertiert. Dadurch brauchen die Stylesheet Angaben nur in einem File editiert werden.
tidy untersucht HTML Quellcode auf Fehler und versucht diese gleich zu korrigieren. Dabei formatiert tidy den HTML Code gleichzeitig um. tidy kann von http://www.w3.org/People/Raggett/tidy/ heruntergeladen werden.
Um die Ergebnisse der Transformation zu kontrollieren brauchst du einen bzw. besser mehrere Browser. Die FAQ sollte in allen gängigen Browsern darstellbar sein. Um ein Build der FAQ zu machen brauchst du ein make Programm. Das sollte aber auf den meisten Installationen bereits vorhanden sein. Ebenso wie sed und perl, die im Makefile verwendet werden, um die XML Files zu bearbeiten. Der Textbrowser lynx schließlich wird gebraucht, um die Textversion der FAQ zu erstellen.
Die Xalan Distribution ist unter http://xml.apache.org/ zu finden. Nach dem Download kann man entweder die mitgelieferten JAR Files benutzen, oder Xalan aus den Sourcen selbst bauen. Zunächst ist der Tarball an geeigneter Stelle zu entpacken:
thomas@crusher:/usr/local > tar xzf xalan-j_2_0_D07.tar.gz
Dabei wird ein Unterverzeichnis xalan-j_2_0_D07/ angelegt, in dem die JAR-Files und die Sourcen zu finden sind.
thomas@crusher:/usr/local > cd xalan-j_2_0_D07/
Will man Xalan aus den Sourcen bauen, sind folgende Schritte durchzuführen:
thomas@crusher:/usr/local/xalan-j_2_0_D07 > perl -i -ne 's/\r\n/\n/; print'
build.sh
thomas@crusher:/usr/local/xalan-j_2_0_D07 > chmod 755 build.sh
thomas@crusher:/usr/local/xalan-j_2_0_D07 > which java
/usr/src/jdk1.3/bin/java
thomas@crusher:/usr/local/xalan-j_2_0_D07 > export JAVA_HOME="/usr/src/jdk1.3/"
thomas@crusher:/usr/local/xalan-j_2_0_D07 >./build.sh
[...]
thomas@crusher:/usr/local/xalan-j_2_0_D07 > cd build
thomas@crusher:/usr/local/xalan-j_2_0_D07/build > ls
classes xalan.jar
Zunächst sind die Zeilenende Zeichen im build.sh zu ersetzen. Mit chmod 755 wird das Skript ausführbar gemacht. Zur Installation muss eine Umgebungsvariable JAVA_HOME gesetzt werden, die auf das Java Installationsverzeichnis zeigt. Dazu wird which java ausgeführt. Der Teil des Verzeichnisnamens bis zum bin ist das JAVA_HOME (hier also /usr/src/jdk1.3/). Nach Ausführen von build.sh sollte im Unterverzeichnis build/ ein Verzeichnis classes, welches alle Classfiels beinhaltet, und eine Datei xalan.jar zu finden sein.
Im Verzeichnis bin/ findet sich das xalan.jar der Distribution und ein xerces.jar, welches von Xalan benötigt wird. Jetzt setzt man noch ein einfaches Shellskript auf um Xalan anzuwerfen:
--[/usr/local/bin/xalan]--
#!/bin/sh
XALAN="/usr/local/xalan-j_2_0_D07/build/xalan.jar";
XERCES="/usr/local/xalan-j_2_0_D07/bin/xerces.jar";
CLASSPATH="$XALAN:$XERCES:$CLASSPATH";
export CLASSPATH
java org.apache.xalan.xslt.Process -in "$1" -xsl "$2" -out "$3";
---
Wenn man Xalan nicht aus den Sourcen gebaut hat, ist die Variable XALAN auf /usr/local/xalan-j_2_0_D07/bin/xalan.jar zu setzen. Damit ist Xalan per `xalan in.xml trans.xsl out.html` benutzbar. Das entspricht auch der im Makefile benutzten Syntax.
Die Installation von FOP läuft analog zur Installation der XSL-Engine Xalan, die in beschrieben ist.
Um FOP auszuführen legt man sich am einfachsten ein Shellskript an:
--[/usr/local/bin/fop]--
#!/bin/sh
XERCES="/usr/local/xalan/bin/xerces.jar";
XALAN="/usr/local/xalan/bin/xalan.jar";
FOP="/usr/local/fop-0_16_0/fop.jar";
W3C="/usr/local/fop-0_16_0/lib/w3c.jar";
CLASSPATH="$XALAN:$XERCES:$FOP:$W3C:$CLASSPATH";
export CLASSPATH
java org.apache.fop.apps.XalanCommandLine $1 $2 $3
---
Achtung: FOP braucht in der aktuellen Version eine 1.x Version von Xalan!
Vorsicht, es ist auf beide Listen nur für Abonnenten derselben möglich, Beiträge and diese Mailing-Listen zu schicken. Der Grund liegt im extrem hohen Spamaufkommen.
Die Liste linux-faq@buug.de befasst sich ausschließlich mit dieser FAQ. Dort werden inhaltliche und technische Aspekte der FAQ diskutiert. Wenn du also einen Beitrag zur FAQ leisten willst, ist diese Liste die richtige Adresse.