opinion: comp lang docs style

Discussion:

(too old to reply)

Xah Lee

2011-01-04 18:24:24 UTC

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

(Source www.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/ ☄

Jason Earl

2011-01-04 20:24:35 UTC

Permalink

Actually, it *does* capture the full range of syntax in a concise way.
If you know of man pages where the Synopsis does not match the syntax
then you have found a documentation bug, which should be reported so
that it can be fixed.

In fact, if anything the real problem with the Synopsis is that it is
too concise. Fortunately gzip is a bit of an extreme example. Most man
pages look more like this:

--8<---------------cut here---------------start------------->8---
NAME
tar — The GNU version of the tar archiving utility

SYNOPSIS
tar [-] A --catenate --concatenate | c --create | d --diff --compare |
--delete | r --append | t --list | --test-label | u --update | x
--extract --get [options] [pathname ...]
--8<---------------cut here---------------end--------------->8---

That synopsis is pretty useful. If you have used tar before and just
need a refresher chances are very good that the synopsis will do the
trick.

If you look at the man pages from the Linux Programmer's Manual the
Synopsis makes even more sense.

--8<---------------cut here---------------start------------->8---
NAME
open, creat - open and possibly create a file or device

SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

int open(const char *pathname, int flags);
int open(const char *pathname, int flags, mode_t mode);

int creat(const char *pathname, mode_t mode);
--8<---------------cut here---------------end--------------->8---

Heck, that's basically precisely what I want to know.

Post by Xah Lee
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.

I've been using UNIX man pages for quite some time, and I don't think
that I have ever come across an error. I am sure that there are errors,
but I am also sure that Mathematica's documentation has its share of
errors as well.

Post by Xah Lee
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.

It seems to me that the problem is not UNIX software in general, but
rather that the zip function does not have an analogue of tar's -C
option (which sets the current directory for the command).

Post by Xah Lee
------------------------------
Python
7.1. The if statement
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 example is taken from the Python Language Reference, which is
really only useful if you are looking to re-implement Python (or create
something that parses Python, I suppose). The particular flavor of BNF
is explained in the Introduction.

I am not sure what you expect from a Language Reference, but in the case
of Python the Language Reference seems to have worked quite well. Very
few languages have as many successful implementations as Python. The
Language Reference is clearly a large part of that.

Post by Xah Lee
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.

If you want to *use* the language the Tutorial is probably what you
want.

Perhaps the most well-known statement type is the if statement. Here's
what the Tutorial has to say about the if statement.

--8<---------------cut here---------------start------------->8---

Post by Xah Lee

x = int(raw_input("Please enter an integer: "))

Please enter an integer: 42
... x = 0
... print 'Negative changed to zero'
... elif x == 0:
... print 'Zero'
... elif x == 1:
... print 'Single'
... else:
... print 'More'
...
More

There can be zero or more elif parts, and the else part is optional. The
keyword ‘elif‘ is short for ‘else if’, and is useful to avoid excessive
indentation. An if ... elif ... elif ... sequence is a substitute for the
switch or case statements found in other languages.
--8<---------------cut here---------------end--------------->8---

Once again, that looks pretty good to me.

Post by Xah Lee
------------------------------
Perl
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.

You might not like Larry Wall's documentation style, but if that is the
case then you are in the minority. IMHO Perl is an example of a
language that prospered almost entirely on the strength of its
documentation. The Camel book is one of the best selling computer
language books of all time.

Much of Perl's "culture" is just plain old marketing, but it is hard to
argue that it has not been successful.

Post by Xah Lee
------------------------------
Haskell
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
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.”
(Source www.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.

I actually agree with you on this example.

Post by Xah Lee
uhmm, happy 2011.

You too.

Jason

Google Poster

2011-01-04 20:29:20 UTC

Permalink

Post by Xah Lee
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
SYNOPSIS
gzip [ -acdfhlLnNrtvV19 ] [-S suffix] [ name ... ]
gunzip [ -acfhlLnNrtvV ] [-S suffix] [ name ... ]
zcat [ -fhLV ] [ name ... ]
SYNOPSIS
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
7.1. The if statement
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
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
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
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