Python documentation in DocBook

[Martin v. Loewis]

"David LeBlanc" <whisper at oz.net> writes:

> How could it not be relevent? If more people know xml then know \tex, then
> the number of random people who might be interested in writing python doc is
> apt to be greater if python doc is in xml. 

I think this is an uninformed hypothesis. In all cases where we have
asked people to write documentation, we have offered them to write
them in *any* form they consider appropriate, and that they shoudl not
worry about formatting errors they introduce.

This has worked quite well, and I know of no case where some author
would have contributed documentation if he could have used XML, but
rejected to contribute because it would Latex.

> It seems to me (I could be wrong) that the need for \tex effectively
> bars what is probably the largest group of python users from
> contributing to the doc: MS-Windows users.

I think you are wrong for a number of reasons:

a) the "typical" MS-Windows users is not a contributor to free
   software at all. If he has ever heard of free software, or Python,
   he thinks that this is something made by geeks funded by the
   government (of the respective country he lives in).

b) if that person has ever voiced the notion that he might contribute
   documentation, we have always explained that plain text (without
   any markup) is just as good as anything else. So he could write the
   documentation with MS Word, and use "Save as text"; we would be
   able to process it.

> I think the advantage of pydoc in xml is THE advantage of xml: it's easy to
> slice and dice the document in different ways for different uses. I don't
> know \tex, so I don't know if this is as easily done in that markup.

So what specific, precise uses you need the Python documentation for
which are not covered by the current processing chain (including the
existing conversion to XML?)

> IMO, people don't "know" MS-Word - they push buttons and fill in dialogues.
> Isn't there, or couldn't there be, GUI-based document processors based on
> docbook? 

No, and maybe. FrameMaker 7 is close, but that is a geek application
as well.

> From an economic viewpoint, I think that's likely to be more viable
> then a similar \tex processor...

I edit Python documentation with Emacs, which serves my needs quite
nicely.

> I think the questions should be "How many more people would write python
> documentation if it where easy?"

Easy to answer: Nobody. If you think otherwise, please name one person.

Regards,
Martin