Howdy, 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 itemSee 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? Best, David
On Wed, Feb 18, 2009 at 1:44 PM, David E. Wheeler <david at kineticode.com> wrote: [snip]> > 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: >[snip]> Comments? Has this ship already sailed?You make a convincing argument. And I must admit your proposal is very nice to look at/read/write. But if it ain't broke, don't fix it. The current implementation was set before I came along some few years ago, and I have never searched through the archives to see how it came about or why. But, people have been using it for this long without issue and there are already numerous existing documents out there that use it, so I see no reason to change it. In fact that last point (numerous existing documents) seems to be the de-facto response to any suggested changes on this list - and understandably so. No doubt that's why you suggested leaving the existing syntax in place, but then we would have two ways to define deflists. What happens when an author mixes the two? Ack! Yeah, this ship has sailed IMO. -- ---- \X/ /-\ `/ |_ /-\ |\| Waylan Limberg
On Feb 18, 2009, at 10:44 AM, David E. Wheeler wrote:> 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?Aristotle was kind enough to point me to some older posts on the subject of definition lists, where I saw this message from Mssr. Gruber: On Jul 27, 2005, at 7:33 AM, John Gruber wrote:> And since the ones with multiple terms and/or definitions are the > exception, not the norm, I think in the common cases, you'd wind up > with something that looks like this: > > Term 1:: Definition a blah blah blah blah blah > Term 2:: Definition b foo bar baz > Term 3:: Definition c even more blah blah blahWas this ever implemented? I haven't noticed it in the documentation for PHP Markdown Extra or MultiMarkdown. I think that, using the tilde as I've suggested in this thread, this can be even better: Term 1 ~ Definition a blah blah blah blah blah Term 2 ~ Definition b foo bar baz Term 3 ~ Definition c even more blah blah blah Basically, it's the same rule, only you don't have to have a newline before the definition starts. Also, the single ~ is a little less ?unnatural? looking than the double : (and I say that as a Perl hacker, so I'm used to ?::?!). Best, David
Yeah, Markdown users in the hard sciences would trigger that constantly. best, Joe On 2/18/09, Yuri Takhteyev <qaramazov at gmail.com> wrote:>> Right. I actually think that using ~ as a range operator (essentially) is >> fairly rare outside of electronic circles, at least in US English. > > In other words, by at least 5% of the world population. :) > > But even just looking at the US English, ~ is often used for > approximation, for the home directory, for equivalence, etc. So, > things like "The cost is ~ $3", "cd to ~ before doing this", "The N > needs a ~ over it", "If we assume x ~ y, then" will all suddenly > become definition lists? > >> Term 1 o Definition a blah blah blah blah blah >> Term 2 o Definition b foo bar baz >> Term 3 o Definition c even more blah blah blah > > ?. O unico problema ? o "o" do Portugues, que ? um artigo nessa linguagem. > > (Our friend "o" is a _word_ in some languages.) > > - yuri > > -- > http://spu.tnik.org/ > _______________________________________________ > Markdown-Discuss mailing list > Markdown-Discuss at six.pairlist.net > http://six.pairlist.net/mailman/listinfo/markdown-discuss >-- Joseph Lorenzo Hall ACCURATE Postdoctoral Research Associate UC Berkeley School of Information Princeton Center for Information Technology Policy http://josephhall.org/
On 18 Feb 2009, at 1:44 PM, David E. Wheeler wrote:> 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 > ).Unlike most syntax suggestions, your suggestion to use tilde as the marker for definitions strikes me as genuinely Markdown-ish. I'm not sure it's any better than colon, though. -J.G.