--- rest25/documenting/markup.rst	2008-12-19 16:58:09.000000000 +0900
+++ rest262/documenting/markup.rst	2009-04-05 05:02:10.000000000 +0900
@@ -1,23 +1,28 @@
 .. highlightlang:: rest
 
 Additional Markup Constructs
 ============================
 
 Sphinx adds a lot of new directives and interpreted text roles to standard reST
 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.
 
-XXX: file-wide metadata
+.. note::
+
+   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
 -----------------------
 
 .. describe:: sectionauthor
 
    Identifies the author of the current section.  The argument should include
    the author's name such that it can be used for presentation (though it isn't)
    and email address.  The domain name portion of the address should be lower
    case.  Example::
 
       .. sectionauthor:: Guido van Rossum <guido@python.org>
@@ -52,31 +57,33 @@
    submodule, in which case the name should be fully qualified, including the
    package name).
 
    The ``platform`` option, if present, is a comma-separated list of the
    platforms on which the module is available (if it is available on all
    platforms, the option should be omitted).  The keys are short identifiers;
    examples that are in use include "IRIX", "Mac", "Windows", and "Unix".  It is
    important to use a key which has already been used when applicable.
 
    The ``synopsis`` option should consist of one sentence describing the
    module's purpose -- it is currently only used in the Global Module Index.
 
+   The ``deprecated`` option can be given (with no value) to mark a module as
+   deprecated; it will be designated as such in various locations then.
+
 .. describe:: moduleauthor
 
    The ``moduleauthor`` directive, which can appear multiple times, names 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
    meaningful since that value will be inserted in the table-of-contents trees
    in overview files.
 
 
 Information units
 -----------------
 
 There are a number of directives used to describe specific features provided by
 modules.  Each directive requires one or more signatures to provide basic
@@ -180,25 +187,38 @@
    Describes an object data attribute.  The description should include
    information about the type of the data to be expected and whether it may be
    changed directly.
 
 .. describe:: method
 
    Describes an object method.  The parameters should not include the ``self``
    parameter.  The description should include similar information to that
    described for ``function``.
 
 .. describe:: opcode
 
-   Describes a Python bytecode instruction.
+   Describes a Python :term:`bytecode` instruction.
+
+.. describe:: cmdoption
+
+   Describes a command line option or switch.  Option argument names should be
+   enclosed in angle brackets.  Example::
+
+      .. cmdoption:: -m <module>
+
+         Run a module as a script.
+
+.. describe:: envvar
+
+   Describes an environment variable that Python uses or defines.
 
 
 There is also a generic version of these directives:
 
 .. describe:: describe
 
    This directive produces the same formatting as the specific ones explained
    above but does not create index entries or cross-referencing targets.  It is
    used, for example, to describe the directives in this document. Example::
 
       .. describe:: opcode
 
@@ -229,101 +249,126 @@
 
 * Within Python highlighting mode, interactive sessions are recognized
   automatically and highlighted appropriately.
 
 * The highlighting language can be changed using the ``highlightlang``
   directive, used as follows::
 
      .. highlightlang:: c
 
   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``
   * ``rest``
   * ``none`` (no highlighting)
 
 * If highlighting with the current language fails, the block is not highlighted
   in any way.
 
 Longer displays of verbatim text may be included by storing the example text in
 an external file containing only plain text.  The file may be included using the
-standard ``include`` directive with the ``literal`` option flag.  For example,
-to include the Python source file :file:`example.py`, use::
+``literalinclude`` directive. [1]_ For example, to include the Python source file
+:file:`example.py`, use::
 
-   .. include:: example.py
-      :literal:
+   .. literalinclude:: example.py
+
+The file name is relative to the current file's path.  Documentation-specific
+include files should be placed in the ``Doc/includes`` subdirectory.
 
 
 Inline markup
 -------------
 
 As said before, Sphinx uses interpreted text roles to insert semantic markup in
 documents.
 
-The default role is ``var``, as that was one of the most common macros used in
-the old LaTeX docs.  That means that you can use ```var``` to refer to a
-variable named "var".
+Names of local variables, such as function/method arguments, are an exception,
+they should be marked simply with ``*var*``.
 
 For all other roles, you have to write ``:rolename:`content```.
 
+There are some additional facilities that make cross-referencing roles more
+versatile:
+
+* You may supply an explicit title and reference target, like in reST direct
+  hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
+  text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* For the Python object roles, if you prefix the content with ``~``, the link
+  text will only be the last component of the target.  For example,
+  ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only
+  display ``get`` as the link text.
+
+  In HTML output, the link's ``title`` attribute (that is e.g. shown as a
+  tool-tip on mouse-hover) will always be the full target name.
+
 The following roles refer to objects in modules and are possibly hyperlinked if
 a matching identifier is found:
 
 .. describe:: mod
 
    The name of a module; a dotted name may be used.  This should also be used for
    package names.
 
 .. describe:: func
 
    The name of a Python function; dotted names may be used.  The role text
