In <mailman.123.1282955703.29448.python-l...@python.org> Benjamin Kaplan <benjamin.kap...@case.edu> writes:
>On Fri, Aug 27, 2010 at 8:01 PM, kj <no.em...@please.post> wrote: >> >> >> Hi! =A0Does anyone know of an easy way to convert a Unicode string into a= >n image file (either jpg or png)? >> >Do you mean you have some text and you want an image containing that >text? PIL's ImageDraw module can do that. Thanks for the pointer, but... <RANT> The documentation I have found for PIL (at http://www.pythonware.com/library/pil/handbook) is beyond atrocious. If this is the only way to learn how to use this library, then I really don't understand how anyone who is not clairvoyant can do it. Example: I went to the docs page for ImageDraw. There I find that the constructor for an ImageDraw.Draw object takes an argument, but *what* this argument should be (integer? object? string?) is left entirely undefined. From the examples given I *guessed* that it was an object of class Image, so I repeated the exercise: I consulted the docs for the Image module. There I learn that the constructor for the Image class takes among its parameters one called "mode" and one called "color", but, here again, what these parameters are is left completely undefined. ("mode" is left both syntactically and semantically undefined; "color" is left syntactically undefined, though the documentation includes a bit by way of semantic definition of this parameter.) What's up with this practice of leaving parameters undefined like this??? Wasn't it obvious to the person writing the Image module docs that without explaining what these parameters should be the documentation is nearly useless? Is such poor documentation an unintended consequence of "duck typing"??? Sorry for the outburst, but unfortunately, PIL is not alone in this. Python is awash in poor documentation. The number two complaint I've heard from those who dislike Python is the poor quality of its documentation, and in particular the fact that function parameters are typically left undefined, as is the case in the PIL docs. I like Python a lot, but I have to agree with this criticism. (The number one complaint has to do with the syntactic significance of whitespace; of course, I find *this* criticism silly.) What is most frustrating about such poor documentation is that it is exactly the opposite from what one would expect from the carefulness and thoroughness found in the PEPs... I have been using Python as my primary scripting language for about one year, after many years of programming in Perl, and now Python is my language of choice. But I must say that the documentation standards I found in the Perl world are *well above* those in the Python world. This is not to say that Perl documentation is always excellent; it certainly has its gaps, as one would expect from volunteer-contributed software. But I don't recall being frustrated by Perl module docs anywhere nearly as often as I am by Python module docs. I have to conclude that the problem with Python docs is somehow "systemic"... </RANT> -- http://mail.python.org/mailman/listinfo/python-list
