> > -1 > > Getting rid of <methodsynopsis> to solve this problem seems bad to me, > > can't we just improve the logic used there to have more freedom ? > > without modifying the DocBook DTD or abusing the "role" attribute we can't > > <methodsynopsis> was designed with C++ and Java in mind, > it is just not up to the additional fexibility we have > with the PHP parameter passing interface (as this example > clearly shows) > > and what do we get from using <methodsynopsis> anyway? > > as long as we only use it for prototype rendering (and afaik > this is the only thing we do?) it just makes things more > complex as we have to do the following transformations > > prototype -> methodsynopsis tag structure -> prototype > > where the first transition has to be done by the documentation > author (maybe aided by tools) *and* looses information as > docbook can't express all the possibilities we have in our > parameter passing API > > the second transformation (within the stylesheets) then > tries to recreate the original prototype (with minimal > markup additions). > > these two transformations do not only introduce problems > like the one we see right now with dba_fetch() as information > was lost on the first transformation so that the original > prototype can't be reconstructed in all cases, > it also makes maintainance harder as there is no simple > way to check code protos against documentation prototypes > anymore
After reading all this, I still clearly beleive that having markup to express the structure of the protos is a good thing. We can render the types, the parenthesis, the parameter names, etc. differently, as it is done in the new CMHs and in the livedocs output. That is a very good visual aid for reading docs. It would be very painful to have some text processing code to guess how the proto is formatted and render the output that way for HTML, PDF and other versions. As I said before I am not against modifying docbook, I am convinced that we have quite some problems, which are only fixable this way, and we won't do harm with modifying the DTD, as it is very well supported, and there are already PHP projects (at least PHP-GTK) using a modified docbook dtd. Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
