Made J2 proposal more prominent, and removed some perceived bias. Minor cleanup.

pep-0318.txt

@@ -14,11 +14,12 @@ Post-History: 09-Jun-2003, 10-Jun-2003, 27-Feb-2004, 23-Mar-2004, 30-Aug-2004
 WarningWarningWarning
 =====================
 
-The final decision on the syntax for 2.4a3 is not yet made. This 
-will be done before 2.4a3, and this document will be updated to 
-match. Note also that this document does not attempt to cover the
-huge number of potential alternative syntaxes, nor is it an attempt
-to exhaustively list all the positives and negatives of each form.
+The final decision on the syntax for 2.4a3 is not yet made.  This will
+be done before 2.4a3, and this document will be updated to match.
+Note also that this document does not attempt to cover the huge number
+of potential alternative syntaxes, nor is it an attempt to
+exhaustively list all the positives and negatives of each form.
+
 
 Abstract
 ========
@@ -112,6 +113,7 @@ few problems seem to be most problematic.
   discussions that were associated with PEP 308 for another example of
   this.
 
+
 Background
 ==========
 
@@ -489,29 +491,36 @@ Syntax forms
     their design needs to be forward-looking, not constrained by what
     can be implemented in 2.3.
 
-* new keyword (and block)
+* _`new keyword (and block)`
 
-  This idea was the consensus alternate from comp.lang.python. Robert
-  Brewer wrote up a detailed `J2 proposal`_ document outlining the arguments
-  in favor of this. The issues with this form are that it requires a new
-  keyword (and therefore a ``from __future__ import decorators`` statement),
-  it seems like there is no obvious choice for the keyword (``using`` is 
-  the choice of the proposal and implementation), and that the form 
-  produces something that looks like a normal code block, but isn't. Attempts
-  to use statements in this block will cause a syntax error. It's also 
-  going to potentially confuse users who don't expect a block to contain
-  bare expressions.
+  This idea was the consensus alternate from comp.lang.python.  Robert
+  Brewer wrote up a detailed `J2 proposal`_ document outlining the
+  arguments in favor of this.  The issues with this form are:
 
+  - It requires a new keyword, and therefore a ``from __future__
+    import decorators`` statement.
 
-.. _J2 proposal:
-    http://www.aminus.org/rbre/python/pydec.html
+  - The choice of keyword is contentious.  However ``using`` emerged
+    as the consensus choice, and is used in the proposal and
+    implementation.
 
+  - The keyword/block form produces something that looks like a normal
+    code block, but isn't.  Attempts to use statements in this block
+    will cause a syntax error.  It may confuse users who don't expect
+    a block to contain bare expressions.  On the other hand, the ``@``
+    syntax is bound to cause at least as much confusion.
+
+  See `Community Consensus`_ below.
+
+  .. _J2 proposal:
+     http://www.aminus.org/rbre/python/pydec.html
 
 There are plenty of other variants and proposals on `the wiki page`_.
 
 .. _the wiki page:
     http://www.python.org/moin/PythonDecorators
 
+
 Why @?
 ------
 
@@ -528,7 +537,6 @@ For syntax options which use a list-like syntax (no matter where it
 appears) to specify the decorators a few alternatives were proposed:
 ``[|...|]``, ``*[...]*``, and ``<...>``.  
 
-
 .. _Javadoc comments:
     http://java.sun.com/j2se/javadoc/writingdoccomments/
 .. _annotations:
@@ -561,19 +569,47 @@ list-after-def syntax is also still kicking around.
 .. _patch: http://www.python.org/sf/979728
 .. _previous patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar-3.diff
 
-After 2.4a2 was released, in response to community reaction, Guido 
-stated that he'd re-examine a community proposal, if the community 
+After 2.4a2 was released, in response to community reaction, Guido
+stated that he'd re-examine a community proposal, if the community
 could come up with a community consensus, a decent proposal, and an
-implementation.
-
-After an amazing number of posts, collecting a vast number of alternatives
-in the `Python wiki`_, the proposed J2 syntax (the new keyword ``using`` 
-in a block before the def). Robert Brewer wrote a `detailed proposal`_ 
-for this form, and Michael Sparks produced `a patch`_. As at time of 
-writing, we're waiting for Guido's decision. 
+implementation.  After an amazing number of posts, collecting a vast
+number of alternatives in the `Python wiki`_, a community consensus
+emerged (below).  As at time of writing, we're waiting for Guido's
+decision.
 
 .. _Python wiki:
     http://www.python.org/moin/PythonDecorators
+
+
+Community Consensus
+-------------------
+
+The consensus that emerged was for the proposed J2 syntax: the new
+keyword ``using`` prefixing a block of decorators before the ``def``
+statement.  For example::
+
+    using:
+        classmethod
+        synchronized(lock)
+    def func(cls):
+        pass
+
+The main arguments for this syntax fall under the "readability counts"
+doctrine.  In brief, they are:
+
+* A suite is better than multiple @lines.  The ``using`` keyword and
+  block transforms the single-block ``def`` statement into a
+  multiple-block compound construct, akin to try/finally and others.
+
+* A keyword is better than punctuation for a new token.  A keyword
+  matches the existing use of tokens.  No new token category is
+  necessary.  A keyword distinguishes Python decorators from Java
+  annotations and .Net attributes, which are significantly different
+  beasts.
+
+Robert Brewer wrote a `detailed proposal`_ for this form, and Michael
+Sparks produced `a patch`_.
+
 .. _detailed proposal:
     http://www.aminus.org/rbre/python/pydec.html
 .. _a patch: