sandbox/rst2chunkedhtml/README.txt

   1 ===============
   2 rst2chunkedhtml
   3 ===============
   4
   5 ------------------------------------
   6 An HTML Chunker for reStructuredText
   7 ------------------------------------
   8
   9
  10 :Author: Andras Mohari <mayday at vizslamail dot hu>
  11 :Date: $Date$
  12 :Status: *Experimental*
  13 :Copyright: This document has been placed in the public domain.
  14
  15 :Abstract: ``rst2chunkedhtml`` reads standalone reStructuredText source files
  16    and produces chunked HTML output. It chunks sections up to a specified
  17    depth, and uses the DocUtils HTML writer to convert the chunks to HTML.
  18
  19 .. contents::
  20 .. sectnum::
  21
  22
  23 Requirements
  24 ============
  25
  26 * Python 2.4 or newer.
  27 * A recent development version of DocUtils.
  28 * `This patch`_. It adds chunking
  29   support to the HTML writer (``docutils/writers/html4css1/__init__.py``).
  30
  31 .. _This patch:
  32 .. _patch: html4css1-external-refs.patch
  33
  34
  35 Setting Up
  36 ==========
  37
  38 To try rst2chunkedhtml, grab the latest development version of DocUtils, copy
  39 the ``docutils`` Python package to a directory of your choice, and apply the
  40 patch_ to it. Finally adjust your PYTHONPATH environment variable so that the
  41 package can be imported.
  42
  43
  44 Quick Start
  45 ===========
  46
  47 Let's chunk a file called ``demo.txt``::
  48
  49    mkdir demo
  50    rst2chunkedhtml --chunk-depth=0 demo.txt demo/index.html
  51
  52 This chunks all sections, writes the root chunk to ``demo/index.html``, and
  53 all other chunks to ``demo/<id>.html``, where ``<id>`` is the section ID. As
  54 you can see above, the directory must already exist, it will not be created
  55 for you. Note that if a chunked section node has an ID called ``index``, the
  56 filename of the chunk would conflict with that of the root chunk, and
  57 rst2chunkedhtml will exit with an error.
  58
  59
  60 Usage
  61 =====
  62
  63 You can invoke ``rst2chunkedhtml`` the same way you would invoke ``rst2html``::
  64
  65    rst2chunkedhtml [options] [<source> [<destination>]]
  66
  67 TODO
  68
  69 .. vim: set tw=78 ts=3 sw=3 sts=3 et ft=rst: