Re: DOCBOOK: DocBook 4.0: ClassSynopsis

[Norman Walsh <ndw at nwalsh dot com>]

/ "Fred L. Drake, Jr." <fdrake@acm.org> was heard to say:
|  > <classsynopsis language="java">
|  > <classname>foo</classname>
|  > <classname>bar</classname>
| 
|   I think the confusion is here.  It's not clear from the DTD that the 
| first one is the class identication and the others are base classes

But if we make that expectation clear, does it leave any
processing problems unresolvable?

| and interfaces that it conforms to.

I think the interface issue is red herring since we have
"interfacename" for that.

|  It's also valid, accoring to the
| DTD, to say:
| 
| <classsynopsis language="java">
| <exceptionname>somename</exceptionname>
| ...
| 
|   Which doesn't make sense

This is about documentation, not modeling. We aren't trying to
be prescriptive. DocBook allows you to do all sorts of
nonsensical things. That, in and of itself isn't a problem, IMHO.

| (unless your language distinguishes
| exceptions from classes; 

True. So one person's nonsensical is another's language feature. :-)

| Java only makes requirements on the
| inheritance chain).  I also understand that C++ allows exceptions to
| be things other than class instances; "int" for example.  But I
| suppose ExceptionName doesn't really say it's a class.

Right.

|   Perhaps the base class(es) and interfaces need to be set up in a
| container, with possibly a different container for allowed exceptions?
| I don't like getting heavy with markup like this, though.  ;(  Perhaps 

I'm hoping that the markup I've proposed is simultaneously rich
enough to capture the required *documentation* semantics for a
wide variety of languages and loose enough to fit the same wide
variety of languages without pervasive tag abuse.

| the name of "this" class/interface/exception should be an attribute,
| with another attribute that allows specifying which it is (or select
| by attribute name); "class" could be the default type for a
| ClassSynopsis.

Design tip o' the day: don't put anything in an attribute that
you might want to mark up with <replaceable> later :-)

| <classsynopsis language="java" type="class" name="foo">
|   <inherits>
|     <classname>bar</classname>
|     <interfacename>baz</interfacename>
|     <interfacename>moo</interfacename>
|     </inherits>

I'm not sure I buy the argument that implementing an interface
is a kind of inheritance, but nevermind...

|   <raises>
|     <exceptionname>x</exceptionname>
|     <exceptionname>y</exceptionname>
|     </raises>
| 
|   I'm not exactly sure I like this much better, but it takes care of
| the potential for ambiguity (for authoring, not processing).

My real fear is that your proposal models Java well at the
expense of C++ or Python or Perl or your other language of
choice.

And I don't see any markup in your model that isn't derivable
(for any given language) from the markup in mine.

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | The facts, although interesting,
http://www.oasis-open.org/docbook/ | are usually irrelevant.
Member, DocBook Editorial Board    |