sandbox/rst2beamer/docs/DEVNOTES.txt

   1 =================
   2 Development notes
   3 =================
   4
   5 This document should not be included in the release distribution, and serves
   6 simply as internal notes and reminders for why certain things are the way they
   7 are.
   8
   9
  10 The literal and quote problem
  11 -----------------------------
  12
  13 20091024 PMA: The reasoning and history here is complicated so it needs to be
  14 written down. Way back in the genesis of rst2beamer, a problem was encountered
  15 with literals. The docutils LateX writer typeset them correctly in a regular
  16 monospace (\ttfamily) font. However in Beamer documents they appeared as an
  17 italic monospace font. This is because (a) docutils expresses literal blocks
  18 as a \quote, and (b) the Beamer document class sets the quote font to be
  19 italic. (See the beamer themes/fonts files.) Way back, I apparently solved
  20 this problem by overriding the LaTeX writers' visit and depart methods for
  21 literals.
  22
  23 Dim memory says that this worked in the days of docutils 0.4, but now
  24 (docutils 0.6), it strips the indenting from literal blocks. The solution is
  25 thus to use the parent literal methods, but to set the quote font to ttfamily
  26 before visiting a literal and reset it after leaving. This appears to work.
  27
  28
  29 Using Pygments to highlight code
  30 --------------------------------
  31
  32 20091029 PMA: Duplicating the Sphinx ability to use Pygments to highlight code
  33 is both easy and hard. You have to use the fancyvrb package to get the
  34 Verbatim environment that Pygments produces. You also have to include a set of
  35 definitions that the LatexFormatter produces in the header. Also, there is
  36 weird problem that crops up when you use a Verbatim environment inside a
  37 frame. You get odd errors about something not completing or terminating,
  38 unless you give a "fragile" qualifier to the frame::
  39
  40    \begin{frame}[fragile]
  41
  42 The commandline arguments that refer to codeblocks are arguably verbose but
  43 clear.
  44
  45 The objective here is to use a syntax that is compatible and simple, which we
  46 do by implementing behaviour just like those in Sphinx, thus making documents
  47 portable to Sphinx.
  48
  49 Initially, it seemed sensible to a "container trick" with codeblocks, allowing
  50 codeblocks within containers with a special class. As with columns, this
  51 should allow a simple portability without requiring a special directive. But
  52 there's a few reasons why this won't work:
  53
  54 * Making it a container means that the contents will be parsed and formatting
  55   lost.
  56
  57 * We can't put a class on a literal block, because in ReST it isn't a
  58   directive, it's pure syntax (`::`).
  59
  60 * Parsed literal blocks are a directive, but parsing it for ReST markup and
  61   highlighting it with Pygments presents an intractable tangle.
  62
  63 * Line blocks are meant for line formatted normal text (like poetry), and
  64   perverting it for codeblocks seems inappropriate.
  65
  66 If you use tabs to indent a codeblock, the indenting comes out in Beamer as
  67 very wide - 8 spaces each. Thus the "replace-tabs" argument was introduced,
  68 but things are complicated. Upon reading ReST replaces tabs with 8 spaces.
  69 This happens even for literal and raw blocks. Thus, to resize the tabs (e.g.
  70 replace them with 3 spaces not 8), we have to search and replace 8 space
  71 stretches. If the source has mixed tabs and spaces, or if the "replace-tabs"
  72 option is used where spaces are used for indenting, bad things could happen.
  73
  74 It's unclear to me what happens if you try to syntax-color (or guess the
  75 language of) incorrect or malformed code.
  76
  77
  78 Normalise directive names
  79 -------------------------
  80
  81 20091029 PMA: Most docutils names use hyphens as opposed to underscores (e.g.
  82 ``code-blocks``). As an added complexity, underscores appear to be translated
  83 into hyphens by docutils, so we've gotten in a a scrap allowing all sorts of
  84 names. From this point on, hyphens shall be the "official" style (``r2b-`` as
  85 opposed to ``r2b_``), although existing underscores shall maintained silently
  86 for compatibility.
  87