Skip to content
vim plugin to work with sections in restructured text documents
VimL Python
Failed to load latest commit information.
doc
ftplugin
.gitignore
LICENSE
README

README

############
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:

For the zip file:

* Unzip to some directory
* ``cd`` into the new subdirectory ``vim-rst-sections-<version>`` where
  ``<version>`` is the version number (e.g ``cd vim-rst-sections-0.1``)
* copy the contents of the ``ftplugin`` directory into your ``~/.vim/ftplugin``
  directory (e.g ``cp ftplugin/* ~/.vim/ftplugin``).

.. vim: ft=rst
Something went wrong with that request. Please try again.