[DOC-SIG] Library reference manual debate

[Fred L. Drake]

Guido van Rossum writes:
 > Some SGML extremists have started lobbying for SGML or XML, which has

  Ouch!

 > The first problem is that the library manual is currently done in
 > LaTeX.  I would guess that 99% of the markup is structural -- the only

  I don't see that this will be too difficult a conversion, actually,
primarily due to the care with which most of the markup was
performed.

 > I see a number of problems with the use of LaTeX -- but the fact that
 > "it's not SGML" is not one of them.  Perhaps the biggest problem is

  Agreed; that's not a relevant issue.

 > would say that LaTeX does computer documentation rather poorly
 > (witness the many hacks in the myformat.sty file), and I haven't even
 > dealt properly with optional or keyword arguments, let alone classes

  LaTeX isn't designed for it; it's supposed to be much more general
than that.  However, as myformat,sty shows, the appropriate markup can 
be created.  With a bit more work, the remaining semantic constructs
can be created, but they may contain a moderate amount of formatting
within the macros.  I think this is the most substantial problem with
a TeX-based solution; myformat.sty has to be completely rewritten to
change the output; the markup is not defined separately from the
processing (formatting) steps.

 > The decreasing popularity of LaTeX is a problem because it means that
 > potential contributors are discouraged -- many simply don't know

  This may have some pertinence, but the relevance is small; it's
still better than most if not all of the more popular systems.
SGML/XML is better due to the separation of semantic relations from
the processing specifications.

 > LaTeX, and even those that do know it may not have access to an
 > implementation any more.  Installing LaTeX is a major undertaking, and

  Agreed, outside some Linux distributions, LaTeX is probably a pain
unless you're willing to spring for a commercial version.  There are a 
few for PCs, but I've not followed them.

 > Another problem, caused by this, is that there are few LaTeX hackers
 > around who can help with the creation of new macros (e.g. for keyword
 > arguments).

  If that's the problem and no superior solution can be agreed upon, I
can help with that.

 > ain't broken."  I personally have access to a working LaTeX
 > installation, the latex2html converter produces adequate HTML (I still

  It's out of date and should be updated, but does work for the Python 
documentation.  I have found very reasonable LaTeX2e documents that
can't be formatted correctly using the CNRI installation.

 > There has been some debate on SGML vs. XML.  It seems that SGML can be
 > made easy to type, at the cost of making it much harder to parse
 > correctly.  XML appears to be designed mostly as a transport format

  I've seen nothing to indicate that SGML is more difficult to parse
correctly in any reasonable interpretation, and if the examples Paul
presented on shortcuts are what yo're refering to, the work's already
been done in Grail's SGMLParser module.

 > structural markup and has a simple macro language to add new
 > structural elements.  This makes it relatively easy to convert to

  The last time I looked at it, the only "structural" elements which
could be added were alternate names for the character-styling controls 
(bold, italic, etc.) and not for larger structural components.  Has
this changed?  It might have.

 > Those who want SGML or XGML should be able to convert TIM to their

  This is not an interesting issue; if you choose to use TIM for the
authoritative version, there should be no reason to convert to
SGML/XML except to have access to powerful formatting tools (DSSSL and 
jade in particular).
  It sounds as if you're convinced that there should be either no
change or conversion to TIM.  If this is the case and you won't
consider other alternatives seriously, please just say so.  I think
all of us advocating other approaches are doing to in good conscious
and not just to waste bandwidth.  If we're wasting time, we can find
more enjoyable ways to do so.
  If, on the other hand, there's a real possibility of switching to at 
all, the advocates / experts for each format / technology / whatever
you want to call it should start to develop sample processes and
converted segments of the Python documentation to allow all of us to
see the behavior of each in practice.  I don't think many of us have
actually tried to use all of the techniques being discussed.  This may 
be more productive than just shouting "Use FOOsplatter!" at each
other.  But we do need to know that we're not wasting our time at it
before we bother.


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