Merged revisions 67154,67157-67159,67175-67176,67189,67224-67227,67234 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r67154 | hirokazu.yamamoto | 2008-11-07 21:46:17 -0600 (Fri, 07 Nov 2008) | 1 line

  Issue #4071: ntpath.abspath returned an empty string for long unicode path.
........
  r67157 | georg.brandl | 2008-11-08 05:47:44 -0600 (Sat, 08 Nov 2008) | 2 lines

  Don't use "HOWTO" as the title for all howto .tex files.
........
  r67158 | georg.brandl | 2008-11-08 05:48:20 -0600 (Sat, 08 Nov 2008) | 2 lines

  Update "Documenting" a bit. Concentrate on Python-specifics.
........
  r67159 | georg.brandl | 2008-11-08 06:52:25 -0600 (Sat, 08 Nov 2008) | 2 lines

  Fix warning.
........
  r67175 | benjamin.peterson | 2008-11-08 19:44:32 -0600 (Sat, 08 Nov 2008) | 1 line

  update link
........
  r67176 | benjamin.peterson | 2008-11-08 19:52:32 -0600 (Sat, 08 Nov 2008) | 1 line

  fix comment
........
  r67189 | benjamin.peterson | 2008-11-11 15:56:06 -0600 (Tue, 11 Nov 2008) | 1 line

  use correct name
........
  r67224 | georg.brandl | 2008-11-15 02:10:04 -0600 (Sat, 15 Nov 2008) | 2 lines

  #4324: fix getlocale() argument.
........
  r67225 | brett.cannon | 2008-11-15 16:33:25 -0600 (Sat, 15 Nov 2008) | 1 line

  Clarify the docs for the 'strict' argument to httplib.HTTPConnection.
........
  r67226 | brett.cannon | 2008-11-15 16:40:44 -0600 (Sat, 15 Nov 2008) | 4 lines

  The docs for httplib.HTTPConnection.putheader() have claimed for quite a while
  that their could be an arbitrary number of values passed in. Turns out the code
  did not match that. The code now matches the docs.
........
  r67227 | georg.brandl | 2008-11-16 02:00:17 -0600 (Sun, 16 Nov 2008) | 2 lines

  #4316: fix configure.in markup problem.
........
  r67234 | benjamin.peterson | 2008-11-16 11:54:55 -0600 (Sun, 16 Nov 2008) | 1 line

  run autoconf
........

1 files changed, 6 insertions, 20 deletions

diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index 7cf89b0..e6f6a52 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -8,24 +8,11 @@ markup.  This section contains the reference material for these facilities.
 Documentation for "standard" reST constructs is not included here, though
 they are used in the Python documentation.
 
-File-wide metadata
-------------------
-
-reST has the concept of "field lists"; these are a sequence of fields marked up
-like this::
-
-   :Field name: Field content
-
-A field list at the very top of a file is parsed as the "docinfo", which in
-normal documents can be used to record the author, date of publication and
-other metadata.  In Sphinx, the docinfo is used as metadata, too, but not
-displayed in the output.
-
-At the moment, only one metadata field is recognized:
+.. note::
 
-``nocomments``
-   If set, the web application won't display a comment form for a page generated
-   from this source file.
+   This is just an overview of Sphinx' extended markup capabilities; full
+   coverage can be found in `its own documentation
+   <http://sphinx.pocoo.org/contents.html>`_.
 
 
 Meta-information markup
@@ -88,7 +75,6 @@ As you can see, the module-specific markup consists of two directives, the
    authors of the module code, just like ``sectionauthor`` names the author(s)
    of a piece of documentation.  It too does not result in any output currently.
 
-
 .. note::
 
    It is important to make the section title of a module-describing file
@@ -272,7 +258,7 @@ Syntax highlighting is handled in a smart way:
   This language is used until the next ``highlightlang`` directive is
   encountered.
 
-* The valid values for the highlighting language are:
+* The values normally used for the highlighting language are:
 
   * ``python`` (the default)
   * ``c``
@@ -799,7 +785,7 @@ Substitutions
 -------------
 
 The documentation system provides three substitutions that are defined by default.
-They are set in the build configuration file, see :ref:`doc-build-config`.
+They are set in the build configuration file :file:`conf.py`.
 
 .. describe:: |release|