[DOC-SIG] Comparing SGML DTDs

[Paul Prescod]

Michael McLay wrote:
> Downside:
> 
>   1) Heavy dependance on external programs which may not be on every platform
>         MAKEINFO = '/usr/bin/makeinfo'
>         TEX = '/usr/bin/tex'
>         TEXINDEX = '/usr/bin/texindex'
>         DVIPS = '/usr/bin/dvips'
> 
>   2) May require some work to get the reference manual indexing
>      working with the new tools.
>   3) Restricted set of tags, which makes it fairly hard to extend
>      (except by using macros.)
>   4) Mixes macro language with markup.  Is this really a problem?
>      The TIM macros seem to primarily be used to declare context names
>      which are then translatable to generic typographic codes.  This
>      should make it easier to move the tagged text to meaningful XML
> tags.

    5) Mixes formatting ("@page, @noindent") with structure
("@codeexample")
    6) Does not seem to allow restrictions on macro roles to be
expressed
    7) There are no editors that will help you to create TIM documents
correctly (and will probably never be)
    8) We will have to develop new output formats from scratch whereas
with SGML/Jade they are reused across an industry.
    9) FrameMaker cannot import or export TIM, so we will have written
off a great WYSIWYG typesetting tool.

More important, to me: using TIM would generally contribute to the
"multiplication of documentation formats". The rest of the software
industry is about to rally around SGML's XML incarnation. Bill Gates
says its the greatest thing since sliced bread. Marc Andreeson agrees
with him (first time in history!). Adobe is also on board. I know many
cygnus people are interested in SGML and are working to move cygnus
tools over.

XML is not exactly what we want, but SGML is at least still in the same
ballpark -- the same parsers and other tools will usually support
either. The same DTDs can support both. Python software that we develop
to support SGML will be used across many different projects. Whereas
software to support TIM will probably be used for the library reference,
ILU and nothing else. Great SGML support in Python would actually
attract new users. I know I've turned some people onto Python via SGML
and so have others...there are even books on SGML that discuss Python.
One day there may be a book on SGML processing in Python.

In short, I think that subscribing to standards is the Right Thing
unless they are flawed. IMO, nobody has yet made a serious case against
SGML in this regard. SGML addressed everything that everyone has
complained about ("too verbose", "no tools", "too many delimiter
chars").

If we want, we can also define an SGML subset simple enough to be parsed
with Python tools alone. We will just take XML and add back in the
shortcuts we like from SGML and fix up sgmllib.py to support them. There
is no reason that SGML should be harder to parse than TIM if we restrict
ourselves to a subset. Really the only thing that's very hard about
generic SGML is automatic tag omission. If we forgo that (as TIM does)
then SGML is not really hard to parse.

 Paul Prescod

_______________
DOC-SIG  - SIG for the Python Documentation Project

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