SF.net SVN: docutils:[9663 ] trunk/docutils/docs/ref

Revision: 9663
          http://sourceforge.net/p/docutils/code/9663
Author:   milde
Date:     2024-04-27 20:58:58 +0000 (Sat, 27 Apr 2024)
Log Message:
-----------
Document the `<compound>` and `<container>` elements.

Close two gaps in the "Docutils Document Tree" documentation.

Modified Paths:
--------------
    trunk/docutils/docs/ref/doctree.txt
    trunk/docutils/docs/ref/rst/directives.txt

Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt	2024-04-27 17:52:53 UTC (rev 9662)
+++ trunk/docutils/docs/ref/doctree.txt	2024-04-27 20:58:58 UTC (rev 9663)
@@ -891,9 +891,66 @@
 <compound>
 ==========
 
-`To be completed`_.
+The <compound> element combines multiple `body elements`_
+to a single logical paragraph.
 
+Details
+-------
 
+:Category:   `Body Elements`_
+
+:Analogues:  The <compound> element has no direct analogues in common DTDs.
+             In HTML, it can be emulated with <div> and CSS styling. [#]_
+
+:Processing: Typically rendered as multiple distinct text blocks, with
+             the possibility of variations to emphasize their logical
+             unity (cf. the `"compound" directive`_).
+
+:Parents:    All elements employing the `%body.elements`_
+             or `%structure.model`_ parameter entities in
+             their content models may contain <compound>.
+
+:Children:   <compound> elements contain one or more `body elements`_.
+
+:Attributes: The <compound> element contains only the `common attributes`_.
+
+:Parameter Entities: The `%body.elements`_ parameter entity directly
+             includes <compound>.  The `%structure.model`_
+             parameter entity indirectly includes <compound>.
+
+
+.. [#] The Docutils counterpart to HTML’s <div> is the `\<container>`_ element.
+
+Examples
+--------
+
+The reStructuredText `"compound" directive`_ creates a
+<compound> element::
+
+    .. compound::
+
+       The 'rm' command is very dangerous.  If you are logged
+       in as root and enter ::
+
+           cd /
+           rm -rf *
+
+       you will erase the entire contents of your file system.
+
+
+Pseudo-XML_ fragment from simple parsing::
+
+    <compound>
+        <paragraph>
+            The 'rm' command is very dangerous.  If you are logged
+            in as root and enter
+        <literal_block xml:space="preserve">
+            cd /
+            rm -rf *
+        <paragraph>
+            you will erase the entire contents of your file system.
+
+
 <contact>
 =========
 
@@ -944,9 +1001,60 @@
 <container>
 ===========
 
-`To be completed`_.
+The <container> element groups multiple `body elements`_ for user- or
+application-specific purposes.
 
+Details
+-------
 
+:Category:   `Body Elements`_
+
+:Analogues:  The <container> element is analogous to the HTML <div>
+             element or the SVG <g> element.
+
+:Processing: A possible use case is a custom style (e.g. a frame or
+             background colour) based on the value of the classes_
+             attribute.
+
+:Parents:    All elements employing the `%body.elements`_
+             or `%structure.model`_ parameter entities in
+             their content models may contain <container>.
+
+:Children:   <container> elements contain one or more `body elements`_.
+
+:Attributes: The <container> element contains only the `common attributes`_.
+
+:Parameter Entities:
+             The `%body.elements`_ parameter entity directly
+             includes <container>.  The `%structure.model`_
+             parameter entity indirectly includes <container>.
+
+Examples
+--------
+
+The reStructuredText `"container" directive`_ creates a
+<container> element::
+
+    .. container:: green boxed-equation
+
+       .. math:: -1^2 = 1
+
+       This paragraph is in the box, too.
+
+Pseudo-XML_ fragment from simple parsing::
+
+    <container classes="framed square">
+        <math_block xml:space="preserve">
+            -1^2 = 1
+        <paragraph>
+            This paragraph is in the box, too.
+
+The HTML output can be placed in a common box with the custom CSS rule ::
+
+    div.framed {border: solid;
+             padding: 1em;}
+
+
 <copyright>
 ===========
 
@@ -4828,6 +4936,7 @@
 .. _class option:               rst/directives.html#class-option
 .. _"code" directive:           rst/directives.html#code
 .. _"compound" directive:       rst/directives.html#compound-paragraph
+.. _"container" directive:      rst/directives.html#container
 .. _"contents" directive:
 .. _table of contents:          rst/directives.html#table-of-contents
 .. _"csv-table":                rst/directives.html#csv-table

Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt	2024-04-27 17:52:53 UTC (rev 9662)
+++ trunk/docutils/docs/ref/rst/directives.txt	2024-04-27 20:58:58 UTC (rev 9663)
@@ -805,8 +805,8 @@
 :Directive Content: Interpreted as body elements.
 
 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
+elements) with a generic block-level "container" element.  
+Combined with the optional argument, this is an
 extension mechanism for users & applications.  For example::
 
     .. container:: custom

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins