[Doc-SIG] [Python-Dev] status of development documentation
Michael Foord
mike at pcblokes.com
Thu Dec 22 11:19:32 CET 2005
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
More information about the Doc-SIG
mailing list