sandbox/chm-writer/rst2chm.txt

   1 =======
   2 rst2chm
   3 =======
   4
   5 :Author: Ollie Rutherfurd <oliver@rutherfurd.net>
   6 :Date: 2003-08-14
   7 :Version: 0.3
   8
   9
  10 Introduction
  11 ============
  12
  13 rst2chm generates Microsoft (TM) HTML Help files from one or more
  14 `reStructuredText`_ source files.
  15
  16
  17 Usage
  18 =====
  19
  20 ::
  21
  22         rst2chm.py OUTFILE INFILE [INFILE...]
  23
  24 Examples
  25 --------
  26
  27 1. CHM for rst2chm
  28
  29 ::
  30
  31         rst2chm.py --title=rst2chm rst2chm.chm rst2chm.txt
  32
  33 2. CHM for Docutils
  34
  35 ::
  36
  37         rst2chm.py --title=Docutils
  38                 --default-topic=spec\rst\introduction.html
  39                 --stylesheet=tools\stylesheets\default.css
  40                 docutils.chm spec\rst\*.txt docs\*.txt *.txt
  41
  42 **Note that text is wrapped for display purposes only.**
  43
  44
  45 How it Works
  46 ============
  47
  48 When you run rst2chm, it does the following:
  49
  50 1. Reads through reST source files, and generates an HTML Help Contents
  51    file (.hhc).
  52
  53    Each reST source file is treated as a `topic` and each section
  54    within the file is treated as a section within that topic.
  55
  56    Topics are ordered in the order they were given on the command line,
  57    however you may specify a default `topic` using the ``--default-topic``
  58    command-line option.  If no default topic is specified, the first
  59    is used.
  60
  61 2. Converts reStructuredText files to HTML (*optional*).
  62
  63    rst2chm uses Docutil's HTML writer to generate HTML.  If you wish
  64    to use change the options, use a different writer, etc... you
  65    may disable HTML generate using the ``--no-html`` command-line option.
  66
  67 3. Creates an HTML Help Project file (.hhp).
  68
  69
  70 4. Uses HTML Help Compiler (hhc.exe), to create a CHM file.
  71
  72    rst2chm searches for "hhc.exe" using ``%PATH%`` environment variable
  73    and lastly in ``C:\Program Files\HTML Help Workshop\hhc.exe``, which was
  74    the default installation location on my machine.  Alternatively, you may
  75    use the ``--compiler`` command-line option to tell rst2chm where to find
  76    "hhc.exe".
  77
  78 5. Removes .hhc, .hhp, and HTML files (if rst2chm generated the HTML files).
  79
  80    To disable removal of these files, for debugging purposes, customization,
  81    etc... use the ``--no-clean`` command-line option.
  82
  83
  84 Todo
  85 ====
  86
  87 * Finish & test support for languages other than English.
  88 * Allow a template to be used for project.hhp?
  89 * Index (.hhk) support.
  90 * Option to include extra HTML files?
  91
  92
  93 License
  94 =======
  95
  96 `Python License <http://www.python.org/doc/Copyright.html>`_
  97
  98
  99 Requirements
 100 ============
 101
 102 * `Microsoft (TM) HTML Help Workshop`_
 103 * `Docutils`_, version 0.3 or higher suggested
 104
 105
 106 Known Issues & Bugs
 107 ===================
 108
 109 * Images sometimes aren't included (for example, tools\test.txt)
 110 * Section links don't work for::
 111
 112         C:\sandbox\rst2chm>rst2chm.py --no-clean --stylesheet=rst2chm.css
 113         sendkeys.chm ..\projects\SendKeys\trunk\doc\SendKeys.txt
 114
 115 * If input file is an absolute path, hhc compilation fails.  This may be a
 116   limitation of hhc.
 117
 118
 119 Version History
 120 ===============
 121
 122 0.3
 123 ---
 124
 125 Released 2003-08-14
 126
 127 * Using Latin-1 (ISO-8859-1) for output encoding.
 128
 129   This fixes ``A^`` thingies appearing between section numbers
 130   and titles in Docutils FAQ.
 131
 132 0.2
 133 ---
 134
 135 Released 2003-07-25
 136
 137 * Fixed StringIO hack in TOC generation.
 138
 139 0.1
 140 ---
 141
 142 Released 2003-07-10
 143
 144 * First release
 145
 146
 147 Feedback
 148 ========
 149
 150 Please send feedback to the author, Ollie Rutherfurd <oliver@rutherfurd.net> or
 151 to the docutils-users lists <docutils-users@lists.sourceforge.net>.
 152
 153
 154 .. _Microsoft (TM) HTML Help Workshop: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp
 155 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 156 .. _Docutils: http://docutils.sf.net/
 157
 158 .. :lineSeparator=\r\n:maxLineLen=80:mode=rest:noTabs=false:tabSize=4:wrap=none: