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...
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.
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)
2.) PHP: standard_doctool => generates standard_intermediate XML
=> might generate template based HTML
=> might generate template based PDF
3.) PHP: standard_docbook_conv => generates DocBook
=> generates HTML
=> generates PDF
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.
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.
Ulf
--
NetUSE AG Dr.-Hell-Straße Fon: +49 431 386 436 00
http://www.netuse.de/ D-24107 Kiel Fax: +49 431 386 435 99
--
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]
