http://www.dcoul.de/faq/

A. Wissenswertes für Autoren

Diese Sektion informiert Autoren und angehende Autoren über die technische Struktur der dcoul-FAQ und gibt Tipps zum Umgang mit den verschiedenen Tools die zur Erzeugung der FAQ eingesetzt werden. Die Struktur der XML Dateien wird erläutert, der Umgang mit dem CVS Server wird an Beispielen erklärt und man erfährt wie man überhaupt als Autor am FAQ-Projekt teilnehmen kann.
  1. Kommandos der Mailingliste
  2. Wie ist die XML Struktur der Sektionen zu verstehen?
  3. Wie sieht die Struktur der übrigen XML-Files aus?
  4. Mit welchen Tags kann ich die Antworttexte formatieren?
  5. Wofür werden die DF_...xml Dateien gebraucht?
  6. Wie funktioniert XML?
  7. Wie funktioniert XSL?
  8. Wie funktioniert CVS?
  9. Wie logge ich mich am CVS Server ein?
  10. Gibt es eine kurze Übersicht, wie ich am geschicktesten mit CVS arbeite?
  11. Wie gehe ich mit Einreichungen von Usern um?
  12. Wie kann ich die Archive der Mailingliste einsehen?
  13. Gibt es ein Webinterface zum CVS Repository?
  14. Wo werden neue Fragen in der FAQ eingefügt?
  15. Ich habe Änderungen vorgenommen und ein diff erstellt. Wer spielt das ein?
  16. Wie sollen neue Einträge in der Datei changes.xml vorgenommen werden?
  17. Welche Tools brauche ich, um an der FAQ zu arbeiten?
  18. Wie installiere ich Xalan?
  19. Wie kann ich FOP nutzen?
  20. Ich möchte eine Dokumentation schreiben, an wen kann ich mich wenden?
  21. Wie kann ich innerhalb der FAQ auf Manual Seiten (man pages) verweisen?
A.1 Kommandos der Mailingliste
Die Mailingliste wird per Mailman gemanaged. Mailman wird primär über ein Webinterface administriert. An- und Abmeldung und Einstellen der persönlichen Optionen ist auf https://buug.de/cgi-bin/mailman/listinfo/linux-faq/ möglich.
Man kann das auch per E-Mail an linux-faq-request@buug.de erledigen, folgende Kommandos sind bekannt, die Angaben in eckigen Klammern sind optional:
  • subscribe [address=E-Mail-adresse]: Anmeldung
  • unsubscribe Passwort [address=E-Mail-adresse]: Abmeldung
  • info: Informartionen über die Liste
  • set option on|off Passwort: (de)aktiviert bestimmte Optionen.
    • ack: Bestätigung für an die Liste versandte Mails.
    • digest: Zustellung als einzelne Mails oder gesammelt.
    • plain: Sammelmails als plain-text statt MIME verschicken.
    • nomail: Keine Mails zustellen, z.B. anstelle sich temporär abzumelden
    • norcv: Kein Empfang selbst versandter Mails an die Liste
Ausführlichere Informationen und Hinweise auf weitere Kommandos und Optionen und Informationen erhält man nach einem Mail mit Betreff help an linux-faq-request@buug.de.
A.2 Wie ist die XML Struktur der Sektionen zu verstehen?
Um die Struktur der XML Files zu verstehen sieht man sich am besten die DTDs (Document Type Definition) dazu an. Die Datei section.dtd beschreibt die Element-Struktur der XML Dateien für Sektionen (section?.xml).
                <!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.
Das section Element muss ein title, ein sectionid und mindestens ein faq Element enthalten, und es bildet damit die Grundstruktur für ein Section-File.
                        <!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).
Das id Attribut dient zurzeit als Dummy Attribut für die Einträge in der Datei changes.xml und muss den ID-Wert "sec" + sectionid enthalten. Ein Beispiel: <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.
A.3 Wie sieht die Struktur der übrigen XML-Files aus?
Auch hier schaut man am besten wieder in die DTDs der einzelnen Dateien.

authors.xml

                <!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.
Das author Element hat zusätzlich noch das Attribut job welches die Hauptaufgabe des Autoren enthält (meine Hauptaufgabe ist z.B. die XML/HTML Struktur der FAQ).
Beide Elemente können zusätzliche Informationen zur Person einschließen. Beim user wird das normalerweise eine Notiz zum eingereichten Vorschlag sein.
Die Informationen über Autoren erscheinen auf der Index-Seite der FAQ. Die vollen Informationen über Autoren und User erscheinen in Sektion F.

changes.xml

                <!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.
