home *** CD-ROM | disk | FTP | other *** search
/ ftp.pasteur.org/FAQ/ / ftp-pasteur-org-FAQ.zip / FAQ / de / comp / linux / dcoul-faq / sectionA / text0000.txt < prev   
Encoding:
Text File  |  2004-04-19  |  31.8 KB  |  780 lines
  1. Archive-name: de/comp/linux/dcoul-faq/sectionA
  2. Posting-frequency: monthly
  3. Last-modified: 2004-04-18 13:49:36
  4. Version: CVS revision 1.52
  5. URL: http://www.dcoul.de/faq/
  6.  
  7.                                               http://www.dcoul.de/faq/
  8.   _________________________________________________________________
  9.  
  10. A. Wissenswertes fⁿr Autoren
  11.  
  12. Diese Sektion informiert Autoren und angehende Autoren ⁿber die
  13. technische Struktur der dcoul-FAQ und gibt Tipps zum Umgang mit den
  14. verschiedenen Tools die zur Erzeugung der FAQ eingesetzt werden. Die
  15. Struktur der XML Dateien wird erlΣutert, der Umgang mit dem CVS Server
  16. wird an Beispielen erklΣrt und man erfΣhrt wie man ⁿberhaupt als Autor
  17. am FAQ-Projekt teilnehmen kann.
  18.   _________________________________________________________________
  19.  
  20. A.1 Kommandos der Mailingliste
  21.  
  22. Die Mailingliste wird per Mailman <http://www.list.org/> gemanaged.
  23. Mailman wird primΣr ⁿber ein Webinterface administriert. An- und
  24. Abmeldung und Einstellen der pers÷nlichen Optionen ist auf
  25. https://buug.de/cgi-bin/mailman/listinfo/linux-faq/ m÷glich.
  26. Man kann das auch per E-Mail an linux-faq-request@buug.de erledigen,
  27. folgende Kommandos sind bekannt, die Angaben in eckigen Klammern sind
  28. optional:
  29.   * subscribe [address=E-Mail-adresse]: Anmeldung
  30.   * unsubscribe Passwort [address=E-Mail-adresse]: Abmeldung
  31.   * info: Informartionen ⁿber die Liste
  32.   * set option on|off Passwort: (de)aktiviert bestimmte Optionen.
  33.        + ack: BestΣtigung fⁿr an die Liste versandte Mails.
  34.        + digest: Zustellung als einzelne Mails oder gesammelt.
  35.        + plain: Sammelmails als plain-text statt MIME verschicken.
  36.        + nomail: Keine Mails zustellen, z.B. anstelle sich temporΣr
  37.          abzumelden
  38.        + norcv: Kein Empfang selbst versandter Mails an die Liste
  39.  
  40. Ausfⁿhrlichere Informationen und Hinweise auf weitere Kommandos und
  41. Optionen und Informationen erhΣlt man nach einem Mail mit Betreff help
  42. an linux-faq-request@buug.de.
  43.  
  44. A.2 Wie ist die XML Struktur der Sektionen zu verstehen?
  45.  
  46. Um die Struktur der XML Files zu verstehen sieht man sich am besten
  47. die DTDs (Document Type Definition) dazu an. Die Datei section.dtd
  48. beschreibt die Element-Struktur der XML Dateien fⁿr Sektionen
  49. (section?.xml).
  50.              <!ELEMENT section (title, sectionid, preamble?, faq+)>
  51.  
  52. Eine Section beginnt immer mit einem Element section. Diese Element
  53. wird auch root-node (Wurzel-Knoten) genannt, da es die Wurzel einer
  54. Baumstruktur bildet.
  55. Das section Element muss ein title, ein sectionid und mindestens ein
  56. faq Element enthalten, und es bildet damit die Grundstruktur fⁿr ein
  57. Section-File.
  58.                      <!ATTLIST section
  59.                              date    CDATA   #REQUIRED
  60.                              title   CDATA   #IMPLIED>
  61.  
  62. Damit das section Element nicht nur die Eigenschaft des root-nodes
  63. hat, transportiert es in den Attributen date und title Informationen
  64. ⁿber das Dokument. date enthΣlt das Datum der letzten ─nderung an der
  65. Datei und ist zwingend notwendig. title enthΣlt den Titel des
  66. Dokumentes. Dieser Titel ist nicht derjenige, der spΣter oben als
  67. ▄berschrift erscheint, sondern dient zur Identifizierung der Datei.
  68. Dieses Attribut ist nicht vorgeschrieben (#IMPLIED).
  69.                      <!ELEMENT title (#PCDATA)>
  70.                      <!ELEMENT sectionid (#PCDATA)>
  71.                              <!ATTLIST sectionid
  72.                                      id      ID      #REQUIRED>
  73.  
  74. Das Element title bildet die ▄berschrift der Section (die, die spΣter
  75. oben auf der Seite erscheint). ▄ber das Element sectionid muss eine
  76. Section eindeutig identifizierbar sein. Die sectionid dient als
  77. Grundlage fⁿr Querverweise innerhalb und von au▀erhalb der FAQ und
  78. bildet gleichzeitig den Dateinamen der HTML Dateien (z.B. 1.html wΣre
  79. das HTML Dokument, das aus der Section mit sectionid 1 erzeugt wurde).
  80. Das id Attribut dient zurzeit als Dummy Attribut fⁿr die EintrΣge in
  81. der Datei changes.xml und muss den ID-Wert "sec" + sectionid
  82. enthalten. Ein Beispiel: <sectionid id="secX">X</sectionid>
  83.                      <!ELEMENT preamble ANY>
  84.                              <!ATTLIST preamble
  85.                                      author  IDREF   #IMPLIED>
  86.  
  87. Das Element preamble dient dazu ein Vorwort zur Sektion zu verfassen.
  88. Es kann jeden m÷glichen Markup enthalten. Das Attribut author sollte
  89. der Autor des Vorwortes mit seiner ID fⁿllen.
  90.                      <!ELEMENT faq (question, answer, comment*)>
  91.                              <!ATTLIST faq
  92.                                      id      ID     #REQUIRED>
  93.  
  94. Das Element faq bildet einen Container fⁿr eine Frage (question), die
  95. dazu geh÷rende Antwort (answer) und eventuelle Kommentare (comment).
  96. Frage und Antwort mⁿssen jeweils genau einmal vorkommen, Kommentare
  97. k÷nnen beliebig viele enthalten sein (beliebig schlie▀t 0 mit ein!).
  98. Das Attribut id ist ein eindeutiger Bezeichner der FAQ, mittels dessen
  99. auf die FAQ referenziert werden kann.
  100.                              <!ELEMENT question (#PCDATA)>
  101.                              <!ELEMENT answer ANY>
  102.                                      <!ATTLIST answer
  103.                                              author  IDREF   #IMPLIED>
  104.                              <!ELEMENT comment ANY>
  105.                                      <!ATTLIST comment
  106.                                              type    (noprint|print) "noprin
  107. t"
  108.                                              author  IDREF   #REQUIRED>
  109.  
  110. Das question Element enthΣlt eine Frage, zu der das answer Element die
  111. Antwort gibt. Im author Attribut sollte sich der Autor der Antwort mit
  112. seiner ID verewigen. Wenn jemand diese kommentieren m÷chte, kann er
  113. dies mit Hilfe des comment Elementes tun. Das comment Element hat zwei
  114. Attribute: type gibt an, ob der Kommentar in der HTML Ausgabe
  115. erscheinen soll ("print") oder nicht ("noprint"). StandardmΣ▀ig wird
  116. "noprint" angenommen. Im author Attribut muss der Kommentator seine ID
  117. angeben.
  118.  
  119. A.3 Wie sieht die Struktur der ⁿbrigen XML-Files aus?
  120.  
  121. Auch hier schaut man am besten wieder in die DTDs der einzelnen
  122. Dateien.
  123.  
  124.  authors.xml
  125.  
  126.              <!ELEMENT authors (author+, user*)>
  127.                      <!ATTLIST authors
  128.                              date    CDATA   #REQUIRED
  129.                              title   CDATA   #IMPLIED>
  130.  
  131.                      <!ELEMENT author ANY>
  132.                              <!ATTLIST author
  133.                                      name    CDATA   #REQUIRED
  134.                                      job     CDATA   #REQUIRED
  135.                                      mail    CDATA   #IMPLIED
  136.                                      id      ID      #REQUIRED>
  137.  
  138.                      <!ELEMENT user ANY>
  139.                              <!ATTLIST user
  140.                                      name    CDATA   #REQUIRED
  141.                                      mail    CDATA   #IMPLIED
  142.                                      id      ID      #REQUIRED>
  143.  
  144. Die Datei authors.xml enthΣlt Informationen ⁿber alle Mitwirkenden an
  145. der FAQ. Aktive Mitglieder in der Mailingliste, die auch einen CVS
  146. Account haben, werden normalerweise als authors betrachtet, wΣhrend
  147. Leser, die eine Kommentar, eine Korrektur oder einen neuen Vorschlag
  148. eingereicht haben, als user aufgefⁿhrt werden. Beide Elemente haben
  149. Σhnliche Attribute. name enthΣlt den Namen des Autoren/Users, mail die
  150. E-Mail Adresse (die Angabe ist optional). ▄ber das Attribut id, kann
  151. der Autor referenziert werden. Der Wert der id muss FAQ-weit eindeutig
  152. sein! Fⁿr Autoren werden normalerweise die Initialen in
  153. Gro▀buchstaben, fⁿr User der volle Name in Kleinbuchstaben verwendet.
  154. Das author Element hat zusΣtzlich noch das Attribut job welches die
  155. Hauptaufgabe des Autoren enthΣlt (meine Hauptaufgabe ist z.B. die
  156. XML/HTML Struktur der FAQ).
  157. Beide Elemente k÷nnen zusΣtzliche Informationen zur Person
  158. einschlie▀en. Beim user wird das normalerweise eine Notiz zum
  159. eingereichten Vorschlag sein.
  160. Die Informationen ⁿber Autoren erscheinen auf der Index-Seite der FAQ.
  161. Die vollen Informationen ⁿber Autoren und User erscheinen in Sektion
  162. F.
  163.  
  164.  changes.xml
  165.  
  166.              <!ELEMENT changesd (dummyhook?,changes+)>
  167.                      <!ATTLIST changesd
  168.                              date    CDATA   #REQUIRED
  169.                              title   CDATA   #IMPLIED>
  170.  
  171.                      <!ELEMENT changes (change+)>
  172.                              <!ATTLIST changes
  173.                                      date    CDATA   #REQUIRED>
  174.  
  175.                                      <!ELEMENT change (#PCDATA)>
  176.                                              <!ATTLIST change
  177.                                                      section CDATA   #REQUIR
  178. ED
  179.                                                      faq     IDREF   #REQUIR
  180. ED>
  181.  
  182.                              <!ELEMENT delete ANY>
  183.                              <!ATTLIST delete
  184.                                      section CDATA   #REQUIRED
  185.                                      faq     CDATA   #REQUIRED
  186.                                      rev     CDATA   #REQUIRED>
  187.  
  188.                              <!ELEMENT globchange ANY>
  189.  
  190.                      <!ELEMENT dummyhook EMPTY>
  191.                              <!ATTLIST dummyhook
  192.                                      id      ID      #IMPLIED>
  193.  
  194. Die Datei changes.xml enthΣlt alle inhaltlichen ─nderungen an der FAQ
  195. zwischen zwei Builds/Releases. Dazu ist ein Container changes
  196. definiert, der im Attribut date das Datum des aktuellen Builds
  197. enthΣlt. Dieses wird immer von demjenigen geΣndert, der ein neues
  198. Build macht (momentan ist das Thomas Nesges (thomas@dcoul.de)). Dieser
  199. setzt in date das Datum des Builds ein (das aktuelle Datum). Damit ist
  200. dieser changes Container abgeschlossen und er er÷ffnet darⁿber einen
  201. neuen Container. Fⁿr alle anderen Autoren gilt also, dass sie weder
  202. neue changes Container anlegen, noch sich an dem m÷glicherweise
  203. falschen Datum im date st÷ren mⁿssen. Es mⁿssen einfach nur im
  204. obersten Container Element der changes.xml Datei neue change Elemente
  205. angelegt werden.
  206. Der Container enthΣlt mindestens ein change Element, welches eine
  207. einzelne ─nderung an einem durch die Attribute section und faq genau
  208. spezifizierten FAQ-Eintrag enthΣlt. Das Attribut faq enthΣlt ab sofort
  209. die ID des Eintrags (nicht mehr die Nr)! Um Probleme mit der
  210. Validierung der Dokumente zu umgehen, kann das faq Attribut mit dem
  211. Wert dummy gefⁿllt werden. Dieses ID-Element wird durch das neue
  212. dummyhook definiert, welches am Anfang von changes.xml steht und
  213. dessen Attribut id den Wert dummy hat. Ein typischer Anwendungsfall
  214. ist zum Beispiel ein Bezug auf ein gel÷schtes FAQ-Element.
  215. Gel÷schte FAQ-Elemente werden nicht mit dem Element change, sondern
  216. mit delete ausgezeichnet. Dieses Element Σhnelt dem change Element in
  217. seinen Attributen, allerdings ist faq hier vom Typ CDATA, welcher
  218. nicht validiert wird. Dadurch kann hier die originale ID verwendet
  219. werden, ohne dass sie im Dokument vorkommen muss (bei gel÷schten
  220. Elementen der Fall). Neu ist das rev. In ihm wird die Revisionsnummer
  221. der Revision angegeben, in der das gel÷schte Element zuletzt vorkam.
  222. Dadurch kann ein Link auf das CVS Webinterface erstellt werden, ⁿber
  223. den der Leser sich das gel÷schte nochmal ansehen kann.
  224. Das Element globchange dient dazu ─nderungen auszuzeichen, die sich
  225. auf die gesamte FAQ auswirken und nicht an einer bestimmten Frage oder
  226. Sektion festzumachen sind. Es kann allen m÷glichen Markup enthalten
  227. und hat keine Attribute.
  228.  
  229.  links.xml
  230.  
  231.              <!ELEMENT links (link+)>
  232.                      <!ATTLIST links
  233.                              date    CDATA   #REQUIRED
  234.                              title   CDATA   #IMPLIED>
  235.  
  236.                      <!ELEMENT link (#PCDATA)>
  237.                              <!ATTLIST link
  238.                                      href    CDATA   #REQUIRED
  239.                                      title   CDATA   #IMPLIED>
  240.  
  241. Die Datei links.xml enthΣlt Links, die auf der Index-Seite der FAQ
  242. erscheinen sollen. Das Element link hat ein Attribut href, welches den
  243. URL enthΣlt und ein optionales Attribut title, welches einen Titel fⁿr
  244. den Link definieren kann. Fehlt dieses Attribut, wird fⁿr den
  245. Linktitel automatisch der Wert aus href genommen.
  246.  
  247.  preamble.xml
  248.  
  249.              <!ELEMENT preamble (title, text)>
  250.                      <!ATTLIST preamble
  251.                              date    CDATA   #REQUIRED
  252.                              title   CDATA   #IMPLIED>
  253.  
  254.                      <!ELEMENT title (#PCDATA)>
  255.                      <!ELEMENT text ANY>
  256.  
  257. Die Datei preamble.xml enthΣlt ein Vorwort zur FAQ. Dieses Vorwort
  258. wird auf der Index-Seite angezeigt. Das Element title definiert einen
  259. Titel, das Element text EnthΣlt den Text des Vorworts. Der Text kann
  260. aus gⁿltigem Markup bestehen (dazu wird html.dtd eingebunden).
  261.  
  262.  overview.xml
  263.  
  264.              <!ELEMENT overview (intro, version+)>
  265.                      <!ATTLIST overview
  266.                              date    CDATA   #REQUIRED
  267.                              title   CDATA   #IMPLIED>
  268.  
  269.                      <!ELEMENT intro (#PCDATA)>
  270.                      <!ELEMENT version (title, browser?, files, text)>
  271.                              <!ATTLIST version
  272.                                      type    CDATA   #IMPLIED
  273.                                      dir     CDATA   #REQUIRED>
  274.  
  275.                              <!ELEMENT title (#PCDATA)>
  276.                              <!ELEMENT browser (#PCDATA)>
  277.                              <!ELEMENT files (file*, tgz*)>
  278.                                      <!ELEMENT file (#PCDATA)>
  279.                                      <!ELEMENT tgz (#PCDATA)>
  280.                              <!ELEMENT text (#PCDATA)>
  281.  
  282. Die Datei overview.xml enthΣlt eine ▄bersicht ⁿber alle Ausgabeformate
  283. der FAQ und kann als Gesamtindex betrachtet werden. Das Element intro
  284. beinhaltet einen einleitenden Text, danach folgen mehrere version
  285. Elemente, von denen jedes fⁿr ein Ausgabeformat steht. Im type
  286. Attribut kann der Mime-Type des Formates angegeben werden (z.B.
  287. text/html, text/plain), das Attribut dir bestimmt das
  288. Unterverzeichnis, in dem die Version auf dem Webserver abgelegt ist.
  289. Das Element title gibt einen Titel fⁿr den Abschnitt der Version auf
  290. der Overview Seite an, im Element browser k÷nnen empfohlene Browser
  291. angegeben werden, falls n÷tig. Das Containerelement files kann
  292. beliebig viele file und tgz Elemente enthalten. Fⁿr jede Datei der
  293. Version sollte ein file Element angelegt werden, das tgz Element
  294. enthΣlt den Speicherplatz eines Tar Archives aller Files. Im Element
  295. text k÷nnen noch nΣhere ErlΣuterungen zu der Version angegeben werden.
  296.  
  297. A.4 Mit welchen Tags kann ich die Antworttexte formatieren?
  298.  
  299. Zur Formatierung der Texte innerhalb der FAQ sind in html.dtd und
  300. misc.dtd einige Tags definiert. html.dtd definiert dabei Nachbildungen
  301. von bekannten HTML Tags, im einzelnen:
  302.              <!ELEMENT a (#PCDATA)>
  303.                      <!ATTLIST a
  304.                              href CDATA #REQUIRED>
  305.              <!ELEMENT br EMPTY>
  306.              <!ELEMENT hr EMPTY>
  307.              <!ELEMENT code ANY>
  308.              <!ELEMENT i ANY>
  309.              <!ELEMENT ul (li+)>
  310.              <!ELEMENT ol (li+)>
  311.              <!ELEMENT li ANY>
  312.              <!ELEMENT pre ANY>
  313.              <!ELEMENT h3 ANY>
  314.              <!ELEMENT h4 ANY>
  315.  
  316. Diese Tags sind genauso wie ihre HTML ─quivalente anzuwenden.
  317. In misc.dtd sind zusΣtzliche Tags definiert, die speziell fⁿr diese
  318. XML Anwendung Geltung haben:
  319.              <!ELEMENT faqlink (#PCDATA)>
  320.                      <!ATTLIST faqlink
  321.                              sec     CDATA   #REQUIRED
  322.                              id      CDATA   #REQUIRED
  323.                              title   CDATA   #IMPLIED>
  324.  
  325.              <!ELEMENT file (#PCDATA)>
  326.              <!ELEMENT dir (#PCDATA)>
  327.              <!ELEMENT attribute (#PCDATA)>
  328.              <!ELEMENT element (#PCDATA)>
  329.              <!ELEMENT authorref EMPTY>
  330.                      <!ATTLIST authorref
  331.                              id      IDREF   #REQUIRED>
  332.              <!ELEMENT insertauthors EMPTY>
  333.              <!ELEMENT codeblock (#PCDATA)>
  334.  
  335.              <!ELEMENT man (#PCDATA)>
  336.                      <!ATTLIST man
  337.                              section CDATA   #IMPLIED>
  338.  
  339. Das Element faqlink definiert einen Querverweis innerhalb der FAQ.
  340. Dazu kann kein normales <a> Tag verwendet werden, weil verschiedene
  341. Versionen der FAQ voneinander abweichende Dateistrukturen haben (z.B.
  342. DHTML Version). Im Attribut sec wird die Sektion, im Attribut id die
  343. ID der FAQ auf die Bezug genommen wird angegeben. Der Text der in den
  344. HTML Versionen angezeigt werden soll, wird entweder im Attribut title,
  345. oder im Content des Elementes angegeben.
  346.  
  347. Das file Element dient zur Auszeichnung von Dateinamen, dir fⁿr
  348. Verzeichnisnamen, attribute fⁿr Attribute und element markiert
  349. Elemente (und Tags). Die letztgenannten Elemente haben allesamt keine
  350. Attribute, sie dienen nur zur Visualisierung des Contents.
  351.  
  352. Das authorref dient dazu, um auf einen FAQ-Autoren zu referenzieren.
  353. Im Attribut id wird die ID des Autoren angegeben, per XSL wird ein
  354. Mailto-Link (<a href="mailto:..) erstellt.
  355.  
  356. Das insertauthors hat keine Attribute und keinen Content. Es
  357. veranlasst die XSL-Engine ein Template aufzurufen, welches alle
  358. Autoren aus authors.xml einzufⁿgen.
  359.  
  360. Ein codeblock wird dazu eingesetzt Bl÷cke von Befehlen, Sourcecode
  361. oder Σhnlichem darzustellen.
  362.  
  363. Das man definiert einen Verweis auf eine Manualseite. Siehe dazu Wie
  364. kann ich innerhalb der FAQ auf Manual Seiten (man pages) verweisen?.
  365.  
  366. A.5 Wofⁿr werden die DF_...xml Dateien gebraucht?
  367.  
  368. Die XML Dateien mit PrΣfix DF_ sind ausschlie▀lich fⁿr den make
  369. Prozess von Bedeutung. Sie verlinken die datenhaltenden XML Files
  370. (z.B. sectionA.xml) per Entityreferenz, so dass die Daten aus zum
  371. Beispiel authors.xml auch in alle Sektionen zur Verfⁿgung stehen. Dies
  372. muss in extra Dateien gemacht werden, da es sonst leicht zu mehrfachen
  373. oder gegenseitigen Links kommen kann, die logisch nicht sinnvoll sind
  374. und beim Validierungsprozess als fehlerhaft gemeldet werden, falls
  375. Attribute vom Typ ID verwendet worden sind (diese erscheinen durch
  376. mehrfache Links auch mehrfach und sind somit nicht mehr eindeutig).
  377.  
  378. A.6 Wie funktioniert XML?
  379.  
  380. Die Referenz zum Thema sind die Seiten des W3C unter
  381. http://www.w3.org/XML/. Diese sind allerdings sehr schwer
  382. verstΣndlich, daher ist das Tutorial auf http://www.w3schools.com/xml/
  383. fⁿr Einsteiger eher zu empfehlen.
  384.  
  385. A.7 Wie funktioniert XSL?
  386.  
  387. Auch zu diesem Thema sind die Seiten des W3C unter
  388. http://www.w3.org/Style/XSL/ die Referenz. Aber auch zu XSL ist fⁿr
  389. Einsteiger eher das Tutorial unter http://www.w3schools.com/xsl/ zu
  390. empfehlen.
  391.  
  392. A.8 Wie funktioniert CVS?
  393.  
  394. Kristian hat dazu eine gute Einfⁿhrung verfasst, die unter
  395. http://www.koehntopp.de/kris/artikel/cvs/ zu finden ist. Unter
  396. http://www.fokus.gmd.de/research/cc/glone/employees/matthias.kranz/pri
  397. vate/cvs_article.html findet man einen sehr guten Artikel aus dem
  398. Linux Magazin von Matthias Kranz.
  399.  
  400. A.9 Wie logge ich mich am CVS Server ein?
  401.  
  402. Wer and der FAQ aktiv mitarbeitet (mitarbeiten will), bekommt einen
  403. Acccount mit Schreibrecht, und kann diesen folgenderma▀en nutzen:
  404.              $ export CVS_RSH=ssh
  405.              $ export CVSROOT=:ext:account@buug.de:/home/cvs
  406.              $ cvs -d $CVSROOT co linux-faq
  407.  
  408. Wer neugierig ist und sich mal den Quellcode anschauen will, kann ⁿber
  409. das Webinterface die ganze FAQ als Tararchiv oder auch nur einzelne
  410. Dateien herunterladen.
  411.  
  412. A.10 Gibt es eine kurze ▄bersicht, wie ich am geschicktesten mit CVS
  413. arbeite?
  414.  
  415. Ja, die gibt es. Dazu hat Kristian ein Paper verfasst:
  416. Cheatsheet fⁿr CVS Benutzer:
  417.  
  418. 0. Ihr k÷nnte ja mal am TODO ⁿben.
  419.  
  420. 1. $HOME/.cvsrc
  421.  
  422. Die Datei $HOME/.cvsrc enthΣlt Default-Optionen fⁿr alle
  423. CVS-Kommandos. Ich habe die folgende Datei installiert:
  424.  
  425. -----
  426. cvs -q
  427. update -dAP
  428. diff -u
  429. status -v
  430. -----
  431.  
  432. Die erste Option bewirkt, dass alle CVS-Connects "-quiet" gemacht
  433. werden.
  434.  
  435. Bei einem CVS update werden automatisch alle Unterverzeichnisse
  436. mit aktualisiert (-d) und leere Unterverzeichnisse entfernt (-P,
  437. prune). Au▀erdem werden sticky-Tags entfernt und es wird immer
  438. die HEAD-Revision geholt (-A).
  439.  
  440. Ein diff wird automatisch mit der Option unified (-u)
  441. aufgerufen.
  442.  
  443. Ein status wird immer verbose (-v) durchgefⁿhrt.
  444.  
  445. 2. $HOME/.cvslist und automatisches Update
  446.  
  447. Ich habe eine Datei $HOME/.cvslist, die jeweils einen Workspace
  448. pro Zeile bezeichnet:
  449.  
  450. /home/kris/Source/mysql-faq
  451. /home/www/servers/kris.koehntopp.de/pages/php
  452. /home/kris/Source/linux-faq
  453.  
  454. Das Script cvs-upall wird vom Cron einmal pro Nacht fⁿr kris
  455. aufgerufen:
  456.  
  457. #! /bin/sh --
  458.  
  459. MAILTO=root
  460.  
  461. [ ! -f $HOME/.cvslist ] && exit 0
  462.  
  463. cat $HOME/.cvslist | while read line
  464. do
  465.   echo "updating $line"
  466.   cd $line
  467.   cvs update
  468.   echo
  469. done 2>&1 | mailx -s "cvs update `date +%Y-%m-%d`" $MAILTO
  470.  
  471. 3. Die wichtigsten Kommandos:
  472.  
  473. - Begriffe:
  474.  
  475.   - Repository: Zentrales Archiv auf dem Server
  476.   - Workspace: Deine Arbeitskopie
  477.  
  478. - Aktualisieren des Workspace
  479.  
  480.   - Wechsle in die Wurzel des Workspace
  481.   - cvs update
  482.  
  483.   - Aufruf nach Bedarf, zur Sicherheit einmal vor dem commit.
  484.  
  485.   cvs update Legende:
  486.  
  487.   - U update:   Neue Datei
  488.   - P patched:  Datei vom Repository in den Workspace aktualisiert
  489.   - M modified: Datei im Workspace ist modified, commit steht aus
  490.   - A added:    Datei im Workspace ist neu, commit steht aus
  491.   - D deleted:  Datei im Worksapce ist gel÷scht, commit steht aus
  492.  
  493. - commit von ─nderungen
  494.  
  495.   - Immer direkt nach einem Update.
  496.   - Immer mit sinnvollem Kommentar. Der Kommentar wird Teil der
  497.  Mail.
  498.   - cvs commit
  499.  Commited alle M, A und D. Nicht immer sinnvoll.
  500.   - cvs commit file1 file2 dir1/file3
  501.  Commited die genannten Dateien, falls sie M, A oder D sind.
  502.  
  503. - Dateien zufⁿgen und l÷schen
  504.  
  505.   - Datei anlegen            - Datei l÷schen
  506.   - cvs add file1            - cvs remove file1
  507.   - cvs commit               - cvs commit
  508.  
  509. - Verzeichnisse anlegen
  510.  
  511.   - NICHT MACHEN, au▀er es ist abgesprochen.
  512.   - Verzeichnisse k÷nnen nicht gel÷scht werden, weil ja bei einem
  513.  checkout der alten Version gel÷schte Dateien wieder auftauchen
  514.  k÷nnen.
  515.   - -P Option l÷scht leere Verzeichnisse, das ist als hΣtte
  516.  man es gel÷scht.
  517.  
  518.   - mkdir dir1; cvs add dir1; cvs commit
  519.  
  520. - Was haben die anderen gemacht?
  521.  
  522.   - cvs diff
  523.  Listet die ─nderungen im Repository gegen den Workspace.
  524.  
  525.   - cvs annotate file1
  526.  Listet die Datei Zeile fⁿr Zeile, mit ─nderungsdatum
  527.  
  528. - Alte Version bekommen
  529.  
  530.   Fⁿr uns ist der Zugriff nach Datum wichtig, da wir keine
  531.   Releases taggen werden.
  532.  
  533.   - cvs update -D 2000-12-29
  534.  Holt die Version vom 29. Dezember 2000 zurⁿck.
  535.  
  536.  Dies ist sticky, d.h. wird die Option -A nicht mit angegeben
  537.  beim "cvs update", bleibt das Repository auf diesem alten
  538.  Stand. Mit dem .cvsrc von oben ist "-A" immer mit angegeben.
  539.  
  540.  Alte Versionen k÷nnen nicht comitted werden, ohne zu
  541.  branchen. Branches sind unⁿbersichtlich UND ZU VERMEIDEN!
  542.  
  543. Kristian
  544.  
  545. A.11 Wie gehe ich mit Einreichungen von Usern um?
  546.  
  547. Wenn ein User einen Vorschlag einsendet, wird die Mail auf dem CVS
  548. Server im Verzeichnis vorschlaege/ gespeichert. Dort bleibt die Mail
  549. solange, bis jemand den Vorschlag weiterbearbeitet.
  550. Derjenige, der die Mail bearbeitet, gibt kurz auf der Mailingliste
  551. Bescheid, damit die Arbeit nicht doppelt gemacht wird.
  552. ZunΣchst ist zu prⁿfen, ob die Korrektur oder der Vorschlag korrekt
  553. ist, d.h. stimmen angegebene URLs, sind angegebene Kommandos
  554. unbedenklich und zielfⁿhrend, usw. Ist dies der Fall, wird die
  555. Korrektur vorgenommen, bzw. der Vorschlag in die passende Section
  556. ⁿbernommen.
  557. Der einreichende User ist als <user> in die Datei authors.xml
  558. aufzunehmen (dazu geh÷rt ein kurzer Kommentar zum eingereichten
  559. Vorschlag), und in der Datei changes.xml ist die ─nderung zu
  560. vermerken. Danach kann die Mail aus vorschlaege/ gel÷scht werden.
  561.  
  562. A.12 Wie kann ich die Archive der Mailingliste einsehen?
  563.  
  564. Die Mailingliste ist vollkommen ÷ffentlich, d.h jeder kann eine Mail
  565. an die Liste senden - auch ohne subscribed zu sein. Und zusΣtzlich
  566. kann auch jeder die Archive der Liste einsehen. Dazu gibt es unter
  567. https://buug.de/pipermail/linux-faq/ ein Webinterface.
  568.  
  569. A.13 Gibt es ein Webinterface zum CVS Repository?
  570.  
  571. Ja, das gibt es. Unter
  572. https://buug.de/cgi-bin/viewcvs.cgi/?cvsroot=linux-faq findet sich ein
  573. anonymer readonly Account zum CVS Repository. Dort k÷nnen alle Files
  574. angesehen und einzeln downloaded werden.
  575.  
  576. A.14 Wo werden neue Fragen in der FAQ eingefⁿgt?
  577.  
  578. Neue Fragen sollten immer unten in der passenden Sektion eingefⁿgt
  579. werden, damit sich die automatisch generierte FAQ-Nr nicht Σndert.
  580. Alle FAQs sind zwar durch das Attribut id eindeutig gekennzeichnet,
  581. aber viele Benutzer werden auf die Fragen mit der Angabe der Nummer
  582. referenzieren ("Steht in dcoul-FAQ Sektion X FAQ-Nr 4711") und keinen
  583. eindeutigen URL mit der ID angeben ("Steht in
  584. http://www.dcoul.de/faq/X.html#tubesenf").
  585.  
  586. A.15 Ich habe ─nderungen vorgenommen und ein diff erstellt. Wer spielt
  587. das ein?
  588.  
  589. Da prinzipiell jeder einen CVS Account mit Schreibrecht erhalten kann,
  590. haben wir uns entschlossen keine diffs einzuspielen. Wenn du also
  591. ─nderungen vornehmen willst, schreibe eine kurze Mail an Kristian oder
  592. Thomas Nesges (thomas@dcoul.de) (siehe auch Sektion F Wer bekommt
  593. einen CVS Account mit Schreibrecht?").
  594.  
  595. A.16 Wie sollen neue EintrΣge in der Datei changes.xml vorgenommen
  596. werden?
  597.  
  598. Die Datei changes.xml hat mit dem Containerelement changes ein Element
  599. um alle ─nderungen zwischen zwei Builddaten der FAQ festzuhalten. Das
  600. hei▀t, dass ein changes Element immer alle ─nderungen in Form von
  601. change, globchange, delete Elementen von einem "offiziellen" Build zum
  602. nΣchsten beinhalten soll. Vor einem Build hat das Attribut date des
  603. changes Elementes also Pseudocharakter. ─nderungen werden immer im
  604. obersten changes Element festgehalten, beim nΣchsten Build wird das
  605. date Attribut aktualisiert und ein neuer Container wird angelegt
  606. (siehe auch Wie sieht die Struktur der ⁿbrigen XML-Files aus?).
  607.  
  608. A.17 Welche Tools brauche ich, um an der FAQ zu arbeiten?
  609.  
  610. Um die FAQ zu bearbeiten, brauchst du die folgenden Tools und
  611. Programme:
  612.   * CVS Client
  613.   * Texteditor
  614.   * Java
  615.   * XSL-Engine
  616.   * FO Prozessor
  617.   * css2fo.pl
  618.   * tidy
  619.   * Browser
  620.   * make
  621.   * sed
  622.   * perl
  623.   * lynx
  624.  
  625. Den CVS Client brauchst du um dir die Sourcen der FAQ aus dem
  626. Repository zu besorgen, und um deine ─nderungen spΣter wieder
  627. einzuchecken. Die Sourcen der FAQ liegen als ASCII-Text vor, also
  628. brauchst du einen Texteditor um sie zu bearbeiten.
  629.  
  630. Java wird zum Betrieb der Tools Xalan und FOP ben÷tigt, wenn andere
  631. Tools als XSL-Engine und FO Prozessor eingesetzt werden ist Java also
  632. evtl. nicht n÷tig. Ein aktuelles JDK (Java Development Kit) ist unter
  633. http://java.sun.com/ erhΣltlich. Die meisten Distributionen liefern
  634. allerdings auch eine Java Version mit.
  635.  
  636. Die XSL-Engine brauchst du, um die XML Dateien in die verschiedenen
  637. Versionen zu konvertieren. Bisher hat sich gezeigt, dass die einzige
  638. XSL-Engine die weit genug implementiert ist um die FAQ zu ⁿbersetzen
  639. Xalan in der Java Version ist. Xalan kannst du von
  640. http://xml.apache.org/ beziehen.
  641.  
  642. "FO" steht fⁿr Formatting Objects, ein in XSL definierter Vorschlag
  643. des W3C fⁿr einen Standard zur Layoutbeschreibung (Σhnlich zu CSS).
  644. Mit Hilfe von XSL-FO wird die PDF Version der FAQ formatiert, deshalb
  645. wird zur Erstellung dieser Version ein FO Prozessor ben÷tigt. Auch
  646. hier hat das Apache-Project mit FOP sehr gute Arbeit geleistet, FOP
  647. ist wie Xalan von http://xml.apache.org/ zu beziehen.
  648.  
  649. css2fo.pl wird im bin Verzeichnis der FAQ mitgeliefert. Es ist ein
  650. Perlskript, welches CSS Files in XSL-FO konvertiert. Dadurch brauchen
  651. die Stylesheet Angaben nur in einem File editiert werden.
  652.  
  653. tidy untersucht HTML Quellcode auf Fehler und versucht diese gleich zu
  654. korrigieren. Dabei formatiert tidy den HTML Code gleichzeitig um. tidy
  655. kann von http://www.w3.org/People/Raggett/tidy/ heruntergeladen
  656. werden.
  657.  
  658. Um die Ergebnisse der Transformation zu kontrollieren brauchst du
  659. einen bzw. besser mehrere Browser. Die FAQ sollte in allen gΣngigen
  660. Browsern darstellbar sein. Um ein Build der FAQ zu machen brauchst du
  661. ein make Programm. Das sollte aber auf den meisten Installationen
  662. bereits vorhanden sein. Ebenso wie sed und perl, die im Makefile
  663. verwendet werden, um die XML Files zu bearbeiten. Der Textbrowser lynx
  664. schlie▀lich wird gebraucht, um die Textversion der FAQ zu erstellen.
  665.  
  666. A.18 Wie installiere ich Xalan?
  667.  
  668. Die Xalan Distribution ist unter http://xml.apache.org/ zu finden.
  669. Nach dem Download kann man entweder die mitgelieferten JAR Files
  670. benutzen, oder Xalan aus den Sourcen selbst bauen. ZunΣchst ist der
  671. Tarball an geeigneter Stelle zu entpacken:
  672.  
  673. thomas@crusher:/usr/local > tar xzf xalan-j_2_0_D07.tar.gz
  674.  
  675. Dabei wird ein Unterverzeichnis xalan-j_2_0_D07/ angelegt, in dem die
  676. JAR-Files und die Sourcen zu finden sind.
  677.  
  678. thomas@crusher:/usr/local > cd xalan-j_2_0_D07/
  679.  
  680. Will man Xalan aus den Sourcen bauen, sind folgende Schritte
  681. durchzufⁿhren:
  682.  
  683. thomas@crusher:/usr/local/xalan-j_2_0_D07 > perl -i -ne 's/\r\n/\n/;
  684. print'
  685. build.sh
  686. thomas@crusher:/usr/local/xalan-j_2_0_D07 > chmod 755 build.sh
  687. thomas@crusher:/usr/local/xalan-j_2_0_D07 > which java
  688. /usr/src/jdk1.3/bin/java
  689. thomas@crusher:/usr/local/xalan-j_2_0_D07 > export
  690. JAVA_HOME="/usr/src/jdk1.3/"
  691. thomas@crusher:/usr/local/xalan-j_2_0_D07 >./build.sh
  692. [...]
  693. thomas@crusher:/usr/local/xalan-j_2_0_D07 > cd build
  694. thomas@crusher:/usr/local/xalan-j_2_0_D07/build > ls
  695. classes xalan.jar
  696.  
  697. ZunΣchst sind die Zeilenende Zeichen im build.sh zu ersetzen. Mit
  698. chmod 755 wird das Skript ausfⁿhrbar gemacht. Zur Installation muss
  699. eine Umgebungsvariable JAVA_HOME gesetzt werden, die auf das Java
  700. Installationsverzeichnis zeigt. Dazu wird which java ausgefⁿhrt. Der
  701. Teil des Verzeichnisnamens bis zum bin ist das JAVA_HOME (hier also
  702. /usr/src/jdk1.3/). Nach Ausfⁿhren von build.sh sollte im
  703. Unterverzeichnis build/ ein Verzeichnis classes, welches alle
  704. Classfiels beinhaltet, und eine Datei xalan.jar zu finden sein.
  705.  
  706. Im Verzeichnis bin/ findet sich das xalan.jar der Distribution und ein
  707. xerces.jar, welches von Xalan ben÷tigt wird. Jetzt setzt man noch ein
  708. einfaches Shellskript auf um Xalan anzuwerfen:
  709.  
  710. --[/usr/local/bin/xalan]--
  711. #!/bin/sh
  712. XALAN="/usr/local/xalan-j_2_0_D07/build/xalan.jar";
  713. XERCES="/usr/local/xalan-j_2_0_D07/bin/xerces.jar";
  714. CLASSPATH="$XALAN:$XERCES:$CLASSPATH";
  715. export CLASSPATH
  716. java org.apache.xalan.xslt.Process -in "$1" -xsl "$2" -out "$3";
  717. ---
  718.  
  719. Wenn man Xalan nicht aus den Sourcen gebaut hat, ist die Variable
  720. XALAN auf /usr/local/xalan-j_2_0_D07/bin/xalan.jar zu setzen. Damit
  721. ist Xalan per `xalan in.xml trans.xsl out.html` benutzbar. Das
  722. entspricht auch der im Makefile benutzten Syntax.
  723.  
  724. A.19 Wie kann ich FOP nutzen?
  725.  
  726. Die Installation von FOP lΣuft analog zur Installation der XSL-Engine
  727. Xalan, die in beschrieben ist.
  728.  
  729. Um FOP auszufⁿhren legt man sich am einfachsten ein Shellskript an:
  730.  
  731. --[/usr/local/bin/fop]--
  732. #!/bin/sh
  733. XERCES="/usr/local/xalan/bin/xerces.jar";
  734. XALAN="/usr/local/xalan/bin/xalan.jar";
  735. FOP="/usr/local/fop-0_16_0/fop.jar";
  736. W3C="/usr/local/fop-0_16_0/lib/w3c.jar";
  737. CLASSPATH="$XALAN:$XERCES:$FOP:$W3C:$CLASSPATH";
  738. export CLASSPATH
  739. java org.apache.fop.apps.XalanCommandLine $1 $2 $3
  740. ---
  741.  
  742. Achtung: FOP braucht in der aktuellen Version eine 1.x Version von
  743. Xalan!
  744.  
  745. A.20 Ich m÷chte eine Dokumentation schreiben, an wen kann ich mich
  746. wenden?
  747.  
  748. Im Rahmen von dcoul.de gibt es zwei Mailinglisten auf denen Autoren
  749. diskutieren:
  750.   * linux-faq@buug.de
  751.   * dcoul-de@buug.de
  752.  
  753. Vorsicht, es ist auf beide Listen nur fⁿr Abonnenten derselben
  754. m÷glich, BeitrΣge and diese Mailing-Listen zu schicken. Der Grund
  755. liegt im extrem hohen Spamaufkommen.
  756. Die Liste linux-faq@buug.de befasst sich ausschlie▀lich mit dieser
  757. FAQ. Dort werden inhaltliche und technische Aspekte der FAQ
  758. diskutiert. Wenn du also einen Beitrag zur FAQ leisten willst, ist
  759. diese Liste die richtige Adresse.
  760. Die Liste dcoul-de@buug.de befasst sich mit dem dcoul.de-Project
  761. allgemein. Das hei▀t, dass hier alle dcoul.de Themen au▀er der FAQ
  762. diskutiert werden. Willst du also einen Artikel fⁿr dcoul.de
  763. verfassen, wende dich an diese Liste.
  764. Au▀erhalb des dcoul.de-Projektes gibt es einige andere Gruppen, die
  765. vielleicht eher deinen Geschmack treffen. Sie alle genauer zu
  766. erlΣutern wⁿrde zu weit fⁿhren, hier nur ein kurzer ▄berblick:
  767.   * Deutsches Linux HOWTO Projekt <http://www.linuxhaven.de/dlhp/>
  768.   * Linux Documentation Project <http://www.tldp.org/>
  769.  
  770. A.21 Wie kann ich innerhalb der FAQ auf Manual Seiten (man pages)
  771. verweisen?
  772.  
  773. Dazu ist das Element man definiert. Es hat ein optionales Attribut
  774. section in dem eine bestimmte Manual Sektion angegeben werden kann.
  775. Das man wird per XSLT in einen Link auf
  776. http://unixhelp.ed.ac.uk/CGI/man-cgi transformiert.
  777.   _________________________________________________________________
  778.  
  779. Build: 18.04.2004
  780.