[DOC-SIG] Re: Python Documentation

[Fred L. Drake]

Michael W. Ryan writes:
 > I keep repeating parts of this.  Please keep the following things in mind:

  Ok, I bit.  I just pulled down 0.99.20 and read the latest
incarnation of the DTD.  I'll try and explain why I don't think the
SGML-Tools suite is good for the project at hand (the Python Library
Reference).

 > 1) SGML-Tools isn't just for documenting Linux.  It's designed for doing
 > technical documentation.

  This was never an issue.

 > 2) SGML-Tools isn't just a DTD.  It's an entire set of tools.

  Yes, but they are still tightly tied to the DTD; I followed the list 
for a long time and the basic assumptions being made just didn't seem
to scale.  Perhaps this has changed, but the cast of characters
appears to have remained quite stable since I last followed the
mailing list.

 > 3) There has been discussion of structuring the package such that other
 > DTDs can be used.

  Some discussion?  Other tools have been designed for this from the
start; that counts quite a bit in my book.

 > 4) SGML-Tools has undergone alot of changes over the original
 > Linuxdoc-SGML.  These changes include a more logical style of markup and
 > becoming more markup-driven as opposed to backend-driven (which was an

  I agree, it has improved.  But it's very basic and doesn't support
the highly structured information in the Python Library Reference.
Sure, it could be extended to do so.  I think using an existing,
tested, and supported DTD provides significant benefits over having to 
(largely) start over.
  I'm not knocking what the SGML-Tools crew has done, I just don't
think it's as far along as it could be, or as other tools are.
  Please direct follow-ups to doc-sig@python.org, as the primary
discussion has moved to that forum.


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive
Reston, VA    20191-5434

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________