> 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
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
To contact the list administrators, e-mail: [EMAIL PROTECTED]