-   should include trailing parentheses to enhance readability.  The parentheses
-   are stripped when searching for identifiers.
+   should not include trailing parentheses to enhance readability.  The
+   parentheses are stripped when searching for identifiers.
 
 .. describe:: data
 
-   The name of a module-level variable.
+   The name of a module-level variable or constant.
 
 .. describe:: const
 
    The name of a "defined" constant.  This may be a C-language ``#define``
    or a Python variable that is not intended to be changed.
 
 .. describe:: class
 
    A class name; a dotted name may be used.
 
 .. describe:: meth
 
    The name of a method of an object.  The role text should include the type
-   name, method name and the trailing parentheses.  A dotted name may be used.
+   name and the method name.  A dotted name may be used.
 
 .. describe:: attr
 
    The name of a data attribute of an object.
 
 .. describe:: exc
 
    The name of an exception. A dotted name may be used.
 
 The name enclosed in this markup can include a module name and/or a class name.
 For example, ``:func:`filter``` could refer to a function named ``filter`` in
 the current module, or the built-in function of that name.  In contrast,
 ``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
 module.
 
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended.  If you prefix the name with a
+dot, this order is reversed.  For example, in the documentation of the
+:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
+while ``:func:`.open``` refers to :func:`codecs.open`.
+
 A similar heuristic is used to determine whether the name is an attribute of
 the currently documented class.
 
 The following roles create cross-references to C-language constructs if they
 are defined in the API documentation:
 
 .. describe:: cdata
 
    The name of a C-language variable.
 
 .. describe:: cfunc
 
@@ -337,24 +382,38 @@
 
    The name of a C-language type.
 
 
 The following role does possibly create a cross-reference, but does not refer
 to objects:
 
 .. describe:: token
 
    The name of a grammar token (used in the reference manual to create links
    between production displays).
 
+
+The following role creates a cross-reference to the term in the glossary:
+
+.. describe:: term
+
+   Reference to a term in the glossary.  The glossary is created using the
+   ``glossary`` directive containing a definition list with terms and
+   definitions.  It does not have to be in the same file as the ``term``
+   markup, in fact, by default the Python docs have one global glossary
+   in the ``glossary.rst`` file.
+
+   If you use a term that's not explained in a glossary, you'll get a warning
+   during build.
+
 ---------
 
 The following roles don't do anything special except formatting the text
 in a different style:
 
 .. describe:: command
 
    The name of an OS-level command, such as ``rm``.
 
 .. describe:: dfn
 
    Mark the defining instance of a term in the text.  (No index entries are
@@ -386,25 +445,25 @@
 .. describe:: kbd
 
    Mark a sequence of keystrokes.  What form the key sequence takes may depend
    on platform- or application-specific conventions.  When there are no relevant
    conventions, the names of modifier keys should be spelled out, to improve
    accessibility for new users and non-native speakers.  For example, an
    *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
    reference to a specific application or platform, the same sequence should be
    marked as ``:kbd:`Control-x Control-f```.
 
 .. describe:: keyword
 
-   The name of a keyword in a programming language.
+   The name of a keyword in Python.
 
 .. describe:: mailheader
 
    The name of an RFC 822-style mail header.  This markup does not imply that
    the header is being used in an email message, but can be used to refer to any
    header of the same "style."  This is also used for headers defined by the
    various MIME specifications.  The header name should be entered in the same
    way it would normally be found in practice, with the camel-casing conventions
    being preferred where there is more than one common usage. For example:
    ``:mailheader:`Content-Type```.
 
 .. describe:: makevar
@@ -447,24 +506,32 @@
    be included.
 
 .. describe:: program
 
    The name of an executable program.  This may differ from the file name for
    the executable for some platforms.  In particular, the ``.exe`` (or other)
    extension should be omitted for Windows programs.
 
 .. describe:: regexp
 
    A regular expression. Quotes should not be included.
 
+.. describe:: samp
+
+   A piece of literal text, such as code.  Within the contents, you can use
+   curly braces to indicate a "variable" part, as in ``:file:``.
+
+   If you don't need the "variable part" indication, use the standard
+   ````code```` instead.
+
 .. describe:: var
 
    A Python or C variable or parameter name.
 
 
 The following roles generate external links:
 
 .. describe:: pep
 
    A reference to a Python Enhancement Proposal.  This generates appropriate
    index entries. The text "PEP *number*\ " is generated; in the HTML output,
    this text is a hyperlink to an online copy of the specified PEP.
@@ -477,25 +544,25 @@
 
 
 Note that there are no special roles for including hyperlinks as you can use
 the standard reST markup for that purpose.
 
 
 .. _doc-ref-role:
 
 Cross-linking markup
 --------------------
 
 To support cross-referencing to arbitrary sections in the documentation, the
-standard reST labels are "abused" a bit:  Every label must precede a section
+standard reST labels are "abused" a bit: Every label must precede a section
 title; and every label name must be unique throughout the entire documentation
 source.
 
 You can then reference to these sections using the ``:ref:`label-name``` role.
 
 Example::
 
    .. _my-reference-label:
 
    Section to cross-reference
    --------------------------
 
@@ -536,25 +603,25 @@
 .. describe:: versionadded
 
    This directive documents the version of Python which added the described
    feature to the library or C API. When this applies to an entire module, it
    should be placed at the top of the module section before any prose.
 
    The first argument must be given and is the version in question; you can add
    a second argument consisting of a *brief* explanation of the change.
 
    Example::
 
       .. versionadded:: 2.5
-         The `spam` parameter.
+         The *spam* parameter.
 
    Note that there must be no blank line between the directive head and the
    explanation; this is to make these blocks visually continuous in the markup.
 
 .. describe:: versionchanged
 
    Similar to ``versionadded``, but describes when and what changed in the named
    feature in some way (new parameters, changed side effects, etc.).
 
 --------------
 
 .. describe:: seealso
@@ -643,100 +710,114 @@
 functions, classes or attributes) like discussed before.
 
 However, there is also an explicit directive available, to make the index more
 comprehensive and enable index entries in documents where information is not
 mainly contained in information units, such as the language reference.
 
 The directive is ``index`` and contains one or more index entries.  Each entry
 consists of a type and a value, separated by a colon.
 
 For example::
 
    .. index::
