opinion: comp lang docs style

[Google Poster]

On Jan 4, 12:24 pm, Xah Lee <xah... at gmail.com> wrote:
> a opinion piece.
>
> 〈The Idiocy of Computer Language Docs〉http://xahlee.org/comp/idiocy_of_comp_lang.html
>
> --------------------------------------------------
> The Idiocy of Computer Language Docs
>
> Xah Lee, 2011-01-03
>
> Worked with Mathematica for a whole day yesterday, after about 10
> years hiatus. Very nice. Mathematica lang and doc, is quite unique.
> Most other langs drivel with jargons, pettiness, comp-sci
> pretentiousness, while their content is mathematically garbage.
> (unixism mumble jumple (perl, unix), or “proper”-engineering OOP
> fantasy (java), or impractical and ivory-tower adacemician idiocy as
> in Scheme & Haskell ( currying, tail recursion, closure, call-cc,
> lisp1 lisp2, and monad monad monad!)) (See: What are OOP's Jargons and
> Complexities ◇ Language, Purity, Cult, and Deception.)
>
> Mathematica, in its doc, is plain and simple. None of the jargon and
> pretention shit. Very easy to understand. Yet, some of its function's
> technical aspects are far more scholarly abstruse than any other lang
> (dealing with advanced math special functions that typically only a
> few thousand people in the world understand.).
>
> ------------------------------
> A Gander into the Idiocies
>
> Here's a gander into the doc drivel in common langs.
>
> ------------------------------
> unix
>
> In unix man pages, it starts with this type of garbage:
>
>     SYNOPSIS
>            gzip [ -acdfhlLnNrtvV19 ] [-S suffix] [ name ...  ]
>            gunzip [ -acfhlLnNrtvV ] [-S suffix] [ name ...  ]
>            zcat [ -fhLV ] [ name ...  ]
>
>     SYNOPSIS
>            zip  [-aABcdDeEfFghjklLmoqrRSTuvVwXyz!@$]  [--
> longoption  ...]   [-b path] [-n suf
>            fixes] [-t date] [-tt date] [zipfile [file ...]]  [-xi
> list]
>
> Here, the mindset of unix idiots, is that somehow this “synopsis” form
> is technically precise and superior. They are thinking that it
> captures the full range of syntax in the most concise way. In
> practice, it's seldomly read. It's actually not accurate as one'd
> thought; no program can parse it and agree with the actual behavior.
> It's filled with errors, incomprehensible to human. Worse of all, the
> semantic of unix software's options are the worst rape to any possible
> science in computer science. See: The Nature of the Unix Philosophy ◇
> Unix Pipe As Functional Language ◇ Unix zip Utility Path Problem.
>
> ------------------------------
> Python
>
> In Python, you see this kinda garbage:
>
>     7.1. The if statement
>
>     The if statement is used for conditional execution:
>     if_stmt ::=  "if" expression ":" suite
>                  ( "elif" expression ":" suite )*
>                  ["else" ":" suite]
>
> (Source docs.python.org)
>
> Here, the mindset of the python idiots is similar to the unix tech
> geekers. They think that using the BNF notation makes their doc more
> clear and precise. The fact is, there are so many variations of BNF
> each trying to fix other's problem. BNF is actually not used as a
> computer language for syntax description. It's mostly used to
> communicate syntax to humans. Like regex, there are so many
> variations. But worse than regex in the sense that there are actually
> not many actual implementations of BNF. Real word syntax description
> language are usually nothing close to BNF. See: Pattern Matching vs
> Lexical Grammar Specification.
>
> This incomprehensible BNF notation is the only thing you get if you
> want to know the basic syntax of “if”, “for”, “while”, “lambda”, or
> other basic constructs of python.
>
> ------------------------------
> Perl
>
> In perl, you see this type of drivel:
>
>     A Perl program consists of a sequence of declarations and
> statements which run from the top to the bottom. Loops, subroutines
> and other control structures allow you to jump around within the code.
>
>     Perl is a free-form language, you can format and indent it however
> you like. Whitespace mostly serves to separate tokens, unlike
> languages like Python where it is an important part of the syntax.
>
>     Many of Perl's syntactic elements are optional. Rather than
> requiring you to put parentheses around every function call and
> declare every variable, you can often leave such explicit elements off
> and Perl will figure out what you meant. This is known as Do What I
> Mean, abbreviated DWIM. It allows programmers to be lazy and to code
> in a style with which they are comfortable.
>
>     Perl borrows syntax and concepts from many languages: awk, sed, C,
> Bourne Shell, Smalltalk, Lisp and even English. Other languages have
> borrowed syntax from Perl, particularly its regular expression
> extensions. So if you have programmed in another language you will see
> familiar pieces in Perl. They often work the same, but see perltrap
> for information about how they differ.
>
> (Source perldoc.perl.org)
>
> Notice they introduced you to their lingo “DWIM”. Juvenile humor is a
> characteristics of perl's docs. It's a whole cult. They have “perl
> republic”, “state of the onion”, “apocalypse”, “perl monger”, “perl
> golf”, etc.(See: Larry Wall and Cults.) Another trait is irrelevant
> rambling. For example, in the above you see: “Perl borrows syntax and
> concepts from many languages: awk, sed, C, Bourne Shell, Smalltalk,
> Lisp and even English.”.
>
> However, perl doc overall is more practically usable than Python's.
>
> ------------------------------
> Haskell
>
> Here's a example of ivory-tower idiocy, from Haskellers:
>
>     Haskell uses a traditional Hindley-Milner polymorphic type system
> to provide a static type semantics [4, 6], but the type system has
> been extended with type classes (or just classes) that provide a
> structured way to introduce overloaded functions.
>
>     A class declaration (Section 4.3.1) introduces a new type class
> and the overloaded operations that must be supported by any type that
> is an instance of that class. An instance declaration (Section 4.3.2)
> declares that a type is an instance of a class and includes the
> definitions of the overloaded operations—called class methods—
> instantiated on the named type.
>
>     For example, suppose we wish to overload the operations (+) and
> negate on types Int and Float. We introduce a new type class called
> Num:
>
>       class Num a  where          -- simplified class declaration for
> Num
>         (+)    :: a -> a -> a     -- (Num is defined in the Prelude)
>         negate :: a -> a
>
>     This declaration may be read “a type a is an instance of the class
> Num if there are class methods (+) and negate, of the given types,
> defined on it.”
>
> (Sourcewww.haskell.org)
>
> Note the words “Hindley-Milner”, “polymorphic”, “static type
> semantics”, “overloaded operations”.
>
> The reason they wrote their doc like that is because they are
> academicians. You might think that their writing is really scholarly,
> mathematically meaningful, almost provably correct, full of dense
> mathematical rigor, and necessarily hard to understand because of the
> advanced math ideas. By the look of it it is really daunting. The
> irony is that the writing is often imprecise, most use of tech jargons
> and terms are absolutely uncessarily to the point of being irrelevant.
> And, the writing quality is pretty bad, far below the quality of
> standard math journal's articles.
>
> --------------------------------------------------
>
> uhmm, happy 2011.
>
>  Xah ∑http://xahlee.org/☄


Fell free to rewrite the docs of those programming languages in iambic
pentameter, adding harp octaves in the background.

-Ramon