Re: Examples

From: "Jirka Kosek" <jirka@kosek.cz> > 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