sandbox/rst2pdf-rubber/README.txt

   1 ..  #!/usr/bin/env python
   2   # -*- coding: utf8 -*-
   3   # $Id$
   4 .. -*- rst-mode -*-
   5
   6 rst2pdf README
   7 ==============
   8
   9 `<rst2pdf.py>`_ is a PDF front-end for Docutils that is compatible
  10 with the ``rst2*.py`` front ends of the Docutils_ suite.
  11 It enables the generation of PDF documents from a reStructuredText source in
  12 one step cleaning up intermediate files.
  13
  14 ``rst2pdf.py`` is implemented as a combination of Docutils' ``rst2latex.py``
  15 and rubber_ by Emmanuel Beffara.
  16
  17 Copyright: © 2008 Günter Milde
  18            Licensed under the `Apache License, Version 2.0`_
  19            Provided WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND
  20
  21 Requirements
  22 ------------
  23
  24 Docutils_
  25   for the reStructuredText -> LaTeX conversion
  26
  27 pdflatex and friends
  28   A recent LaTeX installation including pdflatex.
  29
  30 rubber_
  31   Rubber is a program whose purpose is to handle all tasks related to the
  32   compilation of LaTeX documents. This includes compiling the document
  33   itself, of course, enough times so that all references are defined, and
  34   running BibTeX to manage bibliographic references. Automatic execution of
  35   dvips to produce PostScript documents is also included, as well as usage
  36   of pdfLaTeX to produce PDF documents.
  37
  38   Rubber packages exist for Debian, Gentoo, FreeBSD, NetBSD, Fink and
  39   Darwin.
  40
  41   The current development version contains many bug fixes: `rubber snapshot`_
  42
  43 Installation
  44 ------------
  45
  46 Copy the file rst2pdf.py_ into a directory in the operating
  47 system's PATH for executable binaries or create a link.
  48
  49 Usage
  50 -----
  51 ::
  52
  53   rst2pdf.py [options] [<source> [<destination>]]
  54
  55 Get a list of supported options with ``rst2pdf.py --help``.
  56
  57 Configuration
  58 -------------
  59
  60 ``rst2pdf.py`` uses the "latex" writer for conversion from reStructuredText
  61 which is configured in the ``[latex2e writer]`` section of the configuration
  62 files. (See `Docutils Configuration`_)
  63
  64 Currently, the options for ``rubber`` are "hardcoded" in rst2pdf.py_.
  65 Therfore, the configuration of the LaTeX -> PDF conversion requires changing
  66 the settings directly in the (well documented) rst2pdf.py_ file.
  67
  68 Troubleshooting
  69 ---------------
  70
  71 In case of errors, reproduce the document-generating steps by hand to
  72 localise the problem:
  73
  74 * export the document with ``rst2latex.py INFILE OUTFILE``
  75
  76 * convert to PDF with ``rubber --pdf OUTFILE``
  77
  78   If this fails, try ``pdflatex OUTFILE``
  79
  80 Send bug reports to the author or the docutils-users list.
  81
  82 .. References
  83
  84 .. _Docutils: http://docutils.sourceforge.net/
  85 .. old _rubber site: http://www.pps.jussieu.fr/~beffara/soft/rubber/
  86 .. _rubber: http://iml.univ-mrs.fr/~beffara/soft/rubber/
  87 .. _rubber snapshot: http://iml.univ-mrs.fr/~beffara/soft/rubber/rubber-20080323.tar.gz
  88 .. _Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
  89
  90 .. _Docutils Configuration:
  91       http://docutils.sourceforge.net/docs/user/config.html