Wie man an den Debian-Webseiten arbeitet

Allgemeine Informationen

Ressourcen-Anforderungen

Wenn Sie an unserer Website arbeiten wollen, seien Sie bitte darauf vorbereitet, mindestens 250 MB an Daten auf Ihrer Platte zu speichern. Dies reflektiert die aktuelle Größe des Quellcode-Archivs. Wenn Sie (aus Versehen) alle Seiten neu bauen, werden Sie mindestens doppelt so viel Platz benötigen. Wenn Sie nur teilweise auschecken, benötigen Sie viel weniger Platz, z.B. 50 MB für english/.

Teilweises Auschecken

Viele Leute wollen nicht den kompletten webwml CVS-Verzeichnisbaum ausgecheckt haben, was manchmal zu fehlenden Dateien und nicht funktionierendem Bauen der Seiten führt, im Fall, dass eine entscheidende neue Datei hinzugefügt wurde und man kein komplettes cvs update im Verzeichnis durchgeführt hat. Vergessen Sie nicht, dass Sie alle benötigten Dateien haben (wie .wmlrc-Dateien), bevor Sie sich bei uns beschweren.

Was sind das für Zeilen, die mit # anfangen?

In WML ist eine Zeile, die mit einem # beginnt, ein Kommentar. Diese werden den üblichen HTML-Kommentaren vorgezogen, da sie nicht in der fertigen Seite auftauchen.

Bitte lesen Sie die Seite über die Verwendung von WML für weitere Informationen über WML.

Umgangsformen für Website-Bearbeiter

Kann ich diese Seite modifizieren?

Das kommt darauf an. Wenn Sie einen kleinen Fehler wie z.B. einen Tippfehler sehen, beheben Sie diesen einfach.

Wenn Sie bemerken, dass ein Teil der Informationen fehlt, fühlen Sie sich nicht daran gehindert, es ebenfalls zu beheben.

Wenn Sie das Gefühl haben, dass etwas schrecklich ist und neu geschrieben werden muss, bringen Sie es auf debian-www vor, damit es diskutiert werden kann. Wir werden Ihnen wahrscheinlich zustimmen.

Wenn Sie ein Problem in einer Vorlage entdecken (d.h. in einer Datei im webwml/english/template/debian-Verzeichnis), denken Sie bitte über die Änderungen nach, bevor Sie sie übergeben, da Änderungen in den Vorlagen oft große Teile der Site dazu veranlassen, neu gebaut zu werden.

Wenn Sie neue Verzeichnisse hinzufügen, fügen Sie auch das Makefile hinzu!

Wenn neue Verzeichnisse im CVS hinzugefügt werden, sollten Sie Vorsicht walten lassen. Wenn das aktuelle Verzeichnis in ../Makefile aufgeführt ist, dann müssen Sie ein Makefile darin erstellen – anderenfalls wird make eine Fehlermeldung produzieren.

Verwenden Sie einfaches und klares Englisch

Da die Debian-Webseiten auch von Leuten gelesen werden, deren Muttersprache nicht Englisch ist und da sie in andere Sprachen übersetzt werden, ist es am besten, ein einfaches und klares Englisch zu benutzen und die Verwendung von Umgangssprache, Emoticons und unklaren Dialekten zu vermeiden.

Wenn Sie etwas davon verwenden, fügen Sie einen Kommentar in die Datei ein, der die Bedeutung beschreibt.

Falls Sie unsicher sind, oder um Ihren Entwurf korrekturlesen zu lassen, kontaktieren Sie bitte das englische Lokalisierungs-Team.

Beachten Sie die READMEs

Einige der Verzeichnisse enthalten ein README, um Ihnen dabei zu helfen, zu verstehen, wie das Verzeichnis organisiert ist. Dieses sollte alle speziellen Informationen enthalten, die für das Arbeiten in diesem Bereich notwendig sind.

