[Patches] Re: [Patch #101821] xmldomminidom.tex: Documentation for minidom

[Fred L. Drake, Jr.]

Martin von Loewis writes:
 > I don't think that rationale for rejection is valid: I can fix the
 > formatting of the typeset version if you want (e.g. by not setting it
 > as a minipage). 

  Not using the verbatim environment makes further transformations of
the docs painful; the last I checked LaTeX2HTML had real problems
with alltt environments.  I'm not sure what you're thinking of
specifically, so can't offer much advice on the right markup, but I'd
like to keep it simple in any case.

 > On not being appropriate: The IDL provides documentation that the
 > English text doesn't. For example, the it doesn't tell what the
 > functions return in many cases (e.g. {remove|append}Child). Also, a
 > number of functions that are implemented and ought to be part of the
 > interface are not documented (e.g. getAttributeNode). Using the IDL
 > would provide a better guarantee of consistency.

  I think we only get consistency here if we link to the IDL on
www.w3.org; if we include it ourselves, we're just as well off if we
document the methods directly.  This would be my preference.

 > As for the IDL being screwed: I don't know whether this was a XML-SIG
 > statement (or rather one of individuals); it is certainly not true for
 > DOM Level 1 Second Edition or DOM Level 2 (which the patch proposed to
 > include).

  I thought we determined that there were IDL errors in one version or
another; perhaps that's been corrected.  Perhaps it was the case in
DOM Level 1 first ed.; I don't recall when the discussions took place,
and really don't want to scour the archives right now.
  I also seem to recall that the Python DOM API is not a direct
mapping using the IDL->Python mapping as accepted by the OMG.  That
seems a good reason not to include the IDL, as the association between
IDL and CORBA is tight, and misleading in this case.

 > I can accept that the IDL is not included in the documentation, but
 > I'd like to see the content that it would have provided written in
 > plain English, then.

  Agreed; my intent was not to exclude the information content,
regardless of the presentation.  If we want to include the IDL, we
should do so via a hyperlink, which is problematic for the typeset
versions.  Breaking it up into smaller chunks would be nightmarish as
well.
  At any rate, I do plan to attack this section again this week, so
I'll take all this into consideration.  I agree that we need more
information here, and should not rely excessively on the reader
interpolating the W3C documents and what we provide to figure it out.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs Team Member