How to convert (unicode) text to image?

[Arnaud Delobelle]

kj <no.email at please.post> writes:

> 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.)

The first time you read the PIL docs, read the introduction.  After that
I find the docs pretty easy to use, even though it is true that it is
quite terse.

E.g. for the mode, look at the "concepts" page in the intro:

http://www.pythonware.com/library/pil/handbook/concepts.htm

> 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 find the Python docs very good on the whole.

> 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"...

I have never programmed in Perl (although I have needed to read some
Perl) but over the years I have used C, C++, lisp variants, PHP, Ruby, Caml
variants, Haskell, Javascript (and others before the era of the
web).  I don't find that Python online docs on the web are worse than
online docs for any of those languages.

-- 
Arnaud