Richard Jones' Log: Bruce: how to proceed?

Tue, 13 May 2008

As previously hinted Bruce, the Presentation Tool may now display presentations authored in ReStructuredText. I've had a chance to do some more work on it lately, and need to take a step back and think about what I'm trying to do :)

The ReST capabilities currently available are:

  1. Sections denote pages (just like all the other ReST presentation tools),
  2. Lists are handled (some features missing). A lot of inline markup is handled. Images are handled, both inline and stand-alone.
  3. The stylesheet and other configuration may be changed on the fly with ".. config::" directives.
  4. The background decoration* may be specified with a ".. decoration::" directive.

*: the decoration stuff is new as of very recently too. Currently it controls the background colour, but also allows rendering of quads (with colour gradient if you like) and images in the background. There's still much to do like scaling the decoration layer to the screen size, and adding more toys to decorate with like lines and possibly splines. Not sure how far to take it.

Missing from the ReST side though is:

  1. Pages without titles (this would require some sort of "page" directive to indicate a new page has begun).
  2. Other page types like the Python interpreter, Python code and Video.
  3. Handling notes and running-sheet HTML generation sensibly.
  4. Allowing custom page types, perhaps through ".. custom:: <module name>"

Those things aren't insurmountable. I'm becoming increasibly convinced that ReST is a better way to go than the custom markup format, but I'm having trouble with the final decision to give up on the old format.

Of course maintaining two parsers is ... silly.

I'm pretty sure I've made my decision, but thought I'd throw this post out anyway in case anyone had any thoughts or encouragement...

Comment by Alex on Tue, 13 May 2008

How about using ---- to denote section breaks for untitled sections?

Comment by Juri Pakaste on Tue, 13 May 2008

Have you considered one of the other popular text markup formats, like Markdown or Textile? I usually prefer them to ReST when doing prose, but admittedly I haven't thought about your usecase.

Comment by Nick Efford on Tue, 13 May 2008

+1 from me on shifting your focus to ReST.

I use ReST for all sorts of things, and your support for it is certainly making me think about using Bruce for presentations in the future.

Comment by Richard on Tue, 13 May 2008

Well, the bullet has been bitten and the code switched to focus solely on ReST.

@Juri: if the other formats had a parser that produced docutils-style document trees then it'd actually be pretty easy to support them...

Comment by Shawn Wheatley on Tue, 13 May 2008

How about throwing a demo presentation file up showing the new features, or can I grab one from SVN?

Comment by David Goodger on Tue, 13 May 2008

The way I do title-less pages in Docutils/S5 is to use a blank title: "\ " (escaped space) as the title text, underlined normally. A bit of a hack, but it works fine.

Comment by David Goodger on Tue, 13 May 2008

The problem with adding custom directives is that the source text becomes tied to the specific system, and can't be repurposed. That makes it difficult to reprocess the reST source as a standalone HTML file.

Any thoughts on this? Maybe we should discuss it on the docutils-develop list :-)

Comment by riq on Tue, 13 May 2008

+1 in switching to ReST.
Lot of people already know ReST (I'm thinking of me), so there is no need to learn yet another language.

Comment by Richard on Tue, 13 May 2008

@Shawn: there's a sample in SVN under examples/example.rst

@David: yeah, I'm going to have to write a custom transform that turns my directives into regular docutils nodes. Currently I have a nasty feeling that I'm going to have to re-implement HTML writing too. And every other target :(

I'll look into getting onto the docutils devel list...

Comment by Richard on Tue, 13 May 2008

OK, I'm subscribed to docutils-develop (again, lol, look at the April 2002 archive :)