[DOC-SIG] Library reference manual debate

[Paul Prescod]

Guido van Rossum wrote:
> 
> Any proposed solution that doesn't take into account how to convert
> the existing library manual is a trivial reject.

Although this is definately important, I don't see how that would argue
in favour of one solution or another. The output format of such a
process seems easy to handle -- it's the input that will give us a
headache.
 
> 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
> that LaTeX and TeX are losing popularity.  

? Popularity is a problem for TeX, but TIM, which has no popularity to
speak of and is *built on top of* TeX does not have the same problem?

> TeX may still be the
> standard for respectable and somewhat conservative publications like
> the Astrophysical Journal, but most publishers nowadays are just as
> happy to accept MS Word or other popular wordprocessors.

Right, and SGML can create those trivially. TIM cannot. I am currently
writing a book where I will give them a MIF file which they will
beautify for me.
 
> (I
> did a web search on LaTeX for Windows 95; one of the pages,
> http://www2.eece.maine.edu/~dprice/Latex/latex.htm, which seems to
> have a lot of useful info, leaves me with the impression that one
> needs to be *very* motivated to bring this to a good end.  It ends
> with the admonition "Good Luck! You're gonna need it...")

I'm not advocating that we stay with LaTeX, but I found MIKTEX to be
quite easy to install. It doesn't seem to come with all of the latest
and greatest LaTeX add-ons, but otherwise it is quite good and comes
with a good installation program.

> At the moment, both the
> learning curve and the installation effort for SGML or XML tools
> appears to be still steeper than for LaTeX.

I don't think there is anything confusing...especially if you are using
windows. Here are the steps:

Jade installation:

1. Download Jade binary or source
2. Unzip
3. Type "make" if you downloaded the source.
4. Copy binaries to some directory in your path

Python-doc package installation:

1. Download pythondoc zip file.
2. Unzip

The python-doc package contains stylesheets, sample chapters, chapter
template and DTD.

Python-doc chapter creation:

cp chapter-template.sgm my-chapter.sgm
vi my-chapter.sgm

Jade use:

jade -t tex -d style/pythondoc2print my-chapter.sgm
tex &jadetex my-chapter.tex
dvips my-chapter.dvi

OR

jade -t rtf -d style/pythondoc2print my-chapter.sgm
winword my-chapter.rtf

OR

jade -t mif -d style/pythondoc2print my-chapter.sgm
frame my-chapter.mif

OR

jade -t sgml -d style/pythondoc2html my-chapter.sgm
lynx my-chapter.html
netscape my-chapter.html

As far as truth in advertising, I should point out that if your LaTeX is
out of date, you will need to download a few style and font files here
and there to use the JadeTex package. That's why things are not QUITE as
easy on Unix as on Windows (but isn't that always the case?).

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

I don't see any evidence of that. If we stick to the conventions
supported by sgmllib.py, then SGML is as easy to parse as TIM, and we
already have the parser implemented. That parser is only 400 lines of
code (including test harness) and seems to handle the file I emailed a
few days ago perfectly.

> Finally, TIM has been brought up.  It's a bit easier to type and more
> pleasing to my eye than shorthand SGML (e.g. SGML <title>whatever</>
> vs. TIM @title{whatever}) and it's a lot easier to parse.  

I dunno, I consider <title/whatever/ easier to type than
@title{whatever} (look at the keyboard positions), but I acknowledge
that TIM will allow a little bit less markup in some cases. And I
certainly can't argue with pleasing to your eye. Everyone's eyes are
different...

> TIM's primary weakness at the moment seems to be its toolchain, which
> starts good (the parser it written in Python) but quickly runs into
> problems on non-Unix platforms: for HTML generation it uses a Perl4
> script, and for PostScript it goes through texinfo and hence through
> tex.  For Unix, TIM's toolchain is perfect, however, and I like the
> simplicity of its approach -- it should be simple enough to rewrite
> the TIM-to-HTML converter in Python (maybe using HTMLgen?).

So we would rather rewrite this rather than using the existing HTML
converters for DocBook? Despite the fact that the DocBook converters
already handle print properly on Windows (RTF/TeX/Frame) and
Unix(Tex/Frame)? 
 
> For Windows, it just *may* be possible that Word 97 will actually
> parse the HTML generated by TIM so as to make it possible to generate
> Postscript on Windows platforms with commonly available tools; in any
> case, a prospective TIM author on a Windows platform would only need
> the HTML generating part of the toolchain for on-screen previewing.

Printing HTML documents seems like a solution of last resort. 
 
> However, I don't want to compromise
> TIM to make it possible to parse it with a generic SGML scanner; the
> efforts to move HTML towards strict SGML scanner compatibility have
> taught me a valuable lesson.

I'm not sure what you mean by this. HTML has been SGML compatible since
version 2.0. As far as I know, it lost no useful features in the
changeover.

I can't dispute the point that SGML doesn't look nice to your eyes.
Beauty is in the eye of the beholder. That might be enough to tip the
balance in TIM's favour, but I still feel it is my responsibility to
point out that SGML is not hard to type, need not be hard to parse and
does not require difficult or expensive tools to use. If those
complaints are going to be factors in the decision then they should be
substantiated.
 
 Paul Prescod

_______________
DOC-SIG  - SIG for the Python Documentation Project

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