definition list plugin

This plugin adds support for definition lists to DokuWiki. The plugin is an evolution of the earlier plugins by Stephane Chamberland and Pavel Vitis.

At the time of original publication of this plugin there are two other definition list plugins:

• definitions by Pavel Vitis
• deflist by Matthias Watermann

Why use this plugin rather than one or other of the other two?

This plugin is very similar to definitions, it fixes a couple of problems with that plugin, other markup (e.g. formatting, links, etc) is allowed in the definition term and raw wiki data is properly filtered to maintain wiki security.

I like the simplicity of DokuWiki's markup. I believe this plugin keeps to that ideal, deflist is capable of handling more circumstances but I feel at the cost of some simplicity.

I have also added some configuration settings to allow more heavily styled lists and a choice of markup characters (it is set to MediaWiki's ”; term : definition” by default but can be changed to ”= term : definition” used by definitions). By turning DL_FANCY on (default) the definition list will be output in a two column format, one column for the terms (<dt>) and another for the definitions (<dd>).

A definition list is made up of one or more lines of the format shown below:

  ; term : definition
  ; term
  : definition

Note the two spaces at the beginning of each line.

The lines can be used in any order, the only requirements is that the first line must be one of the two lines commencing with a semi-colon ”;” and the list is terminated by leaving a line completely blank.

In a slight change over standard DokuWiki lists, you use new lines within the list in your raw wiki data. The data on the new line is added to the end of the previous line when the definition list is being processed.

See the page in action here

Plugin sources: zip format (4k), tar.gz format (2k), darcs repository

If your wiki uses either the plugin manager or the darcs plugin you can use them with the links above to install the plugin.

To install the plugin manually, download the source to your plugin folder, lib/plugins and extract its contents. That will create a new plugin folder, lib/plugins/definitionlist, and install the plugin.

The folder will contain:

style.css                              styles for the definition list
images/                                images folder
images/bullet.gif                      dinky little bullet used by styles
syntax.php                             plugin script

The plugin is now installed.

The plugin has three configuration settings. To change these you will need to edit the plugin script file, syntax.php.

• DL_DT — default value ”;” — the character used to indicate a definition list term.
• DL_DD — default value ”:” — the character used to indicate a definition list definition.
• DL_FANCY — default value ”true” — if set to false the plugin will generate pure definition list mark up only. If set to true the plugin will generate extra HTML to enable improved styling of the list. If used with the styles provided this will result in a two column list, with terms on the left, definitions on the right and each definition lining up with its corresponding term.

The plugin consists of three files, the plugin script syntax.php, some style rules in style.css and an image used by the styles

<?php
/**
 * Allow creation of XHTML definition lists:
 * <dl>
 *   <dt>term</dt>
 *   <dd>definition</dd>
 * </dl>
 *
 * Syntax:
 *   ; term : definition
 *   ; term
 *   : definition
 *
 * As with other DokuWiki lists, each line must start with 2 spaces or a tab
 * Nested definition lists are not supported at this time
 *
 * This plugin is heavily based on the definitions plugin by Pavel Vitis which 
 * in turn drew from the original definition list plugin by Stephane Chamberland.
 * A huge thanks to both of them.
 *
 * ODT support provided by Gabriel Birke <birke@d-scribe.de>
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Chris Smith <chris [at] jalakai [dot] co [dot] uk>
 *
 */
 
if (!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if (!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
// ---------- [ Settings ] -----------------------------------------
 
// define the trigger characters
//   ";" & ":" are the mediawiki settings.
//   "=" & ":" are the settings for the original plugin by Pavel
if (!defined('DL_DT')) define('DL_DT', ';');     // character to indicate a term (dt)
if (!defined('DL_DD')) define('DL_DD', ':');     // character to indicate a definition (dd)
 
// define the HTML used to generate the definition list
// - set to false or 0 to use simple list HTML <dl><dt>term</dt><dd>definition</dd> ... </dl>
// - set to true or 1 to use wrap the term element in a span permitting more complex styling
//   <dl><dt><span class='term'>term</span></dt><dd>definition</dd> ... </dl>
if (!defined('DL_FANCY')) define('DL_FANCY', true); 
 
// -----------------------------------------------------------------
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_definitionlist extends DokuWiki_Syntax_Plugin {
 
    var $stack = array();
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Christopher Smith',
            'email'  => 'chris@jalakai.co.uk',
            'date'   => '2008-08-13',
            'name'   => 'Definition list plugin',
            'desc'   => 'Add HTML style definition list '.DL_DT.' term '.DL_DD.' definition',
            'url'    => 'http://www.dokuwiki.org/plugin:definitionlist',
        );
    }
 
    function getType() { return 'container'; }
    function getAllowedTypes() { return array('container','substition','protected','disabled','formatting'); }
    function getPType() { return 'block'; }          // normal, so not surrounded by <p> tags
    function getSort() { return 10; }                // before preformatted (20)
 
    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
 
       $this->Lexer->addEntryPattern('\n {2,}'.DL_DT, $mode, 'plugin_definitionlist');
       $this->Lexer->addEntryPattern('\n\t{1,}'.DL_DT, $mode, 'plugin_definitionlist');
 
       $this->Lexer->addPattern('(?: '.DL_DD.' )', 'plugin_definitionlist');
       $this->Lexer->addPattern('\n {2,}(?:'.DL_DT.'|'.DL_DD.')', 'plugin_definitionlist');
       $this->Lexer->addPattern('\n\t{1,}(?:'.DL_DT.'|'.DL_DD.')', 'plugin_definitionlist');
    }
 
    function postConnect() {
        // we end the definition list when we encounter a blank line
        $this->Lexer->addExitPattern('\n[ \t]*\n','plugin_definitionlist');
    }
 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler) {
        switch ( $state ) {
            case DOKU_LEXER_ENTER:      return array($state, 'dt');
            case DOKU_LEXER_MATCHED:    return array($state, (substr($match, -1) == DL_DT) ? 'dt' : 'dd');
            case DOKU_LEXER_EXIT:       return array($state, '');
            case DOKU_LEXER_UNMATCHED:
                    $handler->_addCall('cdata',array($match), $pos);
                    return false;
        }
 
        return false;
    }
 
    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        if (empty($data)) return false;
 
        switch  ($mode) {
          case 'xhtml' : return $this->render_xhtml($renderer,$data);
          case 'odt' : return $this->render_odt($renderer,$data);
          default :
            //  handle unknown formats generically - by calling standard render methods
            list ($state, $param) = $data;
            switch ( $state ) {
               case DOKU_LEXER_ENTER: 
                $renderer->p_open();
                break;
              case DOKU_LEXER_MATCHED:
                $renderer->p_close();
                $renderer->p_open();
                break;
              case DOKU_LEXER_UNMATCHED:                            // defensive, shouldn't occur
                $renderer->cdata($param);
                break;
              case DOKU_LEXER_EXIT:
                $renderer->p_close();
                break;
            }
            return true;
        }
 
        return false;
    }
 
    function render_xhtml(&$renderer, $data) {
        list ($state, $param) = $data;
 
        switch ( $state ) {
          case DOKU_LEXER_ENTER:
            $renderer->doc .= "\n<dl>\n";
            $renderer->doc .= $this->_open($param);
            break;
          case DOKU_LEXER_MATCHED:
            $renderer->doc .= $this->_close();
            $renderer->doc .= $this->_open($param);
            break;
          case DOKU_LEXER_UNMATCHED:                            // defensive, shouldn't occur
            $renderer->cdata($param);
            break;
          case DOKU_LEXER_EXIT:
            $renderer->doc .= $this->_close();
            $renderer->doc .= "</dl>\n";
            break;
        }
        return true;
    }
 
    /**
     * create output for ODT renderer
     *
     * @author:   Gabriel Birke <birke@d-scribe.de>
     */
    function render_odt(&$renderer, $data) {
        list ($state, $param) = $data;
 
        $param_styles = array('dd' => 'def_f5_list', 'dt' => 'def_f5_term');
        switch ( $state ) {
          case DOKU_LEXER_ENTER:
            $renderer->autostyles["def_f5_term"] = '
                  <style:style style:name="def_f5_term" style:display-name="def_term" style:family="paragraph">
                      <style:paragraph-properties fo:margin-top="0.18cm" fo:margin-bottom="0cm" fo:keep-together="always" style:page-number="auto" fo:keep-with-next="always"/>
                      <style:text-properties fo:font-weight="bold"/>
                  </style:style>';
            $renderer->autostyles["def_f5_list"] = '
                  <style:style style:name="def_f5_list" style:display-name="def_list" style:family="paragraph">
                      <style:paragraph-properties fo:margin-left="0.25cm" fo:margin-right="0cm" fo:text-indent="0cm" style:auto-text-indent="false"/>
                  </style:style>';
            $renderer->doc .= '</text:p>';
            $renderer->doc .= '<text:p  text:style-name="'.$param_styles[$param].'">';
            break;
          case DOKU_LEXER_MATCHED:
            $renderer->doc .= '</text:p>';
            $renderer->doc .= '<text:p  text:style-name="'.$param_styles[$param].'">';
            break;
          case DOKU_LEXER_UNMATCHED:                            // defensive, shouldn't occur
            $renderer->cdata($param);
            break;
          case DOKU_LEXER_EXIT:
            $renderer->doc .= '</text:p>';
            $renderer->p_open();
            break;
        }
        return true;
    }
 
    /**
     * open a definition list item, used by render_xhtml()
     * @param   $tag  (string)    'dt' or 'dd'
     * @return  (string)          html used to open the tag
     */
    function _open($tag) {
        array_push($this->stack, $tag);
        $wrap = (DL_FANCY && $tag == 'dt') ? "<span class='term'>" : "";
        return "<$tag>$wrap";
    }
 
    /**
     * close a definition list item, used by render_xhtml()
     * @return  (string)          html used to close the tag
     */
    function _close() {
        $tag = array_pop($this->stack);
        $wrap = (DL_FANCY && $tag == 'dt') ? "</span>" : "";
        return "$wrap</$tag>\n";
    }
 
}
 
