====== Definition List Syntax Plugin ======

---- plugin ----
description: Full range (X)HTML style definition list
author     : Matthias Watermann
email      : support@mwat.de
type       : syntax
lastupdate : 2007-08-15
compatible : Greebo, !Hogfather, !Jack Jackrum
depends    :
conflicts  :
similar    : definition, dl, definitions, yalist
tags       : formatting, list, definitions

downloadurl: http://dev.mwat.de/dw/syntax_plugin_deflist.zip
----

One of the most important HTML tags marks up a  [[http://www.w3.org/TR/html401/struct/lists.html#h-10.3|list of de­fi­ni­tions]]((But, alas, a lot of beginners and people ignoring the inherent structure of a document abuse [[http://www.w3.org/TR/html401/struct/lists.html#h-10.2|ordinary lists]] ("%%<ol>%%" / "%%<ul>%%") or, even worse, [[http://www.w3.org/TR/html401/struct/tables.html#h-11.2.1|TABLE]] to mark up such a list.
I've even seen tag-soups using nes­ted "%%div/span%%" constructs in combination with lengthy CSS rules just to resemble a structure that al­ready exists ever since HTML 1 (or, if you take SGML into account, actually even longer).)).
In contrast to the more simp­ler [[lists|(un)ordered lists]] which both consist solely of list item ("%%<li>%%") ele­ments, a //defi­ni­tion list// em­beds two elements, a //definition term// ("%%<dt>%%" which is re­stric­ted to in­line con­tent) and its re­spec­tive //definition data// ("%%<dd>%%" which con­tains block-level con­tent)((This makes a //definition list// the element of choice for e.g. glossary like documents and FAQ texts or alike.)).
Such a list of terms/phrases and their de­fi­ni­tion/de­scrip­tion can have -- by ways of HTML -- various slightly dif­fe­rent forms:

	- **1:1** -- The simplest one looks (in HTML) like:<code html>
<dl>
  <dt>Term / phrase</dt>
    <dd>Definition of term.</dd>
</dl>
</code>
	- **n:1** -- The second variant has one definition for multiple terms and looks like:<code html>
<dl>
  <dt>Term 1</dt>
  <dt>Term 2</dt>
    <dd>Definition of terms one and two.</dd>
</dl>
</code>
	- **1:n** -- The next variant has multiple definitions for one term looking like:<code html>
<dl>
  <dt>Term / phrase</dt>
    <dd>First definition of term.</dd>
    <dd>Second definition of term.</dd>
    <dd>Third definition of term.</dd>
</dl>
</code>
	- **n:n** -- The fourth variant has multiple definitions for multiple terms like:<code html>
<dl>
  <dt>Term / phrase One</dt>
  <dt>Term / phrase Two</dt>
    <dd>First definition of terms one and two.</dd>
    <dd>Second definition of terms one and two.</dd>
    <dd>Third definition of terms one and two.</dd>
</dl>
</code>
	- All the former variants may be mixed within one list of definitions giving something like:<code html>
<dl>
  <dt>Item 1</dt>
    <dd>First definition of item one.</dd>
    <dd>Second definition of item one.</dd>
    <dd>Third definition of item one.</dd>
  <dt>Item 2</dt>
    <dd>Definition of item two.</dd>
  <dt>Item 3</dt>
  <dt>Item 4</dt>
    <dd>Definition of items three and four.</dd>
  <dt>Item 5</dt>
  <dt>Item 6</dt>
    <dd>First definition of items five and six.</dd>
    <dd>Second definition of items five and six.</dd>
</dl>
</code>

This plugin allows for using all five variants in your DokuWiki pages thus adding the full range of W3C de­fi­ni­tion lists to DokuWiki.

===== Usage =====

The markup syntax implemented by this plugin looks in its simplest form like <code>
  ?? term/phrase :: definition of term !!
</code>

Everything between __%%??%%__ and __%%::%%__ is marked up as the //definition term// (i.e. %%<dt>%%) and everything bet­ween __%%::%%__ and __%%!!%%__ is ta­ken for the term's //definition data// (i.e. %%<dd>%%)((If one of the delimiters "%%??%%", "%%::%%" or "%%!!%%" is to be used as verbatim text, just escape at least the second character, i.e. write "%%?\?%%", "%%:\:%%" or "%%!\!%%" respectively.
This [[#Plugin Source|plugin]] will take care of the unescaping before the text is passed to the renderer.)) where there is ad­di­tio­nal mark­up allo­wed (see the [[#examples]] below).

==== Whitespace ====

	* All //definition terms// (i.e. "%%?? ...%%") must //start on a new line// and have to be //indented by at least __two__ spaces//((''space'', ASCII char #32 -- not to be confused with //''blanks''//, ASCII char #255)) or a TAB((''tabulator'', ASCII char #9)) character. Every TAB stands for two spaces and vice-versa ((Since a certain Redmond firm started to expand its offences into the area of user applications it's quite hard nowadays to insert a raw TAB in many GUI applications because the afore mentioned firm turned the //character// TAB into kind of //navigation key// (and many people without a grasp for //text// brainlessly aped that bad idea). Therefor you'll most probably use the syntax with two spaces.)).
	* The list's last //definition data// (i.e. the very last "%%!!%%") must be //followed by __two__ con­se­cu­tive line­feeds// thus marking the end'o'list((But //note// that this is //not// true for definition list nested inside a definition data block!)).
	* Linebreaks((''linefeed'', ASCII char #10)) are allowed everywhere appropriate((But //note// that different rules may apply for elements nested within a data definition block.)), i.e. the following vari­ants would end up with the same HTML markup: <code>
  ??term/phraseOne::definition of term!!
  ?? term/phraseTwo ::
definition of term !!
  ??
term/phraseThree
:: definition of term !!
  ??
term/phraseFour
::
definition
of
term
four
!!
</code>
	* If linebreaks are used inside a //definition data// block to create several pa­ra­graphs, ma­ke sure that a new line does //not// start with two or mo­re spa­ces or a TAB, other­wise the respective text will be ren­de­red as //pre­for­mat­ted// text.
	* Whitespace((any occurrence of ''space'', ''tabulator'' and ''linefeed'' character(s) is considered whitespace)) //behind// the "%%??%%", //around// the "%%::%%" and //before// the "%%!!%%" de­li­mi­ters is com­ple­tely op­tio­nal.
	* Empty lines within //definition data// will end up in empty paragraphs((due to the current DokuWiki parser/renderer implementation)); if just (ren­dered) line­breaks (i.e. "%%<br/>%%") are needed, one can use two back­sla­shes followed by whi­te­space.

The most readable form for me seems to be:<code>
	?? the term
:: the definition !!
</code>
But, of course, you're free to use whatever linebreaking style you like.

==== Anchors ====

To allow for linking (either from the same do­cu­ment or an ex­ter­nal do­cu­ment) to a cer­tain definition all //definition terms// automatically get an­chored, that is they are wrapped with­in a\\
''%%<a id="the_term" name="the_term">the Term</a>%%''\\
construct((A more correct way would be to assign the "%%id%%" attribute just to the  respective "%%<dt>%%" tag omitting the "%%<a>%%" tag altogether.
But unfortunately XHTML 1.0 is only seven years old and therefor its grammar isn't understood by all browsers ...
So for the time being we've to stick with the (about 16 years old) anchor tag.)).
The [[http://www.w3.org/TR/xhtml1/#C_8|XHTML specs]] (section C.8) provide a RegEx for valid frag­ment iden­ti­fiers which is re­du­ced by this implementation to "%%[a-z][a-z0-9_]*[a-z0-9]%%"((Although W3C allows for mixed upper and lower letters DokuWiki's current implementation does //not// follow the standard by allowing only lowercase letters.
Therefor this plugin as well converts uppercase letters to lowercase.
Once DokuWiki follows the standard this plugin will allow for mixed letters as well.)).
All non al­pha­nu­meric cha­rac­ters((UTF-8 characters are handled by DokuWiki's "%%utf8_deaccent()%%" function)) are re­pla­ced by un­der­scores((multiple underscores are reduced to just one, leading/trailing underscores are removed)).
So the wiki markup <code>
	?? Item 1(a)
:: Definition of item one (a). !!
</code> would be converted to the HTML markup <code html>
<dt><a id="item_1_a" name="item_1_a">Item 1(a)</a></dt>
  <dd><p>Definition of item one (a).</p></dd>
</code>

Please note that "%%id%%" and "%%name%%" attributes by definition share the same na­me­space((not DokuWiki namespace but (X)HTML document namespace)) and MUST be unique within a document((The exception of "%%form%%" elements (such as radio buttons or checkboxes) sharing the same "%%name%%" value does not apply in this context.)).
As a consequence you have to make sure that no two identical frag­ment iden­ti­fiers are used within one document. --
You should be aware that DokuWiki automatically creates an­chors((unfortunately not following the W3C standard, see [[http://www.w3.org/TR/xhtml1/#h-4.10|'id' and 'name' attributes]] and [[http://www.w3.org/TR/xhtml1/#C_8|Fragment Identifier]]...)) for all headlines.
Therefor you must avoid to use the same string for both a headline and a definition term.
And, of course, there must not be the same de­fi­ni­tion term multiple times within the sa­me document.

==== Nesting a definition list ====

In contrast to older releases of this plugin((prior to 2005-08-26; see [[#Changes]])) the nesting of definition lists is now supported((Whether this really makes any sense or not I leave as a subject of meditation for the reader ...)).
The syntax looks like:<code>
  ?? Level 1 Term 1-1
:: definition __1-1__ !!
  ?? Level 1 Term 1-2
:: Prefix of //1-2//
    ?? Level 2 Term 2-2-1
:: definition of Term __2-2-1__ !!
    ?? Level 2 Term 2-2-2
:: Prefix of **2-2-2**
      ?? Level 3 Term 3-2-2-1
:: definition of Term __3-2-2-1__ !!
      ?? Level 3 Term 3-2-2-2
:: Prefix of __3-2-2-2__
        ?? Level 4 Term 4-2-2-2-1
:: definition of Term __4-2-2-2-1__ !!
        ?? Level 4 Term 4-2-2-2-2
:: definition of Term __4-2-2-2-2__ !!
Postfix of __3-2-2-2__ !!
Postfix of **2-2-2** !!
Postfix of //1-2// !!
  ?? Level 1 Term 1-3
:: definition __1-3__ !!

</code>
As one can see, the //definition term// "''%%?? ... ::%%''" is indented variably for the dif­fe­rent ne­sting levels:
	* "%%Term 1-1%%", "%%Term 1-2%%" and "%%Term 1-3%%" all have //two// leading spaces (in­di­ca­ting the default nesting level of 1),
	* "%%Term 2-2-1%%" and "%%Term 2-2-2%%" each have //four// spaces in front (i.e. ne­sting level 2),
	* "%%Term 3-2-2-1%%" and "%%Term 3-2-2-2%%" both have //six// spaces (i.e. nesting le­vel 3) and finally
	* "%%Term 4-2-2-2-1%%" and "%%Term 4-2-2-2-2%%" have //eight// spaces (i.e. nesting level 4).
Only the very last //definition data// is terminated by //two// linefeeds while the ne­sted lists are han­dled so­lely by the indention level of its //definition term//((The //definition data// is __not__ indented to avoid rendering them as preformatted code.)).
See [[#Lorem ipsum]] below for a working exam­ple.

The "//Prefix of ...//" and "//Postfix of ...//" texts are (apart from the "%%::%%" and "%%!!%%" de­li­mi­ters) completely optional.
In other words the nested list could be started without any pre­ceding text and ended without any subsequent text.
I've used the texts here for de­mon­stra­tion purposes only to make the nestings more obvious.

The generated HTML rendering looks as follows:<code html>
<dl>
  <dt><a id="level_1_term_1_1" name="level_1_term_1_1">Level 1 Term 1-1</a></dt>
    <dd><p>definition <u>1-1</u></p></dd>
  <dt><a id="level_1_term_1_2" name="level_1_term_1_2">Level 1 Term 1-2</a></dt>
    <dd><p>Prefix of <em>1-2</em></dd>
    <dd><dl>
    <dt><a id="level_2_term_2_2_1" name="level_2_term_2_2_1">Level 2 Term 2-2-1</a></dt>
      <dd><p>definition of Term <u>2-2-1</u></p></dd>
    <dt><a id="level_2_term_2_2_2" name="level_2_term_2_2_2">Level 2 Term 2-2-2</a></dt>
      <dd><p>Prefix of <strong>2-2-2</strong></dd>
      <dd><dl>
      <dt><a id="level_3_term_3_2_2_1" name="level_3_term_3_2_2_1">Level 3 Term 3-2-2-1</a></dt>
        <dd><p>definition of Term <u>3-2-2-1</u></p></dd>
      <dt><a id="level_3_term_3_2_2_2" name="level_3_term_3_2_2_2">Level 3 Term 3-2-2-2</a></dt>
        <dd><p>Prefix of <u>3-2-2-2</u></dd>
        <dd><dl>
        <dt><a id="level_4_term_4_2_2_2_1" name="level_4_term_4_2_2_2_1">Level 4 Term 4-2-2-2-1</a></dt>
          <dd><p>definition of Term <u>4-2-2-2-1</u></p></dd>
        <dt><a id="level_4_term_4_2_2_2_2" name="level_4_term_4_2_2_2_2">Level 4 Term 4-2-2-2-2</a></dt>
          <dd><p>definition of Term <u>4-2-2-2-2</u></p></dd>
        </dl>
        <p>Postfix of <u>3-2-2-2</u></p></dd>
      </dl>
      <p>Postfix of <strong>2-2-2</strong></p></dd>
    </dl>
    <p>Postfix of <em>1-2</em></p></dd>
  <dt><a id="level_1_term_1_3" name="level_1_term_1_3">Level 1 Term 1-3</a></dt>
    <dd><p>definition <u>1-3</u></p></dd>
</dl><p>
</code>

==== (X)HTML style markup ====

(X)HTML style Markup (i.e. "%%<sometag>%%" like markup) should generally not be used in wiki pages.
In case it's inserted nevertheless in a definition list the HTML special characters "''&''", "''<''" and "''>''" are converted to HTML en­ti­ties thus ren­de­ring the tag(s) as normal text.
This should make it im­pos­sible to com­pro­mise the wiki by inserting e.g. malicious JavaScript code -- it would show up in plain source code instead of being exe­cuted.((Note that the global "%%$conf['htmlok']%%" setting (configured in "%%.../conf/dokuwiki.php%%") is no longer taken into account as it was erroneously in older releases of this plugin prior to 2005-08-26.))

===== Examples =====

Following the [[#definition_list_syntax_plugin|overview above]] let's see how to write the wiki text accordingly.

==== 1:1 - One term / one definition ====
<code>
	?? Item One
:: Definition of item one. !!

</code>

==== n:1 - Multiple terms / one definition ====
<code>
	?? Item Two
	?? Item Three
:: Definition of items two and three. !!

</code>

==== 1:n - One term / multiple definitions ====
<code>
	?? Item Four
:: First definition of item four. !!
:: Second definition of item four. !!
:: Third definition of item four. !!

</code>

==== n:n - Multiple terms / multiple definitions ====
<code>
	?? Item Five
	?? Item Six
:: First definition of items five and six. !!
:: Second definition of items five and six. !!
:: Third definition of items five and six. !!

</code>

==== Mixed ====
<code>
	?? Item 1
:: First definition of item one. !!
:: Second definition of item one. !!
:: Third definition of item one. !!
	?? Item 2
:: Definition of item two. !!
	?? Item 3
	?? Item 4
:: Definition of items three and four. !!
	?? Item 5
	?? Item 6
::First definition of items five and six. !!
::Second definition of items five and six. !!

</code>

<sub>Note the additional ''linefeed'' at the end of each list marking, er, the end of list.</sub>

==== Lorem ipsum ====

Inside the //definition data// other DokuWiki markup may be used e.g. **strong**, //em­pha­sized// or __un­der­lined__ text.((Because of the way the DokuWiki parser currently works (socalled "%%MATCHED%%" parts are not subject to substitution) __no__ markup is possible within the //definition terms//.
Besides, it wouldn't make much sense, anyway, and one can always use CSS for this.)) --
The following example shows how some other block-level elements are incorporated within a definition list.
Besides the afore­said font manipulations there are //table//, //un/ordered list//((Please note, that in this [[#Lorem ipsum|example]] DokuWiki's builtin list handlers are used.
If you need the full range of list capabilities (including the ability to embed other block elements within a list item) you should install the [[lists|Lists plugin]].)), //footnote// and all pos­sible com­bi­na­tions of definition term/data groups. ---
When using such ne­sted block elements you are, of course, bound by the respective element's syntax con­straints((most notably: linefeeds are __not__ allowed in DokuWiki's builtin list or table markup, and //this// plugin can not change //that//)).

Suppose kind of glossary providing information about Terms, phrases or ab­bre­via­tions((For "APC" see [[http://www.acronymfinder.com/af-query.asp?String=exact&Acronym=APC&Find=Find|www.acronymfinder.com]] with more than 130 hits.)).

<sub>:!: //Once the maintainer of the Wiki decides to [[#installation|install]] this plugin, //this note// and the "%%code%%" tags around the following block could be removed to make its effects actually visible.//</sub>
<code>
	?? AAA
::* //__A__nton's __A__ccelerated __A__bominations//: Morbi sed dui ac arcu nonummy vestibulum.
Class aptent taciti sociosqu ad litora torquent per conubia nostra,
per inceptos hymenaeos.
Vivamus blandit eros mollis tellus. Maecenas egestas posuere wisi. !!
::* //__A__nother __a__bandoned __a__ccessory//: Pellentesque vel odio.
Praesent laoreet nulla nec quam.
Curabitur pede pede, ultrices ornare, accumsan eget, suscipit sed, metus.
Sed volutpat justo sit amet libero. !!
  ?? APC
:: This abbreviation stands for various different things, amongst them:
    ?? Devices
::
      ?? American Power Conversion Corporation
:: A provider of [[#UPS]] (see [[http://www.apc.com/]]).
Quisque non orci ut sapien tincidunt tristique. Duis mollis feugiat dolor.
Etiam elit.  Pellentesque et lacus. Duis ut turpis. In nonummy. Donec
consectetuer pharetra mi. Quisque vestibulum neque non erat.
The following models are quite popular:
        ?? model a
:: Maecenas in purus. Aenean in erat. Morbi ac felis ut lorem dapibus tempus.
^ semper malesuada  ^ Donec ut nulla  ^ Praesent at mauris    ^
| odio    |Duis sed dolor    | Donec tempor    |
| erat eu    |Maecenas auctor neque sit amet lacus    ||
| metus    |Aenean    | id tortor    |
<sup>Sed in dui quis nisl adipiscing semper.</sup> !!
        ?? model b
:: Suspendisse dignissim.
Suspendisse fermentum luctus nulla. Integer ut ipsum sit
amet felis fermentum consequat. Morbi eget augue vel metus pellentesque
eleifend. !!
        ?? model c
::
^ semper malesuada    ^ Donec ut nulla    ^ Praesent at mauris    ^
|In auctor    |ipsum urna    |cursus felis    |
|erat eu pretium    |vitae varius    |elit risus    |
|Aenean rhoncus iaculis ipsum    ||interdum    |

//Sed ornare eget augue. dolor et nisl. Morbi rutrum dui ut mauris. Proin
non felis sit amet odio eleifend iaculis.// !!
 GNU/Linux support: Quisque faucibus nonummy nulla. Nam a nulla sed nibh
condimentum euismod. Integer ac sem eu quam adipiscing rutrum.

//Vestibulum// accumsan. Cras quam. Fusce nibh ante, convallis quis,
sollicitudin a, rutrum a, sem.
!!
      ?? Abra Padrapa Cumulii
:: A private corporation. Vivamus tristique, pede eu vulputate pharetra,
nulla purus volutpat ligula, nec condimentum velit mauris at lorem. Donec
sit amet lacus. !!
    ?? Organizations
::
      ?? Association for Progressive Communications
:: An organization founded ... (see [[http://www.apc.org/]])
The activities of this worldwide acting [[#NGO]] include
  - Aenean ligula mi, feugiat nec, eleifend ac, ullamcorper id, velit. Donec at orci in leo nonummy fermentum. Vestibulum pellentesque wisi sed magna elementum mattis.
  - Donec vel ante quis ipsum vulputate dapibus. Cras ultrices. Sed egestas neque nec augue congue ornare. Sed sit amet lectus ac nibh porta mollis. Aenean justo. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.
  - Pellentesque nonummy nunc eu lacus. Praesent tincidunt mollis wisi. Donec id est. Proin odio wisi, ornare vitae, scelerisque non, ultrices vel, dolor. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Nulla nec risus.
  - Aliquam erat volutpat. Integer non dui id justo sodales dignissim. In molestie suscipit ipsum. Donec nonummy mauris id justo. Nullam vehicula gravida tortor.
!!
      ?? Another Public Community
:: A publically available service. Vivamus tortor erat, dictum ut, ultrices
eget, gravida non, ligula. Vestibulum malesuada, risus nec tempor vulputate,
est velit placerat orci, viverra tincidunt mi sapien eu augue. !!
      ?? Aphasellus polumassa corleo
      :: Nullam tempor adipiscing quam, eleifend eu,
dignissim ac, venenatis a, lorem. Vestibulum sed ipsum quis neque tincidunt
luctus. Curabitur eu nisl. Pellentesque non metus id purus rhoncus rutrum. !!
    ?? other ::
  * Morbi nonummy sodales metus. Praesent semper. Nullam at leo. Cras turpis.
  * Quisque nibh ipsum, malesuada vel, feugiat id, fringilla sit amet, mauris.
  * Morbi imperdiet volutpat tellus. Donec enim libero, auctor at, hendrerit ac, eleifend vitae, arcu.
  * Praesent quis libero ac sapien vestibulum mollis. Quisque eget ante eget velit egestas sagittis.
  * Proin porta pede non quam. Quisque congue nibh id wisi. Curabitur malesuada adipiscing est. Donec eleifend.
  * Morbi tristique congue velit. Etiam placerat aliquet orci. In tincidunt venenatis enim.
  //Maecenas id metus non quam feugiat pretium.// !!
!!
  ?? NGO
:: __N__on-__G__overnmental __O__rganization. Aliquam mollis libero vel elit.
Sed tempus ante et ante. Phasellus sed mauris nec diam ultrices consequat.
Pellentesque habitant morbi tristique senectus et netus et malesuada fames
ac turpis egestas. Phasellus malesuada. !!
  ?? UPS
::
    ?? Uninterruptible Power Supply.
    :: Mauris quis justo nec nibh ultrices molestie. Integer
imperdiet feugiat sapien. Nunc ante justo, dapibus nec, interdum quis,
tempus ut, ligula. !!
    ?? Ut Provo Corpora
    :: Laoreet tellus placerat libero hendrerit posuere. Sed
eleifend sollicitudin felis. Etiam lacinia malesuada augue. Cras eu odio.

Pellentesque id sem. Mauris erat sapien, ullamcorper id, facilisis a, congue
in, lectus. Donec risus nisl, rutrum ornare, imperdiet ut, ultricies eu, neque. !!

</code>

This will be converted to HTML as follows: <code html>
<dl>
  <dt><a id="aaa" name="aaa">AAA</a></dt>
    <dd><p>* <em><u>A</u>nton's <u>A</u>ccelerated <u>A</u>bominations</em>: Morbi sed dui ac arcu nonummy  vestibulum. Class aptent taciti sociosqu ad litora torquent per conubia nostra,  per inceptos hymenaeos. Vivamus blandit eros mollis tellus. Maecenas egestas  posuere wisi.</p></dd>
    <dd><p>* <em><u>A</u>nother <u>a</u>bandoned <u>a</u>ccessory</em>: Pellentesque vel odio. Praesent  laoreet nulla nec quam. Curabitur pede pede, ultrices ornare, accumsan eget,  suscipit sed, metus. Sed volutpat justo sit amet libero.</p></dd>
  <dt><a id="apc" name="apc">APC</a></dt>
    <dd><p>This abbreviation stands for various different things, amongst them:</dd>
    <dd><dl>
    <dt><a id="devices" name="devices">Devices</a></dt>
      <dd><dl>
      <dt><a id="american_power_conversion_corporation" name="american_power_conversion_corporation">American Power Conversion Corporation</a></dt>
        <dd><p>A provider of &rarr;<a href="#ups" title="plugins:deflist_test &crarr;" class="wikilink1">UPS</a> (see <a href="http://www.apc.com/" class="urlextern" target="_blank" title="http://www.apc.com/" onclick="return svchk()" onkeypress="return svchk()" rel="nofollow">http://www.apc.com/</a>). Quisque non orci ut sapien tincidunt tristique. Duis mollis feugiat dolor.  Etiam elit.  Pellentesque et lacus. Duis ut turpis. In nonummy. Donec  consectetuer pharetra mi. Quisque vestibulum neque non erat.  The following models are quite popular:</dd>
        <dd><dl>
        <dt><a id="model_a" name="model_a">model a</a></dt>
          <dd><p>Maecenas in purus. Aenean in erat. Morbi ac felis ut lorem dapibus tempus. </p>
<table class="inline">
  <tr>
    <th class="leftalign"> semper malesuada  </th><th class="leftalign"> Donec ut nulla  </th><th class="leftalign"> Praesent at mauris  </th>
  </tr>
  <tr>
    <td class="leftalign"> odio  </td><td class="leftalign">Duis sed dolor  </td><td class="leftalign"> Donec tempor  </td>
  </tr>
  <tr>
    <td class="leftalign"> erat eu  </td><td colspan="2">Maecenas auctor neque sit amet lacus    </td>
  </tr>
  <tr>
    <td class="leftalign"> metus  </td><td class="leftalign">Aenean  </td><td class="leftalign"> id tortor  </td>
  </tr>
</table>
<p><sup>Sed in dui quis nisl adipiscing semper.</sup></p></dd>
        <dt><a id="model_b" name="model_b">model b</a></dt>
          <dd><p>Suspendisse dignissim.  Suspendisse fermentum luctus nulla. Integer ut ipsum sit  amet felis fermentum consequat. Morbi eget augue vel metus pellentesque  eleifend.</p></dd>
        <dt><a id="model_c" name="model_c">model c</a></dt>
          <dd><p></p>
<table class="inline">
  <tr>
    <th class="leftalign"> semper malesuada  </th><th class="leftalign"> Donec ut nulla  </th><th class="leftalign"> Praesent at mauris  </th>
  </tr>
  <tr>
    <td class="leftalign">In auctor  </td><td class="leftalign">ipsum urna  </td><td class="leftalign">cursus felis  </td>
  </tr>
  <tr>
    <td class="leftalign">erat eu pretium  </td><td class="leftalign">vitae varius  </td><td class="leftalign">elit risus  </td>
  </tr>
  <tr>
    <td class="leftalign" colspan="2">Aenean rhoncus iaculis ipsum  </td><td class="leftalign">interdum  </td>
  </tr>
</table>
<p> <em>Sed ornare eget augue. dolor et nisl. Morbi rutrum dui ut mauris. Proin
non felis sit amet odio eleifend iaculis.</em></p></dd>
        </dl>
        <p> <acronym title="GNU's Not Unix">GNU</acronym>/Linux support: Quisque faucibus nonummy nulla. Nam a nulla sed nibh  condimentum euismod. Integer ac sem eu quam adipiscing rutrum.</p>

<p><em>Vestibulum</em> accumsan. Cras quam. Fusce nibh ante, convallis quis,  sollicitudin a, rutrum a, sem. </p></dd>
      <dt><a id="abra_padrapa_cumulii" name="abra_padrapa_cumulii">Abra Padrapa Cumulii</a></dt>
        <dd><p>A private corporation. Vivamus tristique, pede eu vulputate pharetra,  nulla purus volutpat ligula, nec condimentum velit mauris at lorem. Donec  sit amet lacus.</p></dd>
    </dl>
    <dt><a id="organizations" name="organizations">Organizations</a></dt>
      <dd><dl>
      <dt><a id="association_for_progressive_communications" name="association_for_progressive_communications">Association for Progressive Communications</a></dt>
        <dd><p>An organization founded ... (see <a href="http://www.apc.org/" class="urlextern" target="_blank" title="http://www.apc.org/" onclick="return svchk()" onkeypress="return svchk()" rel="nofollow">http://www.apc.org/</a>) The activities of this worldwide acting &rarr;<a href="#ngo" title="plugins:deflist_test &crarr;" class="wikilink1">NGO</a> include</p>
<ol>
<li class="level1"><div class="li"> Aenean ligula mi, feugiat nec, eleifend ac, ullamcorper id, velit. Donec at orci in leo nonummy fermentum. Vestibulum pellentesque wisi sed magna elementum mattis.</div>
</li>
<li class="level1"><div class="li"> Donec vel ante quis ipsum vulputate dapibus. Cras ultrices. Sed egestas neque nec augue congue ornare. Sed sit amet lectus ac nibh porta mollis. Aenean justo. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</div>
</li>
<li class="level1"><div class="li"> Pellentesque nonummy nunc eu lacus. Praesent tincidunt mollis wisi. Donec id est. Proin odio wisi, ornare vitae, scelerisque non, ultrices vel, dolor. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Nulla nec risus.</div>
</li>
<li class="level1"><div class="li"> Aliquam erat volutpat. Integer non dui id justo sodales dignissim. In molestie suscipit ipsum. Donec nonummy mauris id justo. Nullam vehicula gravida tortor.</div>
</li>
</ol></dd>
      <dt><a id="another_public_community" name="another_public_community">Another Public Community</a></dt>
        <dd><p>A publically available service. Vivamus tortor erat, dictum ut, ultrices  eget, gravida non, ligula. Vestibulum malesuada, risus nec tempor vulputate,  est velit placerat orci, viverra tincidunt mi sapien eu augue.</p></dd>
      <dt><a id="aphasellus_polumassa_corleo" name="aphasellus_polumassa_corleo">Aphasellus polumassa corleo</a></dt>
        <dd><p>Nullam tempor adipiscing quam, eleifend eu,  dignissim ac, venenatis a, lorem. Vestibulum sed ipsum quis neque tincidunt  luctus. Curabitur eu nisl. Pellentesque non metus id purus rhoncus rutrum.</p></dd>
    </dl>
    <dt><a id="other" name="other">other</a></dt>
      <dd><p></p>
<ul>
<li class="level1"><div class="li"> Morbi nonummy sodales metus. Praesent semper. Nullam at leo. Cras turpis. </div>
</li>
<li class="level1"><div class="li"> Quisque nibh ipsum, malesuada vel, feugiat id, fringilla sit amet, mauris. </div&gt;
<;/li>
<li class="level1"><div class="li"> Morbi imperdiet volutpat tellus. Donec enim libero, auctor at, hendrerit ac, eleifend vitae, arcu.</div>
</li>
<li class="level1"><div class="li"> Praesent quis libero ac sapien vestibulum mollis. Quisque eget ante eget velit egestas sagittis.</div>
</li>
<li class="level1"><div class="li"> Proin porta pede non quam. Quisque congue nibh id wisi. Curabitur malesuada adipiscing est. Donec eleifend.</div>
</li>
<li class="level1"><div class="li"> Morbi tristique congue velit. Etiam placerat aliquet orci. In tincidunt venenatis enim.</div>
</li>
</ul>

<p>  <em>Maecenas id metus non quam feugiat pretium.</em></p></dd>
  </dl>
  <dt><a id="ngo" name="ngo">NGO</a></dt>
    <dd><p><u>N</u>on-<u>G</u>overnmental <u>O</u>rganization. Aliquam mollis libero vel elit.  Sed tempus ante et ante. Phasellus sed mauris nec diam ultrices consequat.  Pellentesque habitant morbi tristique senectus et netus et malesuada fames  ac turpis egestas. Phasellus malesuada.</p></dd>
  <dt><a id="ups" name="ups">UPS</a></dt>
    <dd><dl>
    <dt><a id="uninterruptible_power_supply" name="uninterruptible_power_supply">Uninterruptible Power Supply.</a></dt>
      <dd><p>Mauris quis justo nec nibh ultrices molestie. Integer  imperdiet feugiat sapien. Nunc ante justo, dapibus nec, interdum quis,  tempus ut, ligula.</p></dd>
    <dt><a id="ut_provo_corpora" name="ut_provo_corpora">Ut Provo Corpora</a></dt>
      <dd><p>Laoreet tellus placerat libero hendrerit posuere. Sed  eleifend sollicitudin felis. Etiam lacinia malesuada augue. Cras eu odio.</p>

<p>Pellentesque id sem. Mauris erat sapien, ullamcorper id, facilisis a, congue  in, lectus. Donec risus nisl, rutrum ornare, imperdiet ut, ultricies eu, neque.</p></dd>
    </dl></dd>
</dl><p>
</code>

Please note that the plugin tries hard to minimize the effects of DokuWiki's cur­rent handling((... which one could consider buggy in this respect:
Paragraphs are opened/closed un­con­di­tio­nally w/o actually tracking the document's real state.
One could call that muddling with the domains of responsibility.
This, in turn, forces basically uninvolved parties such as, for instance, this plugin to deal with wrong markup produced elsewhere -- thus propagating the bad ...)) of the respective renderers for the nested elements.
This plugin attempts to make the best of the given situation by in­ser­ting/re­mo­ving ope­ning/clo­sing para­graph tags as appropriate((To make it work at all, the [[#Plugin Source|plugin]] has to lie about its "%%PType%%":
While the correct value of the "%%getPType()%%" method is "%%block%%" it instead must return "%%normal%%" because otherwise even inlined
sub­sti­tu­tions (like **strong**, //emphasized// or __underlined__ text) would end up in separate paragraphs each.)).

===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. 

Alternatively, refer to [[:Plugins]] on how to install plugins manually. It's quite easy to integrate this plugin with your DokuWiki:

	- Download the [[http://dev.mwat.de/dw/syntax_plugin_deflist.zip|source archive]] (~6KB) and un­pack it in your Doku­Wiki plugin di­rec­tory ''{dokuwiki}/lib/plugins'' (make sure, included sub­di­rec­to­ries are un­packed cor­rect­ly); this will create the di­rec­tory ''{dokuwiki}/lib/plugins/deflist''.
	- Make sure both the new direc­tory and the files therein are read­able by the web-server e.g.<code>
	chown apache:apache dokuwiki/lib/plugins/* -Rc
</code>


===== Plugin Source =====

Here comes the [[http://www.gnu.org/licenses/gpl.html|GPLed]] PHP source((The comments within the [[#Plugin Source|source]] file are suitable for the OSS [[http://www.stack.nl/~dimitri/doxygen/index.html|doxygen]] tool, a do­cu­men­ta­tion sy­stem for C++, C, Java, Ob­jec­tive-C, Python, IDL and to some extent PHP, C#, and D. ---
Since I'm working with dif­fe­rent pro­gram­ming lan­gua­ges it's a great ease to have one tool that handles the docs for all of them.)) for those who'd like to scan it be­fore actu­ally in­stal­ling it:
<code php>
<?php
if (! class_exists('syntax_plugin_deflist')) {
  if (! defined('DOKU_PLUGIN')) {
    if (! defined('DOKU_INC')) {
      define('DOKU_INC', realpath(dirname(__FILE__) . '/../../') . '/');
    } // if
    define('DOKU_PLUGIN', DOKU_INC . 'lib/plugins/');
  } // if
  // include parent class
  require_once(DOKU_PLUGIN . 'syntax.php');
  define('PLUGIN_DEFLIST', 'plugin_deflist');

/**
 * <tt>syntax_plugin_deflist.php </tt>- A PHP4 class that implements
 * a <tt>DokuWiki</tt> plugin for <tt>definition list</tt> elements.
 *
 * <p>
 * Definition list pattern:<br>
 * <tt>?? Term :: Term definition !!</tt>
 * </p>
 * <pre>
 *  Copyright (C) 2005, 2007 DFG/M.Watermann, D-10247 Berlin, FRG
 *      All rights reserved
 *    EMail : &lt;support@mwat.de&gt;
 * </pre>
 * <p>
 * <em>Credits:</em> This plugin was inspired by ideas of
 * <a href="http://www.dokuwiki.org/plugin:definition_list"
 * target="_blank">Stephane Chamberland</a> and <a target="_blank"
 * href="http://www.dokuwiki.org/plugin:definitions">Pavel
 * Vitis</a> both of whom wrote a similar plugin that <em>almost</em>
 * worked.
 * </p>
 * <div class="disclaimer">
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either
 * <a href="http://www.gnu.org/licenses/gpl.html">version 3</a> of the
 * License, or (at your option) any later version.<br>
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details.
 * </div>
 * @author <a href="mailto:support@mwat.de">Matthias Watermann</a>
 * @version <tt>$Id: syntax_plugin_deflist.php,v 1.14 2007/08/15 12:36:20 matthias Exp $</tt>
 * @since created 05-Aug-2005
 */
class syntax_plugin_deflist extends DokuWiki_Syntax_Plugin {

  /**
   * @privatesection
   */
  //@{

  /**
   * Convert the specified <tt>$aID</tt> to a valid XHTML
   * fragment identifier.
   *
   * <p>
   * <a href="http://www.w3.org/TR/xhtml1/#guidelines" target="_blank">
   * XHTML 1</a> (section C.8, Fragment Identifiers) gives the regex
   * <tt>[A-Za-z][A-Za-z0-9:_.-]*</tt> for valid identifiers. Here
   * it's slightly reduced to <tt>[A-Za-z][A-Za-z0-9_]+</tt> i.e.
   * all non alphanumeric characters are replaced by underscores.
   * </p>
   * @param $aID String The raw ID string.
   * @return String
   * @private
   * @since created 24-Aug-2005
   * @see render()
   */
  function _makeID(&$aID) {
    static $CHARS;
    if (! is_array($CHARS)) {
      $CHARS = array('|[^A-Za-z0-9_]|', // replace invalid characters
        '|_{2,}|',    // reduce multiple underscores
        '|^[^A-Za-z]+|',  // remove invalid leading chars
        '|_+$|');    // remove trailing underscores
    } // if
    // As long as DokuWiki (in contrast to W3C) doesn't allow uppercase
    // letters in internal anchor names we've to use 'strtolower()'
    // here as well to make the anchors work within DokuWiki.
    return strtolower(preg_replace($CHARS, array('_', '_'),
      utf8_deaccent($aID, 0)));
  } // _makeID()

  //@}
  /**
   * @publicsection
   */
  //@{

  /**
   * Tell the parser whether the plugin accepts syntax mode
   * <tt>$aMode</tt> within its own markup.
   *
   * <p>
   * This method mostly returns <tt>TRUE</tt> since all other types
   * are allowed within a definition list's <tt>DD</tt> sections.
   * Only another definition list is denied since <em>nested DLs are
   * currently not supported</em>.
   * </p>
   * @param $aMode String The requested syntaxmode.
   * @return Boolean <tt>TRUE</tt> unless <tt>$aMode</tt>
   * is <tt>plugin_deflist</tt> (which would result in a
   * <tt>FALSE</tt> method result).
   * @public
   * @see getAllowedTypes()
   */
  function accepts($aMode) {
    return (PLUGIN_DEFLIST != $aMode);
  } // accepts()

  /**
   * Connect lookup pattern to lexer.
   *
   * @param $aMode String The desired rendermode.
   * @public
   * @see render()
   */
  function connectTo($aMode) {
    if (PLUGIN_DEFLIST == $aMode) {
      return;
    } // if
    // We have to use assertion patterns here to make sure the DD sections
    // are UNMATCHED since only those are subject to further substitution.
    $this->Lexer->addEntryPattern(
      '\n\x20{2,}\s*\x3F\x3F(?s).+?(?=::(?s).*!!\n\n)',
      $aMode, PLUGIN_DEFLIST);
    $this->Lexer->addEntryPattern(
      '\n\t+\s*\x3F\x3F(?s).+?(?=::(?s).*!!\n\n)',
      $aMode, PLUGIN_DEFLIST);
    $this->Lexer->addPattern(
      '\n\x20{2,}\s*\x3F\x3F(?s).+?\s*(?=::(?s).*?!!)', PLUGIN_DEFLIST);
    $this->Lexer->addPattern(
      '\n\t+\s*\x3F\x3F(?s).+?\s*(?=::(?s).*?!!)', PLUGIN_DEFLIST);
  } // connectTo()

  /**
   * Get an associative array with plugin info.
   *
   * <p>
   * The returned array holds the following fields:
   * <dl>
   * <dt>author</dt><dd>Author of the plugin</dd>
   * <dt>email</dt><dd>Email address to contact the author</dd>
   * <dt>date</dt><dd>Last modified date of the plugin in
   * <tt>YYYY-MM-DD</tt> format</dd>
   * <dt>name</dt><dd>Name of the plugin</dd>
   * <dt>desc</dt><dd>Short description of the plugin (Text only)</dd>
   * <dt>url</dt><dd>Website with more information on the plugin
   * (eg. syntax description)</dd>
   * </dl>
   * @return Array Information about this plugin class.
   * @public
   * @static
   */
  function getInfo() {
    return array(
      'author' =>  'Matthias Watermann',
      'email' =>  'support@mwat.de',
      'date' =>  '2007-08-15',
      'name' =>  'Definition List Syntax Plugin',
      'desc' =>  '(X)HTML style Definition Lists [ ?? Term :: Definition !! ]',
      'url' =>  'http://www.dokuwiki.org/plugin:deflist');
  } // getInfo()

  /**
   * Define how this plugin is handled regarding paragraphs.
   *
   * <p>
   * This method is important for correct XHTML nesting. It returns
   * one of the following values:
   * </p>
   * <dl>
   * <dt>normal</dt><dd>The plugin can be used inside paragraphs.</dd>
   * <dt>block</dt><dd>Open paragraphs need to be closed before
   * plugin output.</dd>
   * <dt>stack</dt><dd>Special case: Plugin wraps other paragraphs.</dd>
   * </dl>
   * @return String <tt>'normal'</tt> instead of the (correct) 'block'
   * since otherwise the current DokuWiki parser would put all
   * substitutions within a DD section in separate paragraphs.
   * @public
   * @static
   */
  function getPType() {
    return 'normal';
  } // getPType()

  /**
   * Where to sort in?
   *
   * @return Integer <tt>18</tt>, an arbitrary value smaller
   * <tt>Doku_Parser_Mode_preformated</tt> (20).
   * @public
   * @static
   */
  function getSort() {
    return 18;
  } // getSort()

  /**
   * Get the type of syntax this plugin defines.
   *
   * @return String <tt>'container'</tt>.
   * @public
   * @static
   */
  function getType() {
    return 'container';
  } // getType()

  /**
   * Handler to prepare matched data for the rendering process.
   *
   * <p>
   * The <tt>$aState</tt> parameter gives the type of pattern
   * which triggered the call to this method:
   * </p>
   * <dl>
   * <dt>DOKU_LEXER_ENTER</dt>
   * <dd>a pattern set by <tt>addEntryPattern()</tt>.</dd>
   * <dt>DOKU_LEXER_MATCHED</dt>
   * <dd>a pattern set by <tt>addPattern()</tt> (here: DT data).</dd>
   * <dt>DOKU_LEXER_EXIT</dt>
   * <dd> a pattern set by <tt>addExitPattern()</tt>.</dd>
   * <dt>DOKU_LEXER_UNMATCHED</dt>
   * <dd>ordinary text encountered within the plugin's syntax mode
   * which doesn't match any pattern (here: DD data).</dd>
   * </dl>
   * @param $aMatch String The text matched by the patterns.
   * @param $aState Integer The lexer state for the match.
   * @param $aPos Integer The character position of the matched text.
   * @param $aHandler Object Reference to the Doku_Handler object.
   * @return Array Index <tt>[0]</tt> holds the current
   * <tt>$aState</tt>, index <tt>[1]</tt> the match (as a list of
   * entries) prepared for the <tt>render()</tt> method.
   * @public
   * @see render()
   * @static
   */
  function handle($aMatch, $aState, $aPos, &$aHandler) {
    static $ESCDELIMS;  // static constants to avoid the runtime overhead
    static $UNDELIMS; // of re-creating the arrays on each method call
    if (! is_array($ESCDELIMS)) {
      $ESCDELIMS = array('\?', '\!', '\:');
    } // if
    if (! is_array($UNDELIMS)) {
      $UNDELIMS = array('?', '!', ':');
    } // if
    switch ($aState) {
      case DOKU_LEXER_ENTER:
        // fall through to extract initial DTs
      case DOKU_LEXER_MATCHED:  // DTs
        $aMatch = preg_split('|\n+(\s*\?\?)\s*|', $aMatch,
          -1, PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
        $dts = array();
        $c = count($aMatch);
        for ($i = 0; $c > $i; ++$i) {
          if ($i & 1) {
            $dts[] = array($aMatch[$i - 1],
              str_replace($ESCDELIMS, $UNDELIMS,
                trim($aMatch[$i])));
            $aMatch[$i - 1] = $aMatch[$i] = NULL;
          } else {
            $aMatch[$i] = strlen(
              str_replace('  ', "\t", $aMatch[$i])) - 2;
          } // if
        } // for
        return array($aState, $dts);
      case DOKU_LEXER_UNMATCHED:  // DDs
        $aMatch = preg_split('|\s*(::\s*.*?!!)|s', $aMatch,
          -1, PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
        $mark = FALSE;  // indication for kind of DD entry
        $c = count($aMatch);
        $hits = $dds = array();
        for ($i = 0; $c > $i; ++$i) {
          if (preg_match('|::\s*(.*?)\s*!!|s', $aMatch[$i], $hits)) {
            $mark = 0;  // complete DD w/o substitution(s)
          } else if (preg_match('|::\s*(.*)|s', $aMatch[$i], $hits)) {
            $mark = -1;  // DD part before substitution(s)
          } else if (preg_match('|(.*?)\s*!!|s', $aMatch[$i], $hits)) {
            $mark = +1;  // DD part behind substitution(s)
          } else {
            $mark = TRUE;  // DD part between substitutions
            $hits[1] = $aMatch[$i];
          } // if
          $dds[] = array(
            str_replace($ESCDELIMS, $UNDELIMS, $hits[1]) => $mark);
        } // for
        return array($aState, $dds);
      case DOKU_LEXER_EXIT:
        // end of list
      default:
        return array($aState);
    } // switch
  } // handle()

  /**
   * Add exit pattern to lexer.
   *
   * <p>
   * Two consecutive linefeeds mark the end'o'list.
   * </p>
   * @note Access <em>public</em>
   */
  function postConnect() {
    $this->Lexer->addExitPattern('(?<=!!)\n(?=\n)', PLUGIN_DEFLIST);
  } // postConnect()

  /**
   * Handle the actual output creation.
   *
   * <p>
   * The method tests the given <tt>$aFormat</tt> returning
   * <tt>FALSE</tt> if it's not supported. <tt>$aRenderer</tt>
   * contains a reference to the renderer object which is currently
   * handling the rendering. The contents of <tt>$aData</tt> is the
   * return value of the <tt>handle()</tt> method.
   * </p>
   * @param $aFormat String The output format to being tendered.
   * @param $aRenderer Object A reference to the renderer object.
   * @param $aData Array The data created by the <tt>handle()</tt>
   * method.
   * @return Boolean <tt>TRUE</tt> if rendered successfully, or
   * <tt>FALSE</tt> otherwise.
   * @public
   * @see handle()
   * @static
   */
  function render($aFormat, &$aRenderer, &$aData) {
    if ('xhtml' != $aFormat) {
      return FALSE;
    } // if
    static $LEVEL = 1;    // current nesting level
    static $INDD = array();  // marks whether there's an open DD
    static $CHARS;  static $ENTS;  // HTML special chars
    if (! is_array($CHARS)) {
      $CHARS = array('&','<', '>');
    } // if
    if (! is_array($ENTS)) {
      $ENTS = array('&#38;', '&#60;', '&#62;');
    } // if
    // XXX: All those <p> and </p> tags handled here are just kind
    // of workaround problems with the current DokuWiki renderer.
    // Basically they are __wrong__ here but, alas, without them
    // invalid HTML would be generated :-(
    // If and when DokuWiki becomes more statefull the superflous
    // tags should be removed.
    switch ($aData[0]) {
      case DOKU_LEXER_ENTER:
        // since we have to use PType 'normal' we must close
        // the current paragraph
        $hits = array();
        if (preg_match('|\s*<p>\s*$|i', $aRenderer->doc, $hits)) {
          $aRenderer->doc = substr($aRenderer->doc,
            0, -strlen($hits[0])) . '<dl>';
        } else {
          $aRenderer->doc .= '</p><dl>';
        } // if
        // fall through to render initial DTs
      case DOKU_LEXER_MATCHED:
        foreach ($aData[1] as $dt) {
          $diff = $dt[0] - $LEVEL;
          if (0 < $diff) {
            // going UP __one__ level
            ++$LEVEL;
            $hits = array();
            if (preg_match('|\s*<dd>\s*<p>\s*$|i',
              $aRenderer->doc, $hits)) {
              $aRenderer->doc = substr($aRenderer->doc,
                0, -strlen($hits[0])) . '<dd><dl>';
            } else {
              $aRenderer->doc .= (preg_match(
                '|\s*</d[dt]>\s*$|i', $aRenderer->doc))
                  ? '<dd><dl>'
                  : '</dd><dd><dl>';
            } // if
          } else if (0 > $diff) {
            do {  // going back some levels
              --$LEVEL;
              $aRenderer->doc .= (isset($INDD[$LEVEL]))
                ? '</dl>'
                : '</dl></dd>';
            } while (0 > ++$diff);
          // ELSE: no level change
          } // if
          $hits = array();
          if (preg_match('|\s*<p>\s*$|i', $aRenderer->doc, $hits)) {
            // remove unneeded P
            $aRenderer->doc = substr($aRenderer->doc,
              0, -strlen($hits[0]));
          } // if
          $id = $this->_makeID($dt[1]);
          // see http://www.w3.org/TR/xhtml1/#h-4.10
          $aRenderer->doc .= '<dt><a id="' . $id . '" name="'
            . $id . '">' . str_replace($CHARS, $ENTS, $dt[1])
            . '</a></dt>';
        } // foreach
        return TRUE;
      case DOKU_LEXER_UNMATCHED:
        $c = count($aData[1]);
        for ($i = 0; $c > $i; ++$i) {
          list($dd, $mark) = each($aData[1][$i]);
          $dd = str_replace($CHARS, $ENTS, $dd);
          if (TRUE === $mark) {
            // part between substitutions
            if (isset($INDD[$LEVEL])) {
              if (strlen($dd)) {
                $aRenderer->doc .= $dd;
              } // if
            } else {
              $tabs = str_repeat("\t", $LEVEL);
              $aRenderer->doc .= (strlen($dd))
                ? '</dl><p>' . $dd
                : '</dl>';
              $INDD[--$LEVEL] = TRUE;
            } // if
          } else if (0 == $mark) {
            // complete definition w/o substitutions
            if (strlen($dd)) {
              $aRenderer->doc .= '<dd><p>' . $dd . '</p></dd>';
            } // if
          } else if (0 > $mark) {
            // DD part before substitutions
            $aRenderer->doc .= (strlen($dd))
              ? '<dd><p>' . $dd
              : '<dd><p>';
            $INDD[$LEVEL] = TRUE;
          } else if (0 < $mark) {
            // DD part behind substitutions
            if (isset($INDD[$LEVEL])) {
              if (strlen($dd)) {
                $aRenderer->doc .= $dd . '</p></dd>';
              } else {
                $hits = array();
                if (preg_match('|\s*<p>\s*$|i',
                  $aRenderer->doc, $hits)) {
                  $aRenderer->doc = substr(
                    $aRenderer->doc, 0,
                    -strlen($hits[0])) . '</dd>';
                } else {
                  $aRenderer->doc .= '</p></dd>';
                } // if
              } // if
              unset($INDD[$LEVEL]);
            } // if
            // ELSE: doesn't ever happen with non-empty $dd
          } // if
        } // for
        return TRUE;
      case DOKU_LEXER_EXIT:
        // Close all possibly open lists:
        while (0 < --$LEVEL) {
          $aRenderer->doc .= '</dl></dd>';
        } // while
        // Since we have to use PType 'normal' we must open
        // a new paragraph for the following text
        $aRenderer->doc = preg_replace('|\s*<p>\s*</p>\s*|', '',
          $aRenderer->doc) . '</dl><p>';
        $INDD = array();
        $LEVEL = 1;
      default:
        return TRUE;
    } // switch
  } // render()

  //@}
} // class syntax_plugin_deflist
} // if
//Setup VIM: ex: et ts=2 enc=utf-8 :
?>
</code>

==== Presentation ====
The accompanying CSS presentation rules:
<code css>
dl{font-size:1em;margin:0.5ex 0 0.5ex 1ex;padding:0.5ex 0 0.5ex 1ex;}
dl dt{font:105% "Book Antiqua","Bitstream Vera Serif",Times,serif;font-weight:bolder;margin:0.5ex 0 0 0;}
dl dt a,dl dt a:hover{text-decoration:none;}
dl dd{margin:0 0 0 2ex;text-align:justify;}
dl dd dl{margin:0;padding:0;}
dl dd p{padding:0;text-indent:0;}
</code>
Of course, you're free to modify this styles((The [[http://dev.mwat.de/dw/syntax_plugin_deflist.zip|source archive]] contains a commented and indented stylesheet for your in­for­ma­tion.)) to suit your personal needs or aesthe­tics((Just be careful when modifying a CSS file: both the order and the selector grou­pings are im­por­tant for CSS to work as intended/expected.)).

==== Changes ====

__2007-08-15__:\\
* added GPL link and fixed some doc problems;

__2007-01-06__:\\
* internal changes to avoid generating useless whitespace;

__2005-08-31__:\\
# minor change to make sure deeper nesting goes only one level per step;\\
- removed unneeded code;

__2005-08-30__:\\
* generated anchor names are compatible with DokuWiki (not W3C);\\
+ implemented nesting of other definition lists;

__2005-08-26__:\\
- removed usage of global //%%$conf%%// variable (HTML special characters are always encoded);

__2005-08-24__:\\
+ added escaping for //%%??%%//, //%%::%%//, //%%!!%%// sequences;\\
+ added automatic generation of anchors for all DT elements;\\
+ added usage of global //%%$conf['htmlok']%%// to determine handling of HTML special characters;\\
+ added encoding of HTML special characters;

__2005-08-20__:\\
* improved handling of inline substitions and nested blocks;\\
* moved some work from //%%render()%%// method to //%%handle()%%//;\\
* added more doc-comments;

__2005-08-18__:\\
* modified pattern to allow for nested block elements;\\
+ implemented 1:1/1:n/n:1/n:n DT:DD relations;

__2005-08-16__:\\
+ initial release providing basic functionality;

//[[support@mwat.de|Matthias Watermann]] 2007-08-15//

===== See also =====

Prior to the release of this implementation there were -- as far as I'm aware -- two other plugins heading for the same goal:
one written by [[http://www.dokuwiki.org/plugin:definition_list|Stephane Chamberland]]
and the other by  [[http://www.dokuwiki.org/plugin:definitions|Pavel Vitis]].
While both of them in fact provided kind of //de­fi­ni­tion list// markup, I found them to lack one feature or the other I thought use­ful (especially the full range of "%%DT:DD%%" combinations((without adding superflous and textual wrong HTML tags: A <code html>
<dl><dt>term1</dt><dt>term2</dt><dd>def of 1 and 2</dd></dl>
</code> block is quite different from <code html>
<dl><dt>term1</dt><dd></dd><dt>term2</dt><dd>def of 1 and 2</dd></dl>
</code> which in fact gives an __empty__ definition for "%%term1%%" instead of
__none__ and this way messing up the whole meaning -- for both, humans and semantic scanners.
The only similarity  between both constructs is that they might, possibly, under certain  conditions, depending  on the user's rendering engine, well, //look// alike on visual output devices.
So clearly that's not a way to go.
Especially if a document might be __read__ (by a screenreader for instance or a Braille device) or passed to some transformation tool (e.g. to store the terms and their respective definitions in a database) or ...)) and nesting of other block elements).
Hence I wrote [[#Plugin Source|this]] PHP class. ---
Later there ap­peared [[http://www.dokuwiki.org/plugin:definitionlist|"yet another plugin"]] which claimed to add support for definition lists to DokuWiki.
It generates superfluous "%%span%%" tags and provides even "some con­fi­gu­ra­tion set­tings" to further mixup markup with presentation in­ten­tions((which is just another point to avoid)).

Please check the respective docs to see what will fit your needs best.

==== Plugins by the same author ====

	* [[bomfix|BOMfix Plugin]] -- ignore Byte-Order-Mark characters in your pages
	* [[code2|Code Syntax Plugin]] -- use syntax highlighting of code fragments in your pages
	* [[deflist|Definition List Syntax Plugin]] -- use the only complete definition lists in your pages
	* [[diff|Diff Syntax Plugin]] -- use highlighting of diff files (aka "patches") in your pages((obsoleted by incorporating its ability into the [[code2|Code]] plugin))
	* [[hr|HR Syntax Plugin]] -- use horizontal rules in nested block elements of your pages
	* [[lang|LANGuage Syntax Plugin]] -- markup different languages in your pages
	* [[lists|Lists Syntax Plugin]] -- use the only complete un-/ordered lists in your pages
	* [[nbsp|NBSP Syntax Plugin]] -- use Non-Breakable-Spaces in your pages
	* [[nstoc|NsToC Syntax Plugin]] -- use automatically generated namespace indices
	* [[shy|Shy Syntax Plugin]] -- use soft hyphens in your pages
	* [[tip|Tip Syntax Plugin]] -- add hint areas to your pages

===== Discussion =====
Hints, comments, suggestions ...


> A couple of quick points. \\ --- You don't appear to be doing any entity conversion on the raw wiki data.  That can allow HTML and JavaScript to be embedded in the page.  \\ --- It's now possible to put the styles required by the plugin in a file ''style.css'' in the plugin's own folder.  DokuWiki will detect the file and link to it.  The file is included before the template style sheets allowing the styles to be overridden, but making installation much easier. \\  --- //[[chris@jalakai.co.uk|Christopher Smith]] 2005-08-25 02:17//
>
>>ad 1: Admittedly I relied (w/o checking/testing) on the config option ''htmlok'' (which is FALSE/0 in my installation). Do I understand you correctly that this assumption is wrong?\\ ad 2: I'm using the last 'stable' release (2005-07-13) and I understand your ''now'' to mean the unstable/develepment version, right? In any case to have style_file_2 overwrite style_file_1 it must be included in the (X)HTML file __after__ the first one.\\ --- //[[support@mwat.de|Matthias Watermann]] 2005-08-25 14:05//
>
>>I've updated the script on account of the security hole you mentioned in your first point. Thanks for noting that!\\ --- //[[support@mwat.de|Matthias Watermann]] 2005-08-25 17:55//
>>>  Your plugin should not need to bother with ''%%$conf['htmlok']%%''. It only refers to data nested within %%<html>%% tags, there is a built in syntax mode for handling that. Its the responsibility of the plugin to ensure that the raw wiki data it handles is safe to be output - i.e. perform entity conversion.  The normal method is to filter the text output between your html tags through ''%%$renderer->xmlEntities()%%''. e.g. <code>
		if (TRUE === $mark) {
		// part between substitutions
		$aRenderer->doc .= $aRenderer->xmlEntities($dd);
		} else if (0 == $mark) {
		// complete definition w/o substitutions
		$aRenderer->doc .= "\n\t<dd><p>$aRenderer->xmlEntities($dd)</p></dd>";
		} else if (0 > $mark) {
		// DD part before substitutions
		$aRenderer->doc .= "\n\t<dd><p>$aRenderer->xmlEntities($dd)";
		} else if (0 < $mark) {
		// DD part behind substitutions
		$aRenderer->doc .= $aRenderer->xmlEntities($dd) . '</p></dd>';
</code>  --- //[[chris@jalakai.co.uk|Christopher Smith]] 2005-08-25 20:30//
>>>
>>>>Thanks for your notes. I've updated the plugin (and doc) removing all references to  ''%%$conf['htmlok']%%''.\\  --- //[[support@mwat.de|Matthias Watermann]] 2005-08-26 13:48//

===== Styles Conflicts with Media Manager =====

Plugin's styles override global styles for ''dl'' element. So for example Media Manager introduced in Angua release is displayed slightly incorrectly. --- //[[rogerdan@mail.ru|DenisK]] 2011-12-29 20:22//

I propose to add class for ''dl'' element:

<code css>
dl.deflist{font-size:1em;margin:0.5ex 0 0.5ex 1ex;padding:0.5ex 0 0.5ex 1ex;}
dl.deflist dt{font:105% "Book Antiqua","Bitstream Vera Serif",Times,serif;font-weight:bolder;margin:0.5ex 0 0 0;}
dl.deflist dt a,dl dt a:hover{text-decoration:none;}
dl.deflist dd{margin:0 0 0 2ex;text-align:justify;}
dl.deflist dd dl{margin:0;padding:0;}
dl.deflist dd p{padding:0;text-indent:0;}
</code>

And change ''syntax.php'' accordingly:

<code diff>
--- syntax_old.php      2007-08-15 16:36:20.000000000 +0400
+++ syntax.php  2012-02-11 22:26:39.590997001 +0300
@@ -356,9 +356,9 @@
                                $hits = array();
                                if (preg_match('|\s*<p>\s*$|i', $aRenderer->doc, $hits)) {
                                        $aRenderer->doc = substr($aRenderer->doc,
-                                               0, -strlen($hits[0])) . '<dl>';
+                                               0, -strlen($hits[0])) . '<dl class="deflist">';
                                } else {
-                                       $aRenderer->doc .= '</p><dl>';
+                                       $aRenderer->doc .= '</p><dl class="deflist">';
                                } // if
                                // fall through to render initial DTs
                        case DOKU_LEXER_MATCHED:
@@ -371,12 +371,12 @@
                                                if (preg_match('|\s*<dd>\s*<p>\s*$|i',
                                                        $aRenderer->doc, $hits)) {
                                                        $aRenderer->doc = substr($aRenderer->doc,
-                                                               0, -strlen($hits[0])) . '<dd><dl>';
+                                                               0, -strlen($hits[0])) . '<dd><dl class="deflist">';
                                                } else {
                                                        $aRenderer->doc .= (preg_match(
                                                                '|\s*</d[dt]>\s*$|i', $aRenderer->doc))
-                                                                       ? '<dd><dl>'
-                                                                       : '</dd><dd><dl>';
+                                                                       ? '<dd><dl class="deflist">'
+                                                                       : '</dd><dd><dl class="deflist">';
                                                } // if
                                        } else if (0 > $diff) {
                                                do {    // going back some levels
</code>