Subject: Re: [docbook] Ruminations on the future of DocBook
On Fri, May 30, 2003 at 01:12:20PM -0500, Jeff Biss wrote: > Conceptually in programming there is the main program (routine) and > smaller modules that are called from the main program (subroutine). > Therefore why couldn't the DocBook DTD have been simplified through the > use of <subroutine role=method> for java and <subroutine role =function> > for C? There may be a lot to be gained from using element names that > define what something is generically (subroutine) rather than what it is > called specifically in any given instance (function). It's been a *long* time since I delved into <methodsynopsis>, <funcsynopsis>, <funcprototype> and the like. This is mostly from memory and from reading TDG v2.0.8. The issue isn't the semantic difference between a 'method', 'function' or generalized 'subroutine'. Theoretically, everything could be tagged as a 'subroutine' and annotated as appropriate. However, that's a lossy down-conversion because it reduces all possible descriptions to a lowest common denominator. The whole point of having different elements to describe these things is to capture the semantic richness of what you're describing. That's why elements like <methodsynopsis> have the content model they have. The problem I alluded to is that the semantic meaning of these elements works very well for C/C++/Java, but doesn't work very well for languages like Perl, and presumably PHP, Python, Scheme, FORTH, etc. If *all* of that semantic richness were captured in the content model for these elements, it would be difficult to use because you'd have to "just know" which variant content models are for documenting Java, which are for Perl, etc. Here's the content model for methodsynopsis: methodsynopsis ::= (modifier*, (type|void)?, methodname, (methodparam+|void), exceptionname*,modifier*) Perl doesn't really use exceptions, so <exceptionname> is easily ignored. But Perl can return multiple values, and it can return different types in different contexts. That is, you can have a function that takes a point and returns ($x, $y) as a pair of values, and another function that returns @list sometimes and $count other times. Add all that up, and the <type> part of <methodsynposis> doesn't match the Perlish case very well. I won't even get into optional named parameters and <methodparam>. I raised some of these issues a few years ago when <funcsynopsis> et. al. were being updated to reflect Java idioms. I let the issue drop because the number of people who write Perl docs in DocBook is approximately zero, and adding even more tags and special cases seemed like a waste of everyone's time. > Would namespace allow this type of generalization? I have an idea of > what a namespace but not that precise. Well, if an element like, say, <methodsynopsis> were taken out of the DocBook core, it could be specified through a different namespace. That is <dbjava:methodsynopsis> would capture the semantic richness of Java method descriptions *EXACTLY*. A different extension could define <dbperl:methodsynopsis> *EXACTLY* to capture the nature and complexity of Perl method descriptions. All of a sudden, we're not bickering over the one true method synopsis anymore -- everyone can have their own finely-tuned and comprehensible markup. If the element names are reused, it doesn't matter, because the elements will belong to different namespaces. Of course, standardizing the processing expectations for these extensions is an exercise left for the reader. It's not an insurmountable obstacle, but it's a consideration nonetheless. Z.