minor updates & fixes

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@859 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

10 files changed, 53 insertions, 68 deletions

diff --git a/HISTORY.txt b/HISTORY.txt
index 1c65aba44..46404e757 100644
--- a/HISTORY.txt
+++ b/HISTORY.txt
@@ -25,7 +25,7 @@ and related projects:
     Marc-Andre Lemburg, Julien Letessier, Wolfgang Lipp, Edward Loper,
     Dallas Mahrt, Ken Manheimer, Skip Montanaro, Paul Moore, Michel
     Pelletier, Sam Penrose, Tim Peters, Pearu Peterson, Mark Pilgrim,
-    Tavis Rudd, Ollie Rutherfurd, Kenichi Sato, Ueli Schlaepfer,
+    Tavis Rudd, Oliver Rutherfurd, Kenichi Sato, Ueli Schlaepfer,
     Gunnar Schwant, tav, Bob Tolbert, Laurence Tratt, Guido van
     Rossum, Greg Ward, Barry Warsaw, Edward Welbourne, Ka-Ping Yee,
     Moshe Zadka
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index e70026510..f198f9560 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -296,9 +296,8 @@ Implementation Docs
 
   - Transforms
 
-* Document the ``pending`` elements, how they're generated and when
-  they're triggered ("first reader", "last writer", etc.; priority
-  system due to be reworked, as noted above).
+* Document the ``pending`` elements, how they're generated and what
+  they do.
 
 * Document the transforms (perhaps in docstrings?): how they're used,
   what they do, dependencies & order considerations.
diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt
index 5e30e4334..377ca31ad 100644
--- a/docs/howto/rst-directives.txt
+++ b/docs/howto/rst-directives.txt
@@ -313,8 +313,8 @@ code::
         else:
             messages = []
             title = None
-        pending = nodes.pending(parts.Contents, 'first writer', 
-                                {'title': title}, block_text)
+        pending = nodes.pending(parts.Contents, {'title': title},
+                                block_text)
         pending.details.update(options)
         state_machine.document.note_pending(pending)
         return [pending] + messages
@@ -345,8 +345,4 @@ Aspects of note include:
    options, effectively communicating the options forward.  The actual
    table of contents processing is performed by a transform,
    ``docutils.transforms.parts.Contents``, after the rest of the
