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
........

5 files changed, 9 insertions, 110 deletions

diff --git a/Doc/documenting/index.rst b/Doc/documenting/index.rst
index 5adbd46..5ec9fb6 100644
--- a/Doc/documenting/index.rst
+++ b/Doc/documenting/index.rst
@@ -8,7 +8,7 @@
 The Python language has a substantial body of documentation, much of it
 contributed by various authors. The markup used for the Python documentation is
 `reStructuredText`_, developed by the `docutils`_ project, amended by custom
-directives and using a toolset named *Sphinx* to postprocess the HTML output.
+directives and using a toolset named `Sphinx`_ to postprocess the HTML output.
 
 This document describes the style guide for our documentation, the custom
 reStructuredText markup introduced to support Python documentation and how it
@@ -16,6 +16,7 @@ should be used, as well as the Sphinx build system.
 
 .. _reStructuredText: http://docutils.sf.net/rst.html
 .. _docutils: http://docutils.sf.net/
+.. _Sphinx: http://sphinx.pocoo.org/
 
 If you're interested in contributing to Python's documentation, there's no need
 to write reStructuredText if you're not so inclined; plain text contributions
@@ -28,7 +29,3 @@ are more than welcome as well.
    rest.rst
    markup.rst
    fromlatex.rst
-   sphinx.rst
-
-.. XXX add credits, thanks etc.
-
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|
 
diff --git a/Doc/documenting/rest.rst b/Doc/documenting/rest.rst
index 8a4fc3d..e018373 100644
--- a/Doc/documenting/rest.rst
+++ b/Doc/documenting/rest.rst
@@ -67,12 +67,6 @@ autonumbered using a ``#`` sign::
    #. This is a numbered list.
    #. It has two items too.
 
-Note that Sphinx disables the use of enumerated lists introduced by alphabetic
-or roman numerals, such as ::
-
-   A. First item
-   B. Second item
-   
 
 Nested lists are possible, but be aware that they must be separated from the
 parent list items by blank lines::
@@ -247,5 +241,3 @@ There are some problems one commonly runs into while authoring reST documents:
 * **Separation of inline markup:** As said above, inline markup spans must be
   separated from the surrounding text by non-word characters, you have to use
   an escaped space to get around that.
-
-.. XXX more?
diff --git a/Doc/documenting/sphinx.rst b/Doc/documenting/sphinx.rst
deleted file mode 100644
index 43da14e..0000000
--- a/Doc/documenting/sphinx.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-.. highlightlang:: rest
-
-The Sphinx build system
-=======================
-
-.. XXX: intro...
-
-.. _doc-build-config:
-
-The build configuration file
-----------------------------
-
-The documentation root, that is the ``Doc`` subdirectory of the source
-distribution, contains a file named ``conf.py``.  This file is called the "build
-configuration file", and it contains several variables that are read and used
-during a build run.
-
-These variables are:
-
-version : string
-   A string that is used as a replacement for the ``|version|`` reST
-   substitution.  It should be the Python version the documentation refers to.
-   This consists only of the major and minor version parts, e.g. ``2.5``, even
-   for version 2.5.1.
-
-release : string
-   A string that is used as a replacement for the ``|release|`` reST
-   substitution.  It should be the full version string including
-   alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
-
-Both ``release`` and ``version`` can be ``'auto'``, which means that they are
-determined at runtime from the ``Include/patchlevel.h`` file, if a complete
-Python source distribution can be found, or else from the interpreter running
-Sphinx.
-
-today_fmt : string
-   A ``strftime`` format that is used to format a replacement for the
-   ``|today|`` reST substitution.
-
-today : string
-   A string that can contain a date that should be written to the documentation
-   output literally.  If this is nonzero, it is used instead of
-   ``strftime(today_fmt)``.
-
-unused_files : list of strings
-   A list of reST filenames that are to be disregarded during building.  This
-   could be docs for temporarily disabled modules or documentation that's not
-   yet ready for public consumption.
-
-add_function_parentheses : bool
-   If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
-   ``:cfunc:`` cross-references.
-
-add_module_names : bool
-   If true, the current module name will be prepended to all description unit
-   titles (such as ``.. function::``).
-
-Builder-specific variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-html_download_base_url : string
-   The base URL for download links on the download page.
-
-html_last_updated_fmt : string
-   If this is not an empty string, it will be given to ``time.strftime()`` and
-   written to each generated output file after "last updated on:".
-
-html_use_smartypants : bool
-   If true, use SmartyPants to convert quotes and dashes to the typographically
-   correct entities.
-
-latex_paper_size : "letter" or "a4"
-   The paper size option for the LaTeX document class.
-
-latex_font_size : "10pt", "11pt" or "12pt"
-   The font size option for the LaTeX document class.
\ No newline at end of file
diff --git a/Doc/documenting/style.rst b/Doc/documenting/style.rst
index 5821bd8..593f6da 100644
--- a/Doc/documenting/style.rst
+++ b/Doc/documenting/style.rst
@@ -66,5 +66,5 @@ Unix
     1970s.
 
 
-.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2006.pdf
+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2008.pdf