Python = Pretentious Sheet
xah's rumination extempore❗ №20131128T183510
much of python doc, and its community, is a mirror of Guido's mindset and demeanor.
for example, the python community, its irc, mailing, often you'll find they require registration to join, and is heavy on ban or kicking out people they deem not good citizens. This is in contrast to, for example, perl community, which welcomes and embraces everyone.
also, in py community, the people are often haughty, pythonic above you.
also, in python doc, you see the pretentiousness everywhere. Most apt description of its style is “Comp Sci Я Us”. When you need to open a file, access stdin/stdout, regex, or anything, instead of showing you directly how to, it resorts holier-than-thou structure with jargons, and no direct link, no examples.
the python doc is one incomprehensible faka.
every year, in comp.lang.python afaik from about 2005 to 2010, there are people complaining about python doc, but the python priests refuse to fix it, retorting things like PEP, wanting you to climb the proper ladder to get the doc fixed, and denial. In this respect, it's not unlike FSF/GNU faka.
and, python priests don't see a problem themselves, with verbiage how it's so clear. This is not surprising, similar to GNU people defending emacs lisp doc style nineteen seventy nine, or the Common Lisper defending the web 0.1 style “HyperSpec”.
i wrote a ton about python doc problem. Python Doc Idiocies
here's a new one today. In trying to refresh my python, i need to do something in emacs to process some string for my website, instead of using elisp, which i can finish in 10 min, i went with python instead. That is, a simple emacs lisp wrapper that call shell which call python script that take stdin and out in stdout and feed back to emacs which shows as the transformed result in buffer. e.g. 〔see Emacs Lisp Wrapper for Perl/Python/Ruby Scripts http://ergoemacs.org/emacs/elisp_perl_wrapper.html 〕
a line like this in buffer:
<span class="ref"><a href="../python_doc_3.3.3/library/os.html#os.walk">16.1. os — Miscellaneous operating system interfaces — Python v3.3.3 documentation #os.walk</a></span>
but i don't remember python io stuff. So first i google. There's
and some mention module
fileinput, which is nice in that it
read lines of all inputs, including
stdin and all files from
script's args. But i can't use because i also need to pass current file
path in order to get relative path. i want to use
So, i read the doc
28.1. sys — System-specific parameters and functions — Python v3.3.3 documentation
it talks about some lala land about file objects and input() and print(). Then, clicking on file object goes to glossary that tells me what it means. LOL. I no need meaning, i need doing. It sayz “ Their interfaces are defined in the io module”. faka u with ur interface faka. I clicked on the io, then it talks about text io, binary io, raw io, high level module interface, class hierarchy. Motherfaka python you.
oh, btw, in python doc, there's often nary one example. Did i mention the writing quality is by a idiot?
it's actually quite funny. The style manifest as comp sci exposition, yet the writing quality is kindergartener.
you see? this is interesting because, contrast to perl community and perl doc, …
in perl, although they love unix drivels and syntax mumble jumble, but the doc is lousy too. Its style is unix drivel, quality is juvenile, but it reasonably let you find stuff and get to know how to do things. It has full examples about every few paragraphs. you wanna know how to do stdin stdout? in 1 min you find full code examples in perl official doc.
btw, one can also contrast this with java doc. Althoug i don't like java, but java doc, the writing quality, and organization, is professional. Written by professional writers. No random juvenile joke, no random proselytization. Note: java doc, also devoid of examples, like python, but, it's professional written, and the effect is quite different. If a programing language doc can be chalked up to computer science, then, Java's doc is a cathedral, Python's The House Of Legos.
my pain, is that, the most interesting thing is that when you talk to perl and python people, or even most programers, they don't know what quality means in lettering. Unix man and scifi is about the best they've read. What a wonder.
this is actually similar to lisp issues when talking to lisp fanatics. When you repeat a fact, with clear proof, again again again, where everybody who don't use lisp see it clearly, but lispers don't see it. The next day, they are back to singing macros and sexp, and in their mind, they thought they proved you are wrong.
that's actually human nature.
Python Documentation Sucks
- Python Doc Problem: os.system
- Python Doc Problem: os.path.split()
- Python Doc Problem: sort()
- Python Doc Problem: gzip
- Python Documentation Problems
- Python Documentation Author Masturbation
- How to Improve Python Doc; Notes on Rewriting Python Regex Doc
- Why Python's Documentation Sucks
- Python Poetry: the __main__ Stanza
- perldoc Coming of Age, What Python Can Learn From?
- Examples of Quality Documentation in Computing Industry
- Python Doc Links Dead
- Python Doc Links All Dead
- Python = Pretentious Sheet
- Optional Function Parameters in Computer Language Docs (the idiocy thereof)
If you have a question, put $5 at patreon and message me.