Re: [PHP-DOC] Examples From: Egon Schmid (eschmid <email protected>)
Date: 10/16/01

From: "Jirka Kosek" <jirka <email protected>>

> Hojtsy Gabor wrote:
> >
> > > I'm not saying that you must customize DTD and add new
element. But this
> > > approach has benefits over role="xxx" tweaking.
> >
> > Well, it is much nicer, to add a new element, but...
> >
> > > Only drawback is that
> > > your documents would not be DocBook DTD compliant. But if you
don't send
> > > your source document outside of phpdoc group there wouldn't be
problems
> > > with it.

Correct, but what is with the peoples inside the phpdoc group?

> > Let's imagine we would like to make a cool book format of
> > the phpdoc files. Then we may use the style sheets used
> > by O'reilly, but if we add tags, and this goes on, we were
> > unable to work with third party tools supporting DocBook.

Correct, nobody can test his own contributions for phpdoc.

> Just kidding. O'Reilly has its own DSSSL stylesheets. If you give
them
> DocBook source, they convert sources by Jade and DSSSL stylesheet
to MIF
> format (for FrameMaker). Final layout is done in Frame. Adding
simple
> rule to their DSSSL stylesheet would be the easiest way in book
> production cycle.

I know that :)

> > With a role attribute we can specify that this is a seealso
> > para. For style sheets not customized for this role,
> > that would be a normal _para_. For style sheets not customized
> > for a new tag, that would be a _problem_...

A new tag (or element) results only in errors and there will be no
rendering.

> To process this element correctly, you must customize stylesheet
in the
> very similar way to adding new element. You will get incorrect
output
> without such customization.

Correct.

> > We can't clearly state, that the docs would strictly stay here,
> > and would only be processed by our scripts. IMHO it is the best
> > way to stay on the way of world standards, and so we are staying
> > open to any standard tools and programs.

I think XML is a standard and DocBook is another standard. The
documentation should IMHO not use elements not used in DocBook.

> By using XML and even customizing DocBook DTD you are not leaving
any
> world standard. Many OSS project needs some custom element and
they add
> it for their own purposes. There is nothing wrong with it.

Publishers can do that for own purposes. The PHP documentation is an
international effort and we donīt need to change the DocBook DTD.
Any help to customize the stylesheets are welcome.

-Egon