Re: Online doc generator (Was: Re: [PEAR-DEV] Amsterdam meeting agenda)

On Sat Apr 10, 2004 at 01:2825PM +0200, Bertrand Mansion wrote: > I don't have a problem with that but it probably requires to think about how > you want to organize the information on the website. Especially, how API doc > will be separated from/related to tutorials. I already have been thinking about this quite a lot. I hope to be able to write something down about this before the meeting at the conference, so you can guys can rip it apart. > The fact that it takes days to build the PEAR documentation looks like an > evidence that the format chosen (docbook to name it) is not > appropriate. It does not take days right now. At the moment the manual builds in something like 45 minutes. > > I do not think we should drop Docbook. Instead I like the idea of > > having a reST -> Docbook converter with which people can > > semi-automatically convert their reST file into proper Docbook, which > > will then be added to the manual. The Horde project has been starting > > to develop a PHP-based reST parser, which I'm planning to use as well. > > Please tell me why we shouldn't drop docbook. Because Docbook is technically the right tool for our needs. I admit that it's hard for people to start with Docbook, but for this we are working on reST support. (I have already finished a first verseion of a reST->Docbook converter for Horde's Text_reST package.) > In the suggested process, you add needless steps which will in turn add > maintenance problems and inconstancies to the doc repository, not to say > about the local copies. I am well aware of the technical and logistical problems that may arise. At the same time I am very confident that we will come up with solutions for those problems. -- - Martin Martin Jansen http://martinjansen.com/