Veröffentlichung Ihres Dokuments auf der Firebird Website

Benennung der PDF-Datei
Einseitiges HTML-Dateien
Hochladen der PDF
Hochladen von mehrseitigen HTML-Dateien
Aktualisieren des Firebird Dokumentationsverzeichnisses

Möchten Sie Ihr Dokument veröffentlichen, müssen erst die HTML- und PDF-Ausgaben generiert werden. Dieser Vorgang wird im Firebird Docbuilding Howto besprochen. Wir gehen in diesem Abschnitt davon aus, dass dies erfoglreich durchgeführt wurde.

Benennung der PDF-Datei

Die Build-Tools benennen die Dateien automatisch nach ihrer ID im obersten DocBook-Element. Wir ändern die Namen der Mehrseiten-HTML-Ausgabe nicht - diese Seiten werden primär für die Onlinebetrachtung genutzt, und das Ändern eines einzigen Dateinamens würde sofort diverse Links zerstören. PDFs hingegen werden häufig heruntergeladen und Dateinamen wie qsg2.pdf oder ubusetup.pdf in einem Downloadverzeichnis oder auf einem Desktop sind wirklich nicht hilfreich bei der Identifizierung als Firebird-Handbücher. Deshalb sind hier ein paar Richtlinien für die Dateinamen:

Stellen Sie sicher, dass der Name das Wort Firebird, bevorzugt am Anfang, verwendet;
Versuchen Sie den Dokumenttitel zu nutzen, aber halten Sie es kurz;
Nutzen Sie Bindestriche („-“) um Wörter zu separieren;
Wenn der Titel sehr lang ist, vermeiden Sie Teile wie „Handbuch“, „Leitfaden“, „Howto“ etc., es sei denn das Weglassen würde zu Konfusionen führen;
Nutzen Sie die Dokumentsprache, verwenden Sie aber nur ASCII-Zeichen (keine Umlaute, etc.)
Falls (und nur falls) die Anwendung der o.a. Regeln zu einem bereits vorhandenen Dateinamen einer anderen Sprache führen, fügen Sie die Dokumentsprache (oder ihre Abkürzung) hinzu.

Um die genannten Richtlinien zu verdeutlichen, werden einige existierende Beispiele unten aufgelistet:

Firebird-2.0-QuickStart.pdf
Firebird-Security.pdf
MSSQL-to-Firebird.pdf
Firebird-Generator-Guide.pdf
Firebird-nbackup.pdf
Firebird-2.0-Schnellanleitung.pdf
Firebird-1.5-Arranque.pdf
Firebird-et-Null.pdf
Firebird-nbackup-fr.pdf
Firebird-su-Ubuntu.pdf
Firebird-nbackup-nl.pdf
Guia-Escrita-Firebird.pdf
Firebird-1.5-BystryjStart.pdf
Firebird-Perehod-s-MSSQL.pdf

Einseitiges HTML-Dateien

Falls und wenn wir mit der Veröffentlichung von einseitigen HTML-Dateien auf der Website beginnen - mittels build monohtml erstellt - sollten wir die gleichen Namen wie die entsprechenden PDFs verwenden, aber natürlich mit der Erweiterung .html.

Hochladen der PDF

Wenn Sie Schreibrechte auf den Firebird Webserver besitzen, stellen Sie eine SFTP-Verbindung zu web.firebirdsql.org und laden Sie die Dateien hoch:

/srv/www/htdocs/pdfmanual (English docs)
/srv/www/htdocs/pdfmanual/fr (French docs)
/srv/www/htdocs/pdfmanual/ja (Japanese docs)
etc.

Release Notes werden in den entsprechenden Verzeichnissen abgelegt:

/srv/www/htdocs/rlsnotes
/srv/www/htdocs/rlsnotes/fr
etc.

Wenn Sie keine Schreibrechte für den Server besitzen, fragen Sie jemanden, der diese besitzt. Falls Sie ein Projektmitglied sind, können Sie auch nach einem Benutzer und Kennwort für den Server fragen.

Hochladen von mehrseitigen HTML-Dateien

Stellen Sie sicher, dass Sie alle notwendigen Dateien hochladen: die HTML-Dateien, die zusammengenommen Ihr Handbuch (oder Handbücher) darstellen, das Stylesheet firebirddocs.css (wenn es seit dem letzten Upload geändert wurde), und das Unterverzeichnis images mit allen geänderten oder hinzugefügten Inhalten. Um alle Links funktionsfähig zu halten, kann es notwendig sein, das übergeordnete book ebenfalls neuzuerstellen und hochzuladen (oder gar das gesamte set). Laden Sie das gesamte Drumherum nach:

/srv/www/htdocs/manual (English docs)
/srv/www/htdocs/manual/fr (French docs)
etc.

Warnung

Wenn in Frage kommende Seiten zu einem anderen Basis-Set gehören als die standardmäßigen firebirddocs (z. B. papers oder rlsnotes), dann platzieren Sie diese nicht in den erwähnten Verzeichnissen. Wir haben hierfür noch keine klaren Regeln definiert, aber mehrseitige HTML-Builds sollten nicht mit anderen Sets gemischt werden. Wenn diese Situation eintritt, melden Sie es bitte auf der firebird-docs Liste.

