[perl-python] Python documentation moronicities (continued)

Discussion in 'Perl Misc' started by Xah Lee, Apr 12, 2005.

  1. Xah Lee

    Xah Lee Guest

    http://python.org/doc/2.4.1/lib/module-re.html
    http://python.org/doc/2.4.1/lib/node114.html

    ---------
    QUOTE
    The module defines several functions, constants, and an exception. Some
    of the functions are simplified versions of the full featured methods
    for compiled regular expressions. Most non-trivial applications always
    use the compiled form
    UNQUOTE


    What does a programer who wants to use regex gets out from this piece
    of motherfucking irrevalent drivel?

    ----------
    QUOTE
    compile(
    pattern[, flags])

    Compile a regular expression pattern into a regular expression object,
    which can be used for matching using its match() and search() methods,
    described below.

    The expression's behaviour can be modified by specifying a flags
    value. Values can be any of the following variables, combined using
    bitwise OR (the | operator).
    UNQUOTE


    What exactly is it fucking saying?

    I wanted to use regex to find & replace on text. I've read in a file.
    Trying to reading this fucking doc is a pain in the ass. What are these
    "flags"? Do i do

    re.compile(r'mypat','M') or
    re.compile(r'mypat',M)
    or perhaps
    re.compile(r'mypat',re.M)

    The M isn't a fucking variable. Why does the doc incompetently use that
    term?
    And what the **** is it unclearly meant by "OR" operator with the
    mother fucking bitwise jargon?

    All a person reading regex really wanted is to see how to use a string
    pattern and replace it with another. The fucking doc cannot be possibly
    fucking worsely written.

    **** the mother fucking coders in the IT industry.

    So, is
    re.compile(r'mypat','M')
    re.compile(r'mypat','MULTILINE')
    equivalent?

    and, by that fucking bitwise shit is it meant to say like
    re.compile(r'mypat','M'|'U')
    ?

    why cannot this piece of shit writing give a single example of usage?
    and motherfucking confusedly organized, with fucking variable terms the
    writer don't fucking understand, and meanwhile always trying to sound
    big asshole and don't stop at masturbation by mention a regex book and
    not hesitate to mention another language Perl. Fucking morons.

    for a exposition of IT's fucking stupid docs and their fuckhead coders,
    see:
    http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html

    a cleaned up account of this post will be appended to the above
    exposition.

    --------

    One final piece of advice here to sober up the fuckheads who are
    currently offended and defiant: you want to ask yourself this question:
    Can a seasoned programer, who is expert at least 2 languages, who is
    also a expert at Perl and knew regex well, and who has also read the
    official Python tutorial and has written at least 10 simple python
    programs over a span of a month, can such a person, who have not yet
    used regex in Python but now wants to use regex in Python and have just
    read the doc, must he, resort to many trial and error to see exactly
    what the doc is talking about?

    But, can this doc be (re-)written effectively and easily so that any
    programers needn't do trial'n'error post-reading?

    The answer to the questions are resounding yeses, you fucking asses.

    paypal me a hundred dollars and i'll rewrite the whole re doc in a few
    hours.

    **** you the standard IT morons. Excuse me for i didn't have time to
    write a more coherent and detailed analysis of the stupidities of the
    re doc.

    Xah

    ∑ http://xahlee.org/PageTwo_dir/more.html ☄
    Xah Lee, Apr 12, 2005
    #1
    1. Advertising

  2. I've had enough.

    *PLONK*
    --
    Michael Hoffman
    Michael Hoffman, Apr 12, 2005
    #2
    1. Advertising

  3. Xah Lee

    Joe Smith Guest

    Xah Lee wrote:

    > of motherf***ing irrevalent drivel?


    I am greatly amused.
    A troll impersonating Xah Lee has made xah look like a total moron.
    LOL
    Joe Smith, Apr 12, 2005
    #3
  4. Xah Lee

    rbt Guest

    Xah Lee wrote:

    > What does a programer who wants to use regex gets out from this piece
    > of motherf**king irrevalent drivel?


    Any resume that ever crosses my desk that includes 'Xah Lee' anywhere in
    the name will be automatically trashed.
    rbt, Apr 12, 2005
    #4
  5. On Tue, 12 Apr 2005 04:02:20 -0700, Joe Smith wrote:

    > Xah Lee wrote:
    >
    >> of motherf***ing irrevalent drivel?

    >
    > I am greatly amused.
    > A troll impersonating Xah Lee has made xah look like a total moron. LOL


    "The fucking doc cannot be possibly fucking worsely written."

    This is very Xahish though, even if it's not him.

    It's right up there with "AND, the writting as usuall is fantastic
    incompetent."
    Richard Gration, Apr 12, 2005
    #5
  6. Xah Lee

    Peter Hansen Guest

    Joe Smith wrote:
    > Xah Lee wrote:
    >> of motherf***ing irrevalent drivel?

    >
    > I am greatly amused.
    > A troll impersonating Xah Lee has made xah look like a total moron.
    > LOL


    Sorry, Joe, but why do you think this wasn't Xah?
    Every detail of the post is consistent with his
    recent postings.

    And a secondary, but purely rhetorical, question:
    how could the post have made him look like a moron
    when he already looked like one?
    Peter Hansen, Apr 12, 2005
    #6
  7. Xah Lee

    Guest

    In comp.lang.perl.misc Xah Lee <> wrote:
    > The answer to the questions are resounding yeses, you fucking asses.


    > paypal me a hundred dollars and i'll rewrite the whole re doc in a few
    > hours.


    > **** you the standard IT morons. Excuse me for i didn't have time to
    > write a more coherent and detailed analysis of the stupidities of the
    > re doc.


    Don't worry! Very soon, some nice men in white coats will show you
    a comfortable room with soft walls in which you can write such
    documentation to your hearts content.

    Axel
    , Apr 13, 2005
    #7
  8. Xah Lee wrote:
    > http://python.org/doc/2.4.1/lib/module-re.html
    > http://python.org/doc/2.4.1/lib/node114.html
    >
    > ---------
    > QUOTE
    > The module defines several functions, constants, and an exception. Some
    > of the functions are simplified versions of the full featured methods
    > for compiled regular expressions. Most non-trivial applications always
    > use the compiled form
    > UNQUOTE
    >
    >
    > What does a programer who wants to use regex gets out from this piece
    > of motherfucking irrevalent drivel?


    Until now, I have regarded you as a mildly amusing moron.

    But now I find you're simply illiterate.

    Buh-bye.

    --
    John W. Kennedy
    A proud member of the reality-based community.
    John W. Kennedy, Apr 14, 2005
    #8
  9. Xah Lee

    Xah Lee Guest

    Re: New Python regex Doc (was: Python documentation moronicities)

    I have now also started to rewrite the re-syntax page. At first i
    thought that page needs not to be rewritten, since its about regex and
    not really involved with Python. But after another look, that page is
    as incompetent as every other page of Python documentation.

    The rewritten page is here:
    http://xahlee.org/perl-python/python_re-write/lib/re-syntax.html

    It's not complete, but is a start. The organization is largely taken
    care of, except the last few paragraphs. The bottom half on capturing
    and extension syntax i haven't started working on. In particular, they
    need examples. The “repetitions†section also needs to be examed.

    here are few notes on this whole rewriting ordeal.

    -------------------

    In the doc, examples are often given in Python command line interface
    format, e.g.

    >>> def f(n):

    .... return n+1
    ....
    >>> f(1)

    2

    instead of:

    def f(n):
    return n+1
    print f(1) # returns 2

    the clean format should be used because it does not require familiarity
    with Python command line, it is more readable, and the code can be
    copied and run readily.

    A significant portion of Python doc's readers, if not majority, didn't
    come to Python as beginning programers, and or one way or another never
    used or cared about the Python command line interface.

    Suppose a non-Python programer is casually shown a page of Python doc.
    She will get much more from the clean example than the version
    cluttered with Python Command line interface irrelevancies.

    Suppose now we have a experienced professional Python programer. Upon
    reading the Python doc, she will also find examples in plain code much
    more readable and familiar, than the version plastered with Python
    Command line interface irrelevancies.

    The only place where the Python command line look-and-feel is
    appropriate is in the Python tutorial, and arguably only in the
    beginning sections.

    -----
    Extra point: If the Python command line interface is actually a robust
    application, like so-called IDE e.g. Mathematica front-end, then things
    are very different. In reality, the Python command line interface is a
    fucking toy whose max use is as a simplest calculator and double as a
    chanting novelty for standard coding morons. In practice it isn't even
    suitable as a trial'n'error pad for real-world programing.

    Extra point: do not use the fucking stupid meaningless jargon
    “interpreterâ€. 90% of its use in the doc should be deleted.They
    should be replaced with "software", "program", "command line
    interface", or "language" or others.

    (I dare say that 50% of all uses of the word interpreter in computer
    language contexts are inane. Fathering large amounts of
    misunderstanding and confusion.)

    -----
    history of Python are littered all over the doc. e.g.
    “Incompatibility note: in the original Python 1.5 release, maxsplit
    was ignored. This has been fixed in later releases.â€

    99% of programers really don't need to give a flying **** about the
    history of a language. Inevitably software including languages change
    over time, however conservative one tries to be. So, move all these
    changes into a "New and Incompatible changes" page at some appendix of
    the lang spec. This way, people who are maintaining older code, can
    find their info and in one coherent place. While, the general
    programers are not forced to wade thru the details of fuckups or
    whatnot of the past in every few paragraphs. (few exceptions can be
    made, when the change is a major fuckup that all practicing Python
    coders really must be informed regardless whether they maintain old
    code.)

    ------

    do not take a attitude like you have to stick to some artificial format
    or order or "correctness" in the doc. Remember, the doc's prime goal is
    to communicate to programers how a language functions, not how it is
    implemented or how technically or computer scientifically speaking.

    In writing a language documentation, there is a question of how to
    organize it. This is a issue of design, and it takes thinking.

    When a doc writer is faced with such a challenge, the easiest route is
    a no-brainer by following the way the language is implemented. For
    example, the doc will start with “data types†supported by the
    language. This no-brainer stupidity is unfortunately how most language
    docs are organized by, and the Python doc is one of the worst.

    One can see this phenomenon in the official doc of Python's RE module.
    For example, it begin with Regex Syntax, then it follows with “Module
    contentsâ€, then Regex Objects, then Match Objects. And in each page,
    the functions or methods are arranged in a alphabetical order. This is
    typical of the no-brainers organization following how the module is
    implemented or certain “computer scientific logicâ€. It has remote
    connection to how the module is used to perform a task.

    In general, language docs should be organize by the tasks it is
    supposed to accomplish, then by each module or function's
    functionalities.

    For example, the RE module doc, organize it by the purposes of the
    module. To begin, we explain in the outset that this module is for the
    purpose of search or replacing a string by a pattern. Then, we organize
    with purpose and functionalities as guide.

    Since Python provides a set of functions and a Object-Oriented set, we
    create a page for each set, with a clear indication on how they relates
    to the string pattern search/replace task. Since Python returns the
    result as a special Object, we again create a section MatchObject and
    clearly tells the reader what that page is about in relation to the
    task. And, we also put the regex syntax on its own page, but again made
    it clear what this page means in relation to the task. And in each
    page, we again organize them by the guide of tasks and functionalities.
    (for example, not alphabetical or some machinery logic) In this way,
    the whole RE module doc is oriented to programing, not how this module
    happens to be classified according to some Python idiosyncrasies or
    categorization by some forced “computer science†outlook.

    The complete rewritten doc is here:
    http://xahlee.org/perl-python/python_re-write/lib/module-re.html

    -----

    There were more issues and notes... but this will be it for today.

    Xah

    ∑ http://xahlee.org/
    Xah Lee, May 5, 2005
    #9
  10. Xah Lee

    alex23 Guest

    Re: New Python regex Doc (was: Python documentation moronicities)

    Xah Lee wrote:
    > 99% of programers really don't need to give a flying **** about the
    > history of a language.


    Ironically, I'm pretty confident that the same percentage of readers on
    this group feel _exactly the same way_ about your 'improvements'.

    -alex23
    alex23, May 6, 2005
    #10
  11. Xah Lee

    Xah Lee Guest

    Re: New Python regex Doc (was: Python documentation moronicities)

    HTML Problems in Python Doc

    I don't know what kind of system is used to generate the Python docs,
    but it is quite unpleasant to work with manually, as there are
    egregious errors and inconsistencies.

    For example, on the “Module Contents†page (
    http://python.org/doc/2.4.1/lib/node111.html ), the closing tags for
    <dd> are never used, and all the tags are in lower case. However, on
    the regex syntax page ( http://python.org/doc/2.4.1/lib/re-syntax.html
    ), the closing tages for <dd> are given, and all tages are in caps.

    The doc's first lines declare a type of:
    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

    yet in the files they uses "/>" to close image tags, which is a XHTML
    syntax.

    the doc litters <p> and never closes them, making it a illegal
    XML/XHTML by breaking the minimal requirement of well-formedness.

    Asides from correctness, the code is quite bloated as in generally true
    of generated HTML. For example, it is littered with: <tt id='l2h-853'
    xml:id='l2h-853'> which isn't used in the style sheet, and i don't
    think those ids can serve any purpose other than in style sheet.

    Although the doc uses a huge style sheet and almost every tag comes
    with a class or id attribute, but it also profusively uses hard-coded
    style tags like <b>, <big> and Netcsape's <nobr>.

    It also abuse tables that effectively does nothing. Here's a typical
    line:
    <table cellpadding="0" cellspacing="0"><tr valign="baseline">
    <td><nobr><b><tt id='l2h-851' xml:id='l2h-851'
    class="function">compile</tt></b>(</nobr></td>
    <td><var>pattern</var><big>[</big><var>,
    flags</var><big>]</big><var></var>)</td></tr></table>


    If Python is supposed to be a quality language, then its
    documentation's content and code seems indicate otherwise.
    -----------------------

    This email is archived at:
    http://xahlee.org/perl-python/re-write_notes.html

    Xah

    ∑ http://xahlee.org/


    ☄
    Xah Lee, May 7, 2005
    #11
  12. Xah Lee

    Xah Lee Guest

    Xah Lee, May 7, 2005
    #12
  13. Xah Lee

    Henry Law Guest

    Re: New Python regex Doc (was: Python documentation moronicities)

    On 5 May 2005 14:28:43 -0700, "Xah Lee" <> wrote:

    >... Python.


    I fail to understand why this has been cross-posted to a Perl group.
    --

    Henry Law <>< Manchester, England
    Henry Law, May 7, 2005
    #13
  14. Re: New Python regex Doc (was: Python documentation moronicities)

    Henry Law <> wrote:
    > On 5 May 2005 14:28:43 -0700, "Xah Lee" <> wrote:
    >
    >>... Python.

    >
    > I fail to understand why this has been cross-posted to a Perl group.



    To stir things up.

    That is what trolls do.


    --
    Tad McClellan SGML consulting
    Perl programming
    Fort Worth, Texas
    Tad McClellan, May 7, 2005
    #14
  15. Re: New Python regex Doc (was: Python documentation moronicities)

    Xah> I don't know what kind of system is used to generate the Python
    Xah> docs, but it is quite unpleasant to work with manually, as there
    Xah> are egregious errors and inconsistencies.

    The main Python documentation is written in LaTeX. I believe most, if not
    all, HTML is generated by latex2html. I suspect most of the HTML cruftiness
    arises from latex2html.

    Skip
    Skip Montanaro, May 7, 2005
    #15
  16. Philippe C. Martin, May 7, 2005
    #16
  17. Xah Lee

    Xah Lee Guest

    Re: New Python regex Doc (was: Python documentation moronicities)

    Let me expose one another fucking incompetent part of Python doc, in
    illustration of the Info Tech industry's masturbation and ignorant
    nature.

    The official Python doc on regex syntax (
    http://python.org/doc/2.4/lib/re-syntax.html ) says:

    --begin quote--

    "|"
    A|B, where A and B can be arbitrary REs, creates a regular expression
    that will match either A or B. An arbitrary number of REs can be
    separated by the "|" in this way. This can be used inside groups (see
    below) as well. As the target string is scanned, REs separated by "|"
    are tried from left to right. When one pattern completely matches, that
    branch is accepted. This means that once A matches, B will not be
    tested further, even if it would produce a longer overall match. In
    other words, the "|" operator is never greedy. To match a literal "|",
    use \|, or enclose it inside a character class, as in [|].

    --end quote--

    Note: “In other words, the "|" operator is never greedy.â€

    Note the need to inject the high-brow jargon “greedy†here as a
    latch on sentence.

    “never greedy� What is greedy anyway?

    “Greedyâ€, when used in the context of computing, describes a
    certain characteristics of algorithms. When a algorithm for a
    minimizing/maximizing problem is such that, whenever it faced a choice
    it simply chose the shortest path, without considering whether that
    choice actually results in a optimal solution.

    The rub is that such stratedgy will often not obtain optimal result in
    most problems. If you go from New York to San Francisco and always
    choose the road most directly facing your destination, you'll never get
    on.

    For a algorithm to be greedy, it is implied that it faces choices. In
    the case of alternatives in regex "regex1|regex2|regex3", there is
    really no selection involved, but following a given sequence.

    What the writer were thinking when he latched on about greediness, is
    that the result may not be from the pattern that matches the most
    substring, therefore it is not “greedyâ€. It's not greedy Python
    docer's ass.

    Such blind jargon throwing, as found everywhere in tech docs, is a
    significant reason why the computing industry is filled with shams the
    likes of unix, Perl, Programing Patterns, eXtreme Programing,
    “Universal Modeling Languageâ€, fucking shits.

    ----
    A better writen doc for the complete regex module is at:
    http://xahlee.org/perl-python/python_re-write/lib/module-re.html

    See also: Responsible Software Licensing
    http://xahlee.org/UnixResource_dir/writ/responsible_license.html

    Xah

    ∑ http://xahlee.org/
    Xah Lee, May 8, 2005
    #17
  18. Xah Lee

    John Bokma Guest

    John Bokma, May 8, 2005
    #18
  19. Xah Lee

    Mike Meyer Guest

    Re: New Python regex Doc

    "Xah Lee" <> writes:

    > Let me expose one another fucking incompetent part of Python doc, in
    > illustration of the Info Tech industry's masturbation and ignorant
    > nature.


    What you actually expose is your own ignorance.

    > Note: “In other words, the "|" operator is never greedy.â€
    >
    > Note the need to inject the high-brow jargon “greedy†here as a
    > latch on sentence.


    Actually, greedy is a standard term when dealing with regular
    expression matching. Anyone who's done even a little work with regular
    expressions - which is pretty much all I've done, as I prefer to avoid
    them - will know what it means.

    > “never greedy� What is greedy anyway?
    >
    > “Greedyâ€, when used in the context of computing, describes a
    > certain characteristics of algorithms. When a algorithm for a
    > minimizing/maximizing problem is such that, whenever it faced a choice
    > it simply chose the shortest path, without considering whether that
    > choice actually results in a optimal solution.


    Except that's not the *only* meaning for greedy in a computing
    context. That's what it means when you're talking about a specific
    kind of problem solving algorithm. Those algorithms have *nothing* to
    do with regular expressions, so this definition is irrelevant.

    After doing a google for "regular expression greedy", the second match
    starts with the text:

    By default, pattern matching is greedy, which means that the matcher
    returns the longest match possible.

    Now, it can be argued that the term ought not to be used, except that
    it's a standard term with a well-known meaning, and exactly describes
    the behavior in question.

    You can argue that it ought to be defined. The problem is, you can't
    explain things to a rock. You have to assume some basic level of
    understanding. In particular, documentation on a regular expression
    package should explain *how to use the package*, not what regular
    expressions are, and the terminology associated with them.

    As I've suggested before, what's really needed is a short tutorial on
    regular expressions in general. That page could include a definition
    of terms that are unique to regular expressions, and the re package
    documentation could link the word greedy to that definition.

    <mike
    --
    Mike Meyer <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
    Mike Meyer, May 8, 2005
    #19
  20. Xah Lee

    Guest

    Re: New Python regex Doc

    In comp.lang.perl.misc Xah Lee <> wrote:
    > Let me expose one another fucking incompetent part of Python doc, in
    > illustration of the Info Tech industry's masturbation and ignorant
    > nature.


    > Note the need to inject the high-brow jargon “greedy†here as a
    > latch on sentence.


    > “never greedy� What is greedy anyway?


    > “Greedyâ€, when used in the context of computing, describes a


    When used in terms of Usenet, I think it can be applied in the sense
    of 'a troll who is greedy for attention'.

    Hence the saying 'do not feed the troll'.

    Axel
    , May 8, 2005
    #20
    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.
Similar Threads
  1. Cameron Laird
    Replies:
    1
    Views:
    639
    Josiah Carlson
    Apr 3, 2004
  2. Kenneth McDonald
    Replies:
    2
    Views:
    711
  3. Replies:
    0
    Views:
    267
  4. Martyn Quick
    Replies:
    1
    Views:
    289
    Kevin Walzer
    Jan 27, 2005
  5. Xah Lee
    Replies:
    75
    Views:
    1,189
    John Bokma
    May 13, 2005
Loading...

Share This Page