//Setup VIM: ex: et ts=4 enc=utf-8 :

These may be modified to suit your own requirements.

/* plugin: definitionlist */
 
dl, dt, dd {margin: 0; padding: 0}
 
dl {
  font-size: 90%;
  padding-top: 1px;
}
 
html>body dl {
  padding-bottom: 0.5em;
  border-bottom: 1px dashed #e0e0e0;
}
 
dl:after {
  content: '.';
  display: block;
  clear: both;
  height: 0;
  visibility: hidden;
}
 
dt {
  clear: left;
  margin-top: 0.5em;
}
 
dt+dt {
  margin-top: 0;
}
 
dd+dt {
  border-top: 1px dashed #e0e0e0;
  padding-top: 0.5em;
}
 
dt span.term {
  float: left;
  width: 10em;
}
 
dd {
  margin-left: 10.3em;
  padding-left: 0.8em;
  background: url(images/bullet.gif) no-repeat 0 0.4em;
}
 
dd p {
  margin: 0;
  padding: 0;
}
 
* html dl { height: 1px; }
 
/* reset above style to prevent messing up plugin manager */
#plugin_manager dd { background-image: none;}
 
/* end plugin: definitionlist */

• 2008-08-13 — Update plugin URL, add OpenDocument renderer support, add generic rendering for unknown render formats
• 2005-09-21 — Style corrections, sources updated.
• 2005-09-17 — Released.

When a page contains a definition list as the last item and there is no line break after the last line, the definition list doesn't get closed. Instead, a closing p tag is inserted.

Don't know if this is a real bug or just a general DokuWiki parser/lexer architecture “feature”. The behavior can be avoided by inserting a new line, so it's not a big issue.
— Gabriel 2007-01-11 16:31

The info link points to plugin:definitions, might want to update it to this page.

Hi, ODT export doesn't work, I get a “format error” when I try to open the generated ODT with OpenOffice 2.4. If I remove the definitions from the doc, it is exported well.

— mat, 2008-08-22

• Remove

  $renderer->doc .= '</text:p>';

  on Line 186 in syntax.php and the export to ODT will work well — Vincent 2009-12-15

Does this work with the new DokuWiki release from 2009-12? I tried it, and I don't think style.css is making it to the final content served.

— rhishi, 2010-02-05

One caveat for usage and one suggestion:

CAVEAT The TERM line [;] need to be either right after the previous DEFINITION [;] or it needs to be separated by two blank lines.

If a single blank line is used, the markup is not triggered and the text, with the punctuation is shown.

SUGGESTION What would be a nice addition to this plugin would be an ANCHOR tag wrapped around the TERM

— walter 2008-01-11 01:59