openSUSE:Documentation Emacs Docbook Macros

Jump to: navigation, search

Here is a macro package to insert the most often used DocBook snippets. The goal was to find the most efficient shortcut for often used tag combinations. All the code inserted to your documents will be indented correctly and the cursor is placed in a way that you can start typing immediately.

The macros require the nxml-mode or, alternatively, the psgml-mode (package psgml). When the macros are loaded, you will see a new menu "DocBook" listing all the macros and the corresponding keyboard shortcuts. Of course you can load the macros with M-x <function-name> as well. The function names all start with "docbook-" followed by an element string: docbook-remark, docbook-table, docbook-step, etc.

The lisp file is located at the DAPS repository on SourceForge: docbook_macros.el and is also available with the DAPS package. To load it, put the following line to your emacs customization file (~/.emacs or ~/.gnu-emacs, ...):

(load "PATH/emacs_docbook_macros.el" t t)

where PATH needs to be replaced with a valid path.

Here is a list of functions currently available. Feedback is welcome, please use the Discussion page.

DocBook DOCUMENT (docbook-docbook, C-c C-c d)

  • inserts a DocBook 4.5 page skeleton
  • prompts for the root element, default is "chapter"; the most important elements can be chosen via TAB-completion
  • cursor is placed in the root element's id attribute

NovDoc DOCUMENT (docbook-novdoc, C-c C-c n)

  • inserts a NovDoc page skeleton
  • prompts for the root element, default is "chapter"; the most important elements can be chosen via TAB-completion
  • cursor is placed in the root element's id attribute

ANNOTATION (docbook-annotation, C-c C-c a)

  • inserts an annotation box ("important" "note" "tip" "warning")
  • prompts for the type, default is "warning"; other values can be chosen via TAB completion. Element must be one of the four specified above.
  • Cursor is placed after <title>

CALLOUT (docbook-callout, C-c C-c c)

  • inserts callout + para elements. No interaction.
  • cursor is placed after <para>

COMMENT (docbook-comment, none)

  • Inserts a comment with the unsername and the current date. No interaction.
  • cursor is placed on an empty line within the comment

FIGURE (docbook-figure, C-c C-c f)

  • inserts a complete figure element
  • prompts for the title and the image file name. The imagedata's width attribute is set to 75%

INDEXTERM (docbook-indexterm, C-c C-c i)

  • Inserts an indexterm
  • prompts for primary, secondary, and tertiary content. Specifying primary is mandatory, secondary and tertiary are optional (press enter to skip)

KEYCOMBO (docbook-keycombo, C-c C-c k)

  • inserts a keycombo element with two keycap elements
  • prompts for an optional function attribute for the first keycap (alt, control, shift, meta, escape)
  • cursor is placed within the second keycap element when a function is specified, otherwise in the first one

LISTITEM (docbook-listitem, C-c C-c l)

  • inserts listitem + para elements. No interaction.
  • cursor is placed after <para>

MENUCHOICE (docbook-menuchoice, C-c C-c m)

  • inserts a menuchoice element with two guimenu elements
  • cursor is placed after the first guimenu element

REMARK (docbook-remark, C-c C-c r)

  • Inserts a remark with the current date and the username
  • prompts for the role-attribute. The default is "clarity", other values can be chosen via TAB completion.

SECT (docbook-sect, C-c C-c s)

  • inserts a sect template with title and para
  • prompts for the section level (can be one of 1-4, 1 being the default).
  • cursor is placed in sect?'s id attibute

STEP (docbook-step, C-c C-c p)

  • inserts step + para elements. No interaction.
  • cursor is placed after <para>

TABLE (docbook-table, C-c C-c t)

  • inserts a complete table with colspecs, thead and tbody
  • prompts for the number of columns
  • thead and tbody contain one row with #col_no number of entry's
  • name and number attributes in the colspec tags are set from 1 to #col_no while width is set to 100/#col_no
  • cursor is placed after <title>

VARLISTENTRY (docbook-varlistentry, C-c C-c v)

  • inserts varlistentry + term + listitem + para elements. No interaction.
  • cursor is placed after <term>