opinion: comp lang docs style

Discussion in 'Python' started by Xah Lee, Jan 4, 2011.

  1. Xah Lee

    Xah Lee Guest

    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/ ☄
    Xah Lee, Jan 4, 2011
    #1
    1. Advertising

  2. Xah Lee

    Jason Earl Guest

    On Tue, Jan 04 2011, Xah Lee 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.


    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.

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

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

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

    > 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---
    Perhaps the most well-known statement type is the if statement. For example:

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

    Please enter an integer: 42
    >>> if x < 0:

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

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


    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.

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


    I actually agree with you on this example.

    > uhmm, happy 2011.


    You too.

    Jason
    Jason Earl, Jan 4, 2011
    #2
    1. Advertising

  3. On Jan 4, 12:24 pm, Xah Lee <> 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
    Google Poster, Jan 4, 2011
    #3
  4. Xah Lee

    Terry Reedy Guest

    On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote:

    what he called
    > a opinion piece.


    I normally do not respond to trolls, but while expressing his opinions,
    AI made statements that are factually wrong at least as regards Python
    and its practitioners.


    1. He correctly notes that the Python Language Reference includes
    snippets of BNF grammar with the intention of making the doc clear and
    precise.

    > The if statement is used for conditional execution:


    > if_stmt ::= "if" expression ":" suite
    > ( "elif" expression ":" suite )*
    > ["else" ":" suite]


    He incorrectly claims that the inclusion fails in its purpose. This is
    based on the irrelevant fact that 'BNF' has many versions (Python only
    uses one, explained in 1.2. Notation) and the false claim that "BNF is
    actually not used as a computer language for syntax description.".

    Actually, the above snippet is a quotation (with initial ':' expanded to
    '::=' and newlines added) from the file Grammar/Grammar:
    "if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]"

    The CPython program Parser/pgen takes Grammar/Grammar as input and
    produces the parser tables that CPython uses to parse Python code. In
    other words, CPython uses its well-defined version of extended BNF as a
    'computer language for syntax description', contrary to AI's claim. I
    presume other implementations make either human or machine use of the
    same file.

    2. AI also claims that this notation is 'incomprehensible'.
    Perhaps to him, but not to me or most the the subset of users who care
    about it. One way to expand the BNF into English is as follows:

    An if-statement starts with an if-clause consisting of the word 'if', an
    expression, a colon, and a suite. 'expression' and a 'suite' have
    already been defined elsewhere. The if clause can optionally be followed
    any count (including 0) of elif-clauses which are the same as if-clauses
    but with 'elif' substituted for 'if'. An if-statement can optionally be
    terminated with an else-clause consisting of 'else' and a suite.

    Even if such long-winded paraphrases were added to the doc (and I do not
    think they should be), in addition to the explanations currently given,
    the grammar snippet would still be needed to show the exact technical
    definition that CPython actually uses, for those who wan precisely that.
    (The people who care include those who want to change the grammar or
    those who think the behavior might might match the grammar.)


    3. AI's complaint is deceptive and deficient in omitting any mention the
    part of the docs *intended* to teach beginners: the Tutorial. The main
    doc pages list the Tutorial first, as what one should start with. That
    is where I started and I cannot remember if I have ever read the formal
    if-statement grammar before, as I knew how to write such before I ever
    looked at the Language Reference. Guido and other developers do not and
    never have expected people to learn about if-statements from the
    grammar. The tutorial says:
    "
    4.1. if Statements
    Perhaps the most well-known statement type is the if statement. For example:

    >>> x = int(input("Please enter an integer: "))

    Please enter an integer: 42
    >>> if x < 0:

    ... x = 0
    ... print('Negative changed to zero')
    ... elif x == 0:
    ... print('Zero')
    ... elif x == 1:
    ... print('Single')
    ... else:
    ... print('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.
    "

    I think this says by example and plain English just what a Python
    programmer needs to know. It is, of course, followed by many other
    examples in the remainder of the tutorial.

    If one wants to critique the 'Python Docs', especially as regards to
    usefulness to beginners, one must start with the Tutorial; and if one
    wants to use if statements as an example, one must start with the above.

    --
    Terry Jan Reedy
    Terry Reedy, Jan 4, 2011
    #4
  5. Xah Lee

    Guest

    On 01/04/2011 01:34 PM, Terry Reedy wrote:
    > On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote:
    >
    > what he called
    >> a opinion piece.

    >
    > I normally do not respond to trolls, but while expressing his opinions,
    > AI made statements that are factually wrong at least as regards Python
    > and its practitioners.


    Given that most trolls include factually false statements,
    the above is inconsistent. And speaking of arrogant, it
    is just that to go around screaming "troll" about a posting
    relevant to the newsgroup it was posted in because you don't
    happen to agree with its content. In doing so you lower
    your own credibility. (Which is also not helped by your
    "Arrogant Ignoramus" name-calling.)

    > [...]
    > 2. AI also claims that this notation is 'incomprehensible'.


    Since incomprehensibility is clearly subjective your claim
    that it is a factual error is every bit as hyperbolic as his.

    > [...]
    > 3. AI's complaint is deceptive and deficient in omitting any mention the
    > part of the docs *intended* to teach beginners: the Tutorial. The main
    > doc pages list the Tutorial first, as what one should start with. That
    > [...]
    > If one wants to critique the 'Python Docs', especially as regards to
    > usefulness to beginners, one must start with the Tutorial; and if one
    > wants to use if statements as an example, one must start with the above.


    No. The language reference (LR) and standard library reference
    (SLR) must stand on their own merits. It is nice to have a good
    tutorial for those who like that style of learning. But it should
    be possible for a programmer with a basic understanding of computers
    and some other programming languages to understand how to program
    in python without referring to tutorials, explanatory websites,
    commercially published books, the source code, etc.

    The difficulty of doing that is a measure of the failure of the
    python docs to achive a level quality commensurate with the language
    itself.

    FWIW, I think the BNF in the LR is perfectly reasonable given the
    target audience I gave above. The failure of the LR has more to
    do with missing or excessively terse material -- it concentrates
    too exclusively on syntax and insufficiently on semantics. Much
    of the relevant semantics information is currently mislocated in
    the SLR.
    , Jan 4, 2011
    #5
  6. On Tue, 04 Jan 2011 15:17:37 -0800, wrote:

    >> If one wants to critique the 'Python Docs', especially as regards to
    >> usefulness to beginners, one must start with the Tutorial; and if one
    >> wants to use if statements as an example, one must start with the
    >> above.

    >
    > No. The language reference (LR) and standard library reference (SLR)
    > must stand on their own merits. It is nice to have a good tutorial for
    > those who like that style of learning. But it should be possible for a
    > programmer with a basic understanding of computers and some other
    > programming languages to understand how to program in python without
    > referring to tutorials, explanatory websites, commercially published
    > books, the source code, etc.


    No it shouldn't. That's what the tutorial is for. The language reference
    and standard library reference are there to be reference manuals, not to
    teach beginners Python.

    In any case, your assumption that any one documentation work should stand
    on its own merits is nonsense -- *nothing* stands alone. Everything
    builds on something else. Technical documentation is no different: it
    *must* assume some level of knowledge of its readers -- should it be
    aimed at Python experts, or average Python coders, or beginners, or
    beginners to programming, or at the very least is it allowed to assume
    that the reader already knows how to read?

    You can't satisfy all of these groups with one document, because their
    needs are different and in conflict. This is why you have different
    documentation -- tutorials and reference manuals and literate source code
    and help text are all aimed at different audiences. Expecting one
    document to be useful for all readers' needs is like expecting one data
    type to be useful for all programming tasks.

    Reasonable people might disagree on what a particular documentation work
    should target, and the best way to target it, but not on the need for
    different documentation for different targets.


    --
    Steven
    Steven D'Aprano, Jan 5, 2011
    #6
  7. On 2011-01-04 22:29:31 -0800, Steven D'Aprano said:

    > In any case, your assumption that any one documentation work should stand
    > on its own merits is nonsense -- *nothing* stands alone.


    +1

    How many RFCs still in use today don't start with:

    > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
    > document are to be interpreted as described in RFC 2119


    I posted a response on the article itself, rather than pollute a
    mailing list with replies to a troll. The name calling was a rather
    large hint as to the intention of the "opinion", either that or whoever
    translated the article (man or machine) was really angry at the time.
    ;)

    - Alice.
    Alice Bevan–McGregor, Jan 5, 2011
    #7
  8. Xah Lee

    Guest

    On 01/04/2011 11:29 PM, Steven D'Aprano wrote:
    > On Tue, 04 Jan 2011 15:17:37 -0800, wrote:
    >
    >>> If one wants to critique the 'Python Docs', especially as regards to
    >>> usefulness to beginners, one must start with the Tutorial; and if one
    >>> wants to use if statements as an example, one must start with the
    >>> above.

    >>
    >> No. The language reference (LR) and standard library reference (SLR)
    >> must stand on their own merits. It is nice to have a good tutorial for
    >> those who like that style of learning. But it should be possible for a
    >> programmer with a basic understanding of computers and some other
    >> programming languages to understand how to program in python without
    >> referring to tutorials, explanatory websites, commercially published
    >> books, the source code, etc.

    >
    > No it shouldn't. That's what the tutorial is for. The language reference
    > and standard library reference are there to be reference manuals, not to
    > teach beginners Python.


    Yes it should. That's not what the tutorial is for. The
    (any) tutorial is for people new to python, often new to
    programming, who have the time and a learning style suitable
    for sitting down and going through a slow step-by-step
    exposition, much as one would get in a classroom. That is
    a perfectly valid way for someone in that target audience
    to learn python.

    Your (and Terry's) mistake is to presume that it is
    appropriate for everyone, perhaps because it worked for you
    personally. There is a large class of potential python
    users for whom a tutorial is highly suboptimal -- people
    who have some significant programming experience, who don't
    have the time or patience required to go through it getting
    information serially bit by bit, or whos learning style is,
    "don't spoon feed me, just tell me concisely what python
    does", who fill in gaps on a need-to-know basis rather than
    linearly. I (and many others) don't need or want an
    explanation of how to use lists as a stack!

    A language reference manual should completely and accurately
    describe the language it documents. (That seems fairly obvious
    to me although there will be differing opinions of how precise
    one needs to be, etc.) Once it meets that minimum standard,
    it's quality is defined by how effectively it transfers that
    information to its target audience. A good reference manual
    meets the learning needs of the target audience above admirably.

    I learned Perl (reputedly more difficult to learn than Python)
    from the Perl manpages and used it for many many years before
    I ever bought a Perl book. I learned C mostly from Harbison
    and Steele's "C: A Reference". Despite several attempts at
    python using its reference docs, I never got a handle on
    it until I forked out money for Beazley's book. There is
    obviously nothing inherently "difficult" about python -- it's
    just that python's reference docs are written for people who
    already know python. Since limiting their scope that narrowly
    is not necessary, as other languages show, it is fair to say
    that python's reference docs are poorer.

    > In any case, your assumption that any one documentation work should stand
    > on its own merits is nonsense -- *nothing* stands alone. Everything
    > builds on something else. Technical documentation is no different: it
    > *must* assume some level of knowledge of its readers -- should it be
    > aimed at Python experts, or average Python coders, or beginners, or
    > beginners to programming, or at the very least is it allowed to assume
    > that the reader already knows how to read?
    >
    > You can't satisfy all of these groups with one document, because their
    > needs are different and in conflict. This is why you have different
    > documentation -- tutorials and reference manuals and literate source code
    > and help text are all aimed at different audiences. Expecting one
    > document to be useful for all readers' needs is like expecting one data
    > type to be useful for all programming tasks.


    I defined (roughly) the target audience I was talking about
    when I wrote "for a programmer with a basic understanding of
    computers and some other programming languages".

    Let's dispense with the 6th-grade arguments about people who
    don't know how to read, etc.

    > Reasonable people might disagree on what a particular documentation work
    > should target, and the best way to target it, but not on the need for
    > different documentation for different targets.


    As I hope I clarified above, that was exactly my point too.
    There is a significant, unsatisfied gap between the audience
    that a tutorial aims at, and the audience that the reference
    docs as currently written seem to be aimed at. Since other
    language manuals incorporate this gap audience more or less
    sucessfully in their reference manuals, python's failure to
    do so is justification for calling them poor.
    (Of course they are poor in lots of other ways too but my
    original response was prompted by the erroneous claim that
    good (in my sense above) reference manuals were unnecessary
    because a tutorial exists.)
    , Jan 5, 2011
    #8
  9. Xah Lee

    Guest

    On 01/05/2011 12:23 AM, Alice Bevan–McGregor wrote:
    > > On 2011-01-04 22:29:31 -0800, Steven D'Aprano said:
    > >
    >> >> In any case, your assumption that any one documentation work should stand
    >> >> on its own merits is nonsense -- *nothing* stands alone.

    > >
    > > +1


    I responded more fully in my response to Steven but you like
    he is taking "stand on it's own merits" out of context. The
    context I gave was someone who wants a complete and accurate
    description of python and who understands programming with
    other languages but not python.

    > > How many RFCs still in use today don't start with:
    > >
    >> >> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    >> >> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
    >> >> document are to be interpreted as described in RFC 2119


    RFC 2119 is incorporated in the others by reference. It is purely
    a matter of technical convenience that those definitions, which are
    common to hundreds of RFCs, are factored out to a single common
    location. RFC 2119 is not a tutorial.

    > > I posted a response on the article itself, rather than pollute a
    > > mailing list with replies to a troll. The name calling was a rather
    > > large hint as to the intention of the "opinion", either that or whoever
    > > translated the article (man or machine) was really angry at the time.
    > > ;)


    I can hint to my neighbor that his stereo is too loud by
    throwing a brick through his window. Neither that nor calling
    people arrogant ignoramus is acceptable in polite society.
    I am not naive, nor not shocked that c.l.p is not always polite,
    and normally would not have even commented on it except that
    1) Terry Reedy is usually more polite and thoughtful,
    and 2) Xah Lee's post was not a troll -- it was a legitimate
    comment on free software documentation (including specifically
    python's) and while I don't agree with some of his particulars,
    the Python docs would be improved if some of his comments
    were considered rather than dismissed with mindless epithets
    like troll and arrogant ignoramus.
    , Jan 5, 2011
    #9
  10. On 1/5/2011 12:10 PM said...

    <snip>

    > A language reference manual should completely and accurately
    > describe the language it documents. (That seems fairly obvious
    > to me although there will be differing opinions of how precise
    > one needs to be, etc.) Once it meets that minimum standard,
    > it's quality is defined by how effectively it transfers that
    > information to its target audience. A good reference manual
    > meets the learning needs of the target audience above admirably.
    >
    > I learned Perl (reputedly more difficult to learn than Python)
    > from the Perl manpages and used it for many many years before
    > I ever bought a Perl book. I learned C mostly from Harbison
    > and Steele's "C: A Reference". Despite several attempts at
    > python using its reference docs, I never got a handle on
    > it until I forked out money for Beazley's book.


    Hmm... I suspect most of us with prior programming experience simply
    worked the tutorial and immediately put python into play, digging deeper
    as necessary. Further, absolute beginners at programming are not likely
    to learn programming from a man page, nor should anyone expect the
    tutorial to be sufficient for their needs.

    I agree that as far as the specific details around the edges and corner
    cases go, it would be nice to have a single reference that provides
    those answers at the level you need (ala postscript's redbook imo), but
    I find this group serves well to fill the gaps when I can't easily find
    what I need.

    Emile
    Emile van Sebille, Jan 5, 2011
    #10
  11. Xah Lee

    Xah Lee Guest

    On Jan 4, 3:17 pm, "" <> wrote:
    > On 01/04/2011 01:34 PM, Terry Reedy wrote:
    >
    > > On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote:

    >
    > > what he called
    > >> a opinion piece.

    >
    > > I normally do not respond to trolls, but while expressing his opinions,
    > > AI made statements that are factually wrong at least as regards Python
    > > and its practitioners.

    >
    > Given that most trolls include factually false statements,
    > the above is inconsistent.  And speaking of arrogant, it
    > is just that to go around screaming "troll" about a posting
    > relevant to the newsgroup it was posted in because you don't
    > happen to agree with its content.  In doing so you lower
    > your own credibility.  (Which is also not helped by your
    > "Arrogant Ignoramus" name-calling.)


    yeah.

    i called them idiots, he calls me Artificial Intelligence ☺. fair
    game.

    > No.  The language reference (LR) and standard library reference
    > (SLR) must stand on their own merits.  It is nice to have a good
    > tutorial for those who like that style of learning.  But it should
    > be possible for a programmer with a basic understanding of computers
    > and some other programming languages to understand how to program
    > in python without referring to tutorials, explanatory websites,
    > commercially published books, the source code, etc.


    yes exactly.

    the best python reference to me is

    Richard Gruet's quick ref:
    http://rgruet.free.fr/PQR26/PQR2.6.html

    on the python doc, afaik people complains all the time, and i know at
    least 3 times in different years people have tried to bring up
    projects to fix it, all shot down with spit badly by python priests,
    of course.

    just 2 days ago, i was pissed due to python doc url disappearance too
    http://xahlee.org/perl-python/python_doc_url_disappearance.html

    Xah
    Xah Lee, Jan 6, 2011
    #11
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.

Share This Page