-   document has been parsed. [#]_
-
-.. [#] Please note that the priority system for transforms, indicated
-   above by ``'first writer'`` in the call to the ``nodes.pending``
-   class, is due for an overhaul.
+   document has been parsed.
diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt
index 8dc00f72e..198ebd9d8 100644
--- a/docs/peps/pep-0256.txt
+++ b/docs/peps/pep-0256.txt
@@ -34,8 +34,8 @@ The concepts of a DPS framework are presented independently of
 implementation details.
 
 
-Roadmap to the Doctring PEPs
-============================
+Road Map to the Doctring PEPs
+=============================
 
 There are many aspects to docstring processing.  The "Docstring PEPs"
 have broken up the issues in order to deal with each of them in
diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt
index e7df5dc04..1a0968ecf 100644
--- a/docs/peps/pep-0258.txt
+++ b/docs/peps/pep-0258.txt
@@ -20,7 +20,7 @@ This PEP documents design issues and implementation details for
 Docutils, a Python Docstring Processing System (DPS).  The rationale
 and high-level concepts of a DPS are documented in PEP 256, "Docstring
 Processing System Framework" [#PEP-256]_.  Also see PEP 256 for a
-"Roadmap to the Docstring PEPs".
+"Road Map to the Docstring PEPs".
 
 Docutils is being designed modularly so that any of its components can
 be replaced easily.  In addition, Docutils is not limited to the
@@ -192,9 +192,9 @@ other context-sensitive processing.
 Some transforms are specific to components (Readers, Parser, Writers,
 Input, Output).  Standard component-specific transforms are specified
 in the ``default_transforms`` attribute of component classes.  After
-the Reader has finished processing, the Publisher_ calls the
-Transformer object's "populate_from_components" method with a list of
-components.
+the Reader has finished processing, the Publisher_ calls
+``Transformer.populate_from_components()`` with a list of components
+and all default transforms are stored.
 
 Each transform is a class in a module in the ``docutils/transforms/``
 package, a subclass of ``docutils.tranforms.Transform``.  Transform
diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt
index 4b4ed4e44..af790a53e 100644
--- a/docs/peps/pep-0287.txt
+++ b/docs/peps/pep-0287.txt
@@ -25,7 +25,7 @@ what-you-see-is-what-you-get plaintext markup syntax.
 
 Only the low-level syntax of docstrings is addressed here.  This PEP
 is not concerned with docstring semantics or processing at all (see
-PEP 256 for a "Roadmap to the Doctring PEPs").  Nor is it an attempt
+PEP 256 for a "Road Map to the Doctring PEPs").  Nor is it an attempt
 to deprecate pure plaintext docstrings, which are always going to be
 legitimate.  The reStructuredText markup is an alternative for those
 who want more expressive docstrings.
diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 92e85179c..a5564f042 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -21,84 +21,70 @@ For background about transforms and the Transformer object, see `PEP
 Transforms Listed in Priority Order
 ===================================
 
-==============================  ======================  ========
-Transform: module.Class         Added By                Priority
-==============================  ======================  ========
-references.Substitutions        standalone (r)          220
+==============================  ============================  ========
+Transform: module.Class         Added By                      Priority
+==============================  ============================  ========
+references.Substitutions        standalone (r), pep (r)       220
 
-                                pep (r)                 
+frontmatter.DocTitle            standalone (r)                320
 
-frontmatter.DocTitle            standalone (r)          320
+frontmatter.DocInfo             standalone (r)                340
 
-frontmatter.DocInfo             standalone (r)          340
+peps.Headers                    pep (r)                       360
 
-peps.Headers                    pep (r)                 360
+peps.Contents                   pep (r)                       380
 
-peps.Contents                   pep (r)                 380
+references.ChainedTargets       standalone (r), pep (r)       420
 
-references.ChainedTargets       standalone (r)          420
+references.AnonymousHyperlinks  standalone (r), pep (r)       440
 
-                                pep (r)                 
+references.IndirectHyperlinks   standalone (r), pep (r)       460
 
-references.AnonymousHyperlinks  standalone (r)          440
+peps.TargetNotes                pep (r)                       520
 
-                                pep (r)                 
+references.TargetNotes          peps.TargetNotes (t/p)        0
 
-references.IndirectHyperlinks   standalone (r)          460
+references.TargetNotes          "target-notes" (d/p)          540
 
-                                pep (r)                 
+references.Footnotes            standalone (r), pep (r)       620
 
-peps.TargetNotes                pep (r)                 520
+references.ExternalTargets      standalone (r), pep (r)       640
 
-references.TargetNotes          peps.TargetNotes (t)    0
+references.InternalTargets      standalone (r), pep (r)       660
 
-                                "target-notes" (d)      540
+parts.SectNum                   "sectnum" (d/p)               710
 
-references.Footnotes            standalone (r)          620
+parts.Contents                  "contents" (d/p),             720
+                                peps.Contents (t/p)
 
-                                pep (r)                 
+peps.PEPZero                    pep.Headers (t/p)             760
 
-references.ExternalTargets      standalone (r)          640
+components.Filter               "meta" (d/p)                  780
 
-                                pep (r)                 
+universal.Decorations           Transformer                   820
 
-references.InternalTargets      standalone (r)          660
+universal.FinalChecks           Transformer                   840
 
-                                pep (r)                 
+universal.Messages              Transformer                   860
 
-parts.SectNum                   "sectnum" (d)           710
+universal.TestMessages          DocutilsTestSupport           890
+==============================  ============================  ========
 
-parts.Contents                  "contents" (d)          720
-
-                                peps.Contents (t)       
-
-peps.PEPZero                    pep.Headers (t)         760
-
-components.Filter               "meta" (d)              780
-
-universal.Decorations           all Readers             820
-
-universal.FinalChecks           all Writers             840
-
-universal.Messages              all Writers             860
-
-universal.TestMessages          DocutilsTestSupport     890
-==============================  ======================  ========
-
-Legend:
+Key:
 
 * (r): Reader
 * (d): Directive
 * (t): Transform
+* (/p): Via a "pending" node
 
 
 Transform Priority Range Categories
 ===================================
 
 ====  ====  ================================================
- Priority   Category
+ Priority
 ----------  ------------------------------------------------
-From   To
+From   To   Category
 ====  ====  ================================================
          0  immediate execution (added by another transform)
 ----------  ------------------------------------------------
diff --git a/docutils/core.py b/docutils/core.py
index 14e794c7e..900498b9e 100644
--- a/docutils/core.py
+++ b/docutils/core.py
@@ -163,11 +163,11 @@ class Publisher:
         output = self.writer.write(document, self.destination)
         if self.settings.dump_settings:
             from pprint import pformat
-            print >>sys.stderr, '\n::: Docutils settings:'
+            print >>sys.stderr, '\n::: Runtime settings:'
             print >>sys.stderr, pformat(self.settings.__dict__)
         if self.settings.dump_internals:
             from pprint import pformat
-            print >>sys.stderr, '\n::: Docutils internals:'
+            print >>sys.stderr, '\n::: Document internals:'
             print >>sys.stderr, pformat(document.__dict__)
         if self.settings.dump_transforms:
             from pprint import pformat
diff --git a/docutils/transforms/peps.py b/docutils/transforms/peps.py
index db1cdf47f..fe82175b8 100644
--- a/docutils/transforms/peps.py
+++ b/docutils/transforms/peps.py
@@ -160,18 +160,21 @@ class TargetNotes(Transform):
         i = len(doc) - 1
         refsect = copyright = None
         while i >= 0 and isinstance(doc[i], nodes.section):
-            if 'references' in doc[i][0].astext().lower().split():
+            title_words = doc[i][0].astext().lower().split()
+            if 'references' in title_words:
                 refsect = doc[i]
                 break
-            if 'copyright' in doc[i][0].astext().lower().split():
+            elif 'copyright' in title_words:
                 copyright = i
             i -= 1
         if not refsect:
             refsect = nodes.section()
             refsect += nodes.title('', 'References')
             if copyright:
+                # Put the new "References" section before "Copyright":
                 doc.insert(copyright, refsect)
             else:
+                # Put the new "References" section at end of doc:
                 doc.append(refsect)
         pending = nodes.pending(references.TargetNotes)
         refsect.append(pending)
diff --git a/setup.py b/setup.py
index 636619bb6..c58ab1725 100755
--- a/setup.py
+++ b/setup.py
@@ -17,7 +17,8 @@ def do_setup():
                       'docutils.transforms', 'docutils.languages', 
                       'docutils.parsers', 'docutils.parsers.rst',
                       'docutils.parsers.rst.directives',
-                      'docutils.parsers.rst.languages'])
+                      'docutils.parsers.rst.languages'],
+          scripts = ['tools/html.py']            )
     return dist
 
 if __name__ == '__main__' :