A Modest Definition List Proposal

David E. Wheeler david at kineticode.com
Thu Feb 19 12:47:01 EST 2009

On Feb 19, 2009, at 3:48 AM, Michel Fortin wrote:

> It seems I've been called into this discussion. :-)

And thanks for taking the bate. :-)

A quick comment: I started using Markdown about six months ago to
write the documentation for pgTAP, my PostgreSQL unit-testing
framework. Since the format for PostgreSQL documentation is a plain-
text README, and I knew I was going to want it in HTML and perhaps
other formats, I adopted Markdown for the documentation without a
second thought. It felt right, it works almost exactly like I've
always worked in email, and I've been absolutely thrilled with the
[plain text][1] and [HTML][2] results.

[1] https://svn.kineticode.com/pgtap/trunk/README.pgtap
[2] https://svn.kineticode.com/pgtap/trunk/README.pgtap

It has just been a delight to work with, very rewarding. And I guess I
shouldn't be surprised that the community behind it, represented by
this list, is no different. I really appreciate you guys taking the
time to really ponder a possible change to something you've been using
as-is for almost 4 years when a late interloper like myself barges in
and says, “what about this?” Such openness is all to rare in the OSS
world, and just makes me love Markdown all the more.

So thanks for taking me and my proposal seriously. Later, we'll see if
folks are as willing when I look at tables. ;-P

> Well, that whole thread left me wondering. I'm of opinion that using

> a tilde is as good as a colon, perhaps even better visually. It has

> the advantage of looking better when you add a colon at the end of

> your term (which, I think, happen often enough):


> Term:

> : Definition


> Term:

> ~ Definition

Yes, much more natural looking to me, and it stands out a bit more; in
a lot of non-programming fonts, colons are really tiny.

> The current syntax using a colon has been there... since PHP

> Markdown Extra's debuts (July 2005). There is obviously a lot of

> documents out there using it, so there's not way I'll just change it

> to something else.

Yes, I was pleased to realize that that one character was the only
thing that wasn't working for me in the PHP Markdown Extra syntax. I
started pondering the syntax thinking that a more radical change would
be necessary to make it appeal to me. But this is so simple and easy
to allow for backwards compatibility that I was really happy to have
it. Plus, it's dead easy to modify existing implementations to support
it, which both makes it an easier sell and makes it easier for me to
just do on my own.

> As for accepting the tilde as an alternate marker, there's obviously

> a precedent of that: unordered lists which can be made of `*`, `+`,

> or `-`, so it wouldn't be counter-nature to add one for definition

> lists. On the other hand, that precedent was meant to allow other

> syntaxes in common use to work with Markdown; I'm not sure any

> syntax we can come with for definition lists is already in common

> use. Definition lists are already some sort of specialized niche

> syntax within Markdown and HTML: useful when you need one, but not

> something a lot of people care for or even know it exists.

Even with the colon, the Markdown Extra syntax is so much better than
any other DL syntax I've seen. So I agree about the lack of precedent
in other markup syntaxes. But I didn't know that `*`, `+`, and `-`
were there for compatibility; as a user of Markdown, I just thought it
was for convenience that I could use either one. In fact, I actually
thought they were there so that I could use different bullets at
different levels of a nested list, which would be more natural than
using just one in plain text.

All that is just to say that I think there are two ways to look at the
precedent of list bullets, regardless of the history, and that
convenience and flexibility apply to the idea of the
interchangeability of `:` and `~` in definition lists.

> So in the end I'm pretty much ambivalent to this proposal: I like it

> but I don't think it's worth wasting another marker character and

> dealing with possible clashes (legitimate text with a tilde in it).

I think we determined that that was only an issue in single-line term/
definition combinations, which aren't implemented with `::` either,
AFAIK. When the `~` has to come at the beginning of the line, it's no
worse than the possible conflict of using `-` for an unordered list

> That said, perhaps I'll change my mind the next time I have to write

> a definition list.

This came up for me because I write a lot of documentation for
libraries I write, and many of the functions and methods support a
parameter list of arguments. This is a very natural fit for definition
lists, so I could potentially use them all the time, like so:


### `new()` ###

$fsa = FSA::Rules->new(
foo_state => { ... },
bar_state => { ... },

Constructs and returns a new FSA::Rules object. An optional
first argument is a hash reference that may contain one or
more of these keys:

~ Causes the `start()` method to be called on the machine
before returning it.

~ A value to which to set the `done` attribute.

~ A value to which to set the `strict` attribute.

~ The name of the class to use for state objects. Defaults
to "FSA::State". Use this parameter if you want to use a
subclass of FSA::State.


I've borrowed this from one of my Perl modules, where the docs are in
[POD][3], which I've come to hate, but I could definitely see using
something like this when writing documentation elsewhere. For example,
PostgreSQL 8.4 supports named parameters on functions, so I'd likely
use something like this a *lot* there.

[3] http://search.cpan.org/perldoc?perlpod

Anyway, if you start writing more definition lists and want to try it,
here's a patch for PHP Markdown Extra. :-)


--- markdown.php.orig 2009-02-19 09:42:43.000000000 -0800
+++ markdown.php 2009-02-19 09:42:45.000000000 -0800
@@ -2400,7 +2400,7 @@
[ ]{0,'.$less_than_tab.'}
((?>.*\S.*\n)+) # $3 = defined term
- [ ]{0,'.$less_than_tab.'}:[ ]+ # colon starting definition
+ [ ]{0,'.$less_than_tab.'}[:~][ ]+ # colon or tilde starting
( # $4


I'd add some tests, too, but I haven't found any. Think I'll do it for
MultiMarkdown, though.

Do you have a repository of some kind I could check out?



PS: Sorry to be so long-winded, and, once again, I appreciate your

More information about the Markdown-Discuss mailing list