Re: Version der PHP-Doku
| From: | Hartmut Holzgraefe | Date: | Mon, 27 Oct 2003 12:58:54 +0000 |
| Subject: | Re: Version der PHP-Doku | ||
| References: | 1 | Groups: | php.doc.de |
| Request: | Send a blank email to doc-de+get-961@lists.php.net to get a copy of this message | ||
Christian Helmbold wrote:
Hallo, ich weiss nicht, ob das der richtige Ort für meine Vorschläge ist, aber ein besserer ist mir nicht eingefallen.passt schon :)
Ich finde es gerade zu unglaublich, dass die Doku keine Versionsnummer trägt (oder sie ist verdammt gut versteckt).Das Manual an sich ist in ständigem Fluss und nie in allen Teilen wirklich up-to-date mit allen PHP Funktionalitäten. Allein von daher lässt sich keine genaue Zuordnung von Stand des Handbuchs zu PHP Release Version treffen. hypothetisches Beispiel: Funktion x wurde in PHP 4.0 hinzugefügt, kurz vor Erscheinen von 4.1 endlich dokumentiert. Für 4.2 wurden in letzer Sekunde Änderungen vorgenommen, die erst kurz nach dem Release von 4.2 dokumentiert wurden. Welche Manual-Version wäre nun für wen die richtige? Wer z.B. noch PHP 4.0 einsetzt möchte trotzdem mindestens die (hypothetische) Manual-Version 4.1 benutzen, um über x zu erfahren ... Generell gilt das das aktuelle Handbuch PHP 4.x beschreibt. Für alle Funktionen ist aus der Manual-Seite zu der jeweiligen Funktion erkennbar, in welchen PHP Releases diese Funktion verfügbar ist. Wenn sich Funktionalitäten innerhalb der PHP 4.x Releases bzw. nach Einführung einer Funktion geändert haben so ist dies i.A. in der Dokumentation mit Angabe der Versionsnummer erwähnt. somit ist das PHP-Manual ein one-size-fits-all Dokument :)
Diese Selbstverständlichkeit sollte auch schleunigst bei PHP einzug erhalten.Wenn du bereit bist bei jedem PHP-Release darauf zu warten, das auch das komplette Manual auf genau den Stand dieses Release gebracht wird gerne. Da aber das Manual noch nie in allen seinen Teilen (wir sind zZ in der PDF-Version bei über 4.000 Seiten und noch immer sind nicht alle Funktionen aller Extensions dokumentiert) noch *nie* up-to-date war würde das wohl bedeuten, das auf absehbare Zeit (gerechnet in Monaten oder eher Jahren) keine weiteren PHP Releases mehr zu erwarten währen ... ansonsten bist du natürlich gerne dazu aufgerufen, "schleunigst" deinen Beitrag zu dieser "Selbstverständlichkeit" zu leisten :)
Überhaupt scheint davon ausgegangen zu werden, dass immer die neueste PHP-Version eingesetzt wird und man nur dazu eine Doku braucht. Warum werden keine alten Versionen angeboten (außer der einen uralten)? Liegt das vielleicht daran, dass die Versionen mangels Nummer niemand unterscheiden kann? ;-)nein, siehe oben
Außerdem wäre bei dem gewachsenen Funktionsumfang vielleicht eine andere Struktur eine Überlegung wert. Man könnte z.B. eine Kategorie für DB-Funktionen, eine für Netzwerkfunktionen usw. machen.hier kämpfen wir mit Unzulänglichkeiten in der DocBook XML DTD, eine Verschachtelung von Referenz-Kapiteln ist im Konzept von DocBook leider (noch ?) nicht vorgesehen ... :( dies ist ein Problem mit dem wir schon lange kämpfen, für das wir aber noch keine praktikable DocBook-konforme Lösung gefunden haben ... -- Hartmut Holzgraefe <hartmut@php.net>