[php] [RfD] PEAR-Dokumentation

[Ralf Geschke]

> 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.

Schau' Dir mal das DocBook intro an: 
http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html
Fand ich als Einfuehrung recht brauchbar, und reicht fuer die 
ersten Schritte. 

> 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!).

Zu PEAR allgemein: Ich faende es wesentlich besser, wenn dies 
aehnlich wie das CPAN oder CTAN organisiert waere. 
Es sollte einzelne, kleine Pakete geben, die man bei Bedarf
downloaden und installieren kann. Wozu sich das ganze PEAR aufspielen,
wenn man nur zwei, drei Module davon benoetigt? Momentan ist
dies angesichts des Platzes zwar noch kein Problem, aber PEAR
wird / soll doch vermutlich wachsen. 
Damit waere auch die Manual-Geschichte klar - jedes Paket 
braechte seine Dokumentation mit. Wie diese aussehen sollte,
darueber mag ich nicht spekulieren, auch hier gefaellt mir
das Perldoc-Konzept letztlich besser, eben weil es keine
zentrale Instanz zur Verwaltung voraussetzt. 
Der Schritt zur Generierung des Manuals koennte dann einher 
gehen mit der Installation des jeweiligen Moduls. 

Das PEAR-Konzept krankt meiner Meinung nach daran, dass 
es einerseits ein Modul-Archiv sein moechte, was bekanntlich
PHP-Code zur Verfuegung stellt, dieser Code (inkl. Manuals & Co)
aber andererseits viel zu stark in der PHP-Distribution 
verankert ist, ebenso das Manual. Man hat nur die Wahl, alles
oder nichts zu installieren, eine Pruefung von Abhaengigkeiten
waehrend der Installation findet nicht statt (vgl. CPAN - 
Modul X setzt Modul Y Voraus, bitte installieren...). 
Die fehlende Doku ist daher eigentlich gar nicht verwunderlich
und stellt nur ein Symptom dar. 

Dieses Konzept macht es auch umso schwieriger, zumindest aber
komplizierter als notwendig, PEAR Code beizusteuern.

Beste Gruesse,
   Ralf
-- 
: www  : http://www.bttr.org  :  http://der.leitweganzeiger.de
: mail : ralf_(at)_bttr.org       :::         rg_(at)_leitweganzeiger.de