sponsor Vim development Vim logo Vim Book Ad

vim-rst-sections : Plugin to work with sections in ReST

 script karma  Rating 0/0, Downloaded by 144    Comments, bugs, improvements  Vim wiki

created by
Matthew Brett
 
script type
ftplugin
 
description
This is a small vim extension to help making sections in restructured text
documents.

It's very closely based on the nice https://github.com/nvie/vim-rst-tables
extension by Vincent Driessen.  It includes some of Vincents's code from
https://github.com/nvie/vim_bridge.

The latest version of the code for this plugin is at:
https://github.com/matthew-brett/vim-rst-sections

You'll need python compiled into your vim for it to work (`:version` in vim will
tell you).

*******
License
*******

I could not see a license for ``vim-rst-tables`` on which this is based.
``vim-bridge`` is BSD licensed, as is this code.

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 details
Please, use pathogen!

If you are using pathogen:

* ``cd ~/.vim/bundle``
* unzip the zip file into that directory.

If you are not using pathogen:

* unzip the source bundle to some directory.
* Change directory into the new ``vim-rst-sections-<version-no>`` directory.
* Copy the contents of the 'ftplugin' directory into your ``.vim/ftplugin`` directory
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vim-rst-sections-0.1.zip 0.1 2013-03-24 7.0 Matthew Brett Initial upload
ip used for rating: 54.147.196.159

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
SourceForge.net Logo