Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!news2.telebyte.nl!border2.nntp.ams.giganews.com!border1.nntp.ams.giganews.com!nntp.giganews.com!fu-berlin.de!uni-berlin.de!not-for-mail

Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!news2.telebyte.nl!border2.nntp.ams.giganews.com!border1.nntp.ams.giganews.com!nntp.giganews.com!fu-berlin.de!uni-berlin.de!not-for-mail
From: [email protected] (dcoul-FAQ Team)
Newsgroups: de.comp.os.unix.linux.infos,de.answers,news.answers
Subject: de.comp.os.unix.linux.infos - FAQ (sectionA)
Followup-To: poster
Date: Sat, 28 Aug 2004 13:42:42 +0000 (UTC)
Organization: dcoul-FAQ Team
Lines: 780
Sender: Andreas Metzler <[email protected]>
Approved: [email protected]
Expires: Sat, 2 Oct 2004 07:02:40 GMT
Message-ID: <[email protected]>
References: <[email protected]>
Reply-To: [email protected]
Mime-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de pK3GJHs1zCaZGP2xWpRomQQTOd2tIQY4U4G3invsoWKlWilN8=
Summary: This is the FAQ of the german newsgroup hierarchy
de.comp.os.unix.linux (dcoul). This article provides answers to
linux and usenet questions. The text is written in german.
User-Agent: mkPosting.pl by Thomas Nesges <[email protected]>
X-Disclaimer: Approval for *.answers is based on form, not content.
Xref: senator-bedfellow.mit.edu de.comp.os.unix.linux.infos:3674 de.answers:10920 news.answers:275470

Archive-name: de/comp/linux/dcoul-faq/sectionA
Posting-frequency: monthly
Last-modified: 2004-08-28 15:40:07
Version: CVS revision 1.52
URL: http://www.dcoul.de/faq/

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 Mailman <http://www.list.org/> 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 [email protected] 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 [email protected].

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) "noprin
t"
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 #REQUIR
ED
faq IDREF #REQUIR
ED>

<!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 ([email protected])). 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/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?

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:[email protected]:/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 ([email protected]) (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:
* [email protected]
* [email protected]

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 [email protected] 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 [email protected] 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:
* Deutsches Linux HOWTO Projekt <http://www.linuxhaven.de/dlhp/>
* Linux Documentation Project <http://www.tldp.org/>

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

Build: 28.08.2004