Trennen Sie inhaltliche von Formatierungsänderungen

Erstellen Sie immer separate Patches oder Commits für inhaltliche Änderungen und Änderungen in der Formatierung. Wenn solche Änderungen vermischt werden, ist es für die Übersetzer wesentlich schwieriger, die Unterschiede zu finden. Wenn Sie cvs diff mit solchen gemischten Änderungen ausführen, werden Sie den Schlamassel selbst sehen.

Vermeiden Sie allgemein zufällige Formatierungsänderungen. Änderungen, die ältere Teile von Seiten XHTML/XML-kompatibel machen, sollten nicht gleichzeitig mit anderen Änderungen eingepflegt werden. (Neue Seiten sollten natürlich von Anfang an richtig geschrieben werden.)

Aktualisieren Sie die Übersetzungen, wenn möglich

Einige Änderungen sind unabhängig von der verwendeten Sprache einer WML-Datei, z.B. Änderungen an URLs oder am eingebetteten Perl-Code. Das Berichtigen von Rechtschreibfehlern o.ä. fällt auch oft in diese Kategorie, weil die Übersetzer sie normalerweise beim Übersetzen ignoriert haben. Solche sprachunabhängigen Änderungen können Sie oft in allen übersetzten Dateien durchführen und die Version in den translation-check-Headern anpassen, ohne die entsprechenden Sprachen zu verstehen.

Es ist nicht sehr schwer für die Übersetzer, diese Arbeit selbst zu erledigen, und es kann unbequem für Englisch sprechende Editoren sein, einen kompletten Checkout zu haben. Wir ermutigen dennoch jeden, dies zu tun, um zu vermeiden, dass zwei Dutzend Personen mit etwas behelligt werden, das schnell von einer erledigt werden kann.

Sie können außerdem das smart_change.pl-Skript aus dem Wurzelverzeichnis des webwml-CVS-Moduls verwenden, um diese Änderungen wesentlich einfacher anzuwenden.

Handhabung von smart_change.pl

smart_change.pl [Optionen] Originaldatei

Es sind derzeit nur Dateien in /english/ als Originaldatei zugelassen. smart_change.pl akzeptiert die folgenden Argumente:

-s, --substitute=REGEXP
Einen regulären Ausdruck in Perlsyntax angeben, der auf die Dateien angewendet wird (dieses Argument kann mehr als einmal angegeben werden). Beispiel:
	  $> ./smart_change.pl -s "s,http://alteurl/,http://neueurl/,g" english/devel/index.wml
	  $> cvs diff -u */devel/index.wml | less
	  $> cvs ci -m "1.23: Updated alteurl to current location" */devel/index.wml
	
Der erste Befehl führt die Änderung durch, der zweite Befehl ist zur Überprüfung der englischen Ursprungsdatei und jeder davon vorhandenen Übersetzung. Sie sollten dies tun, um die tatsächlichen Änderungen vor dem Einpflegen zu überprüfen. Wenn alles so aussieht, wie Sie erwartet haben, pflegen Sie Ihre Änderungen mit dem dritten Befehl ein.
-l, --lang=STRING
Diese Sprache verarbeiten (kann mehr als einmal angegeben werden). Wenn keine Sprache angegeben wird, werden alle verfügbaren verarbeitet.
-n, --no-bump
translation-check-Header nicht aktualisieren. Normalerweise wird die CVS-Revision von Originaldatei als Referenz verwendet. In allen aktuellen Übersetzungen werden die translation-check-Header aktualisiert, in veralteten nicht. Wenn diese Option angegeben wurde, werden überhaupt keine Header verändert. Siehe auch Übersetzungen aktuell halten für eine Erklärung zu translation-check-Headern.
-p, --previous
Vorherige CVS-Revision benutzen. Dies ist z.B. nützlich, wenn die englische Datei schon eingepflegt wurde und die translation-check-Header mit der vorherigen Version verglichen werden sollen.
-h, --help
Kurze Handhabungsinformationen anzeigen.
-v, --verbose
Eine ausführliche Ausgabe erzeugen.

