added "header" & "footer" directives, tests, docs, support, and some tweaks

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

3 files changed, 86 insertions, 33 deletions

diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index dc19bdff3..912789239 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -62,7 +62,7 @@ one-to-many relationships; sections may contain (sub)sections, tables
 contain further body elements, etc. ::
 
   +--------------------------------------------------------------------+
-  | document  [may begin with a title, subtitle, docinfo, decoration]  |
+  | document  [may begin with a title, subtitle, decoration, docinfo]  |
   |                             +--------------------------------------+
   |                             | sections  [each begins with a title] |
   +-----------------------------+-------------------------+------------+
@@ -112,7 +112,7 @@ Structural subelements are child elements of structural elements.
 Simple structuctural subelements (title_, subtitle_) contain text
 data; the others are compound and do not directly contain text data.
 
-Category members: title_, subtitle_, docinfo_, decoration_,
+Category members: title_, subtitle_, decoration_, docinfo_,
 transition_
 
 
@@ -146,7 +146,7 @@ body elements.  There are two subcategories of body elements: simple
 and compound.
 
 Category members: admonition_, attention_, block_quote_, bullet_list_,
-caution_, citation_, comment_, danger_, definition_list_,
+caution_, citation_, comment_, compound_, danger_, definition_list_,
 doctest_block_, enumerated_list_, error_, field_list_, figure_,
 footnote_, hint_, image_, important_, line_block_, literal_block_,
 note_, option_list_, paragraph_, pending_, raw_, rubric_,
@@ -173,9 +173,10 @@ Compound body elements contain local substructure (body subelements)
 and further body elements.  They do not directly contain text data.
 
 Category members: admonition_, attention_, block_quote_, bullet_list_,
-caution_, citation_, danger_, definition_list_, enumerated_list_,
-error_, field_list_, figure_, footnote_, hint_, important_, note_,
-option_list_, system_message_, table_, tip_, warning_
+caution_, citation_, compound_, danger_, definition_list_,
+enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
+important_, note_, option_list_, system_message_, table_, tip_,
+warning_
 
 
 Body Subelements
@@ -959,6 +960,12 @@ Pseudo-XML_ fragment from simple parsing::
 `To be completed`_.
 
 
+``compound``
+============
+
+`To be completed`_.
+
+
 ``contact``
 ===========
 
@@ -1251,6 +1258,7 @@ Details
 :Processing:
     See the individual `decorative elements`_.
 
+
 Content Model
 -------------
 
@@ -1758,20 +1766,21 @@ Content Model
 
 .. parsed-literal::
 
-    ((title_,
-      subtitle_?)?,
-     docinfo_?,
-     decoration_?,
-     `%structure.model;`_)
+    ( (title_, subtitle_?)?,
+      decoration_?,
+      (docinfo_, transition_?)?,
+      `%structure.model;`_ )
 
 Depending on the source of the data and the stage of processing, the
 "document" may not initially contain a "title".  A document title is
 not directly representable in reStructuredText_.  Instead, a lone
 top-level section may have its title promoted to become the document
 title_, and similarly for a lone second-level (sub)section's title to
-become the document subtitle_.  The "docinfo_" may be transformed from
-an initial field_list_, and "decoration_" is usually constructed
-programmatically.
+become the document subtitle_.
+
+The contents of "decoration_" may be specified in a document,
+constructed programmatically, or both.  The "docinfo_" may be
+transformed from an initial field_list_.
 
 See the `%structure.model;`_ parameter entity for details of the body
 of a ``document``.
@@ -2314,7 +2323,7 @@ section numbers inserted by the "sectnum" directive.
 
 The ``header`` element is a container element whose contents are meant
 to appear at the top of a web page, or at the top of every printed
-page.  Docutils does not yet make use of the ``header`` element.
+page.
 
 
 Details
@@ -2350,7 +2359,17 @@ Content Model
 Examples
 --------
 
