updated

pep-0258.txt

@@ -186,7 +186,7 @@ attached to every new document tree.  The Publisher_ calls
 ``Transformer.apply_transforms()`` to apply all stored transforms to
 the document tree.  Transforms change the document tree from one form
 to another, add to the tree, or prune it.  Transforms resolve
-references and footnote numbers, processing interpreted text, and do
+references and footnote numbers, process interpreted text, and do
 other context-sensitive processing.
 
 Some transforms are specific to components (Readers, Parser, Writers,
@@ -366,13 +366,6 @@ Docutils Package Structure
     element class library plus tree-traversal Visitor pattern base
     classes.  See `Document Tree`_ below.
 
-  - Module "docutils.optik" provides option parsing and command-line
-    help; from Greg Ward's http://optik.sf.net/ project, included for
-    convenience.
-
-  - Module "docutils.roman" contains Roman numeral conversion
-    routines.
-
   - Module "docutils.statemachine" contains a finite state machine
     specialized for regular-expression-based text filters and parsers.
     The reStructuredText parser implementation is based on this
@@ -450,16 +443,26 @@ Docutils Package Structure
   - Package "docutils.languages": Language modules contain
     language-dependent strings and mappings.  They are named for their
     language identifier (as defined in `Choice of Docstring Format`_
-    above), converting dashes to underscores.
+    below), converting dashes to underscores.
 
     - Function "get_language(language_code)", returns matching
       language module.  (``docutils/languages/__init__.py``)
 
-    - Modules: en.py (English), de.py (German), fr.py (French), sk.py
-      (Slovak), sv.py (Swedish).
+    - Modules: en.py (English), de.py (German), fr.py (French), it.py
+      (Italian), sk.py (Slovak), sv.py (Swedish).
 
     - Other languages to be added.
 
+* Third-party modules: "extras" directory.  These modules are
+  installed only if they're not already present in the Python
+  installation.
+
+  - ``extras/optparse.py`` and ``extras/textwrap.py`` provide
+    option parsing and command-line help; from Greg Ward's
+    http://optik.sf.net/ project, included for convenience.
+
+  - ``extras/roman.py`` contains Roman numeral conversion routines.
+
 
 Front-End Tools
 ===============
@@ -713,7 +716,12 @@ conditions:
    b) At the top level of a class definition: a class attribute.
 
    c) At the top level of the "``__init__``" method definition of a
-      class: an instance attribute.  (@@@ ``__new__`` methods?)
+      class: an instance attribute.  Instance attributes assigned in
+      other methods are assumed to be implementation details.  (@@@
+      ``__new__`` methods?)
+
+   d) A function attribute assignment at the top level of a module or
+      class definition.
 
    Since each of the above contexts are at the top level (i.e., in the
    outermost suite of a definition), it may be necessary to place
@@ -734,6 +742,11 @@ conditions:
       method's first parameter (the instance parameter) and "attrib"
       is a simple identifier as in 3a.
 
+   c) For context 1d above, the target must be of the form
+      "``name.attrib``", where "``name``" matches an already-defined
+      function or method name and "attrib" is a simple identifier as
+      in 3a.
+
 Blank lines may be used after attribute docstrings to emphasize the
 connection between the assignment and the docstring.
 
@@ -748,9 +761,18 @@ Examples::
         """This is AClass.c's docstring."""
 
         def __init__(self):
+            """Method __init__'s docstring."""
+
             self.i = 'instance attribute'
             """This is self.i's docstring."""
 
+    def f(x):
+        """Function f's docstring."""
+        return x**2
+
+    f.a = 1
+    """Function attribute f.a's docstring."""
+
 
 Additional Docstrings
 '''''''''''''''''''''