[php] [RfD] PEAR-Dokumentation

[Alexander Merz]

Dem aufmerksamen Leser von de.comp.lang.php wird nicht entgangen sein, dass
Chregu und ich derzeit an einer neuen PEAR-Klasse schreiben.

Als ich nun beginnen wollte dazu die Dokumentation zu schreiben, bin ich auf
ein paar Probleme gestossen. Diese könnten evt. mit dafür verantwortlich sein,
das ein Grossteil der PEAR-Klassen derzeit 'suboptimal' dokumentiert sind.

Mit dem Hintergedanken im Kopf, das die Dokumentation mal ins PHP-Manual
eingehen sollte, hab ich mir den Docbook-'Quelltext' des Manuals geholt und
angeguckt. ...Und den Editor erstmal wieder ganz schnell geschlossen - weil
nichts verstanden. Also ab zu www.docbook.org, das Buch von Walsh
heruntergeladen und erneut die Hände über den Kopf zusammengeschlagen - DocBook
ist doch recht komplex und trotz bei Kenntniss von HTML und XML eine erhebliche
Lernaufgabe.
Derzeit liegt die Doku zu Config deshalb als Plain-Text vor.

Doch wohin mit der möglichen DocBook-Doku bei einem PEAR-CVS-Commit eigentlich?
Ins PEAR ja eigentlich nicht, es gibt doch das DOC-CVS-Verzeichniss. Da brauch
ich aber zusätzlich zum PEAR noch CVS-Zugriff aufs Doc-Verzeichniss und muss
mich auch noch dort durch die Unterverzeichnisse wühlen.

Aus Anwendersicht, entsteht damit aber auch noch das Problem, dass er bei einem
Download einer neuen PEAR-Klasse, sein PHP-Manual updaten musss (sprich
komplett neu herunterladen muss), um an die Dokumentation zu gelangen.

Daher folgende Überlegungen:
1. Die Dokumentation zur jeweiligen Klasse befindet sich in dem Verzeichniss,
in dem sich auch die Klasse selbst befindet ( übrigens analog zu CPAN).
Erfordert lediglich CVS-Zugriff auf PEAR und hilft Übersicht zu bewahren.

2. Für die Dokumentation wird nicht DocBook verwendet, sondern ein von
XHTML-abgeleiter Dialekt, der bei Bedarf in DocBook transformiert werden kann
(Online-Manual!).
Wie dies aussehen kann, wird man sich in den nächsten Tagen angucken können -
ich werde testweise einen Teil der Config-Doku entsprechend überarbeiten. Dies
hat vorallem den Vorteil, dass der Arbeits- und Lernaufwand für die Doku
verringert wird, und man insbesondere HTML-Editoren nutzen kann, was bei
DocBook nicht gewährleistet ist.
Und der Anwender kann die Dokumentation problemlos mit jedem XHTML-komp.
Browser betrachten.

Also was denkt ihr darüber?

BTW: Ich stelle diese Frage übrigens, deshalb nicht PEAR-Dev, weil mich
speziell die Anwendersicht interessiert. Auf PEAR-Dev gibt es zuviele
Fachidioten ;-).


--
Cu, Alex