allow topics within sidebars; no topics within body elements

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

3 files changed, 13 insertions, 8 deletions

diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index 912789239..b5458017b 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -3550,7 +3550,7 @@ Details
 
 :Children:
     ``sidebar`` elements begin with a title_ and an optional subtitle_
-    and contain `body elements`_.
+    and contain `body elements`_ and topic_ elements.
 
 :Analogues:
     ``sidebar`` is analogous to the DocBook "sidebar" element.
@@ -3568,7 +3568,7 @@ Content Model
 .. parsed-literal::
 
     (title_, subtitle_?,
-     (`%body.elements;`_)+)
+     (`%body.elements;`_ | topic_)+)
 
 :Attributes:
     The ``sidebar`` element contains only the `common attributes`_:
@@ -3985,7 +3985,7 @@ The ``topic`` element is a nonrecursive section_-like construct which
 may occur at the top level of a section_ wherever a body element
 (list, table, etc.) is allowed.  In other words, ``topic`` elements
 cannot nest inside body elements, so you can't have a ``topic`` inside
-a ``table`` or a ``list``, or inside another ``topic`` (or sidebar_).
+a ``table`` or a ``list``, or inside another ``topic``.
 
 
 Details
@@ -3995,7 +3995,8 @@ Details
     `Structural Elements`_
 
 :Parents:
-    The following elements may contain ``topic``: document_, section_
+    The following elements may contain ``topic``: document_, section_,
+    sidebar_
 
 :Children:
     ``topic`` elements begin with a title_ and may contain `body
diff --git a/docutils/docs/ref/docutils.dtd b/docutils/docs/ref/docutils.dtd
index 0c0a55003..357703f04 100644
--- a/docutils/docs/ref/docutils.dtd
+++ b/docutils/docs/ref/docutils.dtd
@@ -279,7 +279,7 @@ Eventual replacement for docinfo? -->
 <!ELEMENT topic (title?, (%body.elements;)+)>
 <!ATTLIST topic %basic.atts;>
 
-<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)>
+<!ELEMENT sidebar (title, subtitle?, (%body.elements; | topic)+)>
 <!ATTLIST sidebar %basic.atts;>
 
 <!ELEMENT transition EMPTY>
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index 5e07ba449..859d32487 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -331,7 +331,7 @@ A topic is like a block quote with a title, or a self-contained
 section with no subsections.  Use the "topic" directive to indicate a
 self-contained idea that is separate from the flow of the document.
 Topics may occur anywhere a section or transition may occur.  Body
-elements (including topics) may not contain nested topics.
+elements and topics may not contain nested topics.
 
 The directive's sole argument is interpreted as the topic title; the
 next line must be blank.  All subsequent lines make up the topic body,
@@ -854,8 +854,12 @@ Table of Contents
 :Directive Options: Possible.
 :Directive Content: None.
 
-The "contents" directive generates a table of contents (TOC).  Here's
-the directive in its simplest form::
+The "contents" directive generates a table of contents (TOC) in a
+topic_.  Topics, and therefore tables of contents, may occur anywhere
+a section or transition may occur.  Body elements and topics may not
+contain tables of contents.
+
+Here's the directive in its simplest form::
 
     .. contents::