Skip to main content

Ralsina.Me — Roberto Alsina's website

Hacking Restructured Text

I am a great fan of Re­struc­tured Tex­t. I write my blog us­ing it. I write my busi­ness pro­pos­als us­ing it, I write my doc­u­men­ta­tion us­ing it, I think you should write alm­sot ev­ery­thing you write now us­ing it. I have even blogged many times about it.

RST is a min­i­mal markup lan­guage. You can fig­ure it out in a cou­ple of hours, and then use it to pro­duce pret­ty HTML pages, PDF doc­s, man pages, La­TeX doc­u­ments, S5 slides, and oth­er things.

Plus, the source works as a plain text ver­sion, and is very read­able:

This is a title
===============

Some text in a paragraph

A subtitle
----------

* A list

* More items

  1. A numbered sublist

  2. Another item

     a) A sub-sub-list

     b) With more items


+-----------------------+-------------------------+
|   A table             | With two columns        |
+-----------------------+-------------------------+
|  And Two              |   rows                  |
+-----------------------+-------------------------+

See? Nice.

RST has an­oth­er great thing that is not so well known: there is a pars­er for it, which turns the doc­u­ment in­to a tree of nodes rep­p­re­sent­ing dif­fer­ent parts of the doc­u­men­t.

You can ma­nip­u­late this node tree, mod­i­fy­ing the doc­u­men­t, and then gen­er­ate the out­put.

But there is no way, right now, to gen­er­ate RST from the tree. Which means it's a one way road.

Well, I am hack­ing to fix that.

Right now, I han­dle ti­tles, sec­tion­s, all sorts of list­s, tran­si­tion­s, quotes, em­pha­sis, ital­ic­s, and a few oth­er el­e­ments.

The on­ly ones that seem dif­fi­cult to im­ple­ment are ta­bles, but I still think I can do it. Al­though the pro­duced RST does­n't look the same as the orig­i­nal, it is func­tion­al­ly iden­ti­cal.

How do I test if it work­s? With a test suit­e. If it work­s, it should be in­vari­ant this way:

RST­sam­ple -> rst2html pro­duces the ex­act same out­put as RST­sam­ple -> rst2rst -> rst2html

If any­one wants a copy, email me.

sebas / 2006-10-29 21:08:

I'd love to see that in kmail.

Adding layout options like the HTML editing mode, and then send it as RST in my email ...

martin j. ponce / 2006-10-31 17:46:

Have you give a try to txt2tags ?

Roberto Alsina / 2006-11-02 15:40:

I have looked at txt2tags, but only recently, and superficially.


Contents © 2000-2024 Roberto Alsina