A Modest Definition List Proposal

[David E. Wheeler]

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


> 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(
         \%params,
         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:

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

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

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

state_class
   ~ 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
  				\n?
-				[ ]{0,'.$less_than_tab.'}:[ ]+ # colon starting definition
+				[ ]{0,'.$less_than_tab.'}[:~][ ]+ # colon or tilde starting  
definition
  			  )
  			  (?s:.+?)
  			  (								# $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?

Thanks,

David

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