Commits

takanao ENDOH  committed 77d8af6

Imported rst2pdf rev 1243.

  • Participants

Comments (0)

Files changed (457)

+build
+dist
+doc/manual0.pdf
+rst2pdf.egg-info
+rst2pdf/extensions
+tags
+
+syntax: glob
+
+*.pyc
+*.sw?
+.DS_Store
+.svn
+
+syntax: regexp
+
+New in SVN
+----------
+
+* Fix Issue 225 (bad spacing in lineblocks)
+* Fix Issue 223 (non-monospaced styles used in code)
+
+New in 0.12.2
+-------------
+
+* Fix Issue 219 (incompatibility with reportlab 2.1)
+* Added pdf_default_dpi option for pdfbuilder
+* More style docs in the manual
+* Better styling of lists
+* Fix bug reported in comments in my blog where a stylesheet with 
+  showHeader=True and no explicit header caused an exception.
+* Fixed Issue 215: crashes in bookrest's background renderer.
+
+New in 0.12.1
+-------------
+
+* Ship local patched copy of pypoppler-qt4
+* Partial fix for Issue 205: KeyError: 'format'
+* Fixed Issue 212: XML parsing error in bookrest
+* Fixed Issue 210: pickle error in bookrest
+* Switched --enable-splittables to True by default
+* Fixed Issue 204: syntax error on font importing code
+
+New in 0.12
+-----------
+
+* Fixed Issue 202: broken processing of HTML raw nodes
+* New "options" section in stylesheets. New ["options"]["stylesheets"] subsection,
+  which works similar to -s or to an include file: a list of stylesheets to be
+  processed before the current one.   
+* New --config option
+* Fix for Issue 200 (position of frames was miscalculated)
+* Fix For Issue 188 (uniconvertor "'unicode' object has no attribute 'readline'" error)
+* New raw directive command: SetPageCounter. This enables
+  page counter manipulation, and use of different styles,
+  roman, lowerroman, alpha, loweralpha and arabic.
+* New raw directive commands: EvenPageBreak and OddPageBreak
+* New option to make sections break to odd or even pages:
+  --break-side=VALUE
+* New option to add an empty page at the beginning of the
+  document: --blank-first-page.
+* Fixed bug in authors field width calculation
+* Support % in bullet and field lists column widths
+* Use bullet_list or item_list styles for bullet and item lists respectively.
+* Support % in field list column width description.
+* Fix for Issue 184 (font metrics go crazy with TT font)
+* New admonition code based on SplitTable (beta quality)
+* Fix for Issue 180 (support for very very long list items. Needs testing)
+* Fix for Issue 175 (widow/orphan titles)
+* Fix for Issue 174 (line blocks didn't respect indentation)
+* Worked around Issue 173 (quotes didn't indent inside table cells)
+* Respect spaceBefore and spaceAfter for footnotes/endnotes
+* Added tests for (almost) all of sphinx's custom markup
+* Fixed Issue 170 (Wrong font embedding)
+* Fixed Issue 171 (Damaged xref table)
+* Fixed Issue 159 (Admonition and table widths were miscalculated)
+* Fixed Issue 162 (wrong highlighting using sphinx)
+* Changed default language policy as described in Issue 53
+* Fixed Issue 148 (Images should be looked for relative to source document)
+* Fixed Issue 158 (Some admonitions crashed pdfbuilder)
+* Fixed Issue 154 (incompatibility with RL 2.1)
+* Fixed Issue 155 (crash when sidebars split in a certain way)
+* Fixed issue 152 (padding and alignment of table styles, like 
+  when using literal blocks inside lists)
+* Integrated pdfbuilder sphinx extension (more work needed)
+* Kerning support for true type fonts (thanks to wordaxe!), added
+  to the docs, added convenience stylesheet.
+* Fixed Issue 151 and behaviour on Issue 116, about images too large
+  for available space / the full frame height.
+* Fixed problem in admonition titles.
+* Fixed section names in headers/footers: FIRST section on the page
+  is used, not LAST.
+* Fixed Issue 145: padding of literal blocks was broken.
+* Fixed bug: paragraphs with ids should have the matching anchors
+* Fixed bug: internal references were not linked correctly
+* Fixed Issue 144: PDF TOC had wrong page numbers in some cases
+* More sphinx compatibility
+* New table styles code, also make class directive work for tables
+* Fixed Issue 140: html-like markup in titles was kept in the PDF TOC
+* Fixed Issue 138: Redid figure styling. Also fixed bugs in BoxedContainer
+* Fixed Issue 137: bugs in escaping characters in interpreted roles
+* Make it work (in a slightly degraded mode) without PIL, as
+  long as you are only using JPGs or have PythonMagick installed.
+  This is good for OS X, where "installing PIL is a PITA"
+* Fixed issue 134: entities were replaced in interpreted roles 
+  (not needed)
+* Support for aafigure (http://launchpad.net/aafigure)
+* Spacers support units
+* TOC styles now configurable in stylesheet
+
+New in 0.11
+-----------
+
+* Degrade more gracefully when one or more wordaxe hyphenators are
+  broken (currently DWC is the broken one)
+* Fixed issue 132: in some cases, with user-defined fontAlias, bold and
+  italic would get confused (getting italic instead of bold in inline
+  markup, for instance).
+* New stylesheet no-compact-lists to make lists... less compact
+* SVG images now handle % as a width unit correctly.
+* Implemented issue 127: support images in PDF format. Right now they 
+  are rasterized, so it's not ideal. Perhaps something better will come up
+  later.
+* Fixed issue 129: make it work around a prblem with KeepTogether in RL 2.1
+  it probably makes the output look worse in some cases when using that.
+  RL 2.1 is not really supported, so added a warning.
+* Fixed issue 130: use os.pathsep instead of ":" since ":" in windows is used
+  in disk names (and we still pay for DOS idiocy, in 2009)
+* Fixed issue 128: headings level 3+ all looked the same
+* Ugly bugfix for Issue 126: crashes when using images in header + TOC
+* New tstyles section in the stylesheet provides more configurable list layouts 
+  and more powerful table styling.
+* Better syntax highlighting (supports bold/italic)
+* Workaround for issue 103 so you can use borderPadding as a list (but it will look wrong
+  if you are using wordaxe <= 0.3.2) 
+* Added fieldvalue style for field lists
+* Added optionlist tstyle, for option lists
+* Added collection of utility stylesheets and documented it
+* Improved command line parsing and stylesheet loading (guess
+  extension like latest rst2latex does)
+* Fixed Issue 67: completely new list layouting code
+* Fixed Issue 116: crashes caused by huge images
+* Better support for %width in images, n2ow it's % of the container frame's
+  width, not of the text area.
+* Fixed bug in SVG scaling
+* Better handling of missing images
+* Added missing styles abstract, contents, dedication to the default stylesheet
+* Tables style support spaceBefore and spaceAfter
+* New topic-title style for topic titles (obvious ;-)
+* Vertical alignment for inline images (:align: parameter)
+* Issue 118: Support for :scale: in images and handle resizing of inline images
+* Issue 119: Fix placement of headers and footers
+* New background property for page templates (nice for presentations, for example)
+* Default to px for image width specifications instead of pt
+* Support all required measurement units ("em" "ex" "px" "in" "cm" 
+  "mm" "pt" "pc" "%" "")
+* New automated scripts to check test cases for "visual differences"
+* Respect images DPI property a bit like rst2latex does.
+* Issue 110: New --inline-footnotes option
+* Tested with reportlab from SVN trunk
+* Support for Dinu Gherman's svglib. If both svglib and uniconvertor are available,
+  svglib is preferred (for SVG, of course). Patch originally by rute.
+* Issue 109: Separate styles for each kind of admonition
+* For Issue 109: missing styles are not a fatal error
+* Issue 117: TOCs with more than 6 levels now supported (raised limit to 9, which 
+  is silly deep)
+
+New in 0.10.1
+-------------
+
+* Issue 114: Fixed bug in PDF TOC for sections containing ampersands
+
+New in 0.10
+-----------
+
+* Issue 87: Table headers can be repeated in each page (thanks to Yasushi Masuda)
+* Issue 93: Line number support for code blocks (:linenos: true)
+* Issue 111: Added --no-footnote-backlinks option
+* Issue 107: Support localized directives/roles (example: sommaire instead of contents)
+* Issue 112: Fixed crash when processing empty list items
+* Issue 98: Nobreak support, and set as default for inline-literals so they don't hyphenate.
+* Slightly better tests
+* Background colors in text styles work with reportlab 2.3
+* Issue 99: Fixed hyphenation in headers/footers (requires wordaxe 0.3.2)
+* Issue 106: Crash on demo.txt fixed (requires wordxe 0.3.2)
+* Issue 102: Implemented styles for bulleted and numbered lists
+* Issue 38: Default headers/footers via options, config file or stylesheet
+* Issue 88: Implemented much better book-style TOCs
+* Issue 100: Fixed bug with headers/footers and Reportlab 2.3
+* Issue 95: Fixed bug with indented tables
+* Issue 89: Implemented --version
+* Issue 84: Fixed bug with relative include paths
+* Issue 85: Fixed bug with table cell styles
+* Issue 83: Fixed bug with numeric colors in backColor attribute
+* Issue 44: Support for stdin and stdout
+* Issue 79: Added --stylesheet-path option
+* Issue 80: Send warnings to stderr, not stdout
+* Issue 66: Implemented "smart quotes"
+* Issue 77: Work around missing matplotlib
+* Proper translation of labels (such as "Author", "Version" etc.) using the 
+  docutils languages package. (r473)
+* Fixed problems with wrong or non-existing fonts. (r484)
+* Page transition effect support for presentations (r423)
+
+
+New in 0.9
+----------
+
+* Math support via Mathplotlib
+* Huge bug in header/footer page numbers/section names fixed
+* Several bugs in nested lists fixed (not 100% correct yet, but better)
+* Lists that don't start at 1 work now
+* Nicer definition lists
+
+New in 0.8.1
+------------
+
+* Support for more complex headers and footers 
+  (including image directives and tables)
+* Optional inline links
+* Wordaxe 0.2.6 support
+* Several bugs fixed (issues 48,68,41,60,58,64,67)
+* Support for system-wide config file
+* Better author metadata
+
+New in 0.8
+----------
+
+* Support for vector graphics: SVG, EPS, PS, CDR and others (requires uniconvertor)
+* Support for stdin and stdout, so you can use rst2pdf in pipes.
+* Works with reportlab 2.1 and 2.2
+* Simpler stylesheets (guess bulletFontName, leading, bulletFontSize from other parameters)
+* Some support for sphinx
+* Fixed the docutils Writer interface
+* Continue processing when an image is missing
+* Support for user config file
+* Font sizes can be expressed in units or % of parent style's size
+* Larger font size in the default stylesheet
+
+New in 0.7
+----------
+
+* Automatic Type1 and True Type font embedding. Just use the font or family name, and (with a little luck), it will be embedded for you.
+* width attribute in styles, to create narrow paragraphs/tables
+* Styles for table headers and table cells
+* "Zebra tables"
+* Improvements in the handling of overflowing literal blocks (code, for instance)
+* Different modes to handle too-large literal blocks: overflow/truncate/shrink.
+* Real sidebars and "floating" elements.
+* Fixed link style (no ugly black underlining!)
+
+New in 0.6
+----------
+
+* Stylesheet-defined page layout (For example, multicolumn) and layout switching
+* Cascading Stylesheets (change exactly what you need changed)
+* PDF table of contents
+* Current section names and numbers in headers/footers
+* Support for compressed PDF files
+* Link color is configurable
+* Fixed bugs in color handling
+* Multilingual hyphenation
+* Auto-guessing image size, support for sizes in %
+* Gutter margins
+* Big refactoring
+* More tolerant of minor problems
+* Limited _raw_ directive (you can insert pagebreaks and vertical space)
+* Implemented a "traditional" docutils writer
+* Offer a reasonable API for use as a library
+* Fixed copyright/licensing
+* code-block now supports including files (whole or in part) so you can highlight external code.
+
+
+New in 0.5
+----------
+
+* Support for :widths: in tables
+* Support for captions in tables
+* Support for multi-row headers in tables
+* Improved definition lists
+* Fixed bug in image directive 
+* Whitespace conforming to PEP8
+* Fixed bug in text size on code-block
+* Package is more setuptools compliant
+* Fix for option groups in option lists
+* Citations support
+* Title reference role fix
+
+New in 0.4
+----------
+
+* Fixed bullet and item lists indentation/nesting. 
+* Implemented citations 
+* Working links between footnotes and its references 
+* Justification enabled by default 
+* Fixed table bug (demo.txt works now) 
+* Title and author support in PDF properties 
+* Support for document title in header/footer 
+* Custom page sizes and margins 
+
+New in 0.3
+----------
+
+* Font embedding (use any True Type font in your PDFs) 
+* Syntax highlighter using Pygments 
+* User's manual 
+* External/custom stylesheets 
+* Support for page numbers in header/footer 

File Contributors.txt

+* Roberto Alsina <ralsina at netmanagers dot com dot ar>
+* Nicolas Laurance <nlaurance at zindep dot com>
+* Christoph Zwerschke 
+* Yasushi Masuda
+* Josh VanderLinden
+* Runar Tenfjord
+Copyright (c) 2007,2008,2009 Roberto Alsina
+Nicolas Laurance, Christoph Zwerschke, Yasushi Masuda, Josh VanderLinden.
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+Intro
+=====
+
+The usual way of creating PDF from reStructuredText is by going through LaTeX. 
+This tool provides an alternative by producing PDF directly using the ReportLab
+library. 
+
+Installing
+==========
+
+python setup.py install
+
+should do the trick.
+
+Features
+========
+
+* User-defined page layout. Multiple frames per page, multiple layouts per
+  document. 
+
+* Page transitions 
+
+* Cascading stylesheet mechanism, define only what you want changed. 
+
+* Supports TTF and Type1 font embedding. 
+
+* Any number of paragraph styles using the class directive. 
+
+* Any number of character styles using text roles. 
+
+* Custom page sizes and margins. 
+
+* Syntax highlighter for many languages, using Pygments. 
+
+* Supports embedding almost any kind of raster or vector images. 
+
+* Supports hyphenation and kerning (using wordaxe). 
+
+* Full user's manual

File bootstrap.py

+##############################################################################
+#
+# Copyright (c) 2006 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Bootstrap a buildout-based project
+
+Simply run this script in a directory containing a buildout.cfg.
+The script accepts buildout command-line options, so you can
+use the -c option to specify an alternate configuration file.
+
+$Id: bootstrap.py 108 2008-08-28 14:40:09Z webmaster@guichen.com $
+"""
+
+import os, shutil, sys, tempfile, urllib2
+
+tmpeggs = tempfile.mkdtemp()
+
+ez = {}
+exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
+                     ).read() in ez
+ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
+
+import pkg_resources
+
+cmd = 'from setuptools.command.easy_install import main; main()'
+if sys.platform == 'win32':
+    cmd = '"%s"' % cmd # work around spawn lamosity on windows
+
+ws = pkg_resources.working_set
+assert os.spawnle(
+    os.P_WAIT, sys.executable, sys.executable,
+    '-c', cmd, '-mqNxd', tmpeggs, 'zc.buildout',
+    dict(os.environ,
+         PYTHONPATH=
+         ws.find(pkg_resources.Requirement.parse('setuptools')).location
+         ),
+    ) == 0
+
+ws.add_entry(tmpeggs)
+ws.require('zc.buildout')
+import zc.buildout.buildout
+zc.buildout.buildout.main(sys.argv[1:] + ['bootstrap'])
+shutil.rmtree(tmpeggs)

File doc/DEVELOPERS.txt

+===========================
+Help for rst2txt developers
+===========================
+
+-----------------------------
+Or, how do I hack this thing?
+-----------------------------
+
+
+Some real data coming soon.
+
+But first:
+  
+Running tests
+-------------
+
+first run
+~~~~~~~~~
+
+while in project::
+
+  python bootstrap.py
+  ./bin/buildout
+  ./bin/test
+  
+next runs
+~~~~~~~~~
+
+while in project::
+
+  ./bin/test
+
+Testing the tests
+-----------------
+
+while in project::
+
+  ./bin/test --coverage=.
+  
+that may be much longer
+
+results are in part/test

File doc/INSTALL.txt

Empty file added.

File doc/config.sample

+# This is an example config file. Modify and place in ~/.rst2pdf/config
+
+[general]
+# A comma-separated list of custom stylesheets. Example:
+# stylesheets="fruity.json,a4paper.json,verasans.json"
+
+stylesheets=""
+
+# Create a compressed PDF
+# Use true/false (lower case) or 1/0
+compressed=false
+
+# A colon-separated list of folders to search for fonts. Example:
+# font_path="/usr/share/fonts:/usr/share/texmf-dist/fonts/"
+
+font_path=""
+
+# A colon-separated list of folders to search for stylesheets. Example:
+# stylesheet_path="~/styles:/usr/share/styles"
+stylesheet_path=""
+
+# Language to be used for hyphenation support
+
+language="en_US"
+
+# Default page header and footer
+header=None
+footer=None
+
+# What to do if a literal block is too large. Can be
+# shrink/truncate/overflow
+
+fit_mode="shrink"
+
+# What is the maximum level of heading that starts in a new page.
+# 0 means no level starts in a new page.
+
+break_level=0
+
+# How section breaks work. Can be "even", and sections start in an 
+# even page, "odd", and sections start in odd pages, or "any" and 
+# sections start in the next page, be it even or odd.
+
+break_side="any"
+
+# Add a blank page at the beginning of the document
+
+blank_first_page=False
+
+# Treat the first page as even (default False, treat it as odd)
+
+first_page_even=False
+
+# Smart quotes.
+# 0:  Suppress  all  transformations. (Do nothing.)
+# 1: Performs default SmartyPants transformations: quotes (including ‘‘backticks''
+# -style), em-dashes, and ellipses. "--" (dash dash) is used to signify an em-dash;
+# there is no support for en-dashes.
+# 2:  Same as 1, except that it uses the old-school typewriter shorthand for
+# dashes: "--" (dash dash) for en-dashes, "---" (dash dash dash) for em-dashes.
+# 3: Same as 2, but inverts the shorthand for dashes: "--" (dash dash) for
+# em-dashes,  and "---" (dash dash dash) for en-dashes.
+
+smartquotes=0
+
+# Footnote backlinks enabled or not (default: enabled)
+
+footnote_backlinks=True
+
+# Show footnotes inline instead of at the end of the document
+
+inline_footnotes=False

File doc/gen_docs.sh

+#!/bin/sh
+
+python ../rst2pdf/createpdf.py manual.txt -o manual.pdf -s manual.style -b1
+rst2man rst2pdf.txt rst2pdf.1

File doc/manual.style

+{
+  "pageSetup" : {
+    "firstTemplate": "coverPage"
+  },
+  "styles" : [
+    ["thin" , {
+    "parent" : "bodytext",
+    "width" : "35%",
+    "alignment": "TA_JUSTIFY",
+    "hyphenation": true,
+    "language": "es_ES"
+    }
+    ]
+   ]
+}
+

File doc/manual.txt

+==================
+How to use rst2pdf
+==================
+
+:author: Roberto Alsina <ralsina@netmanagers.com.ar>
+:version: 0.12
+:revision: $LastChangedRevision: 1220 $
+
+.. header::
+
+   ###Section###
+
+.. footer::
+
+   Page ###Page###
+
+.. contents::
+
+.. section-numbering::
+
+.. raw:: pdf
+
+   PageBreak oneColumn
+
+Introduction
+============
+
+This document explains how to use rst2pdf. Here is the very short version::
+
+    rst2pdf.py mydocument.txt -o mydocument.pdf
+
+That will, as long as mydocument.txt is a valid Restructured Text (ReST)
+document, produce a file called mydocument.pdf which is a PDF
+version of your document.
+
+Of course, that means you just used default styles and settings. If it
+looks good enough for you, then you may stop reading this document,
+because you are done with it. If you are reading this in a PDF,
+it was generated using those default settings.
+
+However, if you want to customize the output, or are just curious to see
+what can be done, let´s continue.
+
+Command line options
+====================
+
+::
+
+  -h, --help            show this help message and exit
+  --config=FILE         Config file to use. Default=~/.rst2pdf/config  
+  -o FILE, --output=FILE                               
+                        Write the PDF to FILE          
+  -s STYLESHEETS, --stylesheets=STYLESHEETS            
+                        A comma-separated list of custom stylesheets.
+                        Default=""                                   
+  --stylesheet-path=FOLDER:FOLDER:...:FOLDER                         
+                        A list of folders to search for stylesheets,"        "
+                        separated using ":". Default=""                       
+  -c, --compressed      Create a compressed PDF. Default=False                
+  --print-stylesheet    Print the default stylesheet and exit                 
+  --font-folder=FOLDER  Search this folder for fonts. (Deprecated)            
+  --font-path=FOLDER:FOLDER:...:FOLDER                                        
+                        A list of folders to search for fonts, separated using
+                        ":". Default=""                                       
+  --baseurl=URL         The base URL for relative URLs. Default="file:///home/
+                        ralsina/Desktop/proyectos/rst/trunk"                  
+  -l LANG, --language=LANG                                                    
+                        Language to be used for hyphenation and docutils      
+                        localizations. Default="None"                         
+  --header=HEADER       Page header if not specified in the document.         
+                        Default="None"                                        
+  --footer=FOOTER       Page footer if not specified in the document.         
+                        Default="None"                                        
+  --smart-quotes=VALUE  Try to convert ASCII quotes, ellipsis and dashes to   
+                        the typographically correct equivalent. For details,  
+                        read the man page or the manual. Default="0"
+  --fit-literal-mode=MODE
+                        What todo when a literal is too wide. One of error,
+                        overflow,shrink,truncate. Default="shrink"
+  --inline-links        shows target between parenthesis instead of active
+                        link
+  --repeat-table-rows   Repeats header row for each splitted table
+  -q, --quiet           Print less information.
+  -v, --verbose         Print debug information.
+  --very-verbose        Print even more debug information.
+  --version             Print version number and exit.
+  --no-footnote-backlinks
+                        Disable footnote backlinks. Default=False
+  --inline-footnotes    Show footnotes inline. Default=True
+  --default-dpi=NUMBER  DPI for objects sized in pixels. Default=300
+  --show-frame-boundary
+                        Show frame borders (only useful for debugging).
+                        Default=False
+  --enable-splittable   Use alpha-quality splittable flowables in some
+                        elements. Only useful for things like page-long block
+                        quotes or list items
+  -b LEVEL, --break-level=LEVEL
+                        Maximum section level that starts in a new page.
+                        Default: 0
+  --first-page-even     Whether first page is odd (as in the screen on "facing
+                        pages"), or even (as in a book)
+  --blank-first-page    Add a blank page at the beginning of the document.
+  --break-side=VALUE    How section breaks work. Can be "even", and sections
+                        start in an even page,"odd", and sections start in odd
+                        pages, or "any" and sections start in the next page,be
+                        it even or odd. See also the -b option.
+
+
+For the options that take a folder list, like --stylesheet-path, the separator used will
+depend on your platform. On unix-like OSs, it's ":", on Windows it's ";". Don't blame me,
+blame DOS.
+
+Some of these options' defaults can be changed by creating a `configuration file`_
+
+Configuration File
+==================
+
+Since version 0.8, rst2pdf will read (if it is available) configuration files in
+``/etc/rst2pdf.conf`` and ``~/.rst2pdf/config``.
+
+The user's file at ``~/.rst2pdf/config`` will have priority over the system's at
+``/etc/rst2pdf.conf`` [#]_
+
+.. [#] The ``/etc/rst2pdf.conf`` location makes sense for Linux and linux-like systems.
+       if you are using rst2pdf in other systems, please contact me and tell me where
+       the system-wide config file should be.
+
+
+
+Here's an example file showing some of the currently available options:
+
+.. code-block:: ini
+
+    # This is an example config file. Modify and place in ~/.rst2pdf/config
+
+    [general]
+    # A comma-separated list of custom stylesheets. Example:
+    # stylesheets="fruity.json,a4paper.json,verasans.json"
+    stylesheets=""
+
+    # Create a compressed PDF
+    # Use true/false (lower case) or 1/0
+    # Example: compressed=true
+    compressed=false
+
+    # A colon-separated list of folders to search for fonts. Example:
+    # font_path="/usr/share/fonts:/usr/share/texmf-dist/fonts/"
+    font_path=""
+
+    # Language to be used for hyphenation support
+    language="en_US"
+
+    # Default page header and footer
+    header=None
+    footer=None
+
+    # What to do if a literal block is too large. Can be
+    # shrink/truncate/overflow
+    fit_mode="shrink"
+
+    # What is the maximum level of heading that starts in a new page.
+    # 0 means no level starts in a new page.
+    break_level=0
+
+Included with rst2pdf is an example file with every option in it.
+
+Pipe usage
+==========
+
+If no input nor output are provided, stdin and stdout will be used respectively
+
+You may want to use rst2pdf in a linux pipe as such::
+
+    cat readme.txt | rst2pdf | gzip -c > readme.pdf.gz
+
+or::
+
+    curl http://docutils.sourceforge.net/docs/user/rst/quickstart.txt | rst2pdf > quickstart.pdf
+
+If no input argument is provided, stdin will be used::
+
+    cat readme.txt | rst2pdf -o readme.pdf
+
+If outpufile is set to dash '-', output goes to stdout::
+
+    rst2pdf -o - readme.txt > output.pdf
+
+
+Headers and Footers
+===================
+
+ReST supports headers and footers, using the header and footer directive::
+
+  .. header::
+
+     This will be at the top of every page.
+
+Often, you may want to put a page number there, or a section name.The following
+magic tokens will be replaced (More will be added as rst2pdf evolves):
+
+###Page###
+    Replaced by the current page number.
+###Title###
+    Replaced by the document title
+###Section###
+    Replaced by the currect section title
+###SectNum###
+    Replaced by the currect section number. **Important:** You must use the sectnum directive for this to work.
+
+Headers and footers are visible by default but they can be disabled by specific
+`Page Templates`_ for example, cover pages. You can also set headers and footers
+via `command line options` or the `configuration file`_.
+
+Footnotes
+=========
+
+Currently rst2pdf doesn't support real footnotes, and converts them to endnotes.
+There is a real complicated technical reason for this: I can't figure out a
+clean way to do it right.
+
+You can get the same behaviour as with rst2html by specifying --inline-footnotes, 
+and then the footnotes will appear where you put them (in other words, not footnotes,
+but "in-the-middle-of-text-notes" or just plain notes.)
+
+Images
+======
+
+Inline
+------
+
+You can insert images in the middle of your text like this::
+
+  This |biohazard| means you have to run.
+
+  .. |biohazard| image:: ../rst2pdf/tests/input/images/biohazard.png
+
+This |biohazard| means you have to run.
+
+.. |biohazard| image:: ../rst2pdf/tests/input/images/biohazard.png
+
+This only works correctly with reportlab 2.2 or later.
+
+
+
+Supported Image Types
+---------------------
+
+For raster images, rst2pdf supports anything PIL (The Python Imaging Library) supports.
+The exact list of supported formats varies according to your PIL version and system.
+
+For vector image support, you need to install Dinu Gherman's svglib 
+(http://pypi.python.org/pypi/svglib/) or Uniconvertor from http://sk1project.org 
+version 1.1.3 or later.
+
+It provides support for these formats:
+
+* CorelDRAW ver.7-X3,X4 (CDR/CDT/CCX/CDRX/CMX)
+* Adobe Illustrator up to 9 ver. (AI postscript based)
+* Postscript (PS)
+* Encapsulated Postscript (EPS)
+* Computer Graphics Metafile (CGM)
+* Windows Metafile (WMF)
+* XFIG
+* Scalable Vector Graphics (SVG)
+* Skencil/Sketch/sK1 (SK and SK1)
+* Acorn Draw (AFF)
+
+Some features will not work when using these images.For example, gradients will not
+display, and text may cause problems.
+
+To test suitability of your vector images for use with rst2pdf, try converting them
+to PDF using uniconvertor. The result should be exactly the way they will look
+when used in your documents.
+
+If you can choose between raster and vectorial images, for non-photographic images,
+vector files are usually smaller and look better, specially when printed.
+
+If you want to use PDF files as images, you need to install PythonMagick
+(http://www.imagemagick.org), which will be used to convert it to PNG and
+then inserted in your document. If the quality is not good enough, try something like
+``--default-dpi 1200``
+
+This only works for one-page PDF files, and has several drawbacks, such as
+inability to copy text from the embedded image.
+
+In the future, rst2pdf will support ReportLab's PageCatcher to properly embed PDFs. That
+is not implemented yet, though.
+
+If there is any other image format you need supported, please report it as a feature
+request in rst2pdf's site.
+
+Image Size
+----------
+
+PDFs are meant to reflect paper. A PDF has a specific size in centimeters or inches. 
+
+Images usually are measured in pixels, which are meaningless in a PDF. To convert 
+between pixels and inches or centimeters, we use a DPI (dots-per-inch) value.
+
+For example, 300 pixels, with a 300DPI, are exactly one inch. 300 pixels at 100DPI
+are 3 inches.
+
+For that reason, to achieve a nice layout of the page, it's usually a good idea 
+to specify the size of your images in those units, or as a percentage of the 
+available width and you can ignore all this DPI nonsense ;-)
+
+The rst2pdf default is 300DPI, but you can change it using the --default-dpi option
+or the default_dpi setting in the config file.
+
+Examples of images with specified sizes::
+    
+  .. image:: home.png
+     :width: 3in
+     
+  .. image:: home.png
+     :width: 80%
+  
+  .. image:: home.png
+     :width: 7cm
+ 
+  
+The valid units you can use are:
+
+"em" "ex" "px" "in" "cm" "mm" "pt" "pc" "%" "".
+
+
+* px: Pixels. If you specify the size using this unit, rst2pdf will convert it to
+  inches using the default DPI explained above.
+  
+* No unit. If you just use a number, it will be considered as pixels. (**IMPORTANT:** 
+  this used to default to points. It was changed to be more compatible with rst2html)
+  
+* em: This is the same as your base style's font size. By default: 10 points.
+
+* ex: rst2pdf will use the same broken definition as IE: em/2. In truth this should
+  be the height of the lower-case x character in your base style.
+  
+* in: Inches (1 inch = 2.54 cm).
+
+* cm: centimeters (1cm = 0.39 inches)
+  
+* mm: millimeters (10mm = 1cm)
+
+* pt: 1/72 inch
+
+* pc: 1/6 inch
+
+* %: percentage of available width in the frame. Setting a percentage as a height 
+  does **not** work and probably never will.
+  
+If you don't specify a size at all, rst2pdf will do its best to figure out what it should do:
+    
+Since there is no specified size, rst2pdf will try to convert the image's pixel size to
+inches using the DPI information available in the image itself. You can set that value 
+using most image editors. For example, using Gimp, it's in the Image -> Print Size menu.
+
+So, if your image is 6000 pixels wide, and is set to 1200DPI, it will be 5 inches wide.
+
+If your image doesn't have a DPI property set, and doesn't have it's desired size specified,
+rst2pdf will arbitrarily decide it should use 300DPI (or whatever you choose with 
+the --default-dpi option).
+
+As of 0.10.1, images taller than the page will not work (rst2pdf will fail to run), and 
+images wider than the page will be cropped.
+
+
+Styles
+======
+
+You can style paragraphs with a style using the class directive::
+
+  .. class:: special
+
+  This paragraph is special.
+
+  This one is not.
+
+Or inline styles using custom interpreted roles::
+
+   .. role:: redtext
+
+   I like color :redtext:`red`.
+
+For more information about this, please check the ReST docs.
+
+The only special thing about using rst2pdf here is the syntax of
+the stylesheet.
+
+You can make rst2pdf print the default stylesheet::
+
+  rst2pdf --print-stylesheet
+
+If you want to add styles, just create a stylesheet, (or take the standard 
+stylesheet and modify it) and pass it with the -s option::
+
+  rst2pdf mydoc.txt -s mystyles.txt
+
+Those styles will always be searched in these places, in order:
+
+* What you specify using --stylesheet_path
+
+* The option stylesheet_path in the config file
+
+* The current folder
+
+* ~/.rst2pdf/styles
+
+* The styles folder within rst2pdf's installation folder.
+
+You can use multiple -s options, or pass more than one stylesheet
+separated with commas. They are processed in the order you give them
+so the *last* one has priority.
+
+Included StyleSheets
+--------------------
+
+To make some of the more common adjustments easier, rst2pdf includes a 
+collection of stylesheets you can use:
+
+Font styles
+    These stylesheets modfy your font settings.
+    
+    * ``serif`` uses the PDF serif font (Times) instead of the default Sans 
+      Serif (Arial)
+    * ``freetype-sans`` uses your system's default TrueType Sans Serif font
+    * ``freetype-serif`` uses your system's default TrueType Serif font
+    * ``twelvepoint`` makes the base font 12pt (default is 10pt)
+    * ``tenpoint`` makes the base font 10pt
+    * ``eightpoint`` makes the base font 8pt
+    * ``kerning`` switches to document to DejaVu Sans font and enables kerning.
+    
+Page layout styles
+    These stylesheets modify your page layout.
+    
+    * ``twocolumn`` uses the twoColumn layout as the initial page layout.
+    * ``double-sided`` adds a gutter margin (margin at the "in side" of the pages)
+
+Page size styles
+    Stylesheets that change the paper size.
+    
+    The usual standard paper sizes are supported:
+        
+    * A0
+    * A1
+    * A2
+    * A3
+    * A4 (default)
+    * A5
+    * A6
+    * B0
+    * B1
+    * B2
+    * B3
+    * B4
+    * B5
+    * B6
+    * Letter
+    * Legal
+    * 11x17
+
+    The name of the stylesheet is lowercase.
+
+Code block styles
+    See `Syntax Highlighting`_
+
+So, if you want to have a two-column, legal size, serif document with code in murphy style::
+    
+    rst2pdf mydoc.txt -s twocolumn,serif,murphy,legal
+
+StyleSheet Syntax
+-----------------
+
+It´s a JSON file with several elements in it.
+
+Font Alias
+----------
+
+This is the fontsAlias element. By default, it uses some of the standard PDF fonts::
+
+  "fontsAlias" : {
+    "stdFont": "Helvetica",
+    "stdBold": "Helvetica-Bold",
+    "stdItalic": "Helvetica-Oblique",
+    "stdBoldItalic": "Helvetica-BoldOblique",
+    "stdMono": "Courier"
+  },
+
+This defines the fonts used in the styles. You can use, for example, Helvetica
+directly in a style, but if later you want to use another font all through
+your document, you will haveto change it in each style. So, I suggest you
+use aliases.
+
+The standard PDF fonts are these:
+
+  Times_Roman
+  Times-Bold
+  Times-Italic
+  Times-Bold-Italic
+  Helvetica
+  Helvetica_Bold
+  Helvetica-Oblique
+  Helvetica-Bold-Oblique
+  Courier
+  Courier-Bold
+  Courier-Oblique
+  Courier-Bold-Oblique
+  Symbol
+  Zapf-Dingbats
+
+Style Definition
+----------------
+
+Then you have a 'styles' which is a list of [ stylename, styleproperties ]. For example::
+
+    ["normal" , {
+      "parent": "base"
+    }],
+
+This means that the style called "normal" inherits style "base". So, each property
+not defined in the normal style will be taken from the base style.
+
+I suggest you do not remove any style from the default stylesheet. Add or modify at
+will, though.
+
+If your document requires a style that is not defined in your stylesheet, it will
+print a warning and use bodytext instead.
+
+Also, the order of the styles is important: if styleA is the parent of styleB,
+styleA should be earlier in the stylesheet.
+
+These are all the possible attributes for a style and their default values.
+Some of them, like alignment, apply only when used to paragraphs,
+and not on inline styles::
+
+    "fontName":"Times-Roman",
+    "fontSize":10,
+    "leading":12,
+    "leftIndent":0,
+    "rightIndent":0,
+    "firstLineIndent":0,
+    "alignment":TA_LEFT,
+    "spaceBefore":0,
+    "spaceAfter":0,
+    "bulletFontName":"Times-Roman",
+    "bulletFontSize":10,
+    "bulletIndent":0,
+    "textColor": black,
+    "backColor":None,
+    "wordWrap":None,
+    "borderWidth": 0,
+    "borderPadding": 0,
+    "borderColor": None,
+    "borderRadius": None,
+    "allowWidows": 1,
+    "allowOrphans": 0
+
+The following are the only attributes that work on styles when used for interpreted roles
+(inline styles):
+
+* fontName
+
+* fontSize
+
+* textColor
+
+* backColor (if your reportlab is version 2.3 or newer)
+
+Font Embedding
+--------------
+
+There are thousands of excelent free True Type and Type 1 fonts available on the
+web, and you can use many of them in your documents by declaring them in your
+stylesheet.
+
+
+The Easy Way
+~~~~~~~~~~~~
+
+Just use the font name in your style. For example, you can define this::
+
+    ["normal" , {
+      "fontName" : "fonty"
+    }]
+
+And then it *may* work.
+
+What would need to happen for this to work?
+
+Fonty is a True Type font:
+""""""""""""""""""""""""""
+
+1. You need to have it installed in your system, and have the fc-match
+    utility available (it's part of fontconfig_). You can test if it is
+    so by running this command::
+
+        $ fc-match fonty
+        fonty.ttf: "Fonty" "Normal"
+
+    If you are in Windows, I need your help ;-) or you can use `The Harder Way (True Type)`_
+
+2. The folder where fonty.ttf is located needs to be in your font path. You can set it
+    using the --font-path option. For example::
+
+        rst2pdf mydoc.txt -s mystyle.style --font-path /usr/share/fonts
+
+    You don't need to put the *exact* folder, just something that is above it. In my own case,
+    fonty is in /usr/share/fonts/TTF
+
+Whenever a font is embedded, you can refer to it in a style by its name, and
+to its variants by the aliases Name-Oblique, Name-Bold, Name-BoldOblique.
+
+Fonty is a Type 1 font:
+"""""""""""""""""""""""
+
+You need it installed, and the folders where its font metric (.afm) and binary (.pfb) files
+are located need to be in your font fath.
+
+For example, the "URW Palladio L" font that came with my installation of TeX consists of
+the following files::
+
+    /usr/share/texmf-dist/fonts/type1/urw/palatino/uplb8a.pfb
+    /usr/share/texmf-dist/fonts/type1/urw/palatino/uplbi8a.pfb
+    /usr/share/texmf-dist/fonts/type1/urw/palatino/uplr8a.pfb
+    /usr/share/texmf-dist/fonts/type1/urw/palatino/uplri8a.pfb
+    /usr/share/texmf-dist/fonts/afm/urw/palatino/uplb8a.afm
+    /usr/share/texmf-dist/fonts/afm/urw/palatino/uplbi8a.afm
+    /usr/share/texmf-dist/fonts/afm/urw/palatino/uplr8a.afm
+    /usr/share/texmf-dist/fonts/afm/urw/palatino/uplri8a.afm
+
+So, I can use it if I put ``/usr/share/texmf-dist/fonts`` in my font path::
+
+    rst2pdf mydoc.txt -s mystyle.style --font-path /usr/share/texmf-dist/fonts
+
+And putting this in my stylesheet, for example::
+
+    [ "title", { "fontName" : "URWPalladioL-Bold" } ]
+
+There are some standard aliases defined so you can use other names::
+
+    'ITC Bookman'            : 'URW Bookman L',
+    'ITC Avant Garde Gothic' : 'URW Gothic L',
+    'Palatino'               : 'URW Palladio L',
+    'New Century Schoolbook' : 'Century Schoolbook L',
+    'ITC Zapf Chancery'      : 'URW Chancery L'
+
+So, for example, you can use ``Palatino`` or ``New Century SchoolBook-Oblique`` And it will mean
+``URWPalladioL`` or ``CenturySchL-Ital``, respectively.
+
+Whenever a font is embedded, you can refer to it in a style by its name, and
+to its variants by the aliases Name-Oblique, Name-Bold, Name-BoldOblique.
+
+The Harder Way (True Type)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The stylesheet has an element is "embeddedFonts" that handles embedding True Type
+fonts in your PDF.
+
+Usually, it's empty, because with the default styles you are not using any font
+beyond the standard PDF fonts::
+
+  "embeddedFonts" : [ ],
+
+You can put there the name of the font, and rst2pdf will try to embed it as described
+above. Example::
+
+  "embeddedFonts" : [ "Tuffy" ],
+
+Or you can be explicit and tell rst2pdf the files that contain each variant of the
+font.
+
+Suppose you want to use the nice public domain `Tuffy font`_, then you need to give the 
+filenames of all variants::
+
+  "embeddedFonts" : [ ["Tuffy.ttf","Tuffy_Bold.ttf","Tuffy_Italic.ttf","Tuffy_Bold_Italic.ttf"] ],
+
+This will provide your styles with fonts called "Tuffy" "Tuffy_Bold" and so on. They will
+be available with the names based on the filenames (Tuffy_Bold) and also by standard
+aliases similar to those of the standard PDF fonts (Tuffy-Bold/Tuffy-Oblique/Tuffy-BoldOblique).
+
+Now, if you use *italics* in a paragraph whose style uses the Tuffy font, it will use
+Tuffy_Italic. That's why it's better if you use fonts that provide the four variants, and
+you should put them in **that** order. If your font lacks a variant, use the
+"normal" variant instead. 
+
+For example, if you only had Tuffy.ttf::
+
+  "embeddedFonts" : [ ["Tuffy.ttf","Tuffy.ttf","Tuffy.ttf","Tuffy.ttf"] ],
+
+However, that means that italics and bold in styles using Tuffy will not work correctly (they will
+display as regular text).
+
+If you want to use this as the base font for your document, you should change the fontsAlias
+section accordingly. For example::
+
+      "fontsAlias" : {
+        "stdFont": "Tuffy",
+        "stdBold": "Tuffy_Bold",
+        "stdItalic": "Tuffy_Italic",
+        "stdBoldItalic": "Tuffy_Bold_Italic",
+        "stdMono": "Courier"
+      },
+
+If, on the other hand, you only want a specific style to use the Tuffy
+font, don't change the fontAlias, and set the fontName properties for
+that style. For example::
+
+    ["heading1" , {
+      "parent": "normal",
+      "fontName": "Tuffy_Bold",
+      "bulletFontName": "Tuffy_Bold",
+      "fontSize": 18,
+      "bulletFontSize": 18,
+      "leading": 22,
+      "keepWithNext": true,
+      "spaceAfter": 6
+    }],
+
+.. _tuffy font: http://tulrich.com/fonts/
+
+By default, rst2pdf will search for the fonts in its fonts folder and
+in the current folder. You can make it search another folder by passing
+the --font-folder option, or you can use absolute paths in your stylesheet.
+
+The Harder Way (Type1)
+~~~~~~~~~~~~~~~~~~~~~~
+
+To be written (and implemented and tested)
+
+Page Size and Margins
+---------------------
+
+In your stylesheet, the pageSetup element controls your page layout.
+
+Here's the default stylesheet's::
+
+  "pageSetup" : {
+    "size": "A4",
+    "width": null,
+    "height": null,
+    "margin-top": "2cm",
+    "margin-bottom": "2cm",
+    "margin-left": "2cm",
+    "margin-right": "2cm",
+    "spacing-header": "5mm",
+    "spacing-footer": "5mm",
+    "margin-gutter": "0cm"
+  },
+
+Size is one of the standard paper sizes, like A4 or LETTER.
+
+Here's a list: A0, A1, A2, A3, A4, A5, A6, B0, B1, B2, B3, B4, B5, B6,
+LETTER, LEGAL, ELEVENSEVENTEEN.
+
+If you want a non-standard size, set size to null and use width and height.
+
+When specifying width, height or margins, you need to use units, like
+inch (inches) or cm (centimeters).
+
+When both width/height and size are specified, size will be used, and
+width/height ignored.
+
+All margins should be self-explanatory, except for margin-gutter. That's the
+margin in the center of a two-page spread.
+
+This value is added to the left margin of odd pages and the right margin of
+even pages, adding (or removing, if it's negative) space "in the middle" of
+opposingpages.
+
+If you intend to bound a printed copy, you may need extra space there. OTOH,
+if you will display it on-screen on a two-page format (common in many PDF
+readers, nice for ebooks), a negative value may be pleasant.
+
+Advanced: table styles
+----------------------
+
+This is new in 0.12.
+
+These are a few extra options in styles that are only used when the style is applied to a table.
+This happens in two cases:
+    
+1) You are using the class directive on a table:
+    
+.. code-block:: rest
+
+   .. class:: thick
+   
+   +-------+---------+
+   |   A   |   B     |
+   +-----------------+
+   
+2) It's a style that automatically applies to something that is *drawn* using a table. 
+   Currently these include:
+       
+   * Footnotes / endnotes (endnote style)
+   * Lists (item_list, bullet_list option_list and field_list styles)
+   
+The options are as follows:
+
+Commands   
+   For a full reference of these, please check the Reportlab User Guide 
+   specifically the TableStyle Commands section (section 7.4 in the manual 
+   for version 2.3)
+    
+   Here, however, is a list of the possible commands::
+       
+        BOX (or OUTLINE)
+        FONT
+        FONTNAME (or FACE)
+        FONTSIZE (or SIZE)
+        GRID
+        INNERGRID
+        LEADING
+        LINEBELOW
+        LINEABOVE
+        LINEBEFORE
+        LINEAFTER
+        TEXTCOLOR
+        ALIGNMENT (or ALIGN)
+        LEFTPADDING
+        RIGHTPADDING
+        BOTTOMPADDING
+        TOPPADDING
+        BACKGROUND
+        ROWBACKGROUNDS
+        COLBACKGROUNDS
+        VALIGN
+
+   Each takes as argument a couple of coordinates, where (0,0) is top-left, and (-1,-1) is 
+   bottom-right, and 0 or more extra arguments.
+   
+   For example, INNERGRID takes a linewidth and a color::
+       
+       [ "INNERGRID", [ 0, 0 ], [ -1, -1 ], 0.25, "black" ], 
+
+   That would mean "draw all lines inside the table with .25pt black"
+
+colWidths
+   A list of the column widths you want, in the unit you prefer (default unit is pt).
+   
+   Example::
+       
+       "colWidths": ["3cm",null]
+
+   If your colWidths has fewer values than columns in your table, the rest are autocalculated.
+   A column width of null means "guess".
+   
+   If you don't specify column widths, the table will try to look proportional to the restructured 
+   text source.
+
+Multiple Stylesheets
+--------------------
+
+When you use a custom stylesheet, you don't need to define *everything* in it.
+Whatever you don't define will be taken from the default stylesheet. For example,
+if you only want to change page size, default font and font size, this would
+be enough:
+
+.. code-block:: js
+
+    {
+        "pageSetup" : {
+            "size": "A5",
+        },
+        "fontsAlias" : {
+            "stdFont": "Times-Roman",
+        },
+        "styles" : [
+            ["normal" , {
+            "fontSize": 14
+            }]
+        ]
+    }
+
+.. Note::
+    
+    The ``command`` option used for table styles is not kept across stylesheets.
+    For example, the default stylesheet defines endnote with this command list::
+        
+        "commands": [ [ "VALIGN", [ 0, 0 ], [ -1, -1 ], "TOP" ] ]
+
+
+    If you redefine endnote in another stylesheet and use this to create a vertical line between
+    the endnote's columns::
+
+        "commands": [ [ "LINEAFTER", [ 0, 0 ], [ 1, -1 ], .25, "black" ] ]
+        
+    Then the footnotes will **not** have VALIGN TOP!
+    
+    To do that, you **MUST** use all commands in your stylesheet::
+
+        "commands": [ 
+            [ "VALIGN", [ 0, 0 ], [ -1, -1 ], "TOP" ],
+            [ "LINEAFTER", [ 0, 0 ], [ 1, -1 ], .25, "black" ] 
+        ]
+
+.. raw:: pdf
+
+    PageBreak
+
+Styling Your Document
+---------------------
+
+Which styles you need to modify to achieve your desired result is not obvious.
+In this section, you will see some hints and pointers to that effect.
+
+The Base Styles
+~~~~~~~~~~~~~~~
+
+There are three styles which have great effect, they are ``base``,
+``normal`` and ``bodytext``. 
+
+Here's an example, the twelvepoint stylesheet::
+    
+    {"styles": [["base", {"fontSize": 12}]]}
+    
+Since all other styles inherit ``base``, changing the fontSize changes the fontSize 
+for everything in your document.
+
+The ``normal`` style is meant for most elements, so usually it's the same as changing
+``base``. 
+
+The ``bodytext`` style is for elements that form paragraphs. So, for example, you can set
+your document to be left-aligned like this::
+    
+    {"styles": [["bodytext", {"alignment": "TA_LEFT"}]]}
+    
+There are elements, however, that don't inherit from bodytext, for example headings and the
+styles used in the table of contents. Those are elements that are not real paragraphs, so
+they should not follow the indentation and spacing you use for your document's main content.
+
+The ``heading`` style is inherited by all sorts of titles: section titles, topic titles, 
+admonition titles, etc.
+
+Lists
+~~~~~
+
+Styling lists is mostly a matter of spacing and indentation.
+
+The space before and after a list is taken from the ``item_list`` and ``bullet_list`` styles::
+    
+    ["item_list", { 
+      "parent": "bodytext",
+      "spaceBefore": 0,
+      "commands": [
+            [ "VALIGN", [ 0, 0 ], [ -1, -1 ], "TOP" ], 
+            [ "RIGHTPADDING", [ 0, 0 ], [ 1, -1 ], 0 ] 
+        ],
+        "colWidths": ["20pt",null]
+    }]
+    
+    ["bullet_list", {
+      "parent": "bodytext",
+      "spaceBefore": 0,
+      "commands": [
+            [ "VALIGN", [ 0, 0 ], [ -1, -1 ], "TOP" ],
+            [ "RIGHTPADDING", [ 0, 0 ], [ 1, -1 ], 0 ] 
+        ], 
+        "colWidths": ["20",null]
+    }],
+
+Yes, these are table styles, because they are implemented as tables. The RIGHTPADDING command
+and the colWidths option can be used to adjust the position of the bullet/item number.
+
+To control the separation between items, you use the item_list_item and 
+``bullet_list_item`` styles' spaceBefore and spaceAfter options, for example::
+
+    ["bullet_list_item" , {
+      "parent": "bodytext",
+      "spaceBefore": 20
+    }]
+    
+Remember that this is only used **between items** and not before the first or after the 
+last items. 
+
+Syntax Highlighting
+===================
+