Vim ReStructureText Macros
written on Thursday, December 11, 2008
This post is about a great new document generator call Sphinx. It was created with the goal of simplifying document creation for Python projects, but can be used for much more. Using a simple text mark-up called reStructuredText, it will output beautiful HTML and PDF documents such as books, manuals, journals, etc.
Writing reStructuredText is extremely easy, however there are a few tweaks we can add to Vim to make adding reStructureText mark-up easier than using MS Word.
An example of reStructuredText from docs.python.org is shown below:
**********************************
Brief Tour of the Standard Library
**********************************
.. _tut-os-interface:
Operating System Interface
==========================
The :mod:`os` module provides dozens of functions for interacting with the
operating system::
>>> import os
>>> os.system('time 0:02')
0
>>> os.getcwd() # Return the current working directory
'C:\\Python26'
>>> os.chdir('/server/accesslogs')
Be sure to use the ``import os`` style instead of ``from os import *``. This
will keep :func:`os.open` from shadowing the builtin :func:`open` function which
operates much differently.
Section Macros
You will notice there are a few simple ways to denote sections of text. The most basic method is to underline text to indicate the start of a new section or sub-section. Because this is such a common operation when writing reStructureText, we can easily simplify these steps using macros in the Vim text editor.
Simply add the following macros to your ~/.vimrc file to easily turn any line of text into a reStructuredText section heading.
" Restructured Text
" #########################
" Ctrl-u 1: underline Parts w/ #'s
noremap <C-u>1 yyPVr#yyjp
inoremap <C-u>1 <esc>yyPVr#yyjpA
" Ctrl-u 2: underline Chapters w/ *'s
noremap <C-u>2 yyPVr*yyjp
inoremap <C-u>2 <esc>yyPVr*yyjpA
" Ctrl-u 3: underline Section Level 1 w/ ='s
noremap <C-u>3 yypVr=
inoremap <C-u>3 <esc>yypVr=A
" Ctrl-u 4: underline Section Level 2 w/ -'s
noremap <C-u>4 yypVr-
inoremap <C-u>4 <esc>yypVr-A
" Ctrl-u 5: underline Section Level 3 w/ ^'s
noremap <C-u>5 yypVr^
inoremap <C-u>5 <esc>yypVr^A
The macro's can be enabled with the following keypress: Control-U, #. # must be a number from 1-5. The numbering order of the macro's follow the Sphinx Section Heading mark-up definitions. For example the text:
MY SECTION HEADING
will be modified in the following manor for each macro.
| Macro Shortcut | Final Output |
|---|---|
| Ctrl-U 1 | ##################
MY SECTION HEADING
##################
|
| Ctrl-U 2 | ******************
MY SECTION HEADING
******************
|
| Ctrl-U 3 | MY SECTION HEADING
==================
|
| Ctrl-U 4 | MY SECTION HEADING
------------------
|
| Ctrl-U 5 | MY SECTION HEADING
^^^^^^^^^^^^^^^^^^
|