Editing DocBook with Vi

Tabs
To open all of the XML files within a book in tabs start VIM from the root of the book with the following command:

vim -p en-US/*.xml

Issuing  closes the current tab, issuing   switches to the next tab and issuing   switches to the previous tab.

For more information on using tabs issue the following command in VIM:


 * help tab-page-intro

Folding
As of VIM 7.0 support for folds is included in the editor. Folds allow sections of a document which are not being actively worked on to be 'folded' into themselves and hidden. Programmers often use folds to hide and show functions, classes and structures but the functionality is equally useful when editing DocBook XML.

Fold methods
Whether VIM folds content and how it folds it depends on the  setting. There are a number of valid options:


 * - Folds are created manually.
 * - Folds are created based on indentation levels.
 * - Folds are created based on the value of.
 * - Folds are created based on markers.
 * - Folds are created based on syntax highlighting items.
 * - Folds are created based on whether text has/hasn't changed, text that hasn't changed is folded.

When working with consistently indented XML content for example the  method is very easy to invoke and requires no additional setup. It can be accessed by issuing:

set foldmethod=indent

Issuing this command while a consistently indented XML file is open in the buffer will result in a number of folds being created. Folds can be opened by placing the cursor on the line denoting the fold. For example in the following XML block there is an appendix opened on line 4 and closed on line 184. The enclosed content is a fold which contains 179 lines of text.

4  5 +--179 lines: &PRODUCT; Manager backup and recovery 184

Information on the various fold methods and how they handle folds can be accessed by issuing  in VIM.

Work with folds
Some frequently used commands when working with folds are:


 * Use  to open the fold under the cursor.
 * Use  to close the fold under the cursor.
 * Use  to open all folds in the buffer.
 * Use  to close all folds in the buffer.
 * Use  to create a fold from a visual selection when   is set to manual.
 * Use  to delete a fold at the cursor when   is set to manual.

There are many other options to facilitate modification of the way folds behave in VIM. Further information on the use of folds in VIM can be accessed by issuing  from command mode.

Save folds across sessions
By default folds are discarded when exiting. Folds can be explicitly written to disk by issuing. When the file is next opened  can be issued to reload previously saved folds for the document. Alternatively the following lines can be placed in the users  file to ensure that folds are automatically loaded and saved when buffers are opened and closed respectively.

au BufWinLeave * mkview au BufWinEnter * silent loadview

Work with surround
A handy vim plugin exists that allows you to quickly edit surrounding XML, HTML tags or parenthesis etc. First download latest surround plugins. Then unzip it into /usr/share/vim/vimfiles, surround.vim file should be in /usr/share/vim/vimfiles/plugin directory now. Install it's done.

Surround.vim is all about "surroundings": parentheses, brackets, quotes, XML tags, and more. The plugin provides mappings to easily delete, change and add such surroundings in pairs.

It's easiest to explain with examples. Press `cs"'` inside

"Hello world!"

to change it to

'Hello world!'

Now press `cs' ` to change it to

&lt;q>Hello world!

To go full circle, press `cst"` to get

"Hello world!"

To remove the delimiters entirely, press `ds"`.

Hello world!

Now with the cursor on "Hello", press `ysiw]` (`iw` is a text object).

[Hello] world!

Let's make that braces and add some space (use `}` instead of `{` for no space): `cs]{`

{ Hello } world!

Now wrap the entire line in parentheses with yssb or yss)

({ Hello } world!)

Revert to the original text: ds{ds)

Hello world!

Emphasize hello: ysiw&lt;em>

&lt;em>Hello&lt;/em> world!

Finally, let's try out visual mode. Press a capital V (for linewise visual mode) followed by `S&lt;p class="important">`.

&lt;p class="important"> &lt;em>Hello world! &lt;/p>

This plugin is very powerful for HTML and XML editing, a niche which currently seems underfilled in Vim land. (As opposed to HTML/XML &lowast;inserting*, for which many plugins are available). Adding, changing, and removing pairs of tags simultaneously is a breeze.

Set options per file
For convenient editing, I add the following lines to the bottom of any DocBook files I'll be editing in Vi(m):

Block indentation
To support quick indentation of visually selected blocks keys can be bound to decrease and increase the indentation level. In the example  lines below the '&lt;' key is bound to decrease indentation and the '&gt;' key is bound to increase indentation.

vnoremap &lt; &lt;gv vnoremap &gt; &gt;gv