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 fuck 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 [EMAIL PROTECTED] â http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list