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

---- plugin ----
description: (X)HTML Definition lists, simple syntax and smart styling
author     : Christopher Smith, Sam Wilson, LarsDW223
email      : chris@jalakai.co.uk
type       : syntax
lastupdate : 2017-08-17
compatible : Ponder Stibbons, Angua, Adora Belle, Rincewind, Weatherwax, Binky, Hrun, Frusterick Manners
depends    : 
conflicts  : qc, CKGEdit, ckgdoku 
similar    : deflist, dl, definitions, definition, yalist, extlist
screenshot_img :
tags       : formatting, list, definitions, odt

downloadurl: https://github.com/LarsGit223/dokuwiki-plugin-definitionlist/archive/2017-08-17.zip
bugtracker : https://github.com/LarsGit223/dokuwiki-plugin-definitionlist/issues
sourcerepo : https://github.com/LarsGit223/dokuwiki-plugin-definitionlist
donationurl: 
----

This plugin adds support for definition lists to DokuWiki.  Which is nothing more than creating two columns on a page: one column with the term, and another column with the definition.  So it's a very simple plugin.  Basically, the plugin adds some extra syntax to create the two columns.

It can be used with the [[plugin:explain#use_with_deflist_plugin |Explain Plugin]] to make a glossary page for your site.  How?  You add some terms and definitions on a page, and you decide to call it a glossary.  Then, with the explain plugin there is a configuration file that you upload via FTP, or your cPanel file manager (assuming Dokuwiki is running on a server and not locally).

There's no magic.  You'll have to add the same information in two places: the explain configuration file, and the glossary page.  The explain plugin provides a hover pop-up bubble for a term, which includes a definition and an option for an internal link.  You point the internal link to whatever page you want to be the glossary where the definition-list-plugin-syntax is being used.  The glossary can have the same definition that shows in the pop-up bubble (or whatever you want, for that matter).

I might not understand this fully, but people can just fix these paragraphs, or delete this line if I got it right.  I won't be offended.  Delete this paragraph.  Do it.

The following image is a glossary using the definition list syntax.  It's just a regular Dokuwiki page.  The reason Tetrahydrocannabinol and THC appear red, is because the Explain Plugin is active.  Hovering over these red words with the mouse will create a pop-up bubble with the contents of the conf/explain.conf file.

Well, it was my intent to show you a screenshot, but I can't upload a file.


===== 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, if you use new lines within the list the text on the new line is added to the end of the previous line when the definition list is displayed.

See the page in action <del>[[http://wiki.jalakai.co.uk/dokuwiki/doku.php/test/definition_list|here]]</del>


===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:plugin installation instructions]] on how to install plugins manually.
===== Configuration =====

The plugin has two configuration settings.  Where these configuration settings are, well, that's a mystery.

  * ''dt_fancy'' --- on/off, default on. When on will float the term content to the left side of the wiki page, making a faux two column effect with the data content on the right.
  * ''classname'' --- string, default "plugin_definitionlist".  The html classname given to the wrapping <dl> element, e.g. <dl class="plugin_definitionlist">.  Can be used in conjunction with ''userstyle.css'' to vary how the definition is displayed.  [ Forerunner for future enhancements providing multiple display styles with the plugin ].

==== HTML Structure ====

<code html>
<!-- dt_fancy ON, classname plugin_definitionlist -->
<dl class="plugin_definitionlist">
    <dt><span class="term">term</span></dt>
    <dd>definition</dd>
</dl>

<!-- dt_fancy OFF, classname plugin_definitionlist -->
<dl class="plugin_definitionlist">
    <dt>term</dt>
    <dd>definition</dd>
</dl>
</code>

===== History =====

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 were 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>'').

In 2013 the plugin was moved to Github, for easier collaborative development.

Recent changes in the Github repository:
{{rss>https://github.com/LarsGit223/dokuwiki-plugin-definitionlist/commits/master.atom date author}}

Previous revisions:
  * 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.

===== Bugs =====

Please log all bugs and feature requests in the [[https://github.com/LarsGit223/dokuwiki-plugin-definitionlist/issues|issue tracker]] on Github.

===== Discussion ===== 

==== Blank line after list? ====

Can't create blank line after making a list.
--- <del>[[http://mitz.co.kr/wiki/syntax|please check this page]]</del> (Korean) //2014/05/16//

==== Syntax note; and anchor tag? ====

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.

> This is no longer the case.  It is important to make sure the intervening blank lines don't have a couple of blank spaces, which the editor might leave in place.  These confuse the parser and result in it triggering dokuwiki's own [[wiki:syntax#code_blocks|preformatted code block]]

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