A Modest Definition List Proposal

David E. Wheeler david at kineticode.com
Wed Feb 18 13:44:03 EST 2009


I've been thinking a lot about definition list syntax, and what I did
and didn't like about the PHP Markdown Extra syntax (which seems to be
a de-facto standard, discount notwithstanding, yes?). What I came up
with is a single character change to the PHP Markdown Extra syntax. I
just published a detailed explanation of my thoughts and reasoning for
this on [my blog](http://justatheory.com/computers/markup/modest-markdown-proposal.html
). If you would excuse the temerity of my late entry into what I'm
sure has been a contentious issue, I would love feedback.

In a nutshell, I embrace the PHP Markdown Extra syntax, with one
change: I would like to see the colon replaced with a tilde (for
backwards compatibility, both should be supported). That means that a
simple definition list would look like this:

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

And a more complicated one would look like this:

> Term 1:


> ~ This is a definition with two paragraphs. Lorem ipsum

> dolor sit amet, consectetuer adipiscing elit. Aliquam

> hendrerit mi posuere lectus.


> Vestibulum enim wisi, viverra nec, fringilla in, laoreet

> vitae, risus.


> ~ Second definition for term 1, also wrapped in a paragraph

> because of the blank line preceding it.


> Term 2:


> ~ This definition has a code block, a blockquote and a list.


> code block.


> > block quote

> > on two lines.


> 1. first list item

> 2. second list item

See my blog entry for more detailed description of why I prefer the
tilde to the colon for this purpose. The best things about it are that
it makes for a more natural bullet, already has precedent in
dictionaries, and suggest equivalency if you're familiar with
mathematics, which makes for a nice mnemonic.

Comments? Has this ship already sailed?



More information about the Markdown-Discuss mailing list