====== definition list plugin ======

---- plugin ----
description: (X)HTML Definition lists, simple syntax and smart styling
author     : Christopher Smith
email      : chris@jalakai.co.uk
type       : syntax
lastupdate : 2008-08-13
compatible : 2005-09-22 and later
depends    : 
conflicts  : 
similar    : deflist, dl, definitions
tags       : list, definitions, odt
----

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:
  * [[plugin:definitions]] by Pavel Vitis
  * [[plugin:deflist]] by Matthias Watermann

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

This plugin is very similar to [[plugin: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, [[plugin: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 [[plugin: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>'').

===== Syntax =====

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

<code>
  ; term : definition
  ; term
  : definition
</code>

:!: 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 [[http://wiki.jalakai.co.uk/dokuwiki/doku.php/test/definition_list|here]]


===== Installation =====

Plugin sources: [[http://dokuwiki.jalakai.co.uk/plugin-definitionlist.zip|zip format (4k)]], [[http://dokuwiki.jalakai.co.uk/plugin-definitionlist.tar.gz|tar.gz format (2k)]], [[http://wiki.jalakai.co.uk/repo/dokuwiki/plugins/definitionlist|darcs repository]]

If your wiki uses either the [[plugin:plugin]] manager or the [[plugin:darcs|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.

===== Configuration =====

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.

===== Details =====

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

==== syntax.php ====

<code php>
<?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 :
</code>

==== style.css ====

These may be modified to suit your own requirements.

<code css>
/* 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 */
</code>

===== Revision History =====

  * 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.


===== To Do =====



===== Bugs =====
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. \\
--- //[[birke@delti.com|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 //


===== Discussion ===== 

One caveat for usage and one suggestion:

**CAVEATE**
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

--- //[[phpwalter@torres.ws|walter]] 2008-01-11 01:59//