Re: PHPDoc Future

> James Moore wrote: > > > > > Q: What about DocBook? > > > A: I don't have the neccessary knowledge for this, but I know some guys > > > that actually have it. Means, I've send some pizza's and beer crates to > > > send to them and make them feel guilty to help us ;). Help is very much > > > appreciated. > > > > What needs doing on this front?? > > Uff, you're almost too fast. There're two explanations for this: you're > looking for some beer or you don't have a job that occupies you... Both :) Really Ive got a while free until I find another new job... > No, beside kidding: it's hard to give a precise answer to this. To be > honest I don't know which way would be best. Let's try some kind of > reverse engeneering. > > PEAR needs a documentation tool, that's able to generate a basic > framework (or a final document) to be used with the documentation system > on php.net . This, and the whish to use the existing tools to generate > PDF etc. based on DocBook, means that eigther the documentation tool > needs to output DocBook directly or the XML output of the doc tool has > to be transformed using XSLT. > > I expect this situation to become quite familiar. Some company is > looking for a documentation tool. They start searching for it and they > will find about a hundred scripts using ext/phpdoc. The developer > resonsible to select a tool checks two or three of them and decides that > none of them fits the needs of the company. He asks the project manager > for three days to write the 101st customized tool. Of course this tool > must be capable to generate DocBook. Well, he's a XML novice and doesn't > know anything about DocBook which is quite complex. Means he has no > chance to create DocBook on it's own. But he might have the knowledge to > integrate a DocBook conversation plug-in. OK.. > So what I suggest is having a DocBook conversation plug-in that consists > of some basic XSLT function calls and - most important - XSL files. This > way we get: > > 1.) C: ext/phpdoc => simple XML (doc comments unparsed) OK havnt looked at ext/phpdoc yet but I understand what it does :) > 2.) PHP: standard_doctool => generates standard_intermediate XML > => might generate template based HTML > => might generate template based PDF OK thats fine.. > 3.) PHP: standard_docbook_conv => generates DocBook > => generates HTML > => generates PDF Lets start with generating docbook stuff first and leave HTML and PDF for later.. people can use norman's stylesheets for this for now. > I the standard_docbook_conv tool is well documented it should be > possible to alter the XSL files that can handle the XML output of the > standard_doctool - even for a novice. Shouldnt be too hard to do.. > What does this mean for you? We'll have to start a discussion on what > the standard_doctool should look like. This determines it's XML output > format. And this is the base for your standard_docbook_conv tool. > > If you want me, I can try to write some kind of whitepaper draft what a > PHPDoc tool should look like. It would take me about 10 days to do so. > This paper could be discussed on the dev-lists or we start discussing > right the way. OK I havnt even looked at the output that PHPDoc gives but as long as there is enough info in it it shouldnt be too hard to convert. I would suggest a set of XSLT stylesheets that do the job. A white paper might be a good idea so we all know what we are heading for otherwise we will all end up swimming in different directions :) - James