[PYTHON DOC-SIG] SGML-Tools

Fred L. Drake fdrake@CNRI.Reston.Va.US
Mon, 10 Feb 1997 15:56:54 -0500 (EST)


Graham C. Hughes wrote:
> Do you mean `advantages to SGML-Tools' or `advantages to SGML'?  SGML
> has a lot to recommend it for this sort of idea, starting with the fact

Graham,
  Sorry for being unclear; I meant SGML-Tools specifically (I still
tend to think Linuxdoc-SGML, must be getting dated).  I am a strong
advocate of SGML.

> SGML-Tools has the benefit that a large number of translators (to LyX,
> RTF (and thence to Windows Help), HTML, LaTeX, even straight text) are

  Translators are already available, yes, but the source format isn't
sufficiently different from LaTeX to give any particular cause to
convert.  Yes, the interpretation of individual characters is
difference and easier to handle, but that's about it; there is no
additional logical structure to take advantage of, and that's where
the usefulness of SGML comes in.  Something like DocBook would give a
little more useful structure, but still has some fairly substantial
overhead where SGML tools are not the norm, and authoring in emacs
would be non-trivial even with PSGML mode.
  I'd like to see a DTD that is reasonably simple but which includes
elements such as FUNCTION, METHOD, CLASS, CONSTANT, PARAMETER, and
others which might be useful to describe the structure of module
contents with somewhat more clarity than the current LaTeX definitions
do.  I don't expect it to be hard to develop, but it would take time
to think through and really get it right.  This is not something I
expect to be able to allocate any real time to which is why it hasn't
already been done.

> <on distribution, Guido says...>
> > > On the other hand, the list of software that is *required* to make it
> > > work is rather impressive, and I wonder how easy it would be to do
> 
> One option is to distribute the SGML files, and either write a Python
> SGML parser (not a lot of fun...) or simply have the full documentation
> in various formats up on ftp.python.org.  We could even be magnanimous
> and distribute the HTML output with the distribution.

  I don't think there are problems with what is distributed; the
problem is primarily one of maintainability.  Extension authors will
need to be able to keep their documents up-to-date and preview the
formatted versions.  A heavy SGML environment creates a problem for
this (witness the complaints when Guido moved the language
"specification" document to FrameMaker); the processing required
should be readily achievable.
  The Python SGML parser *would* be quite fun, actually, if a little
tedious to make really general.  ;-)


  -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
_______________