Der Container enthält mindestens ein change Element, welches eine einzelne Änderung an einem durch die Attribute section und faq genau spezifizierten FAQ-Eintrag enthält. Das Attribut faq enthält ab sofort die ID des Eintrags (nicht mehr die Nr)! Um Probleme mit der Validierung der Dokumente zu umgehen, kann das faq Attribut mit dem Wert dummy gefüllt werden. Dieses ID-Element wird durch das neue dummyhook definiert, welches am Anfang von changes.xml steht und dessen Attribut id den Wert dummy hat. Ein typischer Anwendungsfall ist zum Beispiel ein Bezug auf ein gelöschtes FAQ-Element.
Gelöschte FAQ-Elemente werden nicht mit dem Element change, sondern mit delete ausgezeichnet. Dieses Element ähnelt dem change Element in seinen Attributen, allerdings ist faq hier vom Typ CDATA, welcher nicht validiert wird. Dadurch kann hier die originale ID verwendet werden, ohne dass sie im Dokument vorkommen muss (bei gelöschten Elementen der Fall). Neu ist das rev. In ihm wird die Revisionsnummer der Revision angegeben, in der das gelöschte Element zuletzt vorkam. Dadurch kann ein Link auf das CVS Webinterface erstellt werden, über den der Leser sich das gelöschte nochmal ansehen kann.
Das Element globchange dient dazu Änderungen auszuzeichen, die sich auf die gesamte FAQ auswirken und nicht an einer bestimmten Frage oder Sektion festzumachen sind. Es kann allen möglichen Markup enthalten und hat keine Attribute.

links.xml

                <!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.

preamble.xml

                <!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).

overview.xml

                <!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.
A.4 Mit welchen Tags kann ich die Antworttexte formatieren?
Zur Formatierung der Texte innerhalb der FAQ sind in html.dtd und misc.dtd einige Tags definiert. html.dtd definiert dabei Nachbildungen von bekannten HTML Tags, im einzelnen:
                <!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.
In misc.dtd sind zusätzliche Tags definiert, die speziell für diese XML Anwendung Geltung haben:
                <!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?.

A.5 Wofür werden die DF_...xml Dateien gebraucht?
Die XML Dateien mit Präfix DF_ sind ausschließlich für den make Prozess von Bedeutung. Sie verlinken die datenhaltenden XML Files (z.B. sectionA.xml) per Entityreferenz, so dass die Daten aus zum Beispiel authors.xml auch in alle Sektionen zur Verfügung stehen. Dies muss in extra Dateien gemacht werden, da es sonst leicht zu mehrfachen oder gegenseitigen Links kommen kann, die logisch nicht sinnvoll sind und beim Validierungsprozess als fehlerhaft gemeldet werden, falls Attribute vom Typ ID verwendet worden sind (diese erscheinen durch mehrfache Links auch mehrfach und sind somit nicht mehr eindeutig).
A.6 Wie funktioniert XML?
Die Referenz zum Thema sind die Seiten des W3C unter http://www.w3.org/XML/. Diese sind allerdings sehr schwer verständlich, daher ist das Tutorial auf http://www.w3schools.com/xml/ für Einsteiger eher zu empfehlen.
A.7 Wie funktioniert XSL?
Auch zu diesem Thema sind die Seiten des W3C unter http://www.w3.org/Style/XSL/ die Referenz. Aber auch zu XSL ist für Einsteiger eher das Tutorial unter http://www.w3schools.com/xsl/ zu empfehlen.
A.8 Wie funktioniert CVS?
Kristian hat dazu eine gute Einführung verfasst, die unter http://www.koehntopp.de/kris/artikel/cvs/ zu finden ist. Unter http://www.fokus.gmd.de/research/cc/glone/employees/matthias.kranz/private/cvs_article.html findet man einen sehr guten Artikel aus dem Linux Magazin von Matthias Kranz.
A.9 Wie logge ich mich am CVS Server ein?
Wer and der FAQ aktiv mitarbeitet (mitarbeiten will), bekommt einen Acccount mit Schreibrecht, und kann diesen folgendermaßen nutzen:
                $ 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.
A.10 Gibt es eine kurze Übersicht, wie ich am geschicktesten mit CVS arbeite?
Ja, die gibt es. Dazu hat Kristian ein Paper verfasst:
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
                
