[Doc-SIG] [Python-Dev] status of development documentation

[Michael Foord]

Steve Holden wrote:
> Laura Creighton wrote:
> 
>>Whenever people have demanded that I write documentation in html
>>I have always done this:
>>
>><pre>
>>all my documentation, as output from a text editor.
>>
>>All subsequent formatting to be done by somebody else who doesn't
>>find dealing with html as excruciatingly painful as I do.
>></pre>
>>
>>I suspect there are lots of people who have concluded that this
>>is all the html that you really need.  The question is, are you
>>willing to put up with documentation like this from people?
>>
> 
> Well the existing system can cope with that style, but for some reason 
> the oft-repeated advice that plain text markup is an acceptable format 
> for documentation contributions doesn't seem to have escaped the gravity 
> field. So that's just as good for the existing docs as anything that 
> replaces them (if anything does).

Hmmm... I submitted some plain text (might have been reST actually) docs
as a suggested addition to urllib2. The response from the maintainer)
was that I ought to submit it as patches against the original Tex document.

Now admittedly what I submitted *does* need breaking into smaller
sections to make it easier to add to fit into the docs. (IIRC the error
classes are barely documented in urllib2 - vital information is missing
from the docs).

*However* - there was no implication that the maintainer was happy to
work with plain text submissions.

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

> regards
>   Steve