RefDB Features: Vim support

RefDB plays well with Vim. You'll get support for both editing of RIS bibliographic data and for your DocBook XML documents. Vim support is not included in the RefDB sources, but available separately.

Vim and DocBook XML editing

Author: David Nebauer <davidnebauer@swtch.com.au>

Package: vim-docbk-xml-refdb (1.2) [source, deb].

Requires: imagemagick [web, deb]; fop [web, deb]; xmllint [web, deb]; xsltproc [web, deb]; libgetopt-declare-perl web, deb]; refdb-cache (1.0) [source, deb]; libperl-refdb-cache (1.0) [source, deb].

If Vim is the editor of your choice, this package installs the syntax, filetype and plugin files that enable you to edit DocBook XML files.

The plugin has a rather extensive list of dependencies as it interacts with a great many components in order to perform all its functions. For example, in order to create and view PDF and (X)HTML output it must use an XML validator (xmllint), an XSLT processor (xsltproc), a FO processor (fop), an HTML viewer and a PDF viewer. There are other dependencies which are not listed as they are commonly available on most *nix systems. For further information on dependencies unpack the source archive, read the README file and type ./configure --help. Debian users need only select the primary package and the rest will happen automagically

While this suite consists of a number of components, all its functionality is exposed as keystroke mappings. All mappings (except special characters) are available via the DocBook menu (menus can be accessed from console vim — see vim help topic 'console-menus').

The source distribution can be built with support for multiple XSLT processors (xsltproc, Saxon, Xalan), FO processors (FOP, Xep), xml validators (xmllint, RXP) and, of course, RefDB.

The Debian package has a minimal configuration with support for only one XSLT processor (xsltproc), one FO processor (Fop), one xml validator (xmllint) and RefDB.

Here is an overview of the functionality supplied by the plugin:

• A skeleton document structure can be generated. The user will be prompted to supply some details such as author name and document title.
• There are mappings for major document divisions: chapter, section and sect1|2|3.
• Minor structures can also be generated: para, comment, (strong) emphasis, footnote, blockquote, filename, verbatim, note, index term, glossary term, warning, sidebar and example. The user is generally prompted to enter the text to be enclosed by the structure. Some of these mappings work in visual mode, where the selected text will be "wrapped" by the structure.
• A mapping is supplied to insert a filepath. The user selects the file from a file selector dialog box. The user can choose whether to insert an absolute or relative filepath.
• A number of mappings are supplied for certain characters that are represented by character entities: ampersand (&), quote marks ('|"), angle brackets (<|>), em and en dashes (—|–), ellipses (…) and non-breaking spaces ( ). When the user types a single or double quote mark ('|") the corresponding character entity (“|‘|’|”) is chosen intelligently. Alternative mappings are supplied for inserting single and double straight quote mark character entities, and for inserting raw single and double quote marks. A mapping is supplied for "raw" ampersands.
• Cross-references and hyperlinks can be inserted into the document. For cross-references the user is presented with a list of element IDs to choose from.
• Support for lists (itemised, ordered and variable type) is supplied.
• Tables and images can be inserted. The user is prompted to supply required information such as numbers of rows and columns for tables and image file, captions and titles for images.
• A mapping is supplied that enables users to jump to a selected element (chosen from a menu of available element IDs).
• Document validation is only a mapping away.
• Output as html, xhtml, pdf and text is generated via a single mapping. The resulting output is opened in an external viewer.
• Various RefDB functions are supported when editing RefDB-created documents. The user can create, edit and delete references from within Vim. References from the current document can be displayed (either all or a subset). The user can change the current document's associated database and/or stylesheet. Finally, citations from the current reference database can be selected and inserted.
• Various help is available via mappings. Help on mappings is available (<Leader>hh). In addition, help on individual docbook elements can be displayed. The user requests help on either the previous or next element and the relevant page from Walsh and Muellner's DocBook: The Definitive Guide is opened in an external html viewer. A summary of document structure can also be displayed.

Fig. 4: GVim editing a DocBook XML file. All the DocBook XML supplied menus are being displayed (they have been "torn off"). The left-most menu is the parent menu. The citations (RefDB) menu is seen on the far right. Note that users of console vim also have access to these menus (see vim help topic 'console-menus'. Click on the image to see a larger version.

Vim and RIS editing

Author: David Nebauer <davidnebauer@swtch.com.au>

Package: vim-ris (1.2) [source, deb].

If Vim is the editor of your choice, this package installs the syntax, filetype and plugin files that enable you to edit RIS files.

• The syntax file enables Vim to highlight legal tags and mark illegal tags as errors.
• It also highlights correct field values, thus helping users to avoid invalid field values.
• It checks the syntax of author names, dates and journal abbreviation fields.
• It checks the values in reprint and pubtype fields.
• It checks the length of length-limited fields and does some other rudimentary error checking.

What the syntax file does not currently do is handle line continuations ('/$') -- it assumes all fields are a single line

The plugin file supplies five convenience commands mapped to keyboard shortcuts:

• \a = insert RIS tag (select from menu)
• \p = insert publication type (select from menu)
• \r = insert reprint status
• \d = duplicate current/previous tag
• \t = add reference template (group of blank tags; choose from three templates: journal|book|other)

Fig. 5: Vim editing RIS. Click on the image to see a larger version. The image shows how Vim spots a few common syntax errors: (1) the second author uses a space after the comma, (2) the publication date lacks the mandatory slashes, and (3) the end tag lacks the trailing space.