Re: [Jython-dev] Jython documentation

[Mats W. <ma...@la...>]

 >> Well, latex does seems somewhat old and dusty (just IMHO). The list of
 >> tools also seems quite intimidating. I haven't searched for them yet,
 >> but some look very unix centric. Obviously I will prefer an enviroment
 >> where I too can generate the output files on my win2k. Does the latex
 >> tools also exists on windows?

 >After surfing a bit, it does seem latex is more *nix-centric and
 >not nearly as ubiquitous as I had thought. I'm terribly uninformed
 >about win/mac tools, so I'd better get things working on Windows
 >before suggesting ;)  All hints are welcome from other win/mac
 >latex users.

TeX itself (and thus Latex) is available for Windows platforms and
works fine.  I've used it (rarely, however) in that environment
for many years. Where we probably get into trouble is all the
conversion tools that turn the base docs into different output styles,
esp. the webpages we know and love...

 >> If we pick a CVS based route, I think we should add a new CVS module (we
 >> already have "jython" and "htdocs") that contains only the doc sources.
 >
 >Agreed.  And better saved for when "formal" layout is figured
 >out (i.e. will latex+win/mac be a nuissance).
 >
 >The idea of generating content in a wiki before
 >formalizing docs might allow quick start despite the
 >unknowns in formal layout.
 >
 >I put up a couple wiki pages for those anxious to get started (I
 >hope this was ok):
 >
 >http://www.jython.org/cgi-bin/moin.cgi/JythonDevelDocs

The advantage in starting from the existing CPython docs is
that there's a lot that's reusable, and it's cleaner to
fold in the changes as the Python languages itself evolves,
always consiering that CPython continues to be the reference
implementation (maybe it will be Python.net instead :-)
(no, really, that was a joke).

I agree with Finn: I also find the Latex stuff old and clunky,
and I say that from the viewpoint of someone who used to *like*
troff. The real irritant, to me, is that to use it effectively
you almost have to use emacs, and I loathe and detest emacs.
So there.

There's also the problem that the CPython docs depend on tools
that are a little fragile - they're not that well understood
and when stuff breaks, tweaking them breaks other things. The
hyperlinks in the html output, for example, are not generating
correctly all the time.  There was big head scratching over the
2.0 tutorial where they were completely broken, and I just ran
across some in the 2.1 docs that are also busted.  Someone might
ask Fred Drake for an opinion, my view is just that of an outside
observer, he's working with this stuff all the time.

I'm not convinced there's a better, stable, cross-platform
answer out there today, but probably *soon* there will be
a stable enough xml-based system (that can even generate
the old latex if needs be).  There are such systems today,
but I don't think they fit all of the criteria one might
want: (stable, usable, cross-platform, free)

So I guess I endorse the concept of gathering information
someplace where at least it's recorded and discussed, and
then hash out the production details.

Mats