This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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.


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]