Links

Dieser Link sieht nicht richtig aus. Soll ich ihn ändern?

Wegen der Art, wie die Web-Server aufgesetzt sind (unter Verwendung von Inhaltsaushandlung), sollten Sie keinen der internen Links ändern müssen. Tatsächlich schlagen wir Ihnen vor, dies nicht zu tun. Schreiben Sie an debian-www, wenn Sie denken, dass ein Link falsch ist, bevor Sie ihn ändern.

Links beheben

Wenn Sie einen Link zu einer externen Website bemerken, der in einer Umleitung (301, 302, eine <meta>-Umleitung oder eine Seite, die meldet: This page has moved.) resultiert, teilen Sie dies bitte debian-www mit.

Wenn Sie einen kaputten Link (404, 403 oder eine Seite, die nicht das zeigt, was der Link sagt) finden, bitte beheben Sie ihn und teilen Sie es debian-www mit, damit die Übersetzer darauf aufmerksam werden. Oder besser noch, reparieren Sie den Link auch in allen anderen Übersetzungen, und aktualisieren Sie die translation-check-Header, falls möglich.

Trennung des Texts von den Daten

Was sind diese foo.def- und foo.data-Dateien?

Um es einfacher zu machen, die Übersetzungen aktuell zu halten, haben wir die allgemeinen Teile (data) von den textlichen Teilen (text) in einigen Seiten geteilt. Die Übersetzer müssen nur die textlichen Teile davon kopieren und übersetzen, die allgemeinen Teile werden automatisch hinzugefügt.

Ein Beispiel dürfte dabei helfen, das zu verstehen. Es werden mehrere Dateien benötigt, um die Seite der Distributor-Listen in CD/vendors zu generieren:

index.wml:
Der Text am oberen Ende der Distributor-Datei befindet sich in dieser Datei. Eine übersetzte Kopie davon sollte in jedem Sprach-Verzeichnis platziert werden.
vendors.CD.def:
Dies beinhaltet alle Text-Teile, die für jeden Distributor-Eintrag benötigt werden. Übersetzungen werden über <sprache>/po/vendors.xy.po hinzugefügt.
vendors.CD:
Diese Datei beinhaltet die tatsächlichen Distributoren-Einträge, die unabhängig von der Sprache sind, daher müssen die Übersetzer diese Datei nicht verändern.

Wenn eine der Personen hinter cdvendors@debian.org einen neuen Distributor hinzufügt, tun sie dies in debiancd.db, konvertieren es ins WML-Format als vendors.CD (dazu wird getvendors.pl verwendet), und lassen dann WML und die Makefiles ihre Magie spielen. Alle Übersetzungen werden unter Verwendung des vorhandenen übersetzten Texts neu übersetzt, aber mit den neuen Distributoren-Daten. (Eine aktualisierte Übersetzung gratis!)

Eine neue Seite hinzufügen

Neue Seiten für Debian hinzuzufügen, ist recht einfach. All die Arbeit, den Kopf und den Fuß der Seite richtig hinzubekommen, wird von WML erledigt. Alles, was Sie tun müssen, ist eine Zeile wie die folgende am Anfang der neuen Datei hinzuzufügen:

#use wml::debian::template title="Titel der Seite"

gefolgt vom Inhalt. Alle Seiten sollten die wml::debian::template Vorlage benutzen, außer sie verwenden eine spezielle, die nur für diese Sektion erstellt wurde, z.B. die News- oder Sicherheits-Beiträge.

Die Vorlagen, die wir haben, erlauben es Ihnen, gewisse Variablen zu definieren, die eine Auswirkung auf die Seiten haben, die erstellt werden. Dies sollte es vermeiden, verschiedene Vorlagen für jede Situation zu erstellen und es ermöglichen, Verbesserungen einfacher zu implementieren. Die Variablen, die im Augenblick verfügbar sind, und ihr Zweck sind:

