[Python-Dev] status of development documentation

[Barry Warsaw]

On Wed, 2005-12-21 at 22:40 +0100, Fredrik Lundh wrote:

> > Sorry, but HTML and (even more so) XML are not human-writable. :)  Yeah,
> > we can all do the simple stuff, but I absolutely hate authoring in HTML,
> > and it would be a nightmare if the documentation production system
> > didn't handle lots and lots of magic for you (like weaving in the right
> > footers, css, etc. -- oh wait, that's ht2html!).
> 
> Sure, and some people hate using whitespace for block structure.

A more proper analogy would be people who hate braces and parentheses.
You have to type so many more < and > characters (not to mention &s
and ;s) to make happy-joy html than you have to type \s and {s and }s to
make nice-nice latex.

> > Maybe it's just because I came in late on this thread, but what exactly
> > is broken about the current LaTeX documentation?
> 
> Checked the python-list archives lately?  

That's a joke, right?

> If you google c.l.python for the
> word "documentation", you'll find recent megathreads with subjects like
> "bitching about the documentation", "opensource documentation problems"
> and "python documentation should be better" among the top hits.  But if
> you check the bug and patch trackers, you don't find many contributions.
> Something's definitely broken.

I'm not convinced it's the toolchain though.  People hate writing
documentation.  Getting people to contribute documentation is worse than
pulling teeth.  If people can't install the required toolchain and
they're still highly motivated to write Python documentation, then we
already recommend they just write it in plain text and "someone" will
mark it up.

Heck, I wouldn't mind an xml2latex converter so those that like a
different kind of pain (writing xml vs. installing latex) can still
contribute documentation and we can convert it to back to latex.

-Barry

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 307 bytes
Desc: This is a digitally signed message part
Url : http://mail.python.org/pipermail/python-dev/attachments/20051221/1b3d2861/attachment.pgp