Re: PEAR documentation

Am Tue, 25 Feb 2003 15:26:16 +0200 (EET) schrieb Mika Tuupola <tuupola@appelsiini.net>: > On Mon, 24 Feb 2003, Eric wrote: > > > What is the proper way to publish docbook xml style documentation to > > the pear website? Is there a "test" place that I can publish and make > > changes to a "non-live" site? > > There is no "test" place, but all the document writers usually > have their own build enviroment for docbook on which they > test the documentation before committing it to cvs. Maybe that´s why there are so few people who drite docbook docs... only those who write docbook have a test environment, those who don´t have a test environment don´t write docbook, because they have no place to test ;-) IMHO using docbook may be nice, but it raises a barrier for those people who don´t have much time to spare on their pet projects and have never used docbook before. Do write proper docs, those people have to: - Learn the docbook tags and document structure - Build a test environment (and for that, they first have to search all the needed tools, tutorials etc.pp. that is needed to make such a thing) There must be better ways, i.e. a web-based frontend where the docs are first stored in a database, having a common logical structure and from where you can then export the docs as either plain-text, docbook or even OpenOffice, LaTeX or PDF. Typo3 does something similar for its documentation writers and I think it´s great and very developer-friendly ;-) > Making a working build enviroment might be a bit confusing > first but after you make it properly once it should not > be a big deal. After you make it once, yes, but one has to find the time. Not too many people like to write docs, so we should provide a very cool and easy way to do it as a way to encourage them - not build barriers by using a format only few people really know. Right now, I´m writing my docs in OpenOffice and hope there´ll be a way to convert that into docbook some day, maybe via a plugin, maybe via XSL. Just my $0.02 ... Regards, Markus -- *21st Media* | Consulting, Konzeption, Produktion für die Bereiche: Markus Wolff | Internet, Intranet, eCommerce, Content Management, Hamburg,Germany | Softwareentwicklung, 3D-Animation, Videostreaming http://21st.de | Tel. [+49](0)40/6887949-0, Fax: [+49](0)40/6887949-1