BARETITLE="true"
Löscht den Debian -- Teil, der üblicherweise allen <title>-Tags vorangestellt wird.
NOHEADER="true"
Löscht den anfänglichen Kopf der Seite. Ein angepasster Kopf kann natürlich in der Datei angegeben werden.
NOMIRRORS="true"
Löscht die Spiegel-Auswahlliste von der Seite. Es ist allgemein nicht empfohlen, dies zu verwenden, außer für eine Handvoll Seiten.
NOHOMELINK="true"
Löscht den Link zurück auf die Haupt-Debian-Seite, die üblicherweise am Ende der Seite hinzugefügt wird.
NOLANGUAGES="true"
Löscht die Links zu den Versionen in anderen Sprachen, die üblicherweise am Ende der Seite hinzugefügt werden.
GEN_TIME="true"
Setzt das Datum der resultierenden Dateien auf den Zeitstempel der generierten Dateien, statt dem Zeitstempel der Quelldatei.
NOCOPYRIGHT="true"
Löscht den Copyright-Hinweis am Ende der Seiten.

Beachten Sie, dass Sie irgendein Wort als den Wert dieser Variablen verwenden können, true, yes, foo, es macht keinen Unterschied.

Ein Beispiel der Verwendung davon ist in den Portierungs-Seiten, die ihren eigenen Kopf haben. ports/arm/index.wml verwendet:

#use wml::debian::template title="ARM-Portierung" NOHEADER="yes"

Wenn Sie etwas tun wollen, das nicht unter Verwendung der vorhandenen Vorlagen möglich ist, erwägen Sie zuerst, eine davon zu erweitern. Wenn es nicht möglich ist, eine in einer abwärtskompatiblen Art zu erweitern, versuchen Sie die neue Vorlage zu einer Übermenge einer existierenden zu machen, damit die Seiten darauf mit der nächsten großen Aktualisierung (hoffentlich niemals öfter als alle 6 Monate) umgestellt werden können.

Wenn Sie eine Seite erstellen, die von einem Skript generiert wird oder wenig Text beinhaltet, erwägen Sie die Verwendung der <gettext>-Tags, um die Aufgabe zu erleichtern, die Übersetzungen aktuell zu halten.

Andere Dateien einbinden

Falls Sie einige Teile Ihrer Seite in eine getrennte Datei auslagern wollen (die dann von Ihrer Hauptdatei eingebunden wird), verwenden Sie die Endung .src, falls Ihre Datei Inhalte enthält, die übersetzt werden sollten, da dann die eingebundene Datei wie jede gewöhnliche .wml-Datei auf Änderungen überwacht wird. Falls Sie eine andere Erweiterung benutzen, wie z.B. .inc, werden die Übersetzer Ihre Aktualisierungen nicht bemerken und verschiedene Sprachen könnten verschiedene Inhalte ausliefern.

Neue Verzeichnisse hinzufügen

Beachten Sie: Erstellen Sie kein Verzeichnis mit dem Namen install. Dies verwirrt make und die Seiten in diesem Verzeichnis werden nicht automatisch aktualisiert.

Unterhalb ist ein kommentiertes Beispiel, wie man ein neues Verzeichnis zur Website hinzufügt.

   mkdir foo
   cvs add foo
   cd foo
   cp ../intro/Makefile .
   cvs add Makefile

Editieren Sie das Makefile im übergeordneten Verzeichnis und fügen Sie das Verzeichnis, das Sie soeben erstellt haben, zur SUBS-Variable hinzu. Dies wird das Verzeichnis beim Übersetzen inkludieren, wenn make aufgerufen wird.

Schlussendlich, übergeben Sie alle Änderungen, die Sie gerade gemacht haben, an das Depot mit

  cvs commit Makefile foo