Aktualisieren des Firebird Dokumentationsverzeichnisses

Das Firebird Dokumentationsverzeichniss unter http://www.firebirdsql.org/index.php?op=doc ist ein PHP-Skript, dass die meisten Inhalte aus den auf dem Server liegenden Dateien holt. Wenn Sie existierende Dokumente aktualisiert haben, die bereits im Verzeichnis aufgeführt sind, ist nichts weiter zu tun, sofern Sie den Dateinamen nicht geändert haben. Wenn Sie jedoch ein neues Dokument oder eine neue Übersetzung erstellt haben, müssen sie dies dem Verzeichnis bekannt geben. Hier steht wie:

Wenn Sie ein komplett neues Dokument erstellt haben

Schauen Sie sich das Dokumentationsverzeichnis an und entscheiden Sie welche Kategorie am besten zu Ihrem Dokument passt. (Kategorien werden durch orange Köpfe gekennzeichnet.)
Verbinden Sie sich zum Server, gehen Sie in Verzeichnis/srv/www/htdocs/doc und werfen Sie einen Blick auf die Dateien, die mit Cat_ beginnen. Öffnen Sie die Datei, die zu Ihrer gewählten Kategorie gehört.
Lesen Sie die Anweisungen am Anfang der Datei.
Erstellen Sie einen neuen Abschnitt, beginnend mit dem Titel des Dokuments in Englisch, durch eine speziell formatierte Zeile für jede verfügbare Version. Bei einem neuen Dokument könnte ein solcher Abschnitt wie folgt aussehen:
```
Firebird Uninstallation Howto
en:/manual/fb-uninstall.html
en:/pdfmanual/Firebird-Uninstall.pdf
```
Jede Versionszeile beginnt mit dem Sprachcode, gefolgt von einem Doppelpunkt, gefolgt von einer URL. Für Dokumente, die auf unserem eigenen Server liegen, ist diese URL einfach der „absolute“ Weg beginnend am Server-Root. Die Abschnitte werden durch Leerzeilen getrennt. Die Reihenfolge der Abschnitte in der Datei bestimmt die Reihenfolge der Dokumente innerhalb ihrer Kategorie im Dokumentationsverzeichnis auf der Webseite. Die Reihenfolge der Versionszeilen innerhalb eines Abschnitts ist irrelevant.
Speichern Sie die Datei. Wenn Sie diese auf Ihrem eigenen Computer bearbeiten, laden Sie sie zurück auf den Server. Aktualisieren Sie jetzt die Firebird Dokumentationsverzeichnis-Seite in Ihrem Web-Browser und überprüfen Sie, ob das Dokument dort aufgeführt ist, wo es sein sollte, und ob die Links funktionieren. Stellen Sie außerdem sicher, dass die Links in der korrekten Spalte sind (HTML in der mittleren Spalte, PDF etc. in der Spalte ganz rechts).
Das PHP-Skript macht einen ziemlich guten Job bei der automatischen Bestimmung des Dokumenttyps, aber es gibt Fälle, in denen es diesen falsch ermittelt. Wenn dies der Fall ist, fügen Sie den Dateityp - zwischen geschweiften Klammern - unmittelbar nach der URL in der Versionszeile ein
```
en:http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_60_sqlref{html}
```
Sobald alles funktioniert, committen Sie die aktualisierte Kategorie-Datei zum CVS. Wenn Sie das Firebird web-Modul vom SourceForge-Server ausgecheckt haben, finden Sie die Kategorie-Dateien (und mehr) im Ordner web/website/doc. Verwenden Sie Ihren SF-Benutzernamen und das zugehörige Kennwort für den Checkout, andernfalls werden Sie nicht in der Lage sein Ihre Änderungen zu committen. Die Arbeit mit CVS ist beschrieben im Firebird Docbuilding Howto.

Wenn Sie ein existierendes Dokument in eine neue Sprache übersetzt haben oder ein neues Dokument hierfür erstellt haben

Schauen Sie sich das Dokumentationsverzeichnis an und entscheiden Sie welche Kategorie am besten zu Ihrem Dokument passt. (Kategorien werden durch orange Köpfe gekennzeichnet.)
Verbinden Sie sich zum Server, gehen Sie in Verzeichnis/srv/www/htdocs/doc und werfen Sie einen Blick auf die Dateien, die mit Cat_ beginnen. Öffnen Sie die Datei, die zu Ihrer gewählten Kategorie gehört.
Lesen Sie die Anweisungen am Anfang der Datei.
Suchen Sie den Abschnitt für das betreffende Dokument und fügen Sie die Versionszeile(n) für Ihre Anpassungen hinzu, z.B.:
```
Firebird Uninstallation Howto
en:/manual/fb-uninstall.html
en:/pdfmanual/Firebird-Uninstall.pdf
fr:/manual/fr/fb-uninstall-fr.html
fr:/pdfmanual/fr/Deinstaller-Firebird.pdf
```
Die Reihenfolge der Versionszeile ist irrelevant, aber der Titel muss ganz oben bleiben.
Schritte 5, 6 und 7 sind die gleichen wie die für neue Dokumente.