[Doc-SIG] SGML Python docs

[Fred L. Drake]

Fred L. Drake, Jr. said:
 >   I think it is very important to make authoring fairly comfortable.

Cees de Groot writes:
 > Don't forget that writing a document is only a small piece of a document's 
 > life cycle; personally, I don't think that the verbose markup style of DocBook 

Cees,
  This points to one of the quirks in the world of Python
documentation:  many sections are contributed (most especially in the
library reference), but are maintained centrally after acceptance.
From that perspective, authoring needs to be easy since it is commonly 
done by people who only write a small number of sections.  Maintenance 
is done by someone working on most of the documentation on a
moderately regular basis (me), where the learning curve is more
effectively ammortized.  For the contributing author, there are
typically no maintenance efforts, and if there are, it is usually
accomplished by submitting a bug report.

 > Note that when adding new elements you need to provide DSSSL enhancements as 
 > well if you want to have them stand out in the final text. When using ROLE 

  I don't see this as a problem; I'd expect to provide at least one
print and one online stylesheet for the system.

 > values, you'll generally have the correct rendition. Furthermore, you need to 

  Most of the semantic markings currently used produce a type-style
change, so the style enhancements will be required one way or the
other.

 > publish DTD fragments with the SGML source, and within some editing 
 > environments it may be cumbersome to load these DTD fragments in order to 

  I'm not terribly concerned about the ease of working with any of the 
commercially available SGML/XML editors, since those are usually too
expensive to have hanging around, and I really don't expect many
contributors already have them for other purposes.  I don't know if
emacs' PSGML mode would have difficulty with DocBook sub-/super-sets,
which is more of an issue.  I know vi and notepad would be ok. ;-)  


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191