-      single: execution!context
+      single: execution; context
       module: __main__
       module: sys
       triple: module; search; path
 
 This directive contains five entries, which will be converted to entries in the
 generated index which link to the exact location of the index statement (or, in
 case of offline media, the corresponding page number).
 
 The possible entry types are:
 
 single
    Creates a single index entry.  Can be made a subentry by separating the
-   subentry text with a semicolon (this is also used below to describe what
-   entries are created).
+   subentry text with a semicolon (this notation is also used below to describe
+   what entries are created).
 pair
    ``pair: loop; statement`` is a shortcut that creates two index entries,
    namely ``loop; statement`` and ``statement; loop``.
 triple
    Likewise, ``triple: module; search; path`` is a shortcut that creates three
    index entries, which are ``module; search path``, ``search; path, module`` and
-    ``path; module search``.
+   ``path; module search``.
 module, keyword, operator, object, exception, statement, builtin
    These all create two index entries.  For example, ``module: hashlib`` creates
    the entries ``module; hashlib`` and ``hashlib; module``.
 
+For index directives containing only "single" entries, there is a shorthand
+notation::
+
+   .. index:: BNF, grammar, syntax, notation
+
+This creates four index entries.
+
 
 Grammar production displays
 ---------------------------
 
 Special markup is available for displaying the productions of a formal grammar.
 The markup is simple and does not attempt to model all aspects of BNF (or any
 derived forms), but provides enough to allow context-free grammars to be
 displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
 the definition of the symbol.  There is this directive:
 
 .. describe:: productionlist
 
    This directive is used to enclose a group of productions.  Each production is
    given on a single line and consists of a name, separated by a colon from the
    following definition.  If the definition spans multiple lines, each
    continuation line must begin with a colon placed at the same column as in the
    first line.
 
    Blank lines are not allowed within ``productionlist`` directive arguments.
 
    The definition can contain token names which are marked as interpreted text
-   (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
-   to the productions of these tokens.  Note that vertical bars used to indicate
-   alternatives must be escaped with backslashes because otherwise they would
-   indicate a substitution reference to the reST parser.
+   (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references
+   to the productions of these tokens.
 
+   Note that no further reST parsing is done in the production, so that you
+   don't have to escape ``*`` or ``|`` characters.
 
-.. XXX describe optional first parameter 
+
+.. XXX describe optional first parameter
 
 The following is an example taken from the Python Reference Manual::
 
    .. productionlist::
-      try_stmt: try1_stmt \| try2_stmt
-      try1_stmt: "try" ":" :token:`suite`
-               : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+
-               : ["else" ":" :token:`suite`]
-               : ["finally" ":" :token:`suite`]
-      try2_stmt: "try" ":" :token:`suite`
-               : "finally" ":" :token:`suite`
+      try_stmt: try1_stmt | try2_stmt
+      try1_stmt: "try" ":" `suite`
+               : ("except" [`expression` ["," `target`]] ":" `suite`)+
+               : ["else" ":" `suite`]
+               : ["finally" ":" `suite`]
+      try2_stmt: "try" ":" `suite`
+               : "finally" ":" `suite`
 
 
 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|
 
    Replaced by the Python release the documentation refers to.  This is the full
    version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
 
 .. describe:: |version|
 
    Replaced by 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.
 
 .. describe:: |today|
 
    Replaced by either today's date, or the date set in the build configuration
    file.  Normally has the format ``April 14, 2007``.
+
+
+.. rubric:: Footnotes
+
+.. [1] There is a standard ``.. include`` directive, but it raises errors if the
+       file is not found.  This one only emits a warning.