-None.
+reStructuredText source fragment::
+
+    .. header:: This space for rent.
+
+Pseudo-XML_ fragment from simple parsing::
+
+    <document>
+        <decoration>
+            <header>
+                <paragraph>
+                    This space for rent.
 
 
 ``hint``
@@ -4611,14 +4630,14 @@ Entity definition:
 
 .. parsed-literal::
 
-    paragraph_ | literal_block_ | doctest_block_ | line_block_
-    | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_
-    | rubric_
+    paragraph_ | compound_ | literal_block_ | doctest_block_
+    | line_block_ | block_quote_
+    | table_ | figure_ | image_ | footnote_ | citation_ | rubric_
     | bullet_list_ | enumerated_list_ | definition_list_ | field_list_
     | option_list_
-    | attention_ | caution_ | danger_ | error_ | hint_ | important_
-    | note_ | tip_ | warning_ | admonition_
-    | target_ | substitution_definition_ | comment_ | pending_
+    | attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_
+    | tip_ | warning_ | admonition_
+    | reference_ | target_ | substitution_definition_ | comment_ | pending_
     | system_message_ | raw_
     %additional.body.elements;
 
@@ -4627,10 +4646,10 @@ wrapper DTDs to extend ``%body.elements;``.
 
 The ``%body.elements;`` parameter entity is directly employed in the
 content models of the following elements: admonition_, attention_,
-block_quote_, caution_, citation_, danger_, definition_, description_,
-entry_, error_, field_body_, footer_, footnote_, header_, hint_,
-important_, legend_, list_item_, note_, sidebar_, system_message_,
-tip_, topic_, warning_
+block_quote_, caution_, citation_, compound_, danger_, definition_,
+description_, entry_, error_, field_body_, footer_, footnote_,
+header_, hint_, important_, legend_, list_item_, note_, sidebar_,
+system_message_, tip_, topic_, warning_
 
 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
 indirectly employed in the content models of the document_ and
diff --git a/docutils/docs/ref/docutils.dtd b/docutils/docs/ref/docutils.dtd
index d9a76ce2e..0c0a55003 100644
--- a/docutils/docs/ref/docutils.dtd
+++ b/docutils/docs/ref/docutils.dtd
@@ -183,9 +183,10 @@ http://www.oasis-open.org/html/tm9901.htm).
 
 <!-- Optional elements may be generated by internal processing. -->
 <!ELEMENT document
-    ((title, subtitle?)?,
-    ((docinfo, decoration?, transition?) | decoration?),
-    %structure.model;)>
+    ( (title, subtitle?)?,
+      decoration?,
+      (docinfo, transition?)?,
+      %structure.model; )>
 <!ATTLIST document %basic.atts;>
 
 <!--
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index d0f6cd453..5af9987e7 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -464,11 +464,10 @@ For example, all the element names in this content model are links::
 
     .. parsed-literal::
 
-        ((title_,
-          subtitle_?)?,
-         docinfo_?,
+       ( (title_, subtitle_?)?,
          decoration_?,
-         `%structure.model;`_)
+         (docinfo_, transition_?)?,
+         `%structure.model;`_ )
 
 The following option is recognized:
 
@@ -958,6 +957,40 @@ The following options are recognized:
     default is 1.
 
 
+.. _header:
+.. _footer:
+
+Document Header & Footer
+========================
+
+:Directive Types: "header" and "footer"
+:Doctree Elements: decoration, header, footer
+:Directive Arguments: None.
+: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::
+
+    .. header:: This space for rent.
+
+This will add a paragraph to the document header, which will appear at
+the top of the generated web page or at the top of every printed page.
+
+These directives may be used multiple times, cumulatively.  There is
+currently support for only one header and footer.
+
+In addition to the use of these directives to populate header and
+footer content, content may also be added automatically by the
+processing system.  For example, if certain runtime settings are
+enabled, the document footer is populated with processing information
+such as a datestamp, a link to `the Docutils website`_, etc.
+
+.. _the Docutils website: http://docutils.sourceforge.net
+
+
 ------------
  References
 ------------