A.11 Wie gehe ich mit Einreichungen von Usern um?
Wenn ein User einen Vorschlag einsendet, wird die Mail auf dem CVS Server im Verzeichnis vorschlaege/ gespeichert. Dort bleibt die Mail solange, bis jemand den Vorschlag weiterbearbeitet.
Derjenige, der die Mail bearbeitet, gibt kurz auf der Mailingliste Bescheid, damit die Arbeit nicht doppelt gemacht wird.
Zunächst ist zu prüfen, ob die Korrektur oder der Vorschlag korrekt ist, d.h. stimmen angegebene URLs, sind angegebene Kommandos unbedenklich und zielführend, usw. Ist dies der Fall, wird die Korrektur vorgenommen, bzw. der Vorschlag in die passende Section übernommen.
Der einreichende User ist als <user> in die Datei authors.xml aufzunehmen (dazu gehört ein kurzer Kommentar zum eingereichten Vorschlag), und in der Datei changes.xml ist die Änderung zu vermerken. Danach kann die Mail aus vorschlaege/ gelöscht werden.
A.12 Wie kann ich die Archive der Mailingliste einsehen?
Die Mailingliste ist vollkommen öffentlich, d.h jeder kann eine Mail an die Liste senden - auch ohne subscribed zu sein. Und zusätzlich kann auch jeder die Archive der Liste einsehen. Dazu gibt es unter https://buug.de/pipermail/linux-faq/ ein Webinterface.
A.13 Gibt es ein Webinterface zum CVS Repository?
Ja, das gibt es. Unter https://buug.de/cgi-bin/viewcvs.cgi/?cvsroot=linux-faq findet sich ein anonymer readonly Account zum CVS Repository. Dort können alle Files angesehen und einzeln downloaded werden.
A.14 Wo werden neue Fragen in der FAQ eingefügt?
Neue Fragen sollten immer unten in der passenden Sektion eingefügt werden, damit sich die automatisch generierte FAQ-Nr nicht ändert. Alle FAQs sind zwar durch das Attribut id eindeutig gekennzeichnet, aber viele Benutzer werden auf die Fragen mit der Angabe der Nummer referenzieren ("Steht in dcoul-FAQ Sektion X FAQ-Nr 4711") und keinen eindeutigen URL mit der ID angeben ("Steht in http://www.dcoul.de/faq/X.html#tubesenf").
A.15 Ich habe Änderungen vorgenommen und ein diff erstellt. Wer spielt das ein?
Da prinzipiell jeder einen CVS Account mit Schreibrecht erhalten kann, haben wir uns entschlossen keine diffs einzuspielen. Wenn du also Änderungen vornehmen willst, schreibe eine kurze Mail an Kristian oder Thomas Nesges (siehe auch Sektion F Wer bekommt einen CVS Account mit Schreibrecht?").
A.16 Wie sollen neue Einträge in der Datei changes.xml vorgenommen werden?
Die Datei changes.xml hat mit dem Containerelement changes ein Element um alle Änderungen zwischen zwei Builddaten der FAQ festzuhalten. Das heißt, dass ein changes Element immer alle Änderungen in Form von change, globchange, delete Elementen von einem "offiziellen" Build zum nächsten beinhalten soll. Vor einem Build hat das Attribut date des changes Elementes also Pseudocharakter. Änderungen werden immer im obersten changes Element festgehalten, beim nächsten Build wird das date Attribut aktualisiert und ein neuer Container wird angelegt (siehe auch Wie sieht die Struktur der übrigen XML-Files aus?).
A.17 Welche Tools brauche ich, um an der FAQ zu arbeiten?

Um die FAQ zu bearbeiten, brauchst du die folgenden Tools und Programme:

  • CVS Client
  • Texteditor
  • Java
  • XSL-Engine
  • FO Prozessor
  • css2fo.pl
  • tidy
  • Browser
  • make
  • sed
  • perl
  • lynx

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.

A.18 Wie installiere ich Xalan?

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.

A.19 Wie kann ich FOP nutzen?

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!

A.20 Ich möchte eine Dokumentation schreiben, an wen kann ich mich wenden?
Im Rahmen von dcoul.de gibt es zwei Mailinglisten auf denen Autoren diskutieren:

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.
Die Liste dcoul-de@buug.de befasst sich mit dem dcoul.de-Project allgemein. Das heißt, dass hier alle dcoul.de Themen außer der FAQ diskutiert werden. Willst du also einen Artikel für dcoul.de verfassen, wende dich an diese Liste.
Außerhalb des dcoul.de-Projektes gibt es einige andere Gruppen, die vielleicht eher deinen Geschmack treffen. Sie alle genauer zu erläutern würde zu weit führen, hier nur ein kurzer Überblick:
A.21 Wie kann ich innerhalb der FAQ auf Manual Seiten (man pages) verweisen?
Dazu ist das Element man definiert. Es hat ein optionales Attribut section in dem eine bestimmte Manual Sektion angegeben werden kann. Das man wird per XSLT in einen Link auf http://unixhelp.ed.ac.uk/CGI/man-cgi transformiert.