Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
vim plugin to work with sections in restructured text documents
VimL Python
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

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.