[Doc-SIG] SGML Python docs

[Fred L. Drake]

 On Tuesday, September 08, 1998 10:01 PM, Fred L. Drake wrote:
 > to this particular documentation set.  I am very concerned about
 > actually authoring in DocBook.

Richard Folwell writes:
 > What are your concerns here?

Richard,
  My primary concern here is in the volume of the DTD and some of the
intricacies of things like indexing.  The current LaTeX markup is
fairly friendly to someone working on the index, making it reasonably
easy to insert new entries.  This includes things which should be
visible at multiple points in the index, using \indexii, \indexiii,
\indexiv.
  When I was working on the conversion script, I looked at the
index-generating elements from DocBook at found them very verbose.
Perhaps some form of tag omission or the use of empty tags (SGML only, 
not XML) can make it tolerable; I'd have to take another look at it to
remember the specifics.
  I think it is very important to make authoring fairly comfortable.
We may be able to use a DocBook variant for authoring, with more
allowable tag omission, but I don't want to require a conversion stage 
or expensive tools.  Authors should be able to use vi or notepad if
that's what they want, and still not to have to do anything more than
is currently needed to mark documents in LaTeX.
  I suspect that to maintain all the semantic codings from the current 
LaTeX markup, new elements would need to be added (or define values
for the ROLE attribute).  I'd personally prefer new elements over ROLE
values to reduce the volume of the markup.


  -Fred

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