path: root/sandbox/paultremblay/python_interface/docs/rst/howto.rst

^^^^^^^^^^^^^^^^^^^^^^^^
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