Documentation update

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

3 files changed, 151 insertions, 192 deletions

diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index 2ad21bcc0..633ee796d 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -4017,6 +4017,9 @@ The ``table`` element identifies a data arrangement with rows and columns.
 Docutils tables are based on the `Exchange subset of the CALS-table
 model` [exchange-table-model]_. [#]_
 
+.. [#] The interpretation of column widths in colspec_ differs from the
+   specification.
+
 Details
 -------
 
@@ -4058,8 +4061,8 @@ table__, csv-table_, or list-table_ directives or directly as
 `grid table`_ or `simple table`_, e.g. ::
 
     ======== ====
-     bread   ¥20
-     butter  ¥300
+     bread   £2
+     butter  £30
     ======== ====
 
 Pseudo-XML_ fragment from simple parsing::
@@ -4075,14 +4078,14 @@ Pseudo-XML_ fragment from simple parsing::
                             bread
                     <entry>
                         <paragraph>
-                            ¥20
+                            £2
                 <row>
                     <entry>
                         <paragraph>
                             butter
                     <entry>
                         <paragraph>
-                            ¥300
+                            £30
 
 __ rst/directives.html#table
 .. _csv-table: rst/directives.html#csv-table
@@ -4090,12 +4093,8 @@ __ rst/directives.html#table
 .. _grid table: rst/restructuredtext.html#grid-tables
 .. _simple table: rst/restructuredtext.html#simple-tables
 
-.. [exchange-table-model] OASIS Technical Memorandum 9901:1999 "XML Exchange
-   Table Model DTD", http://www.oasis-open.org/html/tm9901.htm).
-
-.. [#] The interpretation of column widths in colspec_ differs from the
-   specification. This may be changed in future.
-
+.. [exchange-table-model] `XML Exchange Table Model DTD`, OASIS Technical
+   Memorandum 9901:1999, http://www.oasis-open.org/html/tm9901.html.
 
 ``target``
 ==========
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index e6ba27bf3..c9dac074d 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -78,7 +78,7 @@ Specific Admonitions
 :Doctree Elements: attention, caution, danger, error, hint, important,
                    note, tip, warning, admonition_, title_
 :Directive Arguments: None.
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: Interpreted as body elements.
 
 Admonitions are specially marked "topics" that can appear anywhere an
@@ -130,7 +130,7 @@ Generic Admonition
 :Directive Type: "admonition"
 :Doctree Elements: admonition_, title_
 :Directive Arguments: One, required (admonition title)
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: Interpreted as body elements.
 
 This is a generic, titled admonition.  The title may be anything the
@@ -154,7 +154,7 @@ becomes the following document tree (pseudo-XML)::
             <paragraph>
                 You can make up your own admonition too.
 
-The `:class:`_ option overrides the computed `"classes"`_ attribute
+The class_ option overrides the computed `"classes"`_ attribute
 value.
 
 
@@ -171,7 +171,7 @@ Image
 :Directive Type: "image"
 :Doctree Element: image_
 :Directive Arguments: One, required (image URI).
-:Directive Options: Possible.
+:Directive Options: Possible (see below).
 :Directive Content: None.
 
 An "image" is a simple picture::
@@ -242,7 +242,7 @@ The following options are recognized:
     option argument may be a URI (relative or absolute), or a
     `reference name`_ with underscore suffix (e.g. ```a name`_``).
 
-and the common options `:class:`_ and `:name:`_.
+and the common options class_ and name_.
 
 
 Figure
@@ -251,7 +251,7 @@ Figure
 :Directive Type: "figure"
 :Doctree Elements: figure_, image_, caption_, legend_
 :Directive Arguments: One, required (image URI).
-:Directive Options: Possible.
+:Directive Options: Possible (see below).
 :Directive Content: Interpreted as the figure caption and an optional
                     legend.
 
@@ -343,7 +343,7 @@ Topic
 :Directive Type: "topic"
 :Doctree Element: topic_
 :Directive Arguments: One, required (topic title).
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: Interpreted as the topic body.
 
 A topic is like a block quote with a title, or a self-contained
@@ -399,7 +399,7 @@ The following options are recognized:
 ``subtitle`` : text
     The sidebar's subtitle.
 
-and the common options `:class:`_ and `:name:`_.
+and the common options class_ and name_.
 
 
 Line Block
@@ -415,7 +415,7 @@ Line Block
 :Directive Type: "line-block"
 :Doctree Element: line_block_
 :Directive Arguments: None.
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: Becomes the body of the line block.
 
 The "line-block" directive constructs an element where line breaks and
@@ -449,7 +449,7 @@ Parsed Literal Block
 :Directive Type: "parsed-literal"
 :Doctree Element: literal_block_
 :Directive Arguments: None.
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: Becomes the body of the literal block.
 
 Unlike an ordinary literal block, the "parsed-literal" directive
@@ -485,8 +485,6 @@ Code
 :Directive Content: Becomes the body of the literal block.
 :Configuration Setting: syntax_highlight_.
 
-(New in Docutils 0.9)
-
 The "code" directive constructs a literal block. If the code language is
 specified, the content is parsed by the Pygments_ syntax highlighter and
 tokens are stored in nested `inline elements`_ with class arguments
@@ -495,7 +493,7 @@ a style-sheet (e.g. one `generated by Pygments`__, see the
 `sandbox/stylesheets`__ for examples).
 
 The parsing can be turned off with the syntax_highlight_ configuration
-setting and command line option or by specifying the language as `:class:`_
+setting and command line option or by specifying the language as class_
 option instead of directive argument. This also avoids warnings
 when Pygments_ is not installed or the language is not in the
 `supported languages and markup formats`_.
@@ -516,7 +514,7 @@ The following options are recognized:
     Precede every line with a line number.
     The optional argument is the number of the first line (defaut 1).
 
-and the common options `:class:`_ and `:name:`_.
+and the common options class_ and name_.
 
 Example::
   The content of the following directive ::
@@ -536,14 +534,12 @@ Math
 :Directive Type: "math"
 :Doctree Element: math_block_
 :Directive Arguments: None.
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: Becomes the body of the math block.
                     (Content blocks separated by a blank line are put in
                     adjacent math blocks.)
 :Configuration Setting: math_output_
 
-(New in Docutils 0.8)
-
 The "math" directive inserts blocks with mathematical content
 (display formulas, equations) into the document. The input format is
 `LaTeX math syntax`_ with support for Unicode symbols, for example::
@@ -572,7 +568,7 @@ Rubric
 :Directive Type: "rubric"
 :Doctree Element: rubric_
 :Directive Arguments: One, required (rubric text).
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: None.
 
 ..
@@ -658,11 +654,9 @@ Compound Paragraph
 :Directive Type: "compound"
 :Doctree Element: compound_
 :Directive Arguments: None.
-:Directive Options: `:class:`_, `:name:`_
+:Directive Options: class_, name_
 :Directive Content: Interpreted as body elements.
 
-(New in Docutils 0.3.6)
-
 The "compound" directive is used to create a compound paragraph, which
 is a single logical paragraph containing multiple physical body
 elements such as simple paragraphs, literal blocks, tables, lists,
@@ -708,11 +702,9 @@ Container
 :Directive Type: "container"
 :Doctree Element: `container <container element_>`__
 :Directive Arguments: One or more, optional (class names).
-:Directive Options: `:name:`_
+:Directive Options: name_
 :Directive Content: Interpreted as body elements.
 
-(New in Docutils 0.3.10)
-
 The "container" directive surrounds its contents (arbitrary body
 elements) with a generic block-level "container" element.  Combined
 with the optional "classes_" attribute argument(s), this is an
@@ -754,8 +746,6 @@ Table
 :Directive Options: Possible (see below).
 :Directive Content: A normal `reStructuredText table`_.
 
-(New in Docutils 0.3.1)
-
 The "table" directive is used to associate a
 title with a table or specify options, e.g.::
 
@@ -772,24 +762,24 @@ title with a table or specify options, e.g.::
 The following options are recognized:
 
 ``align`` : "left", "center", or "right"
-    The horizontal alignment of the table.
-    (New in Docutils 0.13)
+    The horizontal alignment of the table (new in Docutils 0.13).
+
+``width`` : `length`_ or `percentage`_
+    Sets the width of the table to the specified length or percentage
+    of the line width.  If omitted, the renderer determines the width
+    of the table based on its contents or the column ``widths``.
 
 ``widths`` : "auto", "grid", or a list of integers
-    A comma- or space-separated list of column widths.
-    Default is "grid", the widths of the input columns in characters.
+    A list of relative column widths.
+    The default is the width of the input columns (in characters).
 
-    The value "auto" directs writers to delegate the determination of
-    column widths to the backend (LaTeX, the HTML browser, ...), if possible.
-    The value "grid" overrules a `table_style`_ configuration setting
-    value "colwidths-auto".
+    *"auto"* delegates the determination of column widths to the backend
+    (LaTeX, the HTML browser, ...).
 
-``width`` : `length`_ or `percentage`_
-    Forces the width of the table to the specified length or percentage
-    of the line width.  If omitted, the renderer determines the width
-    of the table based on its contents.
+    *"grid"* restores the default, overriding a `table_style`_ or class
+    value "colwidths-auto".
 
-and the common options `:class:`_ and `:name:`_.
+Plus the common options class_ and name_.
 
 .. _reStructuredText table: restructuredtext.html#tables
 .. _table_style: ../../user/config.html#table-style
@@ -812,14 +802,21 @@ CSV Table
    a potential security holes.  They can be disabled with the
    "file_insertion_enabled_" runtime setting.
 
-(New in Docutils 0.3.4)
-
 The "csv-table" directive is used to create a table from CSV
 (comma-separated values) data.  CSV is a common data format generated
 by spreadsheet applications and commercial databases.  The data may be
 internal (an integral part of the document) or external (a separate
 file).
 
+* Block markup and inline markup within cells is supported.  Line ends
+  are recognized within cells.
+
+* There is no support for checking that the number of columns in each
+  row is the same. The directive automatically adds empty entries at
+  the end of short rows.
+
+  .. Add "strict" option to verify input?
+
 Example::
 
     .. csv-table:: Frozen Delights!
@@ -831,69 +828,46 @@ Example::
        crunchy, now would it?"
        "Gannet Ripple", 1.99, "On a stick!"
 
-Block markup and inline markup within cells is supported.  Line ends
-are recognized within cells.
-
-Working limitations:
-
-* There is no support for checking that the number of columns in each
-  row is the same.  However, this directive supports CSV generators
-  that do not insert "empty" entries at the end of short rows, by
-  automatically adding empty entries.
-
-  .. Add "strict" option to verify input?
-
-.. [#whitespace-delim] Whitespace delimiters are supported only for external
-   CSV files.
-
-.. [#ASCII-char] With Python 2, the valuess for the ``delimiter``,
-   ``quote``, and ``escape`` options must be ASCII characters. (The csv
-   module does not support Unicode and all non-ASCII characters are
-   encoded as multi-byte utf-8 string). This limitation does not exist
-   under Python 3.
-
 The following options are recognized:
 
-``widths`` : integer [, integer...] or "auto"
-    A comma- or space-separated list of relative column widths.  The
-    default is equal-width columns (100%/#columns).
+``align`` : "left", "center", or "right"
+    The horizontal alignment of the table. (New in Docutils 0.13)
 
-    The special value "auto" directs writers to delegate the
-    determination of column widths to the backend (LaTeX, the HTML
-    browser, ...), if possible.
+``delim`` : char | "tab" | "space" [#whitespace-delim]_
+    A one-character string\ [#ASCII-char]_ used to separate fields.
+    Defaults to ``,`` (comma).  May be specified as a Unicode code
+    point; see the unicode_ directive for syntax details.
 
-``width`` : `length`_ or `percentage`_
-    Forces the width of the table to the specified length or percentage
-    of the line width.  If omitted, the renderer determines the width
-    of the table based on its contents.
+``encoding`` : string
+    The text encoding of the external CSV data (file or URL).
+    Defaults to the document's input_encoding_.
 
-``header-rows`` : integer
-    The number of rows of CSV data to use in the table header.
-    Defaults to 0.
+``escape`` : char
+    A one-character\ [#ASCII-char]_ string used to escape the
+    delimiter or quote characters.  May be specified as a Unicode
+    code point; see the unicode_ directive for syntax details.  Used
+    when the delimiter is used in an unquoted field, or when quote
+    characters are used within a field.  The default is to double-up
+    the character, e.g. "He said, ""Hi!"""
 
-``stub-columns`` : integer
-    The number of table columns to use as stubs (row titles, on the
-    left).  Defaults to 0.
+    .. Add another possible value, "double", to explicitly indicate
+       the default case?
+
+``file`` : string (newlines removed)
+    The local filesystem path to a CSV data file.
 
 ``header`` : CSV data
     Supplemental data for the table header, added independently of and
     before any ``header-rows`` from the main CSV data.  Must use the
     same CSV format as the main CSV data.
 
-``file`` : string (newlines removed)
-    The local filesystem path to a CSV data file.
-
-``url`` : string (whitespace removed)
-    An Internet URL reference to a CSV data file.
-
-``encoding`` : string
-    The text encoding of the external CSV data (file or URL).
-    Defaults to the document's encoding (if specified).
+``header-rows`` : integer
+    The number of rows of CSV data to use in the table header.
+    Defaults to 0.
 
-``delim`` : char | "tab" | "space" [#whitespace-delim]_
-    A one-character string\ [#ASCII-char]_ used to separate fields.
-    Defaults to ``,`` (comma).  May be specified as a Unicode code
-    point; see the unicode_ directive for syntax details.
+``keepspace`` : flag (empty)
+    Treat whitespace immediately following the delimiter as
+    significant.  The default is to ignore such whitespace.
 
 ``quote`` : char
     A one-character string\ [#ASCII-char]_ used to quote elements
@@ -902,26 +876,35 @@ The following options are recognized:
     Unicode code point; see the unicode_ directive for syntax
     details.
 
-``keepspace`` : flag (empty)
-    Treat whitespace immediately following the delimiter as
-    significant.  The default is to ignore such whitespace.
+``stub-columns`` : integer
+    The number of table columns to use as stubs (row titles, on the
+    left).  Defaults to 0.
 
-``escape`` : char
-    A one-character\ [#ASCII-char]_ string used to escape the
-    delimiter or quote characters.  May be specified as a Unicode
-    code point; see the unicode_ directive for syntax details.  Used
-    when the delimiter is used in an unquoted field, or when quote
-    characters are used within a field.  The default is to double-up
-    the character, e.g. "He said, ""Hi!"""
+``url`` : string (whitespace removed)
+    An Internet URL reference to a CSV data file.
 
-    .. Add another possible value, "double", to explicitly indicate
-       the default case?
+``widths`` : integer [integer...] or "auto"
+    A list of relative column widths.
+    The default is equal-width columns (100%/#columns).
 
-``align`` : "left", "center", or "right"
-    The horizontal alignment of the table.
-    (New in Docutils 0.13)
+    "auto" delegates the determination of column widths to the backend
+    (LaTeX, the HTML browser, ...).
 
-and the common options `:class:`_ and `:name:`_.
+``width`` : `length`_ or `percentage`_
+    Sets the width of the table to the specified length or percentage
+    of the line width.  If omitted, the renderer determines the width
+    of the table based on its contents or the column ``widths``.
+
+and the common options class_ and name_.
+
+.. [#whitespace-delim] Whitespace delimiters are supported only for external
+   CSV files.
+
+.. [#ASCII-char] With Python 2, the valuess for the ``delimiter``,
+   ``quote``, and ``escape`` options must be ASCII characters. (The csv
+   module does not support Unicode and all non-ASCII characters are
+   encoded as multi-byte utf-8 string). This limitation does not exist
+   under Python 3.
 
 
 List Table
@@ -933,8 +916,8 @@ List Table
 :Directive Options: Possible (see below).
 :Directive Content: A uniform two-level bullet list.
 
-(New in Docutils 0.3.8.  This is an initial implementation; `further
-ideas`__ may be implemented in the future.)
+(This is an initial implementation; `further ideas`__ may be implemented
+in the future.)
 
 __ ../../dev/rst/alternatives.html#list-driven-tables
 
@@ -965,17 +948,16 @@ Example::
 The following options are recognized:
 
 ``widths`` : integer [integer...] or "auto"
-    A comma- or space-separated list of relative column widths.  The
-    default is equal-width columns (100%/#columns).
+    A list of relative column widths.
+    The default is equal-width columns (100%/#columns).
 
-    The special value "auto" may be used by writers to decide
-    whether to delegate the determination of column widths to the backend
+    "auto" delegates the determination of column widths to the backend
     (LaTeX, the HTML browser, ...).
 
-``width`` : `length`_ or `percentage`_ of the current line width
-    Forces the width of the table to the specified length or percentage
+``width`` : `length`_ or `percentage`_
+    Sets the width of the table to the specified length or percentage
     of the line width.  If omitted, the renderer determines the width
-    of the table based on its contents.
+    of the table based on its contents or the column ``widths``.
 
 ``header-rows`` : integer
     The number of rows of list data to use in the table header.
@@ -989,7 +971,7 @@ The following options are recognized:
     The horizontal alignment of the table.
     (New in Docutils 0.13)
 
-and the common options `:class:`_ and `:name:`_.
+and the common options class_ and name_.
 
 
 ----------------
@@ -1004,7 +986,7 @@ Table of Contents
 :Directive Type: "contents"
 :Doctree Elements: pending_, topic_
 :Directive Arguments: One, optional: title.
-:Directive Options: Possible.
+:Directive Options: Possible (see below).
 :Directive Content: None.
 
 The "contents" directive generates a table of contents (TOC) in a
@@ -1067,7 +1049,7 @@ Automatic Section Numbering
 :Directive Type: "sectnum" or "section-numbering" (synonyms)
 :Doctree Elements: pending_, generated_
 :Directive Arguments: None.
-:Directive Options: Possible.
+:Directive Options: Possible (see below).
 :Directive Content: None.
 :Configuration Setting: sectnum_xform_
 
@@ -1126,8 +1108,6 @@ Document Header & Footer
 :Directive Options: None.
 :Directive Content: Interpreted as body elements.
 
-(New in Docutils 0.3.8)
-
 The "header" and "footer" directives create document decorations,
 useful for page navigation, notes, time/datestamp, etc.  For example::
 
@@ -1174,8 +1154,8 @@ Target Footnotes
 :Directive Type: "target-notes"
 :Doctree Elements: pending_, footnote_, footnote_reference_
 :Directive Arguments: None.
-:Directive Options: `:class:`_, `:name:`_
-:Directive Options: Possible.
+:Directive Options: class_, name_
+:Directive Options: Possible (see below).
 :Directive Content: None.
 
 The "target-notes" directive creates a footnote for each external
@@ -1277,7 +1257,7 @@ Unicode Character Codes
 :Doctree Element: Text
 :Directive Arguments: One or more, required (Unicode character codes,
                       optional text, and comments).
-:Directive Options: Possible.
+:Directive Options: Possible (see below).
 :Directive Content: None.
 
 The "unicode" directive converts Unicode character codes (numerical
@@ -1374,7 +1354,7 @@ Including an External Document Fragment
 :Doctree Elements: Depend on data being included
                    (literal_block_ with ``code`` or ``literal`` option).
 :Directive Arguments: One, required (path to the file to include).
-:Directive Options: Possible.
+:Directive Options: Possible (see below).
 :Directive Content: None.
 :Configuration Setting: file_insertion_enabled_
 
@@ -1450,13 +1430,11 @@ The following options are recognized:
 ``code`` : [string] (formal language)
     The argument and the included content are passed to
     the code_ directive (useful for program listings).
-    (New in Docutils 0.9)
 
 ``number-lines`` : [integer] (start line number)
     Precede every code line with a line number.
     The optional argument is the number of the first line (defaut 1).
     Works only with ``code`` or ``literal``.
-    (New in Docutils 0.9)
 
 ``encoding`` : string
     The text encoding of the external data file.  Defaults to the
@@ -1471,8 +1449,8 @@ The following options are recognized:
 
     .. _tab_width: ../../user/config.html#tab-width
 
-With ``code`` or ``literal`` the common options `:class:`_ and
-`:name:`_ are recognized as well.
+With ``code`` or ``literal`` the common options class_ and
+name_ are recognized as well.
 
 Combining ``start/end-line`` and ``start-after/end-before`` is possible. The
 text markers will be searched in the specified lines (further limiting the
@@ -1556,7 +1534,7 @@ The following options are recognized:
     The text encoding of the external raw data (file or URL).
     Defaults to the document's encoding (if specified).
 
-and the common option `:class:`_.
+and the common option class_.
 
 
 .. _"raw" role: roles.html#raw
@@ -1725,8 +1703,6 @@ Custom Interpreted Text Roles
 :Directive Options: Possible (depends on base role).
 :Directive Content: depends on base role.
 
-(New in Docutils 0.3.2)
-
 The "role" directive dynamically creates a custom `interpreted text
 role`_ and registers it with the parser.  This means that after
 declaring a role like this::
@@ -1822,8 +1798,6 @@ Setting the Default Interpreted Text Role
 :Directive Options: None.
 :Directive Content: None.
 
-(New in Docutils 0.3.10)
-
 The "default-role" directive sets the default interpreted text role,
 the role that is used for interpreted text without an explicit role.
 For example, after setting the default role like this::
@@ -1971,12 +1945,15 @@ Most of the directives that generate doctree elements support the following
 options:
 
 .. _class-option:
+.. _class:
 
-_`:class:` : text (space separated list of `class names`_)
+``class`` : text (space separated list of `class names`_)
     Set a `"classes"`_ attribute value on the doctree element generated by
     the directive. See also the class_ directive.
 
-_`:name:` : text
+    .. _name:
+
+``name`` : text
     Add `text` to the `"names"`_ attribute of the doctree element generated
     by the directive. This allows `hyperlink references`_ to the element
     using `text` as `reference name`_.
@@ -1993,8 +1970,6 @@ _`:name:` : text
 
       .. image:: bild.png
 
-    (New in Docutils 0.8.)
-
 
 .. _reference name:
 .. _reference names: restructuredtext.html#reference-names
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
index 3e05fbd5d..e42bca89d 100644
--- a/docutils/docs/user/latex.txt
+++ b/docutils/docs/user/latex.txt
@@ -237,7 +237,7 @@ Example 2:
   or ::
 
     \makeatletter
-    \@namedef{DUadmonitionadmonition-test}{…}
+    \@namedef{DUCLASSadmonition-test}{…}
     \makeatother
 
 * Elements can have multiple class arguments. In contrast to HTML/CSS, the
@@ -252,11 +252,9 @@ Example 2:
   * The table element recognizes some special class values. See section
     table_.
 
-  * For "historical reasons", the special macros ``\DUadmonition`` and
-    ``\DUtitle`` are written with a comma separated list of class values as
-    optional argument if the legacy-class-functions_ setting is True.
-
-    See the sections on admonitions_ and titles_ for customization examples.
+  * If the legacy-class-functions_ setting is True, the special macros
+    ``\DUadmonition`` and ``\DUtitle`` are written with a comma separated
+    list of class values as optional argument.
 
 .. _"classes" attribute: ../ref/doctree.html#classes
 .. _legacy-class-functions: config.html#legacy-class-functions
@@ -436,62 +434,43 @@ ordinary body element can.
 
 __ ../ref/rst/directives.html#admonitions
 
-Command:
-  ``\DUadmonition`` (with legacy-class-functions_)
-
 Environment:
-  ``DUadmonition`` (with new-class-functions_)
+  ``DUadmonition``
+
+  (Command ``\DUadmonition`` with legacy-class-functions_.)
 
 Default:
   Typeset in a frame (90 % of text width).
 
-.. _new-class-functions: legacy-class-functions_
-
 The admonition title is typeset with the ``\DUtitle`` command (see `titles`_).
 
 Example 1:
   A lighter layout without the frame::
 
-    \newcommand{\DUadmonition}[2][class-arg]{%
-      % try \DUadmonition#1{#2}:
-      \ifcsname DUadmonition#1\endcsname%
-        \csname DUadmonition#1\endcsname{#2}%
-      \else
-        \begin{quote}
-          #2
-        \end{quote}
-      \fi
-    }
-
-  rsp with new-class-functions_::
-
     \newenvironment{DUadmonition}%
       {\begin{quote}}
       {\end{quote}}
 
-
 Example 2:
-  Print admonitions in the margin::
+  Print all admonitions in the margin::
 
-    \newcommand{\DUadmonition}[2][class-arg]{\marginpar{#2}}
-
-  Make sure there is enough space to fit the note.
-  See also the marginnote_ package.
+    \usepackage{environ}
+    \NewEnviron{DUadmonition}{\marginpar{\BODY}}
 
 Example 3:
   Use the ``.. note::`` admonition for a margin note::
 
-    \newcommand{\DUadmonitionnote}[1]{\marginpar{#1}}
-
-  rsp with new-class-functions_ we re-define the environment in the
-  class-wrapper::
-
+    \usepackage{environ}
     \newcommand{\DUCLASSnote}{%
-      \renewcommand{\DUadmonition}{\marginpar}
-
-  Make sure there is enough space to fit the note.
+      \RenewEnviron{DUadmonition}{\marginpar{\BODY}}%
+      \renewcommand{\DUtitle}[1]{}% suppress title ("Note")
+    }
 
+.. caution:: Make sure there is enough space in the margin.
+   ``\marginpar`` fails in some places or with some content. See also the
+   environ_ and marginnote_ packages.
 
+.. _environ: http://ctan.org/pkg/environ
 .. _marginnote: http://ctan.org/pkg/marginnote
 
 
@@ -1666,25 +1645,31 @@ Example:
 titles
 ------
 
-The titles of admonitions_, sidebar_, and `topic element`_ are defined with
-the ``\DUtitle`` command that also takes a "class" argument.
+The titles of admonitions_, sidebar_, and `topic element`_ use
+the ``\DUtitle`` command.
 
 Example 1:
   a centered and somewhat larger title for topcis::
 
-     \newcommand*{\DUtitletopic}[1]{\subsection*{\centering #1}
+     \newcommand*{\DUCLASStopic}{
+       \renewcommand*{\DUtitle}[1]{\subsection*{\centering #1}
+     }
 
 Example 2:
   a right-pointing hand as title for the "attention" directive::
 
     \usepackage{pifont}
-    \newcommand{\DUtitleattention}[1]{\ding{43}}
+    \newcommand*{\DUCLASSattention}{
+      \renewcommand*{\DUtitle}[1]{\ding{43}}
+    }
 
   The title argument is "swallowed" by the command.
   To have both, hand and title use::
 
     \usepackage{pifont}
-    \newcommand{\DUtitleattention}[1]{\ding{43} #1}
+    \newcommand*{\DUCLASSattention}{
+      \newcommand*{\DUtitle}[1]{\ding{43} #1}
+    }
 
 
 table of contents