Creating a branch. The new branch will reflect the way to use the xsl

stylesheets with the pyton interface. I am now going to put a simpler
version of the XSL stylesheets in the trunk.


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

4 files changed, 6593 insertions, 0 deletions

diff --git a/sandbox/paultremblay/python_interface/docs/rst/attribute_sets.rst b/sandbox/paultremblay/python_interface/docs/rst/attribute_sets.rst
new file mode 100644
index 000000000..63c288233
--- /dev/null
+++ b/sandbox/paultremblay/python_interface/docs/rst/attribute_sets.rst
@@ -0,0 +1,3698 @@
+####################
+XSL-FO Documentation
+####################
+
+^^^^^^^^^^^^^^
+Attribute Sets
+^^^^^^^^^^^^^^
+
+.. contents:: Table of Contents
+
+Root Attribute Sets
+===================
+
+Attribute sets root elements. Use these attribute sets to format
+the defaults in a document, such as font, font-size, or
+line-height.
+
+default-page-sequence
+---------------------
+
+:fo: fo:page-sequence
+
+:docutils: document
+
+:defaults:
+
+Formats the properties for the all of the document.
+
+front-page-sequence
+-------------------
+
+:fo: fo:page-sequence
+
+:docutils: document
+
+:inherits: default-page-sequence
+
+:defaults:
+
+     force-page-count: no-force
+
+Formats the properties for the complete run of pages, in this
+case, the front matter.
+
+toc-page-sequence
+-----------------
+
+:fo: fo:page-sequence
+
+:docutils: document
+
+:inherits: default-page-sequence
+
+:defaults:
+
+     format: i
+
+     initial-page-number: 1
+
+     force-page-count: no-force
+
+Formats the properties for the complete run of pages, in this
+case, the toc and any pages associated with it.
+
+body-page-sequence
+------------------
+
+:fo: fo:page-sequence
+
+:docutils: document
+
+:inherits: default-page-sequence
+
+:defaults:
+
+     format: 1
+
+     initial-page-number: 1
+
+Formats the properties for the complete run of pages, in this
+case, the body.
+
+default-flow
+------------
+
+:fo: fo:flow
+
+:docutils: document
+
+:defaults:
+
+Sets up the default attributes for the front-flow, toc-flow, and
+body-flow
+
+front-flow
+----------
+
+:fo: fo:flow
+
+:docutils: document
+
+:inherits: default-flow
+
+:defaults:
+
+Formats the properties of the body in the front sequence of
+pages. Since the front sequence has no headers and footers, that
+means everything.
+
+toc-flow
+--------
+
+:fo: fo:flow
+
+:docutils: document
+
+:inherits: default-flow
+
+:defaults:
+
+Formats the properties of the body in the toc sequence of pages,
+which means everything except headers and footers.
+
+body-flow
+---------
+
+:fo: fo:flow
+
+:docutils: document
+
+:inherits: default-flow
+
+:defaults:
+
+Formats the properties of the body in the body sequence of pages,
+which means everything except headers and footers.
+
+footnote-separator-flow
+-----------------------
+
+:fo: fo:flow
+
+:docutils: footnote
+
+:defaults:
+
+Formats the flow of the footnote.
+
+footnote-separator-block
+------------------------
+
+:fo: fo:block
+
+:docutils: footnote
+
+:defaults:
+
+Formats the block (with the leader) that separates the footnotes
+from the rest of the page.
+
+Page Attribute Sets
+===================
+
+Attribute sets for page. These attributes control the formatting
+of the actual pages: the paper size and margins.
+
+paper-size-simple-page-master
+-----------------------------
+
+:fo: None
+
+:docutils: /
+
+:defaults:
+
+     page-width: 8.5in
+
+     page-height: 11in
+
+Sets up the defaults for the paper size, used in other attribute
+sets.
+
+default-simple-page-master
+--------------------------
+
+:fo: None
+
+:docutils: /
+
+:defaults:
+
+     margin-left: 1.0in
+
+     margin-right: 1.0in
+
+     margin-top: 1.0in
+
+     margin-bottom: 1.0in
+
+Sets up the defaults for the margins of the fo:body-region for
+all the pages.
+
+Simple Page Master Sets
+-----------------------
+
+:fo: fo:simple-page-master
+
+:docutils: /
+
+:inherits: paper-size, default-page-setup
+
+The following attribute sets are identical:
+
+- simple-page-master
+
+- first-simple-page-master
+
+- body-simpe-page-master
+
+- odd-simple-page-master
+
+- even-simple-page-master
+
+- toc-simple-page-master
+
+- toc-first-simple-page-master
+
+- toc-body-simple-page-master
+
+- toc-odd-simple-page-master
+
+- toc-even-simple-page-master
+
+- front-simple-page-master
+
+- front-first-simple-page-master
+
+- front-body-simple-page-master
+
+- front-odd-simple-page-master
+
+- front-even-simple-page-master
+
+These attriute sets format the margins of the
+fo:simple-page-master. By default, they inherit the
+``'paper-size-simple-page-master'`` and
+``'default-simple-page-master'`` attriute-sets, meaning each page
+will have identical size and margins, a satisfactory setup for
+many documents. However, the sizes and margins can be modified by
+page type, if desired.
+
+header-region-before
+--------------------
+
+:fo: fo:region-before
+
+:docutils: decoration/header
+
+:defaults:
+
+     extent: .75in
+
+The extent attribute specifies the header and footer height.
+
+footer-region-after
+-------------------
+
+:fo: fo:region-after
+
+:docutils: decoration/footer
+
+:defaults:
+
+     extent: .75in
+
+The extent attribute specifies the header and footer height.
+
+Bibliograhic Fields Attribute Sets
+==================================
+
+Attribute sets for the bibliograhic fields. These attributes
+control the formatting of bibliographic fields.
+
+bibliographic-fields-list-block
+-------------------------------
+
+:fo: list-block
+
+:docutils: docinfo
+
+:defaults:
+
+     start-indent: 0mm
+
+     provisional-distance-between-starts: 30mm
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+Formats the bibliographic fields as a list. Since this element
+contains all the other list elements, it can be used to set
+values such as the font, background color, line-height, etc, for
+the entire list, as well as the space after and before.
+
+"The provisional-distance-between-starts property of the
+list-block specifies the distance bewteen the start of the label
+(the bullet, for example) and the actual start of the list
+content" (Pawson, 100). In this case, that means the distance
+between the label (such as "Version", and the labels' value (such
+as "1.2").
+
+bibliographic-fields-list-item
+------------------------------
+
+:fo: fo:list-item
+
+:docutils:
+         docinfo/author|docinfo/authors|docinfo/organization|etc.
+
+:defaults:
+
+     space-before: 12pt
+
+For each item (author, authors, organization, contact, address,
+version, date, copyright, custom field) in the bibliograhic
+fields. Use the 'space-after' attribute to control the spacing
+between each item.
+
+bibliographic-fields-first-list-item
+------------------------------------
+
+:fo: fo:list-item
+
+:docutils:
+         docinfo/author|docinfo/authors|docinfo/organization|etc.
+
+:inherits: bibliographic-fields-list-item
+
+:defaults:
+
+     space-before: 0pt
+
+Same as above, but sets the space before to 0pt.
+
+bibliographic-fields-list-item-label
+------------------------------------
+
+:fo: fo:list-item-label
+
+:docutils:
+         docinfo/author|docinfo/authors|docinfo/organization|etc.
+
+:defaults:
+
+     end-indent: label-end()
+
+The default attribute end-indent = "label-end()" ensures that the
+label aligns properly.
+
+bibliographic-fields-item-body
+------------------------------
+
+:fo: fo:list-item-body
+
+:docutils:
+         docinfo/author|docinfo/authors|docinfo/organization|etc.
+
+:defaults:
+
+     start-indent: body-start()
+
+The default of start-indent = "body-start()" ensures the correct
+alignment of the labels.
+
+bibliographic-fields-item-label-block
+-------------------------------------
+
+:fo: fo:block
+
+:docutils:
+         docinfo/author|docinfo/authors|docinfo/organization|etc.
+
+:defaults:
+
+     font-weight: bold
+
+Formats the block that wraps the the name of the field (such as
+Author, Version, etc).
+
+bibliographic-fields-block
+--------------------------
+
+:fo: fo:block
+
+:docutils:
+         docinfo/author|docinfo/authors|docinfo/organization|etc.
+
+:defaults:
+
+Formats the blocks (docutilis paragraphs) of the value of the
+field. Use the 'space-after' attribute to control the spacing
+between a multi-paragraph description.
+
+bibliographic-first-fields-block
+--------------------------------
+
+:fo: fo:block
+
+:docutils:
+         docinfo/author|docinfo/authors|docinfo/organization|etc.
+
+:inherits: bibliographic-fields-block
+
+:defaults:
+
+Same as above, but for the first such paragraph.
+
+address-value-block
+-------------------
+
+:fo: fo:block
+
+:docutils: docinfo/address
+
+:inherits: bibliographic-fields-block
+
+:defaults:
+
+     white-space: pre
+
+Formats the blocks (docutilis paragraphs) of the address field,
+which has to preserve the white space, according to the docutils
+specs. Since this inherits from the bibliographic-fields-bloc, it
+doesn't make sense to change attributes here directly.
+
+author-block
+------------
+
+:fo: fo:block
+
+:docutils: docinfo/author
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the author element, when bibliograhic info is not
+formatted as a list.
+
+authors-block
+-------------
+
+:fo: fo:block
+
+:docutils: docinfo/authors
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the authors element, when bibliograhic info is not
+formatted as a list.
+
+date-block
+----------
+
+:fo: fo:block
+
+:docutils: docinfo/date
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the date element, when bibliograhic info is not formatted
+as a list.
+
+organization-block
+------------------
+
+:fo: fo:block
+
+:docutils: docinfo/organization
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the organization element, when bibliograhic info is not
+formatted as a list.
+
+contact-block
+-------------
+
+:fo: fo:block
+
+:docutils: docinfo/contact
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the contact element, when bibliograhic info is not
+formatted as a list.
+
+status-block
+------------
+
+:fo: fo:block
+
+:docutils: docinfo/status
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the status element, when bibliograhic info is not
+formatted as a list.
+
+copyright-block
+---------------
+
+:fo: fo:block
+
+:docutils: docinfo/copyright
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the copyright element, when bibliograhic info is not
+formatted as a list.
+
+version-block
+-------------
+
+:fo: fo:block
+
+:docutils: docinfo/version
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the version element, when bibliograhic info is not
+formatted as a list.
+
+revision-block
+--------------
+
+:fo: fo:block
+
+:docutils: docinfo/revision
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the revision element, when bibliograhic info is not
+formatted as a list.
+
+address-block
+-------------
+
+:fo: fo:block
+
+:docutils: docinfo/address
+
+:defaults:
+
+     white-space: pre
+
+     space-before: 12pt
+
+Formats the address element, when bibliograhic info is not
+formatted as a list.
+
+Custom bibliographic fields
+---------------------------
+
+:fo: fo:block
+
+:docutils: docinfo/field
+
+The following attribute sets are identical in nature:
+
+* custom-bib-info1
+
+* custom-bib-info2
+
+* custom-bib-info3
+
+* custom-bib-info4
+
+* custom-bib-info5
+
+* custom-bib-info6
+
+* custom-bib-info7
+
+* custom-bib-info8
+
+* custom-bib-info9
+
+* custom-bib-info10
+
+These attribute-sets format the custom bibliographic fields.
+``'custom-bib-info1'`` refers to the first occurrence of such a
+field, ``'custom-bib-info2'`` to the second, and so fourth.
+
+Front Matter Attribute Sets
+===========================
+
+Attribute sets for the dedication and abstract.
+
+dedication-block
+----------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "dedication"]
+
+:defaults:
+
+Formats the dedication text, including the title and subsequent
+paragraphs, by wrapping them in a block.
+
+abstract-block
+--------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "abstract"]
+
+:defaults:
+
+Formats the abstract text, including the title and subsequent
+paragraphs, by wrapping them in a block.
+
+dedication-title-block
+----------------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "dedication"]/title
+
+:defaults:
+
+     text-align: center
+
+     font-weight: bold
+
+     space-after: 12pt
+
+Formats the title for the dedication.
+
+abstract-title-block
+--------------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "abstract"]/title
+
+:defaults:
+
+     text-align: center
+
+     font-weight: bold
+
+Formats the abstract title.
+
+dedication-paragraph-block
+--------------------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "dedication"]/paragraph
+
+:defaults:
+
+     font-style: italic
+
+     space-after: 12pt
+
+Formats the paragraphs of the dedication.
+
+dedication-first-paragraph-block
+--------------------------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "dedication"]/paragraph
+
+:inherits: dedication-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraph of the dedication.
+
+abstract-paragraph-block
+------------------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "abstract"]/paragraph
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the paragraphs of the abstract.
+
+abstract-first-paragraph-block
+------------------------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "abstract"]/paragraph
+
+:inherits: abstract-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraph of the abstract.
+
+Header and Footer Attribute Sets
+================================
+
+Attribute sets for the headers and footers. Since headers and
+footers often need very special formatting, the stylesheets allow
+for the formatting of up to three paragraphs for each header and
+footer. The first refers to the first that occurrs in the
+document, the second to the second, and the third to the third.
+
+header-block
+------------
+
+:fo: fo:block
+
+:docutils: decoration/header
+
+:defaults:
+
+     font-size: 12pt
+
+     text-align: center
+
+     space-before.conditionality: retain
+
+Formats the properties for the header. Use to set the space
+between the header and the body text, using ``'space-before =
+x'`` and setting ``'space-before.conditionality'`` to
+``'retain'``.
+
+first-header-block
+------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='first-header']
+
+:defaults:
+
+Formats the properties for the header for the first page.
+
+odd-header-block
+----------------
+
+:fo: fo:block
+
+:docutils: container[@classes='odd-header']
+
+:defaults:
+
+Formats the properties for the for the header of odd pages, when
+using a layout of ``'first-odd-even'``, or ``'odd-even'``.
+
+even-header-block
+-----------------
+
+:fo: fo:block
+
+:docutils: container[@classes='even-header']
+
+:defaults:
+
+Formats the properties for the for the header of even pages, when
+using a layout of ``'first-odd-even'``, or ``'odd-even'``.
+
+body-header-block
+-----------------
+
+:fo: fo:block
+
+:docutils: container[@classes='body-header']
+
+:defaults:
+
+Formats the properties for the for the header of the body, when
+using a layout of ``'first'``.
+
+footer-block
+------------
+
+:fo: fo:block
+
+:docutils: decoration/footer
+
+:defaults:
+
+     font-size: 12pt
+
+     text-align: center
+
+     space-before.conditionality: retain
+
+Formats the properties for the footer. Use to set the space
+between the header and the body text, using ``'space-before =
+x'`` and setting ``'space-before.conditionality'`` to
+``'retain'``.
+
+first-footer-block
+------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='first-footer']
+
+:defaults:
+
+Formats the properties for the footer for the first page.
+
+odd-footer-block
+----------------
+
+:fo: fo:block
+
+:docutils: container[@classes='odd-footer']
+
+:defaults:
+
+Formats the properties for the for the footer of odd pages, when
+using a layout of ``'first-odd-even'``, or ``'odd-even'``.
+
+even-footer-block
+-----------------
+
+:fo: fo:block
+
+:docutils: container[@classes='even-footer']
+
+:defaults:
+
+Formats the properties for the for the footer of even pages, when
+using a layout of ``'first-odd-even'``, or ``'odd-even'``.
+
+body-footer-block
+-----------------
+
+:fo: fo:block
+
+:docutils: container[@classes='body-footer']
+
+:defaults:
+
+Formats the properties for the for the footer of the body, when
+using a layout of ``'first'``.
+
+toc-first-header-block
+----------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-first-header']
+
+:defaults:
+
+Formats the properties for the header for the first page of the
+TOC.
+
+toc-odd-header-block
+--------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-odd-header']
+
+:defaults:
+
+Formats the properties for the for the header of odd pages of the
+TOC, when using a layout of ``'first-odd-even'``, or
+``'odd-even'``.
+
+toc-even-header-block
+---------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-even-header']
+
+:defaults:
+
+Formats the properties for the for the header of even pages of
+the TOC, when using a layout of ``'first-odd-even'``, or
+``'odd-even'``.
+
+toc-body-header-block
+---------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-body-header']
+
+:defaults:
+
+Formats the properties for the for the header of the body of the
+TOC, when using a layout of ``'first'``.
+
+toc-first-footer-block
+----------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-first-footer']
+
+:defaults:
+
+Formats the properties for the footer for the first page of the
+TOC.
+
+toc-odd-footer-block
+--------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-odd-footer']
+
+:defaults:
+
+Formats the properties for the for the footer of odd pages of the
+TOC, when using a layout of ``'first-odd-even'``, or
+``'odd-even'``.
+
+toc-even-footer-block
+---------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-even-footer']
+
+:defaults:
+
+Formats the properties for the for the footer of even pages of
+the TOC, when using a layout of ``'first-odd-even'``, or
+``'odd-even'``.
+
+toc-body-footer-block
+---------------------
+
+:fo: fo:block
+
+:docutils: container[@classes='toc-body-footer']
+
+:defaults:
+
+     font-size: 12pt
+
+     text-align: center
+
+     space-before.conditionality: retain
+
+Formats the properties for the for the footer of the body of the
+TOC, when using a layout of ``'first'``.
+
+paragraph-header-block
+----------------------
+
+:fo: fo:block
+
+:docutils: decoration/footer/paragraph
+
+:defaults:
+
+     font-size: 12pt
+
+     text-align: center
+
+Formats the properties for the paragraphs in the header. Use to
+set the space between the footer and the body text, using
+``'space-before = x'`` and setting
+``'space-before.conditionality'`` to ``'retain'``.
+
+paragraph-footer-block
+----------------------
+
+:fo: fo:block
+
+:docutils: decoration/footer/paragraph
+
+:defaults:
+
+     font-size: 12pt
+
+     text-align: center
+
+Formats the properties for the footer. Use to set the space
+between the footer and the body text, using ``'space-before =
+x'`` and setting ``'space-before.conditionality'`` to
+``'retain'``.
+
+TOC Matter Attribute Sets
+=========================
+
+Attribute sets for the TOC.
+
+toc-block
+---------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "contents"]
+
+:defaults:
+
+Formats the block that wraps the TOC.
+
+toc-title-block
+---------------
+
+:fo: fo:block
+
+:docutils: topic[@classes = "contents"]/title
+
+:defaults:
+
+     text-align: center
+
+     font-weight: bold
+
+     font-size: 14pt
+
+Formats the block for the title for the TOC.
+
+toc-entry-defaults-block
+------------------------
+
+:fo: None
+
+:docutils: None
+
+:defaults:
+
+     space-after: 3pt
+
+     text-align-last: justify
+
+Sets up the defaults for the TOC entries.
+
+toc-level1-block
+----------------
+
+:fo: fo:block
+
+:docutils: topic[@classes =
+         "contents"]/bullet_list/list_item/paragraph/
+
+:inherits: toc-entry-defaults-block
+
+:defaults:
+
+Formats the block for the level 1 table of contents entry. If a
+number exists, it is formatted according to the parameter
+'number-section1'.
+
+toc-level2-block
+----------------
+
+:fo: fo:block
+
+:docutils: topic[@classes =
+         "contents"]/bullet_list/list_item/bullet_list/list_item/paragraph/
+
+:inherits: toc-entry-defaults-block
+
+:defaults:
+
+     start-indent: 10mm
+
+Formats the block for the level 2 table of contents entry. If a
+number exists, it is formatted according to the parameter
+'number-section2'.
+
+toc-level3-block
+----------------
+
+:fo: fo:block
+
+:docutils: topic[@classes =
+         "contents"]/bullet_list/list_item/bullet_list/list_item/paragraph/etc.
+
+:inherits: toc-entry-defaults-block
+
+:defaults:
+
+     start-indent: 20mm
+
+Formats the block for the level 3 table of contents entry. If a
+number exists, it is formatted according to the parameter
+'number-section3'.
+
+toc-level4-block
+----------------
+
+:fo: fo:block
+
+:docutils: topic[@classes =
+         "contents"]/bullet_list/list_item/bullet_list/list_item/paragraph/etc.
+
+:inherits: toc-entry-defaults-block
+
+:defaults:
+
+     start-indent: 30mm
+
+Formats the block for the level 4 table of contents entry. If a
+number exists, it is formatted according to the parameter
+'number-section4'.
+
+toc-level5-block
+----------------
+
+:fo:
+
+:docutils: topic[@classes =
+         "contents"]/bullet_list/list_item/bullet_list/list_item/paragraph/etc.
+
+:inherits: toc-entry-defaults-block
+
+:defaults:
+
+     start-indent: 40mm
+
+Formats the block for the level 5 table of contents entry. If a
+number exists, it is formatted according to the parameter
+'number-section5'.
+
+Section Attribute Sets
+======================
+
+Attribute sets for the section titles.
+
+default-section-title-block
+---------------------------
+
+:fo: None
+
+:docutils: None
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+     keep-with-next: always
+
+Sets up the defaults for the section titles. The title should
+always have some text beneath it to avoid widows and orphans;
+hence the keep-with-always property.
+
+title-level-block
+-----------------
+
+:fo: fo:block
+
+:docutils: section/title|section/section/title|etc.
+
+:inherits: default-section-title-block
+
+The following attribute sets are identical in nature:
+
+- title-level1-block
+
+- title-level2-block
+
+- title-level3-block
+
+- title-level4-block
+
+- title-level5-block
+
+- title-level6-block
+
+- title-level7-block
+
+- title-level8-block
+
+- title-level9-block
+
+These attribute-sets format the titles of all sections.
+
+title-number-inline
+-------------------
+
+:fo: fo:inline
+
+:docutils: section/title/generated[@classes="sectnum]"
+
+:defaults:
+
+     space-end: 12pt
+
+Formats the title number generated by docutils.
+
+Body Elements
+=============
+
+Attribute sets for body elements, including the document title
+and subtitle; the default paragraph; the transition element; and
+the literal block.
+
+paragraph-block
+---------------
+
+:fo: fo:block
+
+:docutils: document/paragrah|section/paragraph"
+
+:defaults:
+
+     space-after: 12pt
+
+Formats the default paragraph.
+
+first-paragraph-block
+---------------------
+
+:fo: fo:block
+
+:docutils: document/paragrah|section/paragraph"
+
+:inherits: paragraph-block
+
+:defaults:
+
+Formats the first default paragraph.
+
+literal-block
+-------------
+
+:fo: fo:block
+
+:docutils: document/literal_block|section/literal_block"
+
+:defaults:
+
+     font-family: monospace
+
+     font-size: 8
+
+     white-space: pre
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+Formats the literal text.
+
+transition-block
+----------------
+
+:fo: fo:block
+
+:docutils: document/transition|section/transition"
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+     text-align: center
+
+Formats the transition block. The actutal text for this block is
+set by the 'transition-text' parameter.
+
+document-title-block
+--------------------
+
+:fo: fo:block
+
+:docutils: document/title"
+
+:defaults:
+
+     space-after: 12pt
+
+     font-size: 24pt
+
+     text-align: center
+
+     font-weight: bold
+
+Formats the title for the document.
+
+document-title-page-block
+-------------------------
+
+:fo: fo:block
+
+:docutils: document/title|document/subtitle"
+
+:defaults:
+
+The block that wraps both the title and subtitle. This block only
+gets written if the title and subtitle occur in the front
+section, or TOC section.
+
+document-subtitle-block
+-----------------------
+
+:fo: fo:block
+
+:docutils: document/subtitle"
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+     font-size: 18pt
+
+     text-align: center
+
+     font-weight: bold
+
+Formats the subtitle of the document.
+
+block-quote-outer-block
+-----------------------
+
+:fo: fo:block
+
+:docutils: block_quote
+
+:defaults:
+
+     start-indent: 20mm
+
+     end-indent: 20mm
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+The attribute set that formats the block that wraps the other
+blocks in a block quote. Use the attribute set to format space
+after or space before, etc.
+
+block-quote-paragraph-block
+---------------------------
+
+:fo: fo:block
+
+:docutils: block_quote/paragraph
+
+:defaults:
+
+     space-before: 12pt
+
+The attribute set that formats the paragraphs in the block quote.
+A different set of attributes controls the first paragraph (see
+below). Use this attribute set to set the space between
+paragraphs with the 'space-before' attribute.
+
+block-quote-first-paragraph-block
+---------------------------------
+
+:fo: fo:block
+
+:docutils: block_quote/paragraph[1]
+
+:inherits: block-quote-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+The attribute set that formats the first paragraph in the block
+quote. It inherits all the attributes from
+'block-quote-first-paragraph-block' and then sets the
+'space-before' to 0. It does not make sense to modify attributes
+in this attribute set directly.
+
+block-quote-attribution-block
+-----------------------------
+
+:fo: fo:block
+
+:docutils: block_quote/paragraph[1]
+
+:inherits: block-quote-paragraph-block
+
+:defaults:
+
+     text-align: right
+
+This attribute set the attribution in a block quote.
+
+bullet list
+===========
+
+Attribute sets for the bullet list.
+
+bullet-list-block
+-----------------
+
+:fo: list-block
+
+:docutils: bullet_list
+
+:defaults:
+
+     start-indent: 5mm
+
+     provisional-distance-between-starts: 5mm
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+For the bullet list. Since this element contains all the other
+list elements, it can be used to set values such as the font,
+background color, line-height, etc, for the entire list, as well
+as the space after and before.
+
+"The provisional-distance-between-starts property of the
+list-block specifies the distance bewteen the start of the label
+(the bullet, for example) and the actual start of the list
+content" (Pawson, 100)
+
+bullet-list-item
+----------------
+
+:fo: fo:list-item
+
+:docutils: bullet_list/list_item
+
+:defaults:
+
+     space-before: 12pt
+
+For the item in the bullet list. The attributes can control the
+spacing between each item. A different set of attributes controls
+the spacing of the first item (see below).
+
+bullet-first-list-item
+----------------------
+
+:fo: fo:list-item
+
+:docutils: bullet_list/list_item[1]
+
+:inherits: bullet-list-item
+
+:defaults:
+
+     space-before: 0pt
+
+For the first item in the bullet list. This attribute set
+inherits all the properties form 'bullet-list-item', and then
+re-defines the space-before to 0pt. In order to get space between
+the first item and the text before it, use the space-after
+attribute in the bullet-list attribute set.
+
+bullet-level2-list-item
+-----------------------
+
+:fo: fo:list-item
+
+:docutils: bullet_list/bullet_list/list_item
+
+:defaults:
+
+     space-before: 12pt
+
+Same as above, except for a nested bullet list.
+
+bullet-level2-first-list-item
+-----------------------------
+
+:fo: fo:list-item
+
+:docutils: bullet_list/list_item[1]
+
+:inherits: bullet-level2-list-item
+
+:defaults:
+
+     space-before: 0pt
+
+For the first item in a nested bullet list. This attribute set
+inherits all the properties form 'bullet-list-item', and then
+re-defines the space-before to 0pt. In order to get space between
+the first item and the text before it, use the space-after
+attribute in the bullet-list attribute set.
+
+bullet-list-item-label
+----------------------
+
+:fo: fo:list-item-label
+
+:docutils: bullet_list/list_item
+
+:defaults:
+
+     end-indent: label-end()
+
+The default attribute end-indent = "label-end()" ensures that the
+label aligns properly.
+
+bullet-list-item-label-block
+----------------------------
+
+:fo: fo:block
+
+:docutils: bullet_list/list_item
+
+:defaults:
+
+These attributes format the block that wraps the bullet. (FO
+requires such a block, even for a small label like this.)
+
+bullet-list-item-body
+---------------------
+
+:fo: fo:list-item-body
+
+:docutils: bullet_list/list_item
+
+:defaults:
+
+     start-indent: body-start()
+
+The default of start-indent = "body-start()" ensures the correct
+alignment of the labels.
+
+bullet-list-item-body-block
+---------------------------
+
+:fo: fo:block
+
+:docutils: bullet_list/list_item/paragraph
+
+:defaults:
+
+     space-after: 12pt
+
+Formats the blocks (docutilis paragraphs) of the body of each
+item.
+
+bullet-level2-list-block
+------------------------
+
+:fo: list-block
+
+:docutils: bullet_list/bullet_list
+
+:defaults:
+
+     start-indent: 15mm
+
+     provisional-distance-between-starts: 5mm
+
+     space-before: 12pt
+
+Same as for the bullet-list-block attribute. The default sets the
+start-indent property to a greater value to indent this nested
+list.
+
+enumerated list
+===============
+
+Attribute sets for the enumerated list.
+
+enumerated-list-block
+---------------------
+
+:fo: list-block
+
+:docutils: enumerated_list
+
+:defaults:
+
+     start-indent: 5mm
+
+     provisional-distance-between-starts: 10mm
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+For the enumerated list. Since this element contains all the
+other list elements, it can be used to set values such as the
+font, background color, line-height, etc, for the entire list, as
+well as the space after and before.
+
+"The provisional-distance-between-starts property of the
+list-block specifies the distance bewteen the start of the label
+(the bullet, for example) and the actual start of the list
+content" (Pawson, 100)
+
+enumerated-level2-list-block
+----------------------------
+
+:fo: list-block
+
+:docutils: enumerated_list/enumerated_list
+
+:defaults:
+
+     start-indent: 15mm
+
+     provisional-distance-between-starts: 10mm
+
+     space-before: 12pt
+
+     space-before: 12pt
+
+Same as for the enumerated-list-block attribute. The default sets
+the start-indent property to a greater value to indent this
+nested list.
+
+enumerated-list-item
+--------------------
+
+:fo: fo:list-item
+
+:docutils: enumerated_list/list_item
+
+:defaults:
+
+     space-before: 12pt
+
+For the item in the enumerated list. The attributes can control
+the spacing between each item. A different set of attributes
+controls the spacing of the first item (see below).
+
+enumerated-first-list-item
+--------------------------
+
+:fo: fo:list-item
+
+:docutils: enumerated_list/list_item[1]
+
+:inherits: enumerated-list-item
+
+:defaults:
+
+     space-before: 0pt
+
+For the first item in the enumerated list. This attribute set
+inherits all the properties form 'enumerated-list-item', and then
+re-defines the space-before to 0pt. In order to get space
+between the first item and the text before it, use the
+space-after attribute in the enumerated-list attribute set.
+
+enumerated-level2-list-item
+---------------------------
+
+:fo: fo:list-item
+
+:docutils: enumerated_list/list_item/enumerated_list/list-item
+
+:defaults:
+
+     space-before: 12pt
+
+Same as above, but formats item of nested list.
+
+enumerated-level2-first-list-item
+---------------------------------
+
+:fo: fo:list-item
+
+:docutils: enumerated_list/item/enumerated_list/list_item[1]
+
+:inherits: enumerated-level2-list-item
+
+:defaults:
+
+     space-before: 0pt
+
+For the first item in the nested enumerated list.
+
+enumerated-list-item-label
+--------------------------
+
+:fo: fo:list-item-label
+
+:docutils: enumerated_list/list_item
+
+:defaults:
+
+     end-indent: label-end()
+
+The default attribute end-indent = "label-end()" ensures that the
+label aligns properly.
+
+enumerated-list-item-body
+-------------------------
+
+:fo: fo:list-item-body
+
+:docutils: enumerated_list/list_item
+
+:defaults:
+
+     start-indent: body-start()
+
+The default of start-indent = "body-start()" ensures the correct
+alignment of the labels.
+
+enumerated-list-item-body-block
+-------------------------------
+
+:fo: fo:block
+
+:docutils: enumerated_list/list_item/paragraph
+
+:defaults:
+
+     space-after: 12pt
+
+Formats the blocks (docutilis paragraphs) of the body of each
+item.
+
+definition list
+===============
+
+Attribute sets for the definition list.
+
+definition-list-block
+---------------------
+
+:fo: block
+
+:docutils: definition_list
+
+:defaults:
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+For the definition list. Since this element contains all the
+other blocks in the list, it can be used to set values such as
+the font, background color, line-height, etc, for the entire
+list, as well as the space after and before.
+
+definition-list-item-block
+--------------------------
+
+:fo: fo:block
+
+:docutils: definition_list/definition_list_item
+
+:defaults:
+
+     space-before: 12pt
+
+For the items in the definition list. The attributes can control
+the spacing between each item. A different set of attributes
+controls the spacing of the first item (see below).
+
+definition-list-item-first-block
+--------------------------------
+
+:fo: fo:block
+
+:docutils: definition_list/definition_list_item
+
+:inherits: definition-list-item-block
+
+:defaults:
+
+     space-before: 0pt
+
+For the first item in the definition list. This attribute set
+inherits all the properties form 'definition-list-item', and then
+re-defines the space-before to 0pt. In order to get space
+between the first item and the text before it, use the
+space-after attribute in the option-list attribute set.
+
+It does not makes sense to change this set direclty.
+
+definition-term-block
+---------------------
+
+:fo: fo:block
+
+:docutils: definition_list/definition_list_item/term
+
+:defaults:
+
+     font-weight: bold
+
+Formats the bock of the the term. Can be used to control spacing
+between term and definition, but don't use with space before, or
+you won't be able to control spacing before list
+
+definition-block
+----------------
+
+:fo: fo:block
+
+:docutils: definition_list/definition_list_item/definition
+
+:defaults:
+
+Formats the bock of the of the defintion, that wraps the
+paragraph blocks.
+
+classifier-inline
+-----------------
+
+:fo: fo:inline
+
+:docutils: definition_list/definition_list_item/classifier
+
+:defaults:
+
+     font-style: italic
+
+For the inine properties of the classifier item.
+
+definition-paragraph-block
+--------------------------
+
+:fo: fo:block
+
+:docutils:
+         definition_list/definition_list_item/definition/paragraph
+
+:defaults:
+
+     space-before: 12pt
+
+     start-indent: 30pt
+
+Formats the blocks (paragraphs in the defintion. Can be lsed to
+control the space between paragraphs by setting the space-bfore
+attribute. Don't use the space-after attribute, or you won't be
+able to contorl the spacing between items
+
+definition-first-paragraph-block
+--------------------------------
+
+:fo: fo:block
+
+:docutils:
+         definition_list/definition_list_item/definition/paragraph[1]
+
+:inherits: definition-first-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+For the first paragraph in the definition list. This attribute
+set inherits all the properties frorm
+'definition-first-paragraph-block', and then re-defines the
+space-before to 0pt.
+
+It does not makes sense to change this set direclty.
+
+field list
+==========
+
+Attribute sets for the field list.
+
+field-list-block
+----------------
+
+:fo: list-block
+
+:docutils: field_list
+
+:defaults:
+
+     start-indent: 0mm
+
+     provisional-distance-between-starts: 30mm
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+Formats the field list. Since this element contains all the other
+list elements, it can be used to set values such as the font,
+background color, line-height, etc, for the entire list, as well
+as the space after and before.
+
+"The provisional-distance-between-starts property of the
+list-block specifies the distance bewteen the start of the label
+(the bullet, for example) and the actual start of the list
+content" (Pawson, 100).
+
+field-list-item
+---------------
+
+:fo: fo:list-item
+
+:docutils: field_list/field
+
+:defaults:
+
+     space-before: 12pt
+
+For the items, or 'fields' in the field list. The attributes can
+control the spacing between each item. A different set of
+attributes controls the spacing of the first item (see below).
+
+field-first-list-item
+---------------------
+
+:fo: fo:list-item
+
+:docutils: field_list/field[1]
+
+:inherits: field-list-item
+
+:defaults:
+
+     space-before: 0pt
+
+For the first item in the field list. This attribute set inherits
+all the properties form 'field-list-item', and then re-defines
+the space-before to 0pt. In order to get space between the first
+item and the text before it, use the space-after attribute in the
+field-list-block attribute set.
+
+It does not make sense to change this attriubte set directly.
+
+field-list-item-label
+---------------------
+
+:fo: fo:list-item-label
+
+:docutils: field_list/field/field_name
+
+:defaults:
+
+     end-indent: label-end()
+
+The default attribute end-indent = "label-end()" ensures that the
+label aligns properly.
+
+field-list-item-body
+--------------------
+
+:fo: fo:list-item-body
+
+:docutils: field_list/field/field_body
+
+:defaults:
+
+     start-indent: body-start()
+
+The default of start-indent = "body-start()" ensures the correct
+alignment of the labels.
+
+field-body-block
+----------------
+
+:fo: fo:block
+
+:docutils: field_list/field/field_body/paragraph
+
+:defaults:
+
+     space-after: 12pt
+
+Formats the blocks (docutilis paragraphs) of the field.
+
+field-list-item-label-block
+---------------------------
+
+:fo: fo:block
+
+:docutils: field_list/field/field_name
+
+:defaults:
+
+     font-weight: bold
+
+Formats the block that wraps the field name.
+
+option list as list
+===================
+
+Since an option list can be rendered as either a traditonal list,
+or a definition list, there are two sets of attribute sets.
+These attribute sets are used for the options list when it is
+rendered as a list.
+
+option-list-block
+-----------------
+
+:fo: list-block
+
+:docutils: option_list
+
+:defaults:
+
+     start-indent: 0mm
+
+     provisional-distance-between-starts: 50mm
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+For the option list. Since this element contains all the other
+list elements, it can be used to set values such as the font,
+background color, line-height, etc, for the entire list, as well
+as the space after and before.
+
+"The provisional-distance-between-starts property of the
+list-block specifies the distance bewteen the start of the label
+(the bullet, for example) and the actual start of the list
+content" (Pawson, 100)
+
+option-list-item
+----------------
+
+:fo: fo:list-item
+
+:docutils: option_list/option_list_item
+
+:defaults:
+
+     space-before: 12pt
+
+For the items in the option list. The attributes can control the
+spacing between each item. A different set of attributes controls
+the spacing of the first item (see below).
+
+option-first-list-item
+----------------------
+
+:fo: fo:list-item
+
+:docutils: option_list/option_list_item[1]
+
+:inherits: option-list-item
+
+:defaults:
+
+     space-before: 0pt
+
+For the first item in the option list. This attribute set
+inherits all the properties form 'option-list-item', and then
+re-defines the space-before to 0pt. In order to get space between
+the first item and the text before it, use the space-after
+attribute in the option-list attribute set.
+
+It does not make sense to change this attriubte set directly.
+
+option-list-item-label
+----------------------
+
+:fo: fo:list-item-label
+
+:docutils: option_list/option_list_item/option_group
+
+:defaults:
+
+     end-indent: label-end()
+
+The default attribute end-indent = "label-end()" ensures that the
+label aligns properly.
+
+option-list-item-label-block
+----------------------------
+
+:fo: fo:block
+
+:docutils:
+         option_list/option_list_item/option_group/option_string|option_argument
+
+:defaults:
+
+These attributes format the block that wraps the option_string
+and option_argument.
+
+option-list-item-body
+---------------------
+
+:fo: fo:list-item-body
+
+:docutils: option_list/option_list_item/description
+
+:defaults:
+
+     start-indent: body-start()
+
+The default of start-indent = "body-start()" ensures the correct
+alignment of the labels.
+
+option-list-item-body-block
+---------------------------
+
+:fo: fo:block
+
+:docutils: option_list/option_list_item/description/paragraph
+
+:defaults:
+
+Formats the blocks (docutilis paragraphs) that describe the
+options. If there was more than one paragraph, you could use
+attributes such as space after.
+
+option-inline
+-------------
+
+:fo: fo:inline
+
+:docutils:
+         option_list/option_list_item/option_group/option/option_string
+
+:defaults:
+
+     font-family: monospace
+
+Used to format any inline properties of the option_string.
+
+option-argument-inline
+----------------------
+
+:fo: fo:inline
+
+:docutils:
+         option_list/option_list_item/option_group/option/option_argument
+
+:defaults:
+
+     font-family: monospace
+
+     font-style: italic
+
+Used to format any inline properties of the option_string.
+
+option list as definition list
+==============================
+
+These attribute sets are used for the options list when it is
+rendered as a definition list. (See the docutils reference guide
+for an example of a definition list, or see the defintion list in
+the test files.)
+
+option-list-definition-block
+----------------------------
+
+:fo: fo:block
+
+:docutils: option_list
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+Formats the block that wraps the other blocks. Use to control
+space after and before, or to set any block items on the entire
+list.
+
+This block wraps around another block, which in turn wraps around
+a third block.
+
+option-list-item-block
+----------------------
+
+:fo: fo:block
+
+:docutils: option_list/option_list_item
+
+:defaults:
+
+     space-before: 8pt
+
+Formats the block that wraps the options and descriptions, which
+are also blocks.
+
+option-list-first-item-block
+----------------------------
+
+:fo: fo:block
+
+:docutils: option_list/option_list_item
+
+:defaults:
+
+     space-before: 0pt
+
+Same as for option-list-item-block, but sets the space-before to
+0pt
+
+Does not make sense to change the attributes here directly.
+
+option-group-block
+------------------
+
+:fo: fo:block
+
+:docutils: option_list_item/option_list_item/option_group
+
+:defaults:
+
+     keep-with-next: always
+
+Formats the block that contains the inline elements of the
+options and arguments. For a defintion list, this block serves as
+the term, and sits on top, and to the left of the description.
+
+option-list-description-block
+-----------------------------
+
+:fo: fo:block
+
+:docutils: option_list/option_list_item/description
+
+:defaults:
+
+     start-indent: 16pt
+
+     space-before: 8pt
+
+Formats the blocks wrappring the paragraphs describing the
+options or arguments. This groups of blocks sits below the blocks
+formatting the options and arguments, and in a defintion list
+are usually indented right.
+
+option-list-paragraph-block
+---------------------------
+
+:fo: fo:block
+
+:docutils: option_list/option_list_item/description/paragraph
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the paragraphs in the description for an options list
+formatted as a definition list.
+
+option-list-first-paragraph-block
+---------------------------------
+
+:fo: fo:block
+
+:docutils: option_list/option_list_item/description/paragraph
+
+:inherits: option-list-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraph in the description for an options
+list formatted as a definition list.
+
+Line Block
+==========
+
+Attribute sets for the line block.
+
+outer-line-block
+----------------
+
+:fo: fo:block
+
+:docutils: line_block
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+The outer block containing the blocks of lines. Use the outer
+block to set space before or after the verse.
+
+level1-line-block
+-----------------
+
+:fo: fo:block
+
+:docutils: line_block/line
+
+:defaults:
+
+     start-indent: 10mm
+
+Attribute sets for the first level of lines.
+
+level2-line-block
+-----------------
+
+:fo: fo:block
+
+:docutils: line_block/line_block/line
+
+:defaults:
+
+     start-indent: 20mm
+
+Attribute sets for the second level of lines.
+
+level3-line-block
+-----------------
+
+:fo: fo:block
+
+:docutils: line_block/line_block/line_block/line
+
+:defaults:
+
+     start-indent: 30mm
+
+Attribute sets for the third level of lines.
+
+level4-line-block
+-----------------
+
+:fo: fo:block
+
+:docutils: line_block/line_block/line_block/line_block/line
+
+:defaults:
+
+     start-indent: 40mm
+
+Attribute sets for the fourth level of lines.
+
+level5-line-block
+-----------------
+
+:fo: fo:block
+
+:docutils:
+         line_block/line_block/line_block/line_block/line_block/line
+
+:defaults:
+
+     start-indent: 50mm
+
+Attribute sets for the fifth level of lines.
+
+stanza-title-block
+------------------
+
+:fo: fo:block
+
+:docutils: line_block/title_reference
+
+:defaults:
+
+     text-align: center
+
+     space-before: 12
+
+     font-weight: bold
+
+Formats the title of a stanza.
+
+Table
+=====
+
+Attribute sets for the Table.
+
+table-block-container
+---------------------
+
+:fo: fo:block-container
+
+:docutils: table
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+Formats the block container that wraps bothe the table and a the
+table title (captin) if one exists. Use to control space before
+and after the table.
+
+table
+-----
+
+:fo: fo:table
+
+:docutils: table
+
+:defaults:
+
+     table-layout: fixed
+
+     inline-progression-dimension: 100%
+
+Formats the table.
+
+table-header
+------------
+
+:fo: fo:table-header
+
+:docutils: tgroup/thead
+
+:defaults:
+
+     font-weight: bold
+
+Formats the header of the table.
+
+default-cell
+------------
+
+:fo: fo:cell
+
+:docutils: None
+
+:defaults:
+
+     border: solid black 1px
+
+     padding: 1em
+
+     border-collapse: collapse
+
+Sets the defaults for all cells.
+
+table-header-cell
+-----------------
+
+:fo: fo:cell
+
+:docutils: thead/row/entry
+
+:inherits: default-cell
+
+:defaults:
+
+     border-bottom: solid black 2px
+
+Formats the cells in the table header.
+
+table-header-block
+------------------
+
+:fo: fo:block
+
+:docutils: thead/row/entry/paragraph
+
+:defaults:
+
+Attributes for the paragraphs in the header cell.
+
+table-body
+----------
+
+:fo: fo:table-body
+
+:docutils: tbody
+
+:defaults:
+
+Attributes for the table body.
+
+table-row
+---------
+
+:fo: fo:table-row
+
+:docutils: tbody/row
+
+:defaults:
+
+     keep-together.within-page: always
+
+Attributes for the table row.
+
+table-cell
+----------
+
+:fo: fo:table-cell
+
+:docutils: tbody/row/entry
+
+:inherits: default-cell
+
+:defaults:
+
+Attributes for the table cell.
+
+cell-block
+----------
+
+:fo: fo:block
+
+:docutils: tbody/row/entry/paragraph
+
+:defaults:
+
+Attributes for the paragraphs in the cell.
+
+caption-block
+-------------
+
+:fo: fo:block
+
+:docutils: table/title
+
+:defaults:
+
+     text-align: center
+
+     space-before: 6pt
+
+     space-after: 6pt
+
+Attributes for the table title, or caption. The parameter
+'table-title-placement', controls whether this block is placed
+before or after the table. If it is placed on top of the table,
+it has a 'keep-with-next="always"' value that cannot be changed.
+If this block is placed on the bottom it has a
+'keep-with-previous="always"' value that cannot be changed.
+
+Table Extended
+==============
+
+Attribute sets for the Extended Tables.
+
+Custom Tables
+-------------
+
+:fo: See below
+
+:docutils: See below
+
+The table_extend.xsl contains templates to match 30 custom
+tables, and and attribute sets for each of these tables. Each
+attribute set has has the same function as its corresponding
+attribute set in the regular table, as documented above.
+
+* table1-block-container => table-block-contanter
+
+* table1 => table
+
+* table1-header => table-header
+
+* table1-header-cell => table-header-cell
+
+* table1-header-block => table-header-block
+
+* table1-body => table-body
+
+* table1-header-row => table-header-row
+
+* table1-row => table-row
+
+* table1-cell => table-cell
+
+* cell1-block => cell-block
+
+* table2-block-container => table-block-contanter
+
+* table2 => table
+
+* ...
+
+* table2-row => table-row
+
+* table2-cell => table-cell
+
+* cell2-block => cell-block
+
+* ...
+
+* table30-block-container => table-block-contanter
+
+* table30 => table
+
+* table30-header => table-header
+
+* table30-header-cell => table-header-cell
+
+* table30-header-block => table-header-block
+
+* table30-body => table-body
+
+* table30-header-row => table-header-row
+
+* table30-row => table-row
+
+* table30-cell => table-cell
+
+* cell30-block => cell-block
+
+Table Extended 2 (Borderless)
+=============================
+
+Attribute sets for the Extended 2 (Borderless) Tables.
+
+Custom Tables
+-------------
+
+:fo: See below
+
+:docutils: See below
+
+The table_extend2.xsl contains templates for the borderless
+table. Each attribute set has has the same function as its
+corresponding attribute set in the regular table, as documented
+above.
+
+* borderless-table-block-container => table-block-contanter
+
+* borderless-table => table
+
+* borderless-table-header => table-header
+
+* borderless-table-header-cell => table-header-cell
+
+* borderless-table-header-block => table-header-block
+
+* borderless-table-body => table-body
+
+* borderless-table-header-row => table-header-row
+
+* borderless-table-row => table-row
+
+* borderless-table-cell => table-cell
+
+* borderless-cell-block => cell-block
+
+Table Long
+==========
+
+Attribute sets for the Long Tables.
+
+Long Tables
+-----------
+
+:fo: See below
+
+:docutils: See below
+
+The table_long.xsl contains templates for a long table. Each
+attribute set has has the same function as its corresponding
+attribute set in the regular table, as documented above. There is
+no block-container attriute set, because there is no
+block-container element; the caption is rendered as part of the
+header or footer.
+
+* long-table => table
+
+* long-table-header => table-header
+
+* long-table-header-row => table-header-row
+
+* long-thead-cell => thead-cell
+
+* long-table-header-block => table-header-block
+
+* long-table-body => table-body
+
+* long-table-header-row => table-header-row
+
+* long-table-row => table-row
+
+* long-table-cell => table-cell
+
+* long-cell-block => cell-block
+
+* long-caption-block => caption-block
+
+Footnote
+========
+
+Attribute sets for footnotes, endnotes, and the endnotes title.
+
+footnote
+--------
+
+:fo: fo:footnote
+
+:docutils: footnote
+
+:defaults:
+
+     font-weight: normal
+
+     font-style: normal
+
+Formats the footnote. By default, it sets properties to neutral,
+so that it does not inherit any unwanted properties, such as from
+a definition term.
+
+default-footnote-label-inline
+-----------------------------
+
+:fo: fo:inline
+
+:docutils: None
+
+:defaults:
+
+     baseline-shift: super
+
+     font-size: 8pt
+
+Sets of the defaults for the label (1, \*, etc), of each label.
+
+footnote-label-inline
+---------------------
+
+:fo: fo:inline
+
+:docutils: footnote/paragraph[1]
+
+:inherits: default-footnote-label-inline
+
+:defaults:
+
+Formats the label for *traditional* footnotes and endnotes at the
+bottomm of the page or with the endnotes. This attribute set
+does not affect the label for footnotes and endnotes formatted as
+a list.
+
+footnote-body-label-inline
+--------------------------
+
+:fo: fo:inline
+
+:docutils: footnote/paragraph[1]
+
+:inherits: default-footnote-label-inline
+
+:defaults:
+
+Formats the label for *traditional* footnotes and endnotes in the
+body of the text. This attribute set does not affect the label
+for footnotes and endnotes formatted as a list.
+
+footnote-list-block
+-------------------
+
+:fo: fo:list-block
+
+:docutils: footnote
+
+:defaults:
+
+     provisional-label-separation: 0pt
+
+     provisional-distance-between-starts: 18pt
+
+Formats the list that contains the footnote. The
+'provisional-distance-between-starts' controls how far away the
+footnote label is from the text.
+
+footnote-item-label
+-------------------
+
+:fo: fo:list-item-label
+
+:docutils: footnote
+
+:defaults:
+
+     end-indent: label-end()
+
+Formats the item-label when the footnote or endnote is formatted
+as a list.
+
+footnote-label-block
+--------------------
+
+:fo: fo:block
+
+:docutils: footnote_reference
+
+:defaults:
+
+Formats the block in item-label when the footnote or endnote is
+formatted as a list. By default, the label has no superscript (as
+opposed to when formatting a "traditional" footnote.
+
+footnote-item-body
+------------------
+
+:fo: fo:list-item-body
+
+:docutils: footnote
+
+:defaults:
+
+     start-indent: body-start()
+
+Formats the item-body when the footnote or endnote is formatted
+as a list.
+
+footnote-body
+-------------
+
+:fo: fo:footnote-body
+
+:docutils: footnote
+
+:defaults:
+
+Formats the body of the footnote. Space-after and space-before
+seem to have no affect, at least with fop.
+
+footnote-paragraph-block
+------------------------
+
+:fo: fo:block
+
+:docutils: footnote/paragraph
+
+:defaults:
+
+     space-before: 5pt
+
+Formats the paragraphs in the body of a footnote or endnote. Use
+the 'space-before' to set the space between each paragraphs, for
+footnotes or endnotes with multiple paragraphs. In addition, for
+traditional footnotes, use the 'text-indent="18pt" to create a
+traditional footnote. (The deault does not do this, in order to
+accommodate the footnote-as-a-list.)
+
+footnote-first-paragraph-block
+------------------------------
+
+:fo: fo:block
+
+:docutils: footnote/paragraph[1]
+
+:inherits: footnote-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraphs in the body of a footnote or
+endnote. It inherits all the attributes from the
+'footnote-paragraphs-block' and sets the space-before to 0. It
+does not make sense to change attributes on this block directly.
+
+endnotes-block
+--------------
+
+:fo: fo:block
+
+:docutils: footnote
+
+:defaults:
+
+     break-before: page
+
+The block that wraps all the other blocks of the endnotes. Use to
+create a page break before, or to create space before and after
+the endnotes.
+
+endnote-block
+-------------
+
+:fo: fo:block
+
+:docutils: footnote
+
+:defaults:
+
+     space-before: 5pt
+
+The block that wraps each individual endnote ('footnote' in
+docutils). Use to control the spacing between each endnote.
+
+endnote-first-block
+-------------------
+
+:fo: fo:block
+
+:docutils: footnote
+
+:inherits: endnote-block
+
+:defaults:
+
+     space-before: 0pt
+
+The block that wraps each the first endnote ('footnote' in
+docutils). It does not make sense to change attributes on this
+set directly.
+
+endnotes-title-block
+--------------------
+
+:fo: fo:block
+
+:docutils: rubric[@classes='endnotes']
+
+:defaults:
+
+     space-after: 18pt
+
+     font-weight: bold
+
+     font-size: 18pt
+
+     text-align: center
+
+Formats the title for the endnotes, when one is present.
+
+Admonitions
+===========
+
+Attribute sets for Admonitions. By default, the admontioins have
+a border around them. Each admonition gets its title from the
+parameter of that name. For example, the danger admonitions title
+gets its title from the 'danger-title' parameter, the caution
+from the `caution-title` paramter, and so fourth.
+
+Although each admonition and each admonition title has its own
+attribute-set, by default they all inherit these values from two
+default attribute sets. (See below.) Each of these areas can thus
+be customized. In contrast, all the paragrahs in each admonition
+are identical.
+
+default-admonition-outer-block
+------------------------------
+
+:fo: block
+
+:docutils: None
+
+:defaults:
+
+     border-style: solid
+
+     border-width: 1px
+
+     padding: 6pt
+
+     keep-together.within-page: always
+
+Sets up the defaults for the outer blocks of all the admonitions.
+The attributes of this block control the borders and prohibit
+the admonition from breaking across a page.
+
+default-admonition-title-block
+------------------------------
+
+:fo: block
+
+:docutils: None
+
+:defaults:
+
+     space-after: 10pt
+
+     font-size: larger
+
+     color: red
+
+Sets up the defaults for the title blocks of all the admonitions.
+The attributes of this block control the color (red) and font
+size. For certain blocs, the color is set to black (see below).
+
+admonitions outer block
+-----------------------
+
+:fo: fo:block
+
+:docutils: attention | caution | danger | error | hint |
+         important | note | tip | warning |
+         admonitons[@classes='custorm']
+
+:inherits: default-admonition-outer-block
+
+The following attribute sets are identical in nature:
+
+* attention-block
+
+* caution-block
+
+* danger-block
+
+* error-block
+
+* hint-block
+
+* important-block
+
+* note-block
+
+* tip-block
+
+* warning-block
+
+* admonition-custom-block
+
+These attribute-sets format the outer block of all the
+admonitions. By default it puts an border around the text. Use
+this attribute set to set the space before or after, the
+background color, etc.
+
+admonitions title block
+-----------------------
+
+:fo: fo:block
+
+:docutils: attention | caution | danger | error | hint |
+         important | note | tip | warning |
+         admonitons[@classes='custorm']
+
+:inherits: default-admonition-title-block
+
+The following attribute sets are identical in nature:
+
+* attention-title-block
+
+* caution-title-block
+
+* danger-title-block
+
+* error-title-block
+
+* hint-title-block
+
+* important-title-block
+
+* note-title-block
+
+* tip-title-block
+
+* warning-title-block
+
+* admonition-custom-title-block
+
+These attribute-sets format the title block of all the
+admonitions. It sets the color to red.
+
+The attribute-sets ``error-title-block``, ``hint-title-block``,
+``important-title-block``, ``note-title-block``,
+``tip-title-block``, and ``admonition-custom-title-block`` resets
+the color back to black.
+
+admonition-paragraph-block
+--------------------------
+
+:fo: fo:block
+
+:docutils: attention/paragraph|caution/paragraph|etc.
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the paragraphs in the admonitions. A different
+attribute-set formats the first paragraph (see below).
+
+admonition-first-paragraph-block
+--------------------------------
+
+:fo: fo:block
+
+:docutils: attention/paragraph[1]|caution/paragraph[1]|etc.
+
+:defaults:
+
+Formats the first paragraphs in the admonitions. It inherits its
+attributes from the ``admonition-paragraph-block`` and resets the
+``space-before`` property to ``0pt``. It does not make sense to
+modify the attributes in this set directly.
+
+Image and Figure
+================
+
+Attribute sets for Images and Figures. The image property of
+``alt`` and ``target`` are ignored by the stylesheets, since they
+have no use in PDF. In addtion, if the ``align`` is set to
+``top`` or ``bottom``, both properties that have no meaning for
+PDF, the stylesheets will report an error, and if ``strict`` is
+set to ``true``, quit.
+
+Likwise, the figure ``figwidth`` property will be ignored, since
+there is not way to implement this property directy in FO.
+
+In order to control the scaling, alignment, and width of images
+and figures, it is better to use the attribute sets than to try
+to set these properties in RST. The regions of 'image', 'figure',
+'caption', and 'legend' are all wrapped in blocks. Use the
+attribute sets for these blocks to control the properties.
+
+figure-block
+------------
+
+:fo: fo:block
+
+:docutils: figure
+
+:defaults:
+
+Formats the block that wraps the figure. Use this attribute set
+to set properties on the image, caption, and legend, as well as
+to set the space before and after the figure.
+
+image-block
+-----------
+
+:fo: fo:block
+
+:docutils: image
+
+:defaults:
+
+Formats the block that wraps the image, both for an image by
+itself, and for an image included in a figure. Use this attribute
+set to control the space before and after the image, as well as
+to align the image itself.
+
+figure-caption-block
+--------------------
+
+:fo: fo:block
+
+:docutils: figure/caption
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+     font-weight: bold
+
+     font-size: smaller
+
+     text-align: center
+
+Formats the block that wraps the caption.
+
+figure-legend-block
+-------------------
+
+:fo: fo:block
+
+:docutils: figure/legend
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 12pt
+
+Formats the block that wraps the legend. The paragrahs in the
+legend have their own blocks.
+
+legend-paragraph-block
+----------------------
+
+:fo: fo:block
+
+:docutils: figure/legend/paragaph
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the block that wraps the paragraphs in the legend.
+
+legend-first-paragraph-block
+----------------------------
+
+:fo: fo:block
+
+:docutils: figure/legend/paragaph[1]
+
+:inherits: legend-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first block that wraps the paragraphs in the legend.
+
+Body Elements Directives
+========================
+
+Attribute sets for Body Elements Directives.
+
+topic-block
+-----------
+
+:fo: fo:block
+
+:docutils: topic
+
+:defaults:
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+Formats the outermost block of the topic element, which contains
+blocks.
+
+topic-title-block
+-----------------
+
+:fo: fo:block
+
+:docutils: topic/title
+
+:defaults:
+
+     font-weight: bold
+
+     space-after: 12pt
+
+Formats the title of the topic.
+
+topic-paragraph-block
+---------------------
+
+:fo: fo:block
+
+:docutils: topic/paragraph
+
+:defaults:
+
+     space-before: 12pt
+
+     space-after: 0pt
+
+Formats the paragraphs of the topic. A different set of
+attributes formats the first paragraph.
+
+topic-first-paragraph-block
+---------------------------
+
+:fo: fo:block
+
+:docutils: topic/paragraph[1]
+
+:inherits: topic-paragraph-block
+
+:defaults:
+
+Formats the first paragraphs of the topic.
+
+sidebar-block
+-------------
+
+:fo: fo:block
+
+:docutils: sidebar
+
+:defaults:
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+     background-color: #FFFFF0
+
+     padding: 6pt
+
+     start-indent: 10mm
+
+     end-indent: 40mm
+
+Formats the outermost block of the sidebar element, which
+contains blocks. Note that fop does not handle floats, so this
+element is formatted just like a topic block.
+
+sidebar-title-block
+-------------------
+
+:fo: fo:block
+
+:docutils: sidebar/title
+
+:defaults:
+
+     font-weight: bold
+
+     space-after: 12pt
+
+Formats the title of the topic.
+
+sidebar-subtitle-block
+----------------------
+
+:fo: fo:block
+
+:docutils: sidebar/subtitle
+
+:defaults:
+
+     font-weight: bold
+
+     space-after: 12pt
+
+Formats the subtitle of the topic.
+
+sidebar-paragraph-block
+-----------------------
+
+:fo: fo:block
+
+:docutils: sidebar/paragraph
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the paragraphs of the sidebar. A different set of
+attributes formats the first paragraph.
+
+sidebar-first-paragraph-block
+-----------------------------
+
+:fo: fo:block
+
+:docutils: sidebar/paragraph[1]
+
+:inherits: sidebar-paragraph-block
+
+:defaults:
+
+     space-after: 0pt
+
+Formats the first paragraphs of the sidebar.
+
+rubric-block
+------------
+
+:fo: fo:block
+
+:docutils: rubric
+
+:defaults:
+
+     text-align: center
+
+     font-size: larger
+
+     color: red
+
+Formats the rubric.
+
+epigraph-outer-block
+--------------------
+
+:fo: fo:block
+
+:docutils: epigraph
+
+:defaults:
+
+     start-indent: 20mm
+
+     end-indent: 20mm
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+     text-align: right
+
+     font-style: italic
+
+Formats the outermost block of the epigraph element, which
+contains blocks.
+
+epigraph-paragraph-block
+------------------------
+
+:fo: fo:block
+
+:docutils: epigraph/paragraph
+
+:defaults:
+
+     start-indent: inherit
+
+     end-indent: inherit
+
+     space-before: 12pt
+
+Formats the paragraphs of the epigraph. A different set of
+attributes formats the first paragraph.
+
+epigraph-first-paragraph-block
+------------------------------
+
+:fo: fo:block
+
+:docutils: epigraph/paragraph[1]
+
+:inherits: epigraph-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraphs of the epigraph.
+
+epigraph-attribution-block
+--------------------------
+
+:fo: fo:block
+
+:docutils: epigraph/attribution
+
+:defaults:
+
+     text-align: right
+
+Formats the attribution of the epigraph. The parameter
+``text-before-epigraph-attribution`` determines the text to put
+before the attribtion. The default is '—' (an em-dash). To put no
+text before, set this parameter to an empty string.
+
+highlights-outer-block
+----------------------
+
+:fo: fo:block
+
+:docutils: highlights
+
+:defaults:
+
+     start-indent: 20mm
+
+     end-indent: 20mm
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+Formats the outermost block of the epigraph element, which
+contains blocks.
+
+highlights-paragraph-block
+--------------------------
+
+:fo: fo:block
+
+:docutils: highlights/paragraph
+
+:defaults:
+
+     start-indent: inherit
+
+     end-indent: inherit
+
+     space-before: 12pt
+
+Formats the paragraphs of the highlights. A different set of
+attributes formats the first paragraph.
+
+highlights-first-paragraph-block
+--------------------------------
+
+:fo: fo:block
+
+:docutils: highlights/paragraph[1]
+
+:inherits: highlights-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraphs of the highlights.
+
+pull-quote-outer-block
+----------------------
+
+:fo: fo:block
+
+:docutils: pull-quote
+
+:defaults:
+
+     start-indent: 20mm
+
+     end-indent: 20mm
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+Formats the outermost block of the pull-quote element, which
+contains blocks.
+
+pull-quote-paragraph-block
+--------------------------
+
+:fo: fo:block
+
+:docutils: pull-quote/paragraph
+
+:defaults:
+
+     start-indent: inherit
+
+     end-indent: inherit
+
+     space-before: 12pt
+
+Formats the paragraphs of the pull-quote. A different set of
+attributes formats the first paragraph.
+
+pull-quote-first-paragraph-block
+--------------------------------
+
+:fo: fo:block
+
+:docutils: pull-quote/paragraph[1]
+
+:inherits: pull-quote-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraphs of the pull-quote.
+
+pull-quote-attribution-block
+----------------------------
+
+:fo: fo:block
+
+:docutils: pull-quote/attribution
+
+:defaults:
+
+     text-align: right
+
+Formats the attribution of the pull-quote. The parameter
+``text-before-pull-quote-attribution`` determines the text to put
+before the attribtion. The default is '—' (an em-dash). To put
+no text before, set this parameter to an empty string.
+
+container-outer-block
+---------------------
+
+:fo: fo:block
+
+:docutils: container
+
+:defaults:
+
+     space-after: 12pt
+
+     space-before: 12pt
+
+Formats the outermost block of the container element, which
+contains blocks.
+
+container-paragraph-block
+-------------------------
+
+:fo: fo:block
+
+:docutils: container/paragraph
+
+:defaults:
+
+     space-before: 12pt
+
+Formats the paragraphs of the container. A different set of
+attributes formats the first paragraph.
+
+container-first-paragraph-block
+-------------------------------
+
+:fo: fo:block
+
+:docutils: container/paragraph[1]
+
+:inherits: container-paragraph-block
+
+:defaults:
+
+     space-before: 0pt
+
+Formats the first paragraphs of the container.
+
+Inline
+======
+
+Attribute sets for all the inline elements. The parameter
+'footnote-style' controls the style of the footnote. The
+paramater 'footnote-placement' determines whether the footnotes
+that are numbered will be placed as footnotes or endnotes.
+
+The parameter 'space-between-foototes' controls the space between
+footnotes. (Becuase of a flaw(?) in FOP, an attribute set could
+not be used.) This parameter has no effect on the space between
+endnotes.
+
+emphasis-inline
+---------------
+
+:fo: fo:inline
+
+:docutils: emphasis
+
+:defaults:
+
+     font-style: italic
+
+Formats the emphasis element.
+
+strong-inline
+-------------
+
+:fo: fo:inline
+
+:docutils: strong
+
+:defaults:
+
+     font-weight: bold
+
+Formats the strong element.
+
+basic-link-inline
+-----------------
+
+:fo: fo:inline
+
+:docutils: basic_link
+
+:defaults:
+
+     text-decoration: underline
+
+     color: blue
+
+Formats the basic_link element.
+
+literal-inline
+--------------
+
+:fo: fo:inline
+
+:docutils: literal
+
+:defaults:
+
+     font-family: monospace
+
+     font-size: 8
+
+     white-space: pre
+
+Formats the literal element.
+
+title-reference-inline
+----------------------
+
+:fo: fo:inline
+
+:docutils: title-reference
+
+:defaults:
+
+     font-style: italic
+
+Formats the title_reference element.
+
diff --git a/sandbox/paultremblay/python_interface/docs/rst/howto.rst b/sandbox/paultremblay/python_interface/docs/rst/howto.rst
new file mode 100644
index 000000000..e7fa31e5f
--- /dev/null
+++ b/sandbox/paultremblay/python_interface/docs/rst/howto.rst
@@ -0,0 +1,2220 @@
+^^^^^^^^^^^^^^^^^^^^^^^^
+HOWTO: Docutils2fo 0.6
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+..  $Id$ 
+
+.. contents::
+
+================
+Convert to XML
+================
+
+Use the rst2xml.py script, and pass the the ``'--strip-comments'`` and 
+``'--trim-footnote-reference-space'`` options::
+
+ rst2xml.py --strip-comments --trim-footnote-reference-space my_file.rst > my_file.xml
+
+================
+Convert to FO 
+================
+
+Use the docutils_to_fo.py script::
+
+ docutils_to_fo.py  my_file.xml > my_file.fo
+
+Use the ``'--help'`` option to get options.
+
+Alternatively, you can convert from RST to FO in one step::
+
+ rst2xml.py --strip-comments --trim-footnote-reference-space my_file.rst | docutils_to_fo.py > my_file.fo
+
+================
+Convert to PDF 
+================
+
+Use the fop processor, an open source Java application at http://xmlgraphics.apache.org/fop/.
+In order to run in from a unix system::
+
+ fop my_file.fo my_file.pdf
+
+To convert from RST to PDF with one command::
+
+ rst2xml.py --strip-comments --trim-footnote-reference-space my_file.rst\
+ | docutils_to_fo.py | fop -fo - my_file.pdf
+
+===================
+Format a Document
+===================
+
+1. Create a config file that with a section and instructions (as explained
+   below)::
+
+    [FO]
+
+    paragraph.space-before = 12pt
+
+
+2. Enable the ``'docutils_to_fo'`` script to read the config file. Either pass 
+   the ``'--config'`` option::
+
+     docutils_to_fo.py  --config my_config_file my_file.xml > my_file.fo
+
+  or put this file where the script automatically reads it, either in 
+  ``./docutils.conf``, or ``~/home/.docutils``. 
+
+Unless otherwise noted, the rest of this document refers to creating the
+config file.
+
+==================
+Create a Command
+==================
+
+Commands consist of instructions without a period in them. The following
+sets ``'strict'`` = ``'True'``, making the processing quit when an error is 
+encountered::
+
+ strict = True 
+
+ 
+
+================================
+Create a Formatting Instruction
+================================
+
+Formatting instructions consist of 3 parts: the region to be formatted,
+followed by a period; the formatting property, followed by an equal sign; and
+the value of the property. The following command sets the space before plain
+paragrahs to 12pt::
+
+ paragraph.space-before = 12pt
+
+.. tip::
+
+ You can use the config file to pass commonly-used options of the 
+ rst2xml.py command. Put these commands in the *general* section::
+
+   [general]
+
+   strip_comments = true
+   trim-footnote-reference-space = true
+
+   [FO]
+   paragraph.space-before = 12pt
+
+
+==============================
+General Formatting for Blocks
+==============================
+
+Most of the regions in a docutils document consists of blocks. This is true of
+the title, subtitle, section titles, paragrahs, block quotes, etc. All of thes
+blocks can take the following properties:
+
+* space-before
+* space-after
+* first-line-indent
+* font (the same as font-family)
+* font-size
+* font-style
+* color (for the color of the text)
+* backgroud-color
+* left-indent 
+* right-indent 
+* border (for the boders around the block) 
+* line-spacing (for double space, for exampe)
+* alignment 
+* keep-with-next (to keep the block from ending a page)
+* keep-with-previous (to keep the block from starting a new page)
+* keep-on-same-page (to prevent a block form splitting across a page)
+* page-break-before (to create page breaks) 
+* page-break-after (to create page breaks) 
+
+These properties are the most commonly used and have an easy-to-remember,
+short name. In addition, one can use any of the valid FO properties, which can
+be found, among other places, at http://www.w3schools.com/xslfo/obj_block.asp.
+For example, ``'paragraph.border-before-color = red'`` specifies the color of the 
+border on the before-edge for plain paragraphs.
+
+============
+Page Layout
+============
+
+Paper Size
+-----------
+
+::
+
+ paper-size.height = 11in
+ paper-size.width = 8.5in
+
+Margins
+---------
+::
+
+ page.top-margin = .75in
+ page.bottom-margin = .75in
+ page.right-margin = .75in
+ page.left-margin = .75in
+
+Different Margins for Odd and Even Pages (if desired)
+------------------------------------------------------
+::
+
+ odd-page.top-margin = 1in
+ odd-page.bottom-margin = 1in
+ odd-page.right-margin = 1in
+ odd-page.left-margin = 2in
+ 
+ even-page.top-margin = 1in
+ even-page.bottom-margin = 1in
+ even-page.right-margin = 2in
+ even-page.left-margin = 1in
+
+Different Margins for the First Page (if desired)
+---------------------------------------------------
+::
+
+ first-page.top-margin = 3in
+ first-page.bottom-margin = 1in
+ first-page.right-margin = .8in
+ first-page.left-margin = 2in
+
+
+====================
+Headers and Footers
+====================
+
+Create a header
+---------------
+
+In the *document* (not the config file), use the following::
+
+ .. header:: 
+
+    A Christmas Carol 
+
+The header will appear on every page, including any pages in the table
+of contents section.
+
+Create a footer
+---------------
+
+In the *document* (not the config file), use the following::
+
+ .. footer:: 
+
+    Charles Dickens 
+
+The footer will appear on every page, including any pages in the table
+of contents section.
+
+Create a page number in a header or footer
+--------------------------------------------
+
+In the *document* (not the config file), use the following::
+
+ .. role:: page-num
+    
+ .. footer:: 
+
+    Charles Dickens.
+    
+    :page-num:`1`
+
+Page numbers will be generated automatically.
+
+Create space for a header or footer
+------------------------------------
+
+The defaults should create enough space for headers or footers. If you want to
+change the defaults, use::
+
+ header.height = 1in
+ footer.height = 1in
+
+
+Create space between header and body text
+------------------------------------------
+
+::
+
+ header.space-before = .2in
+    
+Create space between footer and body text
+------------------------------------------
+
+::
+
+ footer.space-before = -.1in
+
+Format header and footer text
+------------------------------
+
+If your header or footer contains just one paragraphs, use the header or
+footer region plus any block property::
+
+ header.color = blue
+ header.background-color = black
+
+
+Create custom headers and footers for odd, even, etc.
+--------------------------------------------------------
+
+You can create different headers and footers for the following
+regions:
+
+* first page of the body
+* odd page of the body
+* even page of the body
+* first page of the table of contents section
+* odd page of the table of contents section
+* even page of the table of contents section
+
+These headers and footers can be formatted all at once, using the ``'header'``
+and ``'footer'`` identifiers. By default, these headers and footers are all
+centered. However, each inidividua header and footer can be customized, as
+shown below.
+
+Create a different header for the first and subsequent pages
+-------------------------------------------------------------
+
+In the *document* set up the headers and footers::
+
+
+ .. container:: first-header
+ 
+  first header text
+ 
+ .. container:: first-footer
+ 
+  first footer text
+ 
+ .. container:: body-header
+ 
+  body header
+ 
+ .. container:: body-footer
+ 
+  body footer
+
+Use ``'first-header'``, ``'first-footer'``, ``'body-header'`` and
+``'body-footer'`` to format these headers and footers::
+
+ body-header.color = red
+ body-footer.color = red
+ first-header.background-color = red
+ first-footer.background-color = red
+
+Create a different header for odd and even pages
+-------------------------------------------------
+
+In the *document* set up the headers and footers::
+
+
+ .. container:: odd-header
+ 
+  odd header
+ 
+ .. container:: odd-footer
+ 
+  odd footer
+ 
+ .. container:: even-header
+ 
+  even header
+ 
+ .. container:: even-footer
+ 
+  even footer
+
+Use ``'odd-header'``, ``'odd-footer'``, ``'even-header'`` and
+``'even-footer'`` to format these headers and footers::
+
+ odd-header.color = red
+ odd-footer.color = red
+ even-header.background-color = red
+ even-footer.background-color = red
+
+Create a different header for first, odd and even pages
+--------------------------------------------------------
+
+In the *document* set up the headers and footers::
+
+ .. container:: first-header
+ 
+  first header text
+ 
+ .. container:: first-footer
+ 
+  first footer text
+
+ .. container:: odd-header
+ 
+  odd header
+ 
+ .. container:: odd-footer
+ 
+  odd footer
+ 
+ .. container:: even-header
+ 
+  even header
+ 
+ .. container:: even-footer
+ 
+  even footer
+
+Use ``'first-header'`` ``'first-footer'``, ``'odd-header'``,
+``'odd-footer'``, ``'even-header'`` and ``'even-footer'`` to format
+these headers and footers::
+
+ first-header.font-style = italic
+ first-footer.font-style = italic
+ odd-header.color = red
+ odd-footer.color = red
+ even-header.background-color = red
+ even-footer.background-color = red
+
+Suppress first page header or footer
+--------------------------------------
+
+For simple pages
++++++++++++++++++
+
+Use the following method if you want the same headers and footers on
+all pages except the first. In the *document* create headers and
+footers for the body, but not for the first page::
+
+ .. container:: body-header
+ 
+  body header
+ 
+ .. container:: body-footer
+ 
+  body footer
+
+For odd and even pages if using standard page margins
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Use the following method if (1) you wish to have different headers and
+footers on odd and even pages, but no headers and footers on the first
+page; and (2) you have the same margins for odd and even pages.
+
+1. First, tell the formatter you desire a first-odd-even layout.
+   (Without specifying this explicitly, the formatter will simply
+   think you want an odd-even layout.)::
+
+     document.page-layout = first-odd-even
+
+2. Create odd and even headers, without creating any first headers
+   and footers::
+
+    .. container:: odd-header
+    
+     odd header
+    
+    .. container:: odd-footer
+    
+     odd footer
+    
+    .. container:: even-header
+    
+     even header
+    
+    .. container:: even-footer
+    
+     even footer
+
+For odd and even pages if using custom page margins
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Use the following method if (1) you wish to have different headers and
+footers on odd and even pages, but no headers and footers on the first
+page; and (2) you have different margins for odd and even pages.
+
+1. First, set the margins for the first page to that of the odd page.
+   (This step tells the formatter that set the page layout to
+   first-odd-even, the layout desired; and it makes sure the first,
+   odd page, is identical to the other odd pages.)  
+   
+::
+
+     first-page.top-margin = .75in
+     # etc.
+
+2. Create odd and even headers, without creating any first headers
+   and footers::
+
+    .. container:: odd-header
+    
+     odd header
+    
+    .. container:: odd-footer
+    
+     odd footer
+    
+    .. container:: even-header
+    
+     even header
+    
+    .. container:: even-footer
+    
+     even footer
+
+
+Create a different header for the first and subsequent pages for the TOC
+-------------------------------------------------------------------------
+
+In the *document* set up the headers and footers::
+
+
+ .. container:: toc-first-header
+ 
+     First header 
+     
+ .. container:: toc-first-footer
+ 
+     First footer
+     
+ .. container:: toc-body-header
+ 
+     Body header 
+     
+ .. container:: toc-body-footer
+ 
+     Body footer
+    
+
+Use ``'toc-first-header'``, ``'toc-first-footer'``, ``'toc-body-header'`` and
+``'toc-body-footer'`` to format these headers and footers::
+
+ toc-body-header.color = red
+ toc-body-footer.color = red
+ toc-first-header.background-color = red
+ toc-first-footer.background-color = red
+
+Create a different header for odd and even pages for the TOC
+--------------------------------------------------------------
+
+In the *document* set up the headers and footers::
+
+
+ .. container:: toc-odd-header
+ 
+  odd header
+ 
+ .. container:: toc-odd-footer
+ 
+  odd footer
+ 
+ .. container:: toc-even-header
+ 
+  even header
+ 
+ .. container:: toc-even-footer
+ 
+  even footer
+
+Use ``'toc-odd-header'``, ``'toc-odd-footer'``, ``'toc-even-header'`` and
+``'toc-even-footer'`` to format these headers and footers::
+
+ toc-odd-header.color = red
+ toc-odd-footer.color = red
+ toc-even-header.background-color = red
+ toc-even-footer.background-color = red
+
+Create a different header for first, odd and even pages for the TOC
+--------------------------------------------------------------------
+
+In the *document* set up the headers and footers::
+
+ .. container:: toc-first-header
+ 
+  first header text
+ 
+ .. container:: toc-first-footer
+ 
+  first footer text
+
+ .. container:: toc-odd-header
+ 
+  odd header
+ 
+ .. container:: toc-odd-footer
+ 
+  odd footer
+ 
+ .. container:: toc-even-header
+ 
+  even header
+ 
+ .. container:: toc-even-footer
+ 
+  even footer
+
+Use ``'toc-first-header'`` ``'toc-first-footer'``, ``'toc-odd-header'``,
+``'toc-odd-footer'``, ``'toc-even-header'`` and ``'toc-even-footer'`` to format
+these headers and footers::
+
+ toc-first-header.font-style = italic
+ toc-first-footer.font-style = italic
+ toc-odd-header.color = red
+ toc-odd-footer.color = red
+ toc-even-header.background-color = red
+ toc-even-footer.background-color = red
+
+Suppress first page header or footer for the TOC
+-------------------------------------------------
+
+Follow the same procedures as for the body. To supress the header and
+footer when the headers and footers are otherwise the same for all
+pages, create body headers and footers for the toc, but not for the
+first page::
+
+ .. container:: toc-body-header
+ 
+     Body header 
+
+To suppress when using different headers and footers for odd and even
+pages, set up the odd and even headers/footers, and then signal to the
+formatter that you wish for a first-odd-even layout, either through
+the ``'document.page-layout'`` property, or by setting margins for the
+first page.
+
+
+Formatting the paragraphs in headers and footers
+--------------------------------------------------
+
+Use the header-paragraph and footer-paragraph to format paragraphs:: 
+
+ header-paragraph.font-style = bold
+ footer-paragraph.font-style = italic
+
+
+================
+Non Body Matter
+================
+
+Non Body matter refers to the document title and subtitle; the
+bibliographic fields; the dedication; the abstract; and the table of
+contents. 
+
+Each such matter can be put in the front part, the toc (table of
+contents) part, or the body part. 
+
+The front part of a document occurrs first and has not headers or
+footers. The toc part occurrs next, generally starts with page 1
+(thought this can be changed), and page numberas are  formamtted with
+Roman numberals (though this can be changed.)
+
+The body part is part of any document. It generally starts with page 1
+(though this can be changed) and page numbers are formatted with
+Arabic numbers (though this can be changed).
+
+Placing the title/subtitle
+---------------------------
+
+With the front part (default)
++++++++++++++++++++++++++++++++
+
+::
+
+ title-subtitle.placement = with-front
+
+With the toc part
+++++++++++++++++++
+
+::
+
+ title-subtitle.placement = with-toc
+
+With the body part
++++++++++++++++++++
+
+::
+
+ title-subtitle.placement = with-body
+
+Placing the bibliograph fields
+-------------------------------
+
+With the front part 
+++++++++++++++++++++
+
+::
+
+ bibliographic-fields.placement = with-front
+
+With the toc part (default)
+++++++++++++++++++++++++++++
+
+::
+
+ bibliographic-fields.placement = with-toc
+
+With the body part
++++++++++++++++++++
+
+::
+
+ bibliographic-fields.placement = with-body
+
+Placing the dedication
+-----------------------
+
+With the front part 
+++++++++++++++++++++
+
+::
+
+ dedication.placement = with-front
+
+With the toc part (default)
+++++++++++++++++++++++++++++
+
+::
+
+ dedication.placement = with-toc
+
+With the body part
++++++++++++++++++++
+
+::
+
+ dedication.placement = with-body
+
+Placing the abstract
+-----------------------
+
+With the front part (default)
+++++++++++++++++++++++++++++++
+
+::
+
+ abstract.placement = with-front
+
+With the toc part 
+++++++++++++++++++
+
+::
+
+ abstract.placement = with-toc
+
+With the body part
++++++++++++++++++++
+
+::
+
+ abstract.placement = with-body
+
+Placing the toc
+----------------
+
+With the front part 
+++++++++++++++++++++
+
+::
+
+ toc.placement = with-front
+
+With the toc part 
+++++++++++++++++++
+
+::
+
+ toc.placement = with-toc
+
+With the body part
++++++++++++++++++++
+
+::
+
+ toc.placement = with-body
+
+Changing the order of non-body matter
+---------------------------------------
+
+By default, docutils to fo places the non-body matter in the order it
+occurrs in the docutils XML document (which may be different than the
+RST document). This order is title/subtitle, bibliographic,
+dedication, and table of contents. To change this order, use the
+``'front.order'`` property. Its value is a list of the non-body order
+areas in the order you wish it to occurr, speparated by commas::
+
+ # changes the order of the abstract and the bibliographic fields
+ front.order = title, abstract, dedication, toc, bibliographic
+
+Changing the starting page number
+----------------------------------
+
+In order to change the starting page number of a toc section or body
+section, use the ``'toc-section.start-page'`` or
+``'body-section.start-page'`` properties::
+
+ # toc now start on page 3
+ toc-section.start-page = 3
+ # body starts on page 15
+ body-section.start-page = 15
+
+Changing the format of the page number
+----------------------------------------
+
+In order to change the formatting of the page numbers, use the
+``'toc-section.page-format'`` and ``'body-section.page-format'``::
+
+ # upper case Roman numberals
+ toc-section.page-format = I
+ # upper case letters
+ body-section.page-format = A
+
+Formatting the title/subtitle
+------------------------------
+
+Use the property ``'title-subtitle'`` to format both the title and
+subtitle. Use the property ``'title'``  to format just the title. Use the
+property ``'subtitle'`` to format just the subtitle. All of these
+properites are block properties, and can take any of the
+properites of a block (see paragraph)::
+
+ # center the title an subtitle
+ title-subtitle.alignment = center
+ # format the title
+ title.font-size = 24pt
+ # format the subtitle
+ subtitle.font-size = 18pt
+
+To create space before a title/subtitle, and to put the title/subtitle
+on their own page::
+
+ title-subtitle.page-break-before= true
+ title-subtitle.space-before=3in
+
+===================================
+Formatting the bibliograhic fields
+===================================
+
+Formatting as a list
+---------------------
+
+By defaullt, bibliographic fields are formatted as a list. Use the
+``'bibliograhic-fields'`` property to format the space after and before, the
+left and right indent, and any other property you want to set on the list,
+such as font for font-size::
+
+ bibliographic-fields.space-after = 20pt
+ bibliographic-fields.space-before = 20pt
+ bibliographic-fields.left-indent = 20pt
+ bibliographic-fields.right-indent = 20pt
+ bibliographic-fields.background-color = grey
+
+Putting the bibliographic fields on its own page
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+::
+
+ bibliographic-fields.page-break-before = true
+ # or, depending on your layout
+ bibliographic-fields.page-break-after = true
+
+
+To format space between items
+++++++++++++++++++++++++++++++
+
+Use the ``'space-between-items'`` property.
+
+::
+
+
+  bibliographic-fields.space-between-items = 30pt
+
+To format space between field and text
++++++++++++++++++++++++++++++++++++++++
+
+The ``'space-from-fields'`` works exactly as the ``'space-from-bullet''``: both
+properties control the spacing from the list label and the text.
+
+::
+
+  bibliographic-fields.space-from-field = 3in
+
+Formatting the field
+++++++++++++++++++++++
+
+Use the ``'bibliographic-field'`` property, and apply any block properties.
+Note the slight, one letter difference between ``'bibliographic-fields``, which
+formats the entire list, and ``'bibliographic-field'`` which formats just the
+field::
+
+ # change default font to normal
+ bibliographic-field.font-style = normal
+
+Changing the default text of the fields
++++++++++++++++++++++++++++++++++++++++++
+
+By default, the docutils to FO converter gives expected names to each of the
+bibliographic fields. If you wish to change the name, use the
+``'bibliographic-fields.<fieldname-text>`` property::
+
+  # change all the fields from the default to lower case
+  bibliographic-fields.author-text = author
+  bibliographic-fields.authors-text = authors
+  bibliographic-fields.organization-text = organization
+  # change 'contact' to 'email'
+  bibliographic-fields.contact-text = email
+  bibliographic-fields.status-text = status
+  bibliographic-fields.copyright-text = copyright
+  bibliographic-fields.address-text = address
+  bibliographic-fields.revision-text = revision
+  bibliographic-fields.date-text = date
+
+Formatting the text of the field
++++++++++++++++++++++++++++++++++++
+
+Use the ``'bibliographic-fields-text'`` identifier::
+
+ bibliographic-fields-text.font-weight=bold
+
+Formatting the text for individual paragraphs
++++++++++++++++++++++++++++++++++++++++++++++
+
+For fields that have more than one paragraph, use the ``'bibliographic-fields-paragraph'``
+identifier. This identifier can take any block property::
+
+ bibliographic-fields-paragraph.space-before = 12pt
+
+Note that using the ``'space-before'`` property has the same effect as
+controlling the space between each paragraph, without putting unwated space
+before the first paragraph. 
+
+Formatting as blocks of text
+-----------------------------
+
+Use ``'the bibliographic-fields.format'`` to change the value of the default
+format::
+
+ bibliographic-fields.format = normal
+
+Formatting the author field, etc.
+----------------------------------
+
+Each bibliographic field is a block, and its identifier is the name of the
+field . 
+
+:address: formats the address field
+:author: formats the author field
+:authors: formats the authors field
+:contact: formats the contact field
+:copyright: formats the copyright field
+:date: formats the date field
+:organization: formats the organization field
+:revision: formats the revision field
+:status: formats the status field
+:version: formats the version field
+
+::
+
+ address.space-before=24pt
+ author.font-style = bold
+ authors.alignment = center
+ contact.font-style = italic
+ copyright.color = red
+ date.background-color = blue
+ organization.font-size = 24pt
+ revision.alignment = center
+ status.alignment = right
+ version.font-style = bold-italic
+        
+
+Formatting custom bibliographic fields
+----------------------------------------
+
+Use the ``'bibliographic-fields-custom1'``,
+``'bibliographic-fields-custom2'``, etc, to format each custom field, where
+``'-custom1'`` refers to the first occurrence of a custom field,
+''`-custom2'`` refers to the second such occurrence, and so on:: 
+
+ bibliographic-field-custom1.color = green
+ bibliographic-field-custom2.color = red
+
+Changing the default text of the fields
++++++++++++++++++++++++++++++++++++++++++
+
+As when the bibliiographic fields are formatted as a list, the text of the
+fields can likewise be changed in the same manner when formatting the
+bibliographic fields as blocks. It often makes sense to makes these fields
+empty, especially when creating title page::
+
+  bibliographic-fields.author-text = by
+  bibliographic-fields.date-text = 
+
+Including text for custom fields
++++++++++++++++++++++++++++++++++
+
+Use the ``'bibliographic-field-custom#.text'`` property::
+
+ bibliographic-field-custom1.text = Country
+ bibliographic-field-custom2.text = Uses of software: 
+
+Making a Title Page
+--------------------
+
+Here is the actual RST document::
+
+ ======
+ Title
+ ======
+ 
+ Subtitle
+ =========
+ 
+ 
+ :by: by
+ :Author: Paul Tremblay
+ :Address: Paul Tremblay 
+           100 Market St. 
+           Boston, MA, 01800
+ 
+ :Country: USA
+ :Organization: Open Source Software
+ :useline: Uses
+ :Uses: text processing
+ 
+        documentation
+ :Date: $Date$
+ :Copyright: This document is in the public domain
+ 
+ Text after.
+
+Here is the configuration file::
+
+ [general]
+ trim-footnote-reference-space = true
+ [FO]
+ bibliographic-fields.format = normal
+ 
+ # the by line by itself
+ bibliographic-field-custom1.space-after = 12pt
+ bibliographic-field-custom1.alignment = center
+
+ # the line with 'usline' 
+ bibliographic-field-custom3.space-after = 0pt
+ bibliographic-field-custom3.font-style = bold
+
+ # the Uses field
+ bibliographic-field-custom4.space-before = 0pt
+
+ # center align author
+ author.alignment = center
+ author.font-size = 16pt
+ # put a border after the title
+ author.border-bottom = 2px solid
+ author.padding = 6pt
+
+ # put a borer after copyright
+ copyright.border-bottom = 2px solid
+ copyright.padding = 6pt
+ 
+ 
+ 
+ # set the default text to nothing
+ bibliographic-fields.author-text =
+ bibliographic-fields.authors-text = 
+ bibliographic-fields.organization-text = 
+ bibliographic-fields.copyright-text = 
+ bibliographic-fields.address-text = 
+ bibliographic-fields.date-text = 
+
+ # commands
+ strict = True
+
+
+Formatting the dedication
+--------------------------
+
+Creating a dedication
++++++++++++++++++++++++
+
+::
+
+ :Dedication: I dedicate this thesis to my good friend John, who
+   stood by me for many years while I struggled ...
+
+Putting dedication on its own page
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+::
+
+ dedication.page-break-before = true
+ # or, depending on your layout
+ dedication.page-break-after = true
+
+Formatting the title
++++++++++++++++++++++++
+
+Use the ``'dedication-title'`` identifier, which can take any block property::
+
+ dedication-title.alignment = center
+ dedication-title.font-size = 24pt
+
+Formatting the paragraphs
+++++++++++++++++++++++++++
+
+Use the ``'dedication-paragraph'`` identifier, which can take any block property::
+
+ dedication-paragraph.font-size = 10pt
+ dedication-paragraph.alignment = right
+ dedication-paragraph.font-style = italic
+
+
+Formatting the abstract
+--------------------------
+
+Creating a abstract
++++++++++++++++++++++++
+
+::
+
+
+ :Abstract: Just an example of bibliograhic fields.
+  This continues on.
+
+Putting abstract on its own page
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+::
+
+ abstract.page-break-before = true
+ # or, depending on your layout
+ abstract.page-break-after = true
+
+Formatting the title
++++++++++++++++++++++++
+
+Use the ``'abstract-title'`` identifier, which can take any block property::
+
+ abstract-title.alignment = center
+ abstract-title.font-size = 24pt
+
+Formatting the paragraphs
+++++++++++++++++++++++++++
+
+Use the ``'abstract-paragraph'`` identifier, which can take any block property::
+
+ abstract-paragraph.font-size = 10pt
+ abstract-paragraph.alignment = right
+ abstract-paragraph.font-style = italic
+
+
+Formatting the toc
+--------------------------
+
+Creating a toc
++++++++++++++++++++++++
+
+::
+
+ .. contents:: Table of Contents
+
+Putting toc on its own page
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+::
+
+ toc.page-break-before = true
+ # or, depending on your layout
+ toc.page-break-after = true
+
+Formatting the title
++++++++++++++++++++++++
+
+Use the ``'toc-title'`` identifier, which can take any block property::
+
+ toc-title.alignment = center
+ toc-title.font-size = 24pt
+
+Setting the defaults on each entry
+++++++++++++++++++++++++++++++++++++
+
+Use the ``'toc-default'`` to set properties for all of the toc entries
+at once::
+
+
+ # sets space between entries to 12pt
+ toc-default.space-after = 12pt
+
+
+Formatting the entries
+++++++++++++++++++++++++++
+
+Use the identifierst ``'toc-entry1'``, ``'toc-entry2'``, etc.
+which can take any block property::
+
+ # increase indents by 10mm
+ toc-entry1.left-indent = 10mm
+ toc-entry2.left-indent = 20mm
+ toc-entry3.left-indent = 30mm
+ toc-entry4.left-indent = 40mm
+ toc-entry5.left-indent = 50mm
+
+
+Format the toc numbers
++++++++++++++++++++++++
+
+The format of the numbers for toc entry takes the same format as the
+section numbers. See section numbers.
+
+=========
+Sections
+=========
+
+Creating sections
+------------------
+
+Sections are identified through their titles, which are marked up with
+adornment: "underlines" below the title text, or underlines and matching
+"overlines" above the title.
+
+
+Here are some examples::
+
+ ===============
+ Heading1 Title
+ ===============
+ 
+ ---------------
+ Heading2 Title
+ ---------------
+ 
+ Heading3 Title
+ =============
+ 
+ Heading4 Title
+ -------------
+ 
+ Heading5 Title
+ `````````````
+ 
+ Heading6 Title
+ '''''''''''''
+ 
+ Heading7 Title
+ .............
+ 
+Any combination of valid adornments can be used. The rst2xml.py utility
+recognizes the first such example as the main section, the next such example
+as the sub section, and so on.
+
+See the http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections.
+
+
+Formatting titles
+-------------------
+
+Use the identifiers ``'heading1'``, ``'heading2'``, ``'heading3'``, etc, to
+format the titles for each section. Docutils to fo allows sections to go 7
+levels deep. Headings are blocks and can take any property of a block (see
+paragrahs). 
+
+::
+
+ heading1.font-size = 30pt
+ heading1.font-style = bold
+ heading2.font-size = 24pt
+ # etc.
+ heading7.font-size = normal
+ heading7.font-style = bold
+
+Creating section numbers
+-------------------------
+
+At the start of the document, put::
+
+ .. sectnum::
+
+Formatting section numbers
+---------------------------
+
+Use the ``'heading#'`` identifier plus the ``'number-format'`` to format the
+section numbers. The value for formatting can take a combination of
+punctuation and numbers, letters, or Roman numberals
+
+::
+
+ # (I.), (II.), (III.), etc
+ heading1.number-format = (I.)
+
+ # i.), ii.), etc 
+ heading2.number-format = i.)
+
+ # .1., .2., .3., etc
+ heading3.number-format = .1.
+
+ # a, b, c, etc
+ heading4.number-format = a
+
+ # A, B, C., etc
+ heading5.number-format = A
+
+.. Don't inherit section numbers
+.. ------------------------------
+.. 
+.. By default, the numbers of each section inherit the numbers of the parent
+.. section. to disable this formatting::
+.. 
+..  headings.inherit-sections-number = False
+
+============
+Transitions
+============
+
+Creating transitions
+---------------------
+
+To create a transition, in the *document* (not the config file), use
+horizontal line of 4 or more repeated punctuation characters.
+
+::
+
+
+ Para.
+
+ ----------
+
+ Para.
+
+Changing the text of the transtion.
+-------------------------------------
+
+The default transition text is a single paragraph of three asteristics. To
+change the default, use the ``'transition.text'`` property::
+
+ # change to three hypens
+ transition.text = ---
+ # change to nothing
+ transition.text = 
+
+Formatting the transition paragraph
+------------------------------------
+
+Use the ``'transition'`` identifier to format the paragraph of the transition
+text. This identifier can take any block property.
+
+::
+
+ transition.space-before = 24pt
+ transition.space-after = 24pt
+ # change the default alignment from center
+ transition.alignment = left
+
+
+===========
+Paragraphs
+===========
+
+Space before or after paragraphs
+---------------------------------
+
+::
+
+ paragraph.space-before = 12pt
+ paragraph.space-after = 12pt
+
+Indent first line
+-------------------
+
+::
+
+ paragraph.first-line-indent = 12pt
+
+Font Family
+-------------
+
+::
+
+ paragraph.font = monospace
+
+Font Size
+----------
+
+::
+
+ paragraph.font-size = 12pt
+
+Font Style
+-----------
+
+Set ``'font-style'`` to ``'bold'``, ``'italic'``, ``'bold-italic'``,
+or ``'normal'``::
+
+ paragraph.font-style = bold-italic
+
+Color (font color)
+-------------------
+
+::
+
+ paragraph.color = red
+
+Background color
+------------------
+
+::
+
+ paragraph.backgroud-color = red
+
+Left and right indent
+----------------------
+
+::
+
+ paragraph.left-indent = 12pt 
+ paragraph.right-indent = 12pt 
+
+Borders
+---------
+
+::
+
+ paragraph.border = solid black 1px
+
+Use ``'border-top'``, ``'border-bottom'``, ``'border-left'``, and
+``'border-right'`` to set properties on specific borders::
+
+ # creates a bottom border
+ paragraph.border-bottom = solid black 1px
+
+Line spacing
+--------------
+
+::
+
+ # double spaces paragraphs
+ paragraph.line-spacing  = 2
+
+Alignment
+-----------
+
+Use ``'alignment'`` to align text. Valid values are ``'left'``,
+``'right'``, ``'center'``, and ``'justify'``.
+
+::
+
+ # center aligns text
+ paragraph.alignment = center
+
+Keep with previous text
+-------------------------
+
+::
+
+ # paragrah won't start a new page
+ keep-with-previous = true
+
+Keep  with next text
+----------------------
+
+::
+
+ # paragrah won't end the page
+ keep-with-next = true
+
+Keep from breaking across pages
+---------------------------------
+::
+
+ keep-on-same-page = true
+
+
+Page break before or after
+----------------------------
+
+::
+
+ paragraph.page-break-before = yes
+ paragraph.page-break-after = yes
+
+
+No page break before or after
+-------------------------------
+
+::
+
+ paragraph.page-break-after = no
+ paragraph.page-break-before = no
+
+Formatting for first paragrahs
+--------------------------------
+
+Docutils to FO allows first paragraphs to be formatted differently
+from all others. First paragraphs refers to the first paragraphs after
+a section of document, or the first paragaph after a list, code block,
+admonition block, or table. British style dictates that such
+paragraphs do not have their first line indented. 
+
+::
+
+ #indents all but first paragraph 12pt
+ paragraph.first-line-indent = 12pt
+ first-paragraph.first-line-indent = 0pt
+
+============
+Bullet List
+============
+
+
+Formatting the bullet list
+----------------------------
+
+Use the ``'bullet-list'`` property to format the space after and
+before, the left and right indent, and any other property you want to
+set on the list, such as font for font-size::
+
+ bullet-list.space-after = 20pt
+ bullet-list.space-before = 20pt
+ bullet-list.left-indent = 20pt
+ bullet-list.right-indent = 20pt
+ bullet-list.background-color = grey
+
+
+To format space between items
+-------------------------------
+
+Use the ``'space-between-items'`` property.
+
+::
+
+
+  bullet-list.space-between-items = 30pt
+
+To format space between bullets and text
+-------------------------------------------
+
+Use the ``'space-from-bullet'`` identifier::
+
+
+  bullet-list.space-from-bullet = 1in
+
+Choosing the text for the bullet
+-----------------------------------
+
+Use the ``'bullet-list.text'`` property to change the default bullet::
+
+ # change to hyphen
+ bullet-list.text = -
+
+If the ``'bullet-list.text'`` property is left empty, the converter
+uses the text in the actual document::
+
+ # use the text in the document 
+ bullet-list.text = 
+
+
+Formatting the  paragraphs
+----------------------------
+
+Use the ``'bullet-list-paragraph'`` identifier to format the text of
+the bullet list. This identifier can take any block property::
+
+ bullet-list-paragraph.space-before = 12pt
+ bullet-list-paragraph.font-style = italic
+
+Note that using the ``'space-before'`` property has the same effect as
+controlling the space between each paragraph, without putting unwated space
+before the first paragraph. 
+
+Formatting nested bullet lists
+-------------------------------
+
+Use the ``'bullet-list-level2'`` to format nested lists::
+
+ bullet-list-level2.space-before = 20pt
+ bullet-list-level2.left-indent = 40pt
+ bullet-list-level2.background-color = blue
+ bullet-list-level2.space-from-bullet = 1.5in
+ bullet-list-level2.text = †
+ bullet-list-level2.space-between-items = 50pt
+
+
+=================
+Enumerated List
+=================
+
+Formatting the enumerated list
+-------------------------------
+
+Use the ``'enumerated-list'`` property to format the space after and
+before, the left and right indent, and any other property you want to
+set on the list, such as font for font-size::
+
+ enumerated-list.space-after = 20pt
+ enumerated-list.space-before = 20pt
+ enumerated-list.left-indent = 20pt
+ enumerated-list.right-indent = 20pt
+ enumerated-list.background-color = grey
+
+
+To format space between items
+-------------------------------
+
+Use the ``'space-between-items'`` property.
+
+::
+
+
+  enumerated-list.space-between-items = 30pt
+
+To format space between enumerateds and text
+---------------------------------------------
+
+Use the ``'space-from-number'`` identifier::
+
+
+  enumerated-list.space-from-number = 1in
+
+
+Formatting the  paragraphs
+---------------------------
+
+Use the ``'enumerated-list-paragraph'`` identifier to format the text of
+the enumerated list. This identifier can take any block property::
+
+ enumerated-list-paragraph.space-before = 12pt
+ enumerated-list-paragraph.font-style = italic
+
+Note that using the ``'space-before'`` property has the same effect as
+controlling the space between each paragraph, without putting unwated space
+before the first paragraph. 
+
+Formatting nested enumerated lists
+-----------------------------------
+
+Use the ``'enumerated-list-level2'`` to format nested lists::
+
+ enumerated-list-level2.space-before = 20pt
+ enumerated-list-level2.left-indent = 40pt
+ enumerated-list-level2.background-color = blue
+ enumerated-list-level2.space-from-number = 1.5in
+ enumerated-list-level2.space-between-items = 50pt
+
+
+=================
+Definition List
+=================
+
+Formatting the definition list
+-------------------------------
+
+Use the ``'definition-list'`` property to format the space after and
+before, the left and right indent, and any other property you want to
+set on the list, such as font for font-size::
+
+ definition-list.space-after = 20pt
+ definition-list.space-before = 20pt
+ definition-list.left-indent = 20pt
+ definition-list.right-indent = 20pt
+ definition-list.background-color = grey
+
+Formatting space between items
+-------------------------------
+
+An item consists of both the term and definition.
+
+::
+
+ definition-list.space-between-items = 0pt
+
+To format space below term
+---------------------------
+
+Use the ``'space-below-term'`` property.
+
+::
+
+  definition-list.space-below-term = 30pt
+
+Formatting the term
+---------------------
+
+Use the ``'definition-term'`` identifier, which can take any block property::
+
+ definition-term.right-indent = 10pt
+ definition-term.color = red
+
+Formatting the definition
+--------------------------
+
+Use the ``'definition-list-definition'`` identifier, which can take any block property::
+
+ definition-list-definition.color = blue
+
+Formatting the classifier
+-------------------------
+
+Use the ``'definition-list-classifier'`` identifier, which can take any inline property::
+
+::
+
+ definition-list-classifier.color = green
+
+Formatting the  paragraphs
+---------------------------
+
+The ``'definition-list-definition'`` formats all the paragraphs in the
+definiton. If you wish to change a property on the paragraphs instead, use the
+``'definition-list-paragraph'`` identifier::
+
+ # the space before dtermines the space between each paragraph
+ definition-list-paragraph.space-before = 12pt
+
+============
+Field List
+============
+
+
+Formatting the field list
+----------------------------
+
+Use the ``'field-list'`` property to format the space after and
+before, the left and right indent, and any other property you want to
+set on the list, such as font for font-size::
+
+ field-list.space-after = 20pt
+ field-list.space-before = 20pt
+ field-list.left-indent = 20pt
+ field-list.right-indent = 20pt
+ field-list.background-color = grey
+
+
+To format space between items
+-------------------------------
+
+Use the ``'space-between-items'`` property.
+
+::
+
+
+  field-list.space-between-items = 30pt
+
+To format space between field and text
+-------------------------------------------
+
+Use the ``'space-from-name'`` identifier::
+
+
+  field-list.space-from-name = 1in
+
+Formatting the field names
+---------------------------
+
+Use the ``'field-name'`` identifier, which can take any inline
+properties::
+
+
+  field-name.color = blue
+
+
+Formatting the  paragraphs
+----------------------------
+
+Use the ``'field-list-paragraph'`` identifier to format the text of
+the bullet list. This identifier can take any block property::
+
+ field-list-paragraph.space-before = 12pt
+ field-list-paragraph.font-style = italic
+
+Note that using the ``'space-before'`` property has the same effect as
+controlling the space between each paragraph, without putting unwated space
+before the first paragraph. 
+
+
+============
+Option List
+============
+
+Choosing the layout
+-------------------
+
+::
+
+ option-list.format = definition
+
+Choosing the options separator
+-------------------------------
+
+By default, the docutils to FO convertor uses a comma to separate
+options. To change the default, use the ``'options-list.separate'``
+property::
+
+ options-list.separator = :
+
+Formatting the option list format
+-----------------------------------
+
+The option list can either be formatted as a list, with the options as
+labels to the left of the description; or as a definition list, with
+the options serving as the terms, and the descriptions in a paragraph
+right below. For an option list with lenghty options, a definition
+list may work better.
+
+Use the ``'option-list.format'`` to determine the style, choosing
+either ``'list'`` or ``'definition'``::
+
+ # change default layout to a definitio list
+ option-list.format = definition
+
+Formatting the option list
+----------------------------
+
+Use the ``'option-list'`` property to format the space after and
+before, the left and right indent, and any other property you want to
+set on the list, such as font for font-size::
+
+ option-list.space-after = 20pt
+ option-list.space-before = 20pt
+ option-list.left-indent = 20pt
+ option-list.right-indent = 20pt
+ option-list.background-color = grey
+
+
+To format space between items
+-------------------------------
+
+Use the ``'space-between-items'`` property.
+
+::
+
+
+  option-list.space-between-items = 30pt
+ 
+
+To format space between option and text
+-------------------------------------------
+
+Use the ``'space-from-option'`` identifier::
+
+
+  option-list.space-from-option = 1in
+
+Note: this option is only valid for option lists formatted as lists,
+not for optons lists formatted as definition lists.
+
+To format space below option and text
+-------------------------------------------
+
+Use the ``'space-below-option'`` identifier::
+
+
+  option-list.space-below-option = 1in
+
+Note: this option is only valid for option lists formatted as
+definition lists, not for optons lists formatted as lists.
+
+
+Formatting the options
+---------------------------
+
+Use the ``'options'`` identifier to format the option with the
+arguments of the options. This identifier  can take any inline
+properties::
+
+
+  options.font-size = xx-small
+
+Formatting the options without the argument
+----------------------------------------------
+
+Use the ``'option'`` identifier to format only the option without the
+arguments of the options. This identifier  can take any inline
+properties::
+
+
+  option.color = green
+
+.. option-group-block
+
+Formatting the arguments of the options
+----------------------------------------------
+
+Use the ``'option-argument'`` identifier to format just the option of
+the arugment. This identifier  can take any inline properties::
+
+
+  option-argument.color = green
+
+
+Formatting the description
+----------------------------
+
+Use the ``'option-list-body'`` identifier to format the text of
+the option list::
+
+ option-list-body.font-style = italic
+
+..  option-list-description-block
+
+Formatting the paragraphs
+----------------------------
+
+Use the ``'option-list-paragraph'`` identifier to format the text of
+the bullet list. This identifier can take any block property::
+
+ option-list-paragraph.space-before = 12pt
+ option-list-paragraph.font-style = italic
+
+Note that using the ``'space-before'`` property has the same effect as
+controlling the space between each paragraph, without putting unwated space
+before the first paragraph. 
+
+===============
+Literal Blocks
+===============
+
+To format a literal block, use the ``'literal-block'`` identifier. The
+literal block takes any block properties::
+
+ literal-block.background-color = red
+
+===========
+Line Blocks
+===========
+
+Formatting the entire line block
+---------------------------------
+
+Use the ``'line-block'`` indentifier to format the entire line block.
+This identifier can take any block property::
+
+ line-block.space-before = 24pt
+ # set font properties, etc
+ line-block.font-size = 10pt
+ line-block.line-spacing = 1
+
+Formatting the lines
+----------------------
+
+The lines have the identifier ``'line-level1'``, ``'line-level2'`` and
+so fourth. Each level indicates how many levels the line is nested.
+Lines may be nesed up to 5 levels deep. It makes sense to set overall
+properties with the ``'line-block'`` identifier, and to use the
+``'line-level#'`` to set the indents of for each level::
+
+ line-level1.left-indent = 15mm
+ line-level2.left-indent = 25mm
+ line-level3.left-indent = 35mm
+ line-level4.left-indent = 45mm
+ line-level5.left-indent = 55mm
+
+Create a stanza title
+----------------------
+
+In order to create a title for a stanza, in the *document* (not the
+configuration file) include the line in a title_reference::
+
+ | `stanza title 1` 
+ | A one, two, a one two three four
+ |
+ | `stanza title 2`
+ | Half a bee, philosophically,
+ |     must, *ipso facto*, half not be.
+ | But half the bee has got to be,
+ |     *vis a vis* its entity.  D'you see?
+ |
+ | `stanza title 3`
+ | But can a bee be said to be
+ |     or not to be an entire bee,
+ |         when half the bee is not a bee,
+ |             due to some ancient injury?
+ |
+ | Singing...
+
+Formatting the stanza title
+-----------------------------
+
+Use the ``'stanza-title'`` to format the stanza title::
+
+ stanza-title.font-style = bold
+
+You cannot do any formatting with a title reference (the text between
+the \`\`). If you need to do inline markup on part of a stanza title,
+only put the \`\` around the part that does not need the markup::
+
+ 
+ | *stanza title* `3` 
+ | But can a bee be said to be
+
+If you need to format the entire stanza title, use the following work
+around::
+
+
+ .. role:: title
+ 
+ | *stanza title 3* :title:`x` 
+ | But can a bee be said to be
+ |     or not to be an entire bee,
+ |         when half the bee is not a bee,
+ |             due to some ancient injury?
+
+Number lines
+------------
+
+Use the ``'line-block.number'`` property, and choose a number for the
+value. If a value of 5 is choosen, every 5th line will be numbered. If
+10 is choosen, every 10th line will be nummbered, and so on.
+
+::
+
+ line-block.number = 5
+
+Make numers closer to line
+----------------------------
+
+By default, docutils to fo puts the number to the very right of the
+margin. There is not way to change this default. However, by
+increasing the margin on the line-block, the numbers will render
+closer::
+
+ line-block.right-indent = 20mm
+
+Keeping the lines on the same page
+-----------------------------------
+
+If the line block is relatively short, use the ``'keep-on-same-page'``
+property.
+
+::
+
+ line-block.keep-on-same-page = true
+
+If the line block is long, using this property could lead to
+huge space on a page.
+
+.. note a work around is to create a completely new stanza, and use
+.. keep-on-same-page property. 
+
+Creating space between stanzas
+-------------------------------
+
+Use a blank line to control the space between stanzas. There is no
+othe way to control space. The rst2xml.py utility marks a new set of
+line blocks when it detects a new indentation. In contrast, real verse
+is marked by the space between stanzas.
+
+==============
+Block Quotes
+==============
+
+Creating block quotes
+----------------------
+
+Indent text to creat a block quote. Use two dashes before a single
+paragraph to create an attribution for the block quote::
+
+ This is an ordinary paragraph, introducing a block quote.
+
+    "It is my business to know things.  That is my trade."
+
+    -- Sherlock Holmes
+
+Formatting block quotes
+------------------------
+
+Use the ``'block-quote'`` identifier to format block quotes. This
+identifier can take any block properties::
+
+ block-quote.space-before = 24pt
+ block-quote.left-indent = 30mm
+ block-quote.right-indent = 30mm
+
+Formatting the paragraphs in block quotes
+------------------------------------------
+
+Use the ``'block-quote-paragraph'`` identifier to format the
+individual paragraphs. Setting the ``'space-before'`` property changes
+the space between each paragraph::
+
+ block-quote-paragraph.space-before = 0pt
+ block-quote-paragraph.first-line-indent = 12pt
+
+Formatting the attribution 
+----------------------------
+
+Use the ``'block-quote-attribution'`` identifier to format the
+attribution::
+
+ block-quote-attribution.space-before = 12pt
+ block-quote-attribution.font-style = italic
+
+
+Changing the default text for the attribution
+-----------------------------------------------
+
+By default, the |script_name| puts and em-dash before the attribution
+text. To change this text, use the
+``'block-quote.attriubution-text'``. Set this to an empty string to
+set no text before the attribution::
+
+ # have no text before the attribution
+ block-quote.attriubution-text = 
+
+======
+Tables
+======
+
+Creating Tables
+----------------
+
+Either::
+
+ =====  =====
+ col 1  col 2
+ =====  =====
+ 1      Second column of row 1.
+ 2      Second column of row 2.
+        Second line of paragraph.
+ 3      - Second column of row 3.
+ 
+        - Second item in bullet
+          list (row 3, column 2).
+ \      Row 4; column 1 will be empty.
+ =====  =====
+
+Or::
+
+ +------------------------+------------+----------+----------+
+ | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+ | (header rows optional) |            |          |          |
+ +========================+============+==========+==========+
+ | body row 1, column 1   | column 2   | column 3 | column 4 |
+ +------------------------+------------+----------+----------+
+ | body row 2             | Cells may span columns.          |
+ +------------------------+------------+---------------------+
+ | body row 3             | Cells may  | - Table cells       |
+ +------------------------+ span rows. | - contain           |
+ | body row 4             |            | - body elements.    |
+ +------------------------+------------+---------------------+
+
+Or::
+
+ .. csv-table:: Frozen Delights!
+    :header: "Treat", "Quantity", "Description"
+    :widths: 15, 10, 30
+ 
+    "Albatross", 2.99, "On a stick!"
+    "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
+    crunchy, now would it?"
+    "Gannet Ripple", 1.99, "On a stick!"
+
+Formatting tables
+-------------------
+
+Use the ``'table'`` identifier to format properties on the entire
+table::
+
+ table.space-before = 24pt
+ table.space-after = 24pt
+
+Use the ``'width'`` property to change the width of the table::
+
+ table.width = 4in
+
+Changing the widths of the columns
+------------------------------------
+
+The formatter uses the columns values generated by the rst2xml.py
+script to determine the width of the columns. In order to change this
+default, use the ``'table.column-widths'`` property, followed by a
+series of numbers separated by commas::
+
+ # column 2 will be 4 times as wide as column 1
+ table.column-widths = 10, 40 
+
+Formatting tables and captions
+-------------------------------
+
+Use the identifier ``'table-and-caption'`` if (1) you have a CVS table
+with a title (caption) and; (2) you wish to treat both table and
+caption as one block of text to control spacing::
+
+ table-and-caption.keep-on-same-page = true
+ table-and-caption.space-before = 12pt
+
+Formatting the table header
+----------------------------
+
+Use ``'table-header'`` identifier to format the head of a table. Use
+this identfier to set font styles, background colors, font color,
+alingnment, etc.
+
+::
+
+ table-header.font-style = bold
+ table-header.color = white
+ table-header.background-color = blue
+ table-header.alignment = center
+
+Formatting the table header cells
+-----------------------------------
+
+Use the ``'table-header-cell'`` identifier to format cells.
+
+Formatting borders
++++++++++++++++++++
+
+The defaults of cells are:
+
+* 1px black solid for all borders except the top
+* 2px black solid for the bottom border
+* border-collapse = collapse (merget adjacent borders)
+* padding = 1em
+
+To change, use the ``'border-bottom'``, ``'border-top'``,
+``'border-left'`` and ``'border-right'``.
+
+::
+
+ # set the bottom border of the cell to a more solid line
+ table-header.border-bottom = 3 px black solid
+
+Changing the vertical alignment
+++++++++++++++++++++++++++++++++
+
+::
+
+ # set the vertical alingment to bottom
+ # get rid of padding  on bottom
+ table-header-cell.padding-bottom = 0em
+ # vertically align text with bottom
+ table-header-cell.vertical-alignment = bottom
+
+Formatting the table body 
+--------------------------
+
+Use ``'table-body'`` identifier to format the body of a table. Use
+this identfier to set font styles, background colors, font color,
+alingnment, etc.
+
+::
+
+ table-body.font-style = normal
+ table-body.color = green
+ table-body.background-color = red
+ table-body.alignment = left
+
+Formatting the table body cells
+-----------------------------------
+
+Use the ``'table-cell'`` identifier to format cells.
+
+::
+
+ # set the vertical alingment to bottom
+ # get rid of padding  on bottom
+ table-cell.padding-bottom = 0em
+ # vertically align text with bottom
+ table-cell.vertical-alignment = bottom
+ table-cell.border = .5px solid green
+
+.. |script_name| replace:: docutils to Of
+
+
diff --git a/sandbox/paultremblay/python_interface/docs/rst/parameters.rst b/sandbox/paultremblay/python_interface/docs/rst/parameters.rst
new file mode 100644
index 000000000..71041c399
--- /dev/null
+++ b/sandbox/paultremblay/python_interface/docs/rst/parameters.rst
@@ -0,0 +1,521 @@
+####################
+XSL-FO Documentation
+####################
+
+^^^^^^^^^^
+Parameters
+^^^^^^^^^^
+
+.. contents:: Table of Contents
+
+strict
+======
+
+**Possible Values**: ``True``, ``False``, ``''``
+
+**Default:**
+
+If set to True, stylesheet processing quits when an error is
+found.
+
+page-layout
+===========
+
+**Possible Values**: ``simple``, ``first``, ``odd-even``,
+``first-odd-even``
+
+**Default:**
+
+This parameter determines the page layout for the document. A
+value of ``simple`` will create a document with the same page
+layout for all pages. A value of ``first`` creates a document
+with a dfferent page layout for the first page and for the rest
+of the pages. A value of ``odd-even`` creates a different layout
+for for odd and even pages. A value of ``first-odd-even`` creates
+a different layout for the first page, for odd pages, and for
+even pages.
+
+Because restructured text only allows one footer and header, the
+footer and header will be the same for bth odd and even pages.
+However, if the ``first`` or ``first-odd-even`` values is chosen,
+you can suppress the first footer and header (see below).
+
+Using a value other than ``simple`` allows for different margins
+for different page sequences, depending on the value.
+
+custom-spacing-header-footer
+============================
+
+**Possible Values**: ``boolean``
+
+**Default:**
+
+Tells the stylesheets to use attributes of body and region-before
+that will determine the spacing for the header. Normally, the
+stylesheets sets the area to .75in, if a relevant header or
+footer is found. When ``'custom-spacing-header-footer'`` is set
+to true, the stylesheets won't try to generate any spacing, but
+will require these attributes to be set in the relevant attribute
+sets.
+
+pagination for front matter
+===========================
+
+**Possible Values**: ``with-front``, ``with-toc``, ``with-body``
+
+**Defaults:** See below
+
+The function is the same for the following parameters:
+
+* title-pagination
+
+* bibliographic-pagination
+
+* dedication-pagination
+
+* abstract-pagination
+
+* toc-pagination
+
+Each determines what region to place the textual matter. There
+are three regions, the front matter, the toc matter, and the body
+matter. The front matter has no footers and headers. The toc
+matter starts a new page run, in which the numbers start with 1
+(or any other value), and can take any formatting. The body
+matter again starts a new run of pages with its own page
+numbering and formatting of these numbers.
+
+In practice, the abstract and title page often occurr before the
+other front matter material, and they appear on pages with no
+footers and headers. The dedication and Table of Contents appear
+next, with the first numbering of the document, the numbers being
+formatted as lower-case Roman numberals. The bibliographic
+information could appear in either the front matter or toc
+matter. In order to achieve this standard layout, the defaults
+choose a ``with-front`` for the ``title-pagination``,
+``abstract-pagination.``, and ``bibliographic-pagination; and a
+``with-toc`` for the ``toc-pagination`` and
+``dedication-pagination``.
+
+In order to change these defaults, choose a different value. For
+example, to place the dedication in the front matter, set
+``dedication-pagination`` to ``with-front``. For a simple
+document, in which there is only one set of page runs, simply set
+each of these parameters to ``with-body``.
+
+front-order
+===========
+
+**Possible Values**: ``title``, ``bibliographic``,
+``dedication``, ``abstract``, ``toc``
+
+**Default:** title,bibliographic,dedication,abstract,toc
+
+The param ``front-order`` is a string of each region, separated
+by a comma, that determines the order of the title, the
+bibliographic information, the dedication, the abstract, and the
+Table of Contents. The default puts them in order that docutils
+puts them in when the document is converted to XML. In order to
+change this, change the order in the string. For example, to
+place the abstract before the dedication, use
+``'title,bibliographic,dedication,abstract,toc'`` as a value.
+
+If you have a region in your parameter value that does not
+actually exist in your document, no error will occurr. For
+example, if you set your value to
+``title,bibliographic,dedication,abstract,toc``, but have no
+``title`` in your document, the XSL stylesheet will still place
+the abstract before the dedication without raising any error.
+
+However, if you lack a region in your value that exists in the
+document, the stylesheets will recognize this as an error,
+notifiy you, and quit. For eaxmple, if your value is
+``,bibliographic,dedication,abstract,toc``, and your document
+contains a title, the processing will quit.
+
+bibliographic-format
+====================
+
+**Possible Values**: ``list``, ``normal``, ``''``
+
+**Default:** list
+
+Determines the formatting of the bibliographic info. When set to
+``'list'`` (the default), the bibliograhic fields will be
+formatted as a list. When set to ``'normal'`` or ``''``, the each
+bibliographic field will be formatted as a block.
+
+Custom Table Columns
+====================
+
+**Possible Values**: ``numbers separated by commas``
+
+**Defaults:** ''
+
+The function is the same for the following parameters:
+
+* table-cols
+
+* table-borderless-cols
+
+* table-long-cols
+
+* table1-cols
+
+* table2-cols
+
+* ...
+
+* table30-cols
+
+Each parameter sets the columns for the table. ``'table-cols'``
+sets the columns for the default table;
+``'table-borderless-cols'`` sets the columns for the borderless
+table, and ``'table-long-cols'`` sets the columns for the long
+table. There are also 30 custom tables, and the parameter for the
+columns is ``'table1-cols'``, ``'table2-cols'`` ...
+``'table30-cols'``.
+
+Use these parameters to override the defualts created by
+rst2xml.py
+
+Use a value of numbers separated by commas. For example, a value
+of ``'10,20,10'`` sets the first column to 10, the second to 20,
+and the third to 10. That means the first and third columns will
+have the same width, and the second will be twice as large as
+those.
+
+long-rows-first-page
+====================
+
+**Possible Values**: ``numbers separated by commas``
+
+**Default:**
+
+Use this property to set the number of rows you want on the first
+page for a table with a class of ``'long'``. Only use if you
+desire a different caption from that which appears on the first
+page.
+
+FO by itself cannot create different table headings or footings
+from on subsequent pages. The stylesheets get around this
+limitation by creating two tables, one which takes the first
+heading (or footing), and one which takes the second. The user
+must tell the stylesheets when to start the new table; the
+stylesheets have no way of calcuating this on their own.
+
+Use numbers separated by commas for this parameter, where the
+first number inidcatetes the first long table, the second the
+second table, and so on. For example, a value of ``'8,10'`` tells
+the stylesheet to break the first *long* table at 8 rows, and
+the second at 10 rows.
+
+Leave this parameter empty, or set it to 0 in order to have the
+same caption on all pages.
+
+Bibliographic Field Names
+=========================
+
+**Possible Values**: Any Text
+
+**Defaults:** See below
+
+The function is the same for the following parameters:
+
+* author-text (default: Author: )
+
+* authors-text (default: Authors: )
+
+* organization-text (default: Organization: )
+
+* contact-text (default: Contact: )
+
+* status-text (default: Status: )
+
+* copyright-text (default: Copyright: )
+
+* address-text (default: Address: )
+
+* version-text (default: Version: )
+
+* revision-text (default: Revison: )
+
+* date-text (default: Date: )
+
+Each parameter sets the text in the list for that particular
+bibliographic item. For example if you wanted to change the
+default for ``contact`` from 'contact' to email, you would simply
+set this value to 'email'.
+
+Custom bibliographic field names
+================================
+
+**Possible Values**: Any Text
+
+**Defaults:** ''
+
+The function is the same for the following parameters:
+
+* custom-bib-info1-name
+
+* custom-bib-info2-name
+
+* custom-bib-info3-name
+
+* custom-bib-info4-name
+
+* custom-bib-info5-name
+
+* custom-bib-info6-name
+
+* custom-bib-info7-name
+
+* custom-bib-info8-name
+
+* custom-bib-info9-name
+
+* custom-bib-info10-name
+
+Each parameter sets the value of the corresponding text for cutom
+bibliographic fields.
+
+Admonition Title Names
+======================
+
+**Possible Values**: Any Text
+
+**Defaults:** See below
+
+The function is the same for the following parameters:
+
+* attention-title (default: Attention!)
+
+* caution-title (default: Caution!)
+
+* danger-title (default: !Danger!)
+
+* error-title (default: Error)
+
+* hint-title (default: Hint)
+
+* important-title (default: Important)
+
+* note-title (default: Note)
+
+* tip-title (default: Tip)
+
+* warning-title (default: Warning!)
+
+Each parameter sets the text for the title for that particular
+Admonition. For example if you wanted to change the default for
+``attention-title`` from 'Important' to 'Pay Attention!', you
+would simply set this value to 'Pay Attnetion!'.
+
+transition-text
+===============
+
+**Possible Values**: Any Text
+
+**Defaults:** \*\*\*
+
+The text to use for a transtion element. Use any text (including
+an empty string) to change that value.
+
+Formatting of Section Numbering
+===============================
+
+**Possible Values**: Valid Number Formatting String
+
+**Defaults:** See below
+
+The function is the same for the following parameters:
+
+* number-section1 (default: 1)
+
+* number-section2 (default: .1)
+
+* number-section3 (default: .1)
+
+* number-section4 (default: .1)
+
+* number-section5 (default: .1)
+
+* number-section6 (default: .1)
+
+* number-section7 (default: .1)
+
+* number-section8 (default: .1)
+
+* number-section9 (default: .1)
+
+Each parameter sets the formatting (not the actual number) for
+that particular level. The stylesheets allow for a great deal of
+flexibility here. For example, in order to set a level 3 number
+format to '(II)3.b', you would set ``number-section1`` to '(I)',
+``number-section2`` to '.1' (the default, in this case, meaning
+you woud not need to make a change), and ``number-section3`` to
+'.a'.
+
+inherit-section-num
+===================
+
+**Possible Values**: ``True``, ``False``
+
+**Default:** True
+
+If set to 'True', each section inherits the section numbering
+from the sections above it. For example, section '1.1.2' will
+appear as '1.1.2'. If set to 'False', the section number will
+appear as '2'.
+
+bullet-text
+===========
+
+**Possible Values**: Any Text
+
+**Default:** •
+
+Use to set the value for the bullets in a bullet list. If this
+string is left blank, then the stylesheets will use the value in
+the XML.
+
+bullet-text-level2
+==================
+
+**Possible Values**: Any Text
+
+**Default:** °
+
+Use to set the value for the bullets in a nested bullet list. If
+this string is left blank, then the stylesheets will use the
+value in the XML.
+
+option-list-format
+==================
+
+**Possible Values**: ``list``, ``definition``
+
+**Default:** list
+
+Use to determine the formatting of an options list. If ``list``
+is choosen, then the options list is formatted as a traditional
+list, with the options to the left and the description to the
+right. If ``definition`` is choosen, the options list is
+formatted as a defintion list, with the options above the
+description, which is indented. Lists with long options are
+probably better formatted using ``definition.``
+
+options-separator
+=================
+
+**Possible Values**: Any Text
+
+**Default:** ,
+
+Use to set the value for the text that separates the options in
+an option list. For example, if your RST file has ``-f -file`` as
+the options, and you choose ';' as the ``options-separator``,
+the output becomes ``-f; -file``.
+
+number-verse
+============
+
+**Possible Values:** any positive integer, or ``''``
+
+**Default:** 5
+
+When set, this parameter numbers a line block ("verse") every
+``value`` lines. The value of ``'5'`` numbers every 5th line. If
+``number-verse`` is left empty, the line block will not be
+numbered.
+
+Text Before Attributions
+========================
+
+**Possible Values**: Any Text
+
+**Defaults:** —
+
+The function is the same for the following parameters:
+
+* text-before-block-quote-attribution
+
+* text-before-epigraph-attribution
+
+* text-before-pull-quote-attribution
+
+Each parameter determines the text before the attribution. When
+the parameter is left empty, no text will appear before an
+attribution.
+
+table-title-placement
+=====================
+
+**Possible Values**: ``top``, ``bottom``
+
+**Default:** bottom
+
+Where to place the table title, or caption.
+
+footnote-placement
+==================
+
+**Possible Values**: ``footnote``, ``endnote``
+
+**Default:** footnote
+
+This parameter determines whether footnotes will function as
+footnotes, or endnotes. When ``footnote`` is choosen, footnotes
+appear at the bottom of the page. When ``endnote`` is choosen,
+the *numbered* footnotes appear as endnotes, in the same position
+where they are in the RST document. If ``endnote`` is choosen,
+symbolic footnotes still appear as footnotes, thus giving a user
+the ability to use both footnotes and endnotes.
+
+footnote-style
+==============
+
+**Possible Values**: ``list``, ``traditional``
+
+**Default:** list
+
+This parameter determines the style of the footnote or endnote
+text. When ``'list'``, is choosen, the text is formatted as a
+list, with the number as the item. When ``'traditional'`` is
+choosen, the footnote appears in the more traditional manner, as
+a paragraph with the first line indented.
+
+space-between-footnotes
+=======================
+
+**Possible Values**: Any Measure
+
+**Default:** 5pt
+
+Use to set the space between footnotes. (I have not determined
+how to set this property in the normal way, which is why this
+property appears as a parameter, rather than in an attribute set,
+like the other similar properties.)
+
+internal-link-type
+==================
+
+**Possible Values**: ``link``, ``page``, ``page-link``
+
+**Default:** link
+
+When set to ``'page'``, the page number of the target appears.
+When set to ``'link'``, the text of the link appears, and
+clicking on that link takes you to the target. When set to
+``'page-link'``, the page of the target appears, and clicking on
+that page number takes you to the target.
+
+test
+====
+
+**Possible Values**: ``True``, ``False``, ``''``
+
+**Default:**
+
+For testing purposes only.
+
diff --git a/sandbox/paultremblay/python_interface/docs/rst/user_guide.rst b/sandbox/paultremblay/python_interface/docs/rst/user_guide.rst
new file mode 100644
index 000000000..011bf468a
--- /dev/null
+++ b/sandbox/paultremblay/python_interface/docs/rst/user_guide.rst
@@ -0,0 +1,154 @@
+Page Layout
+=============
+
+Paper Size
+------------
+
+The following determmine the size of the paper:
+
+Height
++++++++
+
+* default-simple-page-master.page-height = 11in
+
+The short version is:
+
+* paper-size.height = 11in
+
+Width
+++++++
+
+* default-simple-page-master.page-width = 8.5in
+
+The short version is:
+
+* paper-size.width = 8.5in
+
+Page Margins
+---------------
+
+For a Simple Document
++++++++++++++++++++++++
+
+Each set of properties has the same effect.
+
+* simple-page-master.top-margin = 1in
+* simple-page-master.bottom-margin = 1in
+* simple-page-master.right-margin = 1in
+* simple-page-master.left-margin = 2in
+
+The short versions are:
+
+* page.top-margin = .75in
+* page.bottom-margin = .75in
+* page.right-margin = .75in
+* page.left-margin = .75in
+
+The properties can be reversed:
+ 
+* page.margin-top = .75in
+* page.margin-bottom = .75in
+* page.margin-right = .75in
+* page.margin-left = .75in
+
+
+For Documents with First, Odd, and Even Pages
+++++++++++++++++++++++++++++++++++++++++++++++
+
+Here is how to set margins for the first, even, and odd pages. Note that these
+will work only if you choose ``page-layout``=``odd-even``, or ``page-layout``
+= ``first-odd-even,`` or ``page-layout`` = ``first``.
+
+The long version:
+
+* odd-simple-page-master.top-margin = 1in
+* odd-simple-page-master.bottom-margin = 1in
+* odd-simple-page-master.right-margin = 1in
+* odd-simple-page-master.left-margin = 2in
+* 
+* even-simple-page-master.top-margin = 1in
+* even-simple-page-master.bottom-margin = 1in
+* even-simple-page-master.right-margin = 2in
+* even-simple-page-master.left-margin = 1in
+
+* first-simple-page-master.top-margin = 1in
+* first-simple-page-master.bottom-margin = 1in
+* first-simple-page-master.right-margin = 2in
+* first-simple-page-master.left-margin = 1in
+
+The short versions:
+
+* odd-page.top-margin = 1in
+* odd-page.bottom-margin = 1in
+* odd-page.right-margin = 1in
+* odd-page.left-margin = 2in
+* 
+* even-page.top-margin = 1in
+* even-page.bottom-margin = 1in
+* even-page.right-margin = 2in
+* even-page.left-margin = 1in
+
+* first-page.top-margin = 3in
+* first-page.bottom-margin = 1in
+* first-page.right-margin = .8in
+* first-page.left-margin = 2in
+
+Headers and Footers
+---------------------
+
+Setting the space, or height.
+++++++++++++++++++++++++++++++
+
+Long version:
+
+* header-region-before.extent = 1in
+* footer-region-after.extent = 1in
+
+Short version:
+
+* header.height = 1in
+* footer.height = 1in
+
+To make the header closer to the page, use the ``space-before`` property::
+
+ header.space-before = .2in
+
+Use the ``'space-before'`` property for the footer, as well, to move it
+closer to the  text::
+
+ footer.space-before = -.1in
+
+Documnet
+=============
+
+The following properties can be set for the entire document:
+
+* font-size
+* font-family or font
+
+The short version of ``'font-family'`` is ``'font'``; they are synonymous.
+
+Possible font-families are serif, sans-seif, monospace; Times, Helvitica
+Coureir, ZapfDingbats, and Symbol. Since these font families are buiit in,
+they are guarenteed to work, regardless of the availability of fonts on 
+an operating system.
+
+Body
+=====
+
+The following properties can be set for the body of the document. The body
+is defined as everything except headers and footers.
+
+* font-size
+* font
+* line-height or line-spacing
+
+The property ``'line-spacing'`` is the short version of ``'line-height'``;
+They are synomous. 
+
+Set ``line-spacing`` to a number to determine the spacing relative to
+the font size. For example, a value of ``'2'`` sets the line spacing to
+double. 
+
+Set ``'line-spacing'`` to a measure, such as ``'24pt'`` to set an absolute
+value to the line spacing.