[DOC-SIG] Library reference manual debate

[raf]

Here are some opinions regarding the choice of doc
submission formats and what will deter contributors from
submitting docs:

>John Skaller writes:
> > My opinion is that fixing a format is the best way to exclude
> > most potential submitters. But if a format has to be
> > picked, it had better be ordinary old HTML, so it can
> > be put up on a website and used immediately by everyone.

Many years ago, I was unfortunate enough to have to use troff.
I detested it for what I believe are the obvious reasons.
I've looked at TeX but wasn't unfortunate enough to have to use it.
Of this, I am glad. I've looked at Lout - far less repulsive to the eye
but they are *all* dreadful. TeX and Lout may produce lovely documents
but troff's and TeX's user interfaces (i.e. syntax) are foul and as far
as I could see, there were all *output* formats :) I could never help
but think:

    "This could never have been intended for humans.
     Surely programs are meant to generate and read this.
     This must be against the Geneva Convention!."

If you've already invested time in learning TeX, I can see that you'd
be willing to use it, but what proportion of actual and *potential* python
contributors are TeX literate? What will that figure be ten years from now?

I can't believe that those who don't already know TeX would be
happy about having to learn it (What would be the point? Suffer pain
just for Python docs? No thanks). SGML/XML is another system I know
bugger all about but the difference is severe genericity and a
much better user interface (i.e. syntax). It doesn't look painful at all.
And learning SGML doesn't feel like a dead end. I think far more people,
given a choice, would be willing to learn SGML rather than TeX.
If they can cope with HTML, they can cope with SGML.

What I'd like to see (to enhance public contribution to the docs):

    1) Accept SGML
    2) Select/Create a DTD
    3) Implement an wysiwyg-ish editor for that DTD in Python
    4) Distribute the editor along with Python

Then it would be easy for people to contribute docs.

If TeX is the choice chosen, at least:

    1-4) above
    5) Define the process for converting the aforementioned DTD into TeX
    6) Distribute that along with Python (and the editor) as well


raf


_______________
DOC-SIG  - SIG for the Python Documentation Project

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