A PML bundle for Vim.
This plugin adds the following functionality:
- context aware autocompletion (aka omni-complete)
- PML snippets for SnipMate
- generate a clickable table of contents for
<title>s in a chapter
This README file is primarily concerned with how to install the plugin and its dependencies. For a guide on how to use it, check the Authors wiki.
Some of the functionality depends on other Vim plugins. Brief installation notes follow for each of these.
TextMate style snippets for PML
Install the RagTag plugin to get smart tag completion. These commands are particularly useful:
<C-X><Space> create an inline tag from the word in front of the cursor <C-X><CR> create a block level tag from the word in front of the cursor <C-X>/ insert the closing tag for the previous unpaired opening tag
Generate a table of contents per chapter
On OS X, you can get exuberant tags by running:
brew install ctags. On linux, you can install it by running:
sudo apt-get install exuberant-ctags.
You can install the taglist.vim plugin the traditional way, by following the instructions on the vim.org page. Or if you use pathogen with git submodules then you might want to use the git mirror of taglist.vim instead.
The exuberant tags program supports over 40 programming languages, but it doesn’t know anything about PML. Luckily it’s quite easy to extend exuberant tags to support other languages, by adding rules to a
~/.ctags file. In the repository for this plugin, you'll find a file called
ctags. Append the contents of this file to your
~/.ctags file. The exuberant tags site has more information on extending ctags to support other languages.
The taglist plugin needs to know where you have installed exuberant tags. You can find out by running
which ctags. On my system, this returns "/usr/local/bin/ctags". Put this line in your vimrc file:
let Tlist_Ctags_Cmd = "/usr/local/bin/ctags"
You might also want to create a mapping so that you can quickly toggle the taglist table of contents. For example, if you put these lines in your vimrc:
let mapleader = "," nmap <Leader>/ :TlistToggle<CR>
You could now toggle the taglist by pressing
,/ (comma forward-slash).
Fold by section
The pml.vim plugin includes a custom folding expression, which allows you to fold sections of your PML document. This screenshot shows how a document looks when opened, with all
<sect1> tags folded. Note that the fold indicates how many lines have been hidden, and shows the title of the folded section.
The next screenshot demonstrates how the document looks after opening the first
<sect1> tag. Note that the
<sect2> blocks are indented more than the
<sect1> blocks, and the section level is indicated in brackets:
If you just learn one folding command, make it this one:
zi. This toggles folding behaviour on and off. You'll want folding disabled until you learn some of the finer grained folding commands. Then run
:help fold-commands and swat up.
Folding other elements
By default, the
figure elements are also folded. If you want to customize the list of elements that are folded, you can do so by assigning a list of element names to the
g:pml_foldable_elements global variable. For example, if you included this line in your
let g:pml_foldable_elements = ['story','sidebar']
This would make
sidebar elements foldable (but not
Room for improvement
The table of contents (TOC) generated by this method is rough and ready. It's just a list of links to
<title>s from throughout the document. That means that it includes the title of figures, e.g.:
<figure id="fig.soft.vs.hard.wrapping"> <title>Soft versus hard wrapping</title> <imagedata width="full" fileref="images/eps/soft-V-hard-wrap.eps"/> </figure>
Ideally, I would prefer if the all figures were collected in a separate list. Also, I would like it if the TOC showed the heirarchy of a chapter by indenting
<sect3>. These optimisations would be nice, but even without them, this is a very useful feature.
Generating a vimball
To distribute the script on vim.org wrap it up as a vimball by following these steps:
- first, ensure that the file
pml.vbais not loaded in a Vim buffer
- open the file
- set the variable
g:vimball_hometo the development directory of this plugin (e.g. run:
- visually select all lines in
That should create a file called
pml.vba which you can upload to vim.org.
Written and maintained by Drew Neil, with contributions from:
- Brendan McAdams (created the omni-completion)
- Nathan Eror (created the snipMate snippets)
- Dion Nicolaas