How to convert (unicode) text to image?

rurpy at yahoo.com rurpy at yahoo.com
Tue Aug 31 06:44:06 CEST 2010


On 08/30/2010 04:50 AM, Thomas Jollans wrote:
> On Monday 30 August 2010, it occurred to rurpy at yahoo.com to exclaim:
>> Face the facts dude.  The Python docs have some major problems.
>> They were pretty good when Python was a new, cool, project used
>> by a handful of geeks.  They are good relative to the "average"
>> (whatever that is) open source project -- but that bar is so low
>> as to be a string lying on the ground.
>
> Actually, the Python standard library reference manual is excellent. At least
> that's my opinion.
>
> Granted, it's not necessarily the best in the world. It could probably be
> better. But that goes for just about every documentation effort there is.
>
> What exactly are you comparing the Python docs to, I wonder? Obviously not
> something like Vala, but that goes without saying. "kj" said that the Perl
> docs were better. I can't comment on that. I also won't comment on the sorry
> mess that the language "Perl" is, either.
> There are a few documentation efforts that I recognize are actually better
> than the Python docs: Firstly, the MSDN Library docs for the .Net framework.
> Not that I refer to it much, but it is excellent, and it probably was a pretty
> darn expensive project too. Secondly, the libc development manual pages on
> Linux and the BSDs. Provided you know your way around the C library, they are
> really a top-notch reference.

The Postgresql docs have always seemed pretty good to me.  And I'll
second
kj's nomination of Perl.  The Perl docs have plenty of faults but
many
years ago I was able to learn Perl with nothing more than those docs.
It
was well over five years later that I ever got around to buying a
commercial
Perl book.  In contrast, I made several, honest efforts to learn
Python
the same way but found it impossible and never got a handle on it
until
I bought Lutz's and Beazley's books.  (Of which Bealey's was by far
the
most useful; Lutz became a doorstop pretty quickly.  And yes, I knew
about
but didn't use the tutorial -- tutorials are one way of presenting
information
that aren't appropriate for everyone or in every situation, and the
existence
of one in no way excuses inadequate reference material.)

If one is comparing the Python docs to others, comparing it to
Beazley's
book is informative.  Most of the faults I find with the book are the
places
he took material from the Python docs nearly verbatim.  The material
he
interprets and explains (usually quite tersely) is much clearer that
similar material (if it even exists) in the Python docs.

Finally, it it not really necessary to compare the Python docs to
others
to make a judgment -- simply looking at the hours taken to solve some
problem that could have been avoided with a couple more sentences in
the
docs -- the number of hours spent trying figure out some behavior by
pouring over the standard lib code -- the number of times one decides
how
to write code by "trying it", with fingers crossed that one isn't
relying
on some accidental effect that will change with the next version or
platform -- these can give a pretty good indication of the magnitude
of the doc problems.

I think one reason for the frequent "Python docs are great" opinions
here
is that eventually one figures out the hard way how things work, and
tends
to rely less on the docs as documentation, and more as a memmonic.
And
for that the existing docs are adequate.





More information about the Python-list mailing list