[XML-SIG] Re: PyDoc/XML?

[Fred L. Drake, Jr.]

uche.ogbuji@fourthought.com writes:
 > [Note: you might want to suggest your ideas to the doc-sig, which, as Fred 
 > Drake pointed out to me, is also relevant]

Uche,
  Thanks for pointing this out.  The Python-documentation aspect of
this discussion belongs in the Doc-SIG, but some of this makes more
sense here (like most of the message to which I'm responding).

 > find XML as readable as any other presentation of such structure.
 > Some say that optional end-tags, etc. would help, but I often find
 > the un-closed "<LI>" and "<P>" in HTML a bit more confusing.

  There's always someone willing to espouse any given view, even if
you have to pay them.  ;-)
  I think the only thing I'd really like to be able to use from SGML
that XML doesn't offer is the empty end tag.  When marking one or two
words, XML is incredibly verbose.  If I have:

       In the module foo, the function bar() provides...

The XML might be:

       In the module <module>foo</module>, the function
       <function>bar</function> provides...

The corresponding SGML (with the right declaration) might be:

       In the module <module>foo</>, the function <function>bar</>
       provides...

An alternative XML, which I don't really like, might be:

       In the module <module n="foo"/>, the function
       <function n="bar"/> provides...

This is shorter, but I don't like using an attribute for this (not
really sure why; the name of a function is an attribute of the
function, but that relationship isn't that important), and it strongly 
relies on using a *short* name for the attribute.
  (Let's just assume my stylesheets will generate the parentheses
following the function name.)
  It's only a coincidence that my example might vaguely resemble API
documents.  ;-)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives