How to reformat reStructuredText?

Question

I'm writing reST in vim, which handles line breaks for me (after 80 chars). However, since I frequently go back and edit the text before, lines get ugly again. For example, in tables, it's sometimes annoying to re-format a complete table just because you need a line break in some place.

So I wish I had a program that reads my ugly-but-correct reStructuredText and outputs it nicely formatted and wrapped.

I found that pandoc in.rst -w rst mostly works, but it has some drawbacks. For example

:author: John Doe

becomes

author
    John Doe

and title formatting is changed as well. Sadly, there seems to be no rst2rst or something similar. Does anyone have some advice?

Answer 1

You could use:

setlocal formatoptions+=a

to turn on automatic formatting of paragraphs in vim. Adding that line to the ftplugin/rst.vim file in your vim configuration directory should do it automatically whenever you start editing a .rst file.

If that reformats too much, it may improve things to also add the w option. That causes vim to only consider a paragraph to extend onto the next line when a line ends with a space. It will automatically put a space at the ends of lines that are automatically inserted.

Answer 2

Use -s with pandoc if you want the title block to be handled better.