|
Archive-name: /de/comp/linux/dcoul-faq/sectionA
Posting-frequency: monthly Last-modified: 2001-02-04 21:21:51 Version: CVS revision 1.36 URL: http://www.dcoul.de/faq/ See reader questions & answers on this topic! - Help others by sharing your knowledge
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.
_________________________________________________________________
A.1 Kommandos der Mailingliste
Die Mailingliste wird per EZMLM <http://www.ezmlm.org/> gemanaged.
EZMLM nimmt Kommandos in Form von Mails an bestimmte Adresse entgegen.
Folgende "Kommando-Mail-Adressen" sind dem Programm bekannt:
* linux-faq-info@lists.netuse.de
Allgemeine Infos zur Liste
* linux-faq-faq@lists.netuse.de
FAQ zur Mailingliste
* linux-faq-help@lists.netuse.de
Hilfe zu administrativen Kommandos der Mailingliste
* linux-faq-subscribe@lists.netuse.de
Einschreiben bei der Liste
* linux-faq-unsubscribe@lists.netuse.de
Austragen von der Liste
* linux-faq-owner@lists.netuse.de
Mail an den "Besitzer" der Liste
* linux-faq-get.1_10@lists.netuse.de
Anfordern der Mails mit den Nummern 1 - 10 (get.1_10). Es können
maximal 100 Artikel pro Anforderung versandt werden.
* linux-faq-index.1_10@lists.netuse.de
Anfordern eines Indexes über die Mails mit den Nummern 1 - 10
(index.1_10). Der Index enthält Subject und Autor der Mail.
* linux-faq-thread.12345@lists.netuse.de
Anfordern aller Mails aus dem Thread, der mit der Mail mit der
Nummer 12345 beginnt.
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 (thomas@dcoul.de)). 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 Attributem, 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 CVSWeb
<http://phplib.netuse.de/cgi/cvsweb.cgi/linux-faq/> erstellt werden,
über den der Leser sich das gelöschte nochmal ansehen kann.
Das Element globchange dient dazu Änderungen auszuzeichen, die sich
auf die gesammte 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)>
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 (zB
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 letzt genannten Elemente haben allesammt
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.
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/
<http://www.koehntopp.de/kris/artikel/cvs7> zu finden ist. Unter
http://www.fokus.gmd.de/research/cc/glone/employees/matthias.kranz/pri
vate/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?
Es gibt einen readonly Account am CVS Server, an dem sich jeder
einloggen kann um die aktuellen Sourcen aus dem CVS zu bekommen. Der
Username lautet cvsread und das Passwort lautet ebenfalls cvsread.
Einloggen kann man sich folgendermaßen:
$ export CVSROOT=:pserver:cvsread@phplib.netuse.de:/repository
$ cvs -d $CVSROOT login
Password: cvsread
$ cvs -d $CVSROOT co linux-faq
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 -z9
update -dAP
diff -u
status -v
-----
Die erste Option bewirkt, daß alle CVS-Connects "-quiet" gemacht
werden und "gzip -9" auf die Übertragung angewendet wird.
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
Comitted alle M, A und D. Nicht immer sinnvoll.
- cvs commit file1 file2 dir1/file3
Comitted 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
http://lists.netuse.de/list.php3?show_overview=linux-faq ein
Webinterface.
A.13 Gibt es ein Webinterface zum CVS Repository?
Ja, das gibt es. Unter
http://phplib.netuse.de/cgi/cvsweb.cgi/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 gekenzeichnet,
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 (thomas@dcoul.de) (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
heisst, 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ältich. 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öigt. 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 convertiert. 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
schliesslich 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 benoetigt 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 Maillisten auf denen Autoren
diskutieren:
* linux-faq@lists.netuse.de
* dcoul-de@lists.netuse.de
Die Liste linux-faq@lists.netuse.de befasst sich ausschliesslich 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@lists.netuse.de befasst sich mit dem
dcoul.de-Project allgemein. Das heisst, das hier alle dcoul.de Themen
ausser der FAQ diskutiert werden. Willst du also einen Artikel für
dcoul.de verfassen, wende dich an diese Liste.
Ausserhalb 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:
* Deutsches Linux HOWTO Projekt <http://tu-harburg.de/dlhp/>
* Linux Documentation Project <http://metalab.unc.edu/LDP>
* Linux Knowledge Base <http://linuxkb.cheek.com>
_________________________________________________________________
04.02.2001 dcoul-FAQ authors
User Contributions:
[ Usenet FAQs | Web FAQs | Documents | RFC Index ]
Send corrections/additions to the FAQ Maintainer: linux-faq@lists.netuse.de
Last Update March 27 2014 @ 02:11 PM
|
de.comp.os.unix.linux.infos - FAQ (sectionA)
Search the FAQ Archives
N - O - P - Q - R - S - T - U - V - W - X - Y - Z
de.comp.os.unix.linux.infos - FAQ (sectionA)
[ Usenet FAQs | Web FAQs | Documents | RFC Index | Airports ]
Comment about this article, ask questions, or add new information about this topic: