sandbox/rst2beamer/README.txt

   1 Introduction
   2 ============
   3
   4 A docutils script converting restructured text into Beamer-flavoured LaTeX.
   5
   6 Beamer is a LaTeX document class for presentations. rst2beamer [#homepage]_
   7 provides a Docutils [#docutils]_ writer that transforms restructured text
   8 [#rst]_ into Beamer-flavoured LaTeX. and provides a commandline script for the
   9 same. Via this script, ReST can therefore be used to prepare slides and
  10 presentations.
  11
  12
  13 Installation
  14 ============
  15
  16 rst2beamer can be installed via setuptools / easy_install or manually. Consult
  17 the enclosed manual for further details.
  18
  19
  20 Usage
  21 =====
  22
  23 rst2beamer should interpret a reasonable subset of restructured text and
  24 produce reasonable LaTeX. Not all features of beamer have been implemented,
  25 just a (large) subset that allows the quick production of good looking slides.
  26 These include:
  27
  28 * Overlay lists (i.e. list items that appear point-by-point)
  29 * Beamer themes
  30 * Automatic centering and resizing of figures
  31 * Embedded notes and the output of note slides.
  32 * Arranging slide contents into columns.
  33
  34 Some examples can be found in the ``docs/examples`` directory of the
  35 distribution. In practice, rst2beamer can be used with ``pdflatex`` to get PDF
  36 versions of a presentation.
  37
  38 .. note::
  39
  40         Depending on your platform, the script may be installed as ``rst2beamer``,
  41         or ``rst2beamer.py``.
  42
  43 rst2beamer is called::
  44
  45   rst2beamer [options] [<source> [<destination>]]
  46
  47 For example::
  48
  49         rst2beamer infile.txt outfile.tex
  50
  51 where ``infile.txt`` contains the ReST and ``outfile.tex`` contains the
  52 produced Beamer LaTeX.
  53
  54 It supports the usual docutils and LaTeX writer (rst2latex) options, save the
  55 ``documentclass`` option (which is fixed to ``beamer``) and hyperref options
  56 (which are already set in beamer). It also supports:
  57
  58 --theme=THEME           Specify Beamer theme.
  59 --overlaybullets=OVERLAYBULLETS
  60                         Overlay bulleted items. Put [<+-| alert@+>] at the end
  61                         of \begin{itemize} so that Beamer creats an overlay
  62                         for each bulleted item and the presentation reveals
  63                         one bullet at a time
  64 --centerfigs=CENTERFIGS
  65                         Center figures.  All includegraphics statements will
  66                         be put inside center environments.
  67 --documentoptions=DOCUMENTOPTIONS
  68                         Specify document options. Multiple options can be
  69                         given, separated by commas.  Default is
  70                         "10pt,a4paper".
  71 --shownotes=SHOWNOTES   Print embedded notes along with the slides. Possible
  72                         arguments include 'false' (don't show), 'only' (show
  73                         only notes), 'left', 'right', 'top', 'bottom' (show in
  74                         relation to the annotated slide).
  75
  76
  77 Limitations
  78 ===========
  79
  80 Earlier versions of rst2beamer did not work with docutils 0.4, seemingly due
  81 to changes in the LaTeX writer. While this has been fixed, most work has been
  82 done with docutils snapshots from version 0.5 and up. In balance, users are
  83 recommended to update docutils.
  84
  85 More recently, changes in the LaTeX writer in docutils 0.6 broke rst2beamer
  86 again. We think all those bugs have been caught.
  87
  88 Not all features of beamer are supported, and some - that deal with with page
  89 layout or presentation - may never be. Introducing complex syntax to achieve
  90 complex and specific page effects defeats the point of ReST's simple and
  91 easy-to-write format. If you need a complex presentation, use Powerpoint or
  92 Keynote.
  93
  94 If the content for an individual slide is too large, it will simply overflow
  95 the edges of the slide and disappear. Arguably, this is a sign you should put
  96 less on each slide.
  97
  98
  99 Credits
 100 =======
 101
 102 rst2beamer is developed by `Ryan Krauss <ryanwkrauss@gmail.com>`__ and
 103 `Paul-Michael Agapow <agapow@bbsrc.ac.uk>`__. Thanks to those who reported and
 104 helped us track down bugs: Perttu Laurinen, Mike Pennington, James Haggerty
 105 and Dale Hathaway.
 106
 107
 108 References
 109 ==========
 110
 111 .. [#homepage] rst2beamer homepages at `agapow.net
 112    <http://www.agapow/net/software/rst2beamer>`__ and `cs.siue.edu
 113    <http://home.cs.siue.edu/rkrauss/python_website/>`__
 114
 115 .. [#docutils] `Docutils homepage <http://docutils.sourceforge.net/>`__
 116
 117 .. [#rst] `Restructured text <http://docutils.sourceforge.net/rst.html>`__
 118
 119 .. [#beamer] `Beamer homepage <http://latex-beamer.sourceforge.net/>`__
 120