rst-sections

This is a small vim extension to help making sections in restructured text documents.

It was inspired by the nice https://github.com/nvie/vim-rst-tables extension by Vincent Driessen. The structure of this extension follows vim-rst-tables, and it uses more of Vincents's code from https://github.com/nvie/vim_bridge.

For install instructions see the Install section at the end.

Requirements

You'll need python compiled into your vim (:version in vim will tell you).

I've tested the python tests with Python 2.5, 2.6 and 3.3.

Latest version

Should be at https://github.com/matthew-brett/vim-rst-sections

License

I could not see a license for vim-rst-tables. vim-rst-sections contains some structure, but very little code, from vim-rst-tables.

Assuming that that the vim-rst-tables code is in the public domain or BSD licensed, I (Matthew Brett) release this code under the 2-clause BSD license. The full text is in the LICENSE file in the same directory as this README. Thanks to Vincent Driessen for sharing.

In use

Once you've installed the extension, then you can access it with your <leader> key in vim. I believe the default is \, for me it is mapped to ,. You can also call the various functions directly with commands such as :call RstSectionStandardize() - see below.

Conventional standard section markup

The script mostly assumes that you are using, or want to use, the section headings that the python documents use - see http://sphinx.pocoo.org/rest.html#sections . In summary, the convention is:

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

Autoconverting section markers to the convention

If you aren't using these conventions already, and you want to be able to use rst-sections in a happy way, you may be able to automatically change to use these conventions using the RstSectionStandardize vim function provided by this extension. Open the document you want to change, then run this:

call RstSectionStandardize()

The same function should also be accessible with the key combination <leader><leader>p ("p" for Python standard sections).

Making new sections

Imagine you've just started a document. You type this:

A big overall section

While the cursor is on that line, type <leader><leader>d (for me that is ,,d). d is for 'down', you may see why later. When you do this, you should get the top section heading formatting:

#####################
A big overall section
#####################

Then write some more text. Add another section below:

A subsection for the big one

Type (for me) ,,d and you get the top-level '#' under and overlining. That is, you get the same level as the nearest section above you. Type ,,d again and you go Down a level in the heirarchy to:

****************************
A subsection for the big one
****************************

Now, with the cursor in the same place, try ,,u (Up). Notice that the heading level goes Up one level to the top level in the heirarchy again:

############################
A subsection for the big one
############################

So, if you are on a line that is not currently a section, then either of ,,d or ,,u will format the line with the same section level as the nearest section above you (or the top level if there is no section above you). However, pressing ,,d on an existing section heading, will take you down a level in the heirarchy, and pressing ,,u will take you up a level in the heirarchy.

Reformatting section markup

Let's say you edited your section title, so now the heading isn't aligned with the text anymore:

############################
A section for the big one
############################

Yes, you've guessed it, ,,r on the section or the underlining will reformat for you:

#########################
A section for the big one
#########################

Install

I hope you are using vim pathogen!

If you are using pathogen

For the zip file:

Change into your ~/.vim/bundle` directory
Unzip the zip archive

From latest code at https://github.com/matthew-brett/vim-rst-sections:

Change into your ~/.vim/bundle` directory
clone vim-rst-sections into this directory, or add it as a submodule

If you aren't using pathogen

It's a really good idea to use pathogen. But: