Definition lists

[A. Pagaltzis]

* Michel Fortin <michel.fortin at michelf.com> [2005-07-26 19:20]:

> But what happens if you mix the two? Let's see...

> 

>   Apple

>   :   Pomaceous fruit of plants of the genus Malus in

>   the family Rosaceae.

>   :   An american computer company.

>   Orange

>   :   The fruit of an evergreen tree of the genus Citrus.

> 

> This isn't right at all.


The isn’t just problematic for a machine to parse – even humans
have trouble reading that. With the right combination of words
the meaning might in fact be irresolvably ambiguous even to us.
How is a computer supposed to parse that? Not possible.


> PHP Markdown Extra 1.0b2 sees three terms, and we get this:

> 

>   <dl>

>   <dt>Apple</dt>

>   <dd>Pomaceous fruit of plants of the genus Malus in</dd>

> 

>   <dt>the family Rosaceae.</dt>

>   <dd>An american computer company.</dd>

> 

>   <dt>Orange</dt>

>   <dd>The fruit of an evergreen tree of the genus Citrus.</dd>

>   </dl>


At least it doesn’t do the opposite: find a single term with
three definitions.


> Now, I see two ways to solve that: either we make indentation

> mandatory, or we say definition terms must be preceded by an

> empty line. I think the first goes against current Markdown

> behaviours, but I also happen to like the compact form which is

> nice for lists with many short definitions.

> 

> Any ideas?


It’s possible to have both if you require an empty line only
after a lazily indented definition, eg.

    Apple
    :   Pomaceous fruit of plants of the genus Malus in
    the family Rosaceae.

    :   An american computer company.
    Orange
    :   The fruit of an evergreen tree of the genus Citrus.

The rule is: a line starting a definition, followed only by lines
which don’t start a defition, followed by an empty line, is a
single definition of the previous term. This is unambiguous.

In this example, humans will want an extra empty line after the
second definition for Apple, to help us synch up mentally, but
for a computer it isn’t strictly necessary.

This way, you have the choice to use either indentation (more
compact source) or a following empty line (lazier editing) to
disambiguate the formatting.

My 2c,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>