Definition Lists

[theory]

One of the main things I use Markdown for is writing documentation. And one thing I do over and over again is document parameters to functions and methods. Definition lists are perfect for this. I end up using MultiMarkdown to get them. Alas, I've been unable to find any support for definition lists in any of GitHub's Markdown flavors.

Would really appreciate definition list support to your upskirt fork. The PHP Markdown Extra definition list syntax is okay, though it's not great for reading as plain text. (I wrote a proposal for a slight variation here. But really, any definition list support would be great.

Thanks!

[vmg]

Hey David, thanks for the suggestion!

We've received a few tweets and comments regarding definition lists... You see, the main thing stopping us from implementing them in Upskirt is that the most "adopted" syntax (the one from PHP-Markdown) is, as you say, not great.

Apart from readability issues (which I think are not that significant), the whole Definition List syntax has been designed to be parsed with (slow) Regex-based Markdown implementations. For an incremental parser like Upskirt, the support for multiple terms sharing a definition and the colon after newline that creates the definition list implies a ridiculous amount of lookahead when parsing any given text block. It's tricky to implement this without suffering a performance hit.

I'll be looking into this with more detail, because it looks like there's actual interest on these definition lists. I'll keep you up to date on what I find -- hopefully I can come up with something that's both fast and clean in the code base.

Thanks again for your interest!

[theory]

Hrm. Well if the definition term was required to end with : and the definitions were required to begin with : or ~ or something, then I think you wouldn't have to look ahead so for, right?

[vmg]

Indeed, indeed, that would make things easier. However, GitHub is about social coding, and social coding means making cooperation easier between developers; standards, although sometimes a nuisance, make this happen, so if we want Definition List support in Upskirt, it needs to follow the same syntax that everybody else is using.

Oh well, nobody said this was going to be easy, but I'll try my best to make it happen. :)

[theory]

I think you might be able to get away with requiring the : at the end of a term. It's worth bringing up. There was some discussion here, if it helps any.

[consiliens]

I'm also interested in definition list support, even if it doesn't follow the standard syntax.

[msteveb]

I'll add my +1 for this feature. kramdown syntax seems to work ok.

[trans]

Double colon?

term:: definition

I thought this is what RDoc used for DL's but that actually creates a TABLE. Which is actually nice in that it keeps the term and definition aligned rather than the definition appearing under the term. But maybe CSS can be used to do the same thing to a DL?

[theory]

I don't care for a double-colon because it's not very natural to prose. I think the cleanest thing to do is to have dts indicated by a : and dds by an alternate bullet character. Something like:

apples:
~ delicious fruit

Or

oranges:
o ripe in winter

My challenge was always to come up with a decent ASCII character for the dd bullet, and I've thought for some time that the tilde was the least obnoxious of the options, though some fonts show it small and high, making it hard to see.

[trans]

Hmm... yea, I suppose if we are being technical about dl dt dd then dt and dd need to be "listable".

Kramdown does:

term
: definition
: another definition

another term
and another term
: and a definition for the term

That's fine by me. I actually am looking for something else for my needs. I want a 1:1 table kind of list. So maybe :: can work like RDoc after all.

[theory]

Yes, that's actually the PHP Markdown extra syntax. It's also used by MultiMarkdown. I personally don't care for the : as a bullet, and would also like to have a character to indicate a dt (colon is perfect for that), but barring a ruling from @gruber, that ship has likely sailed.

[bdarcus]

FWIW, pandoc (which is always well thought out) has DL support:

http://johnmacfarlane.net/pandoc/README.html#definition-lists

[theory]

@bdarcus That looks like the PHP Markdown Extra/Multimarkdown format.

[bdarcus]

@theory - yes, mostly; it does say it's "inspired by" PHP Markdown. I'm not sure where it differs.

[mytharcher]

Just +1 for this. I really need this feature in writing any markdown based document. Hope you can implement it soon!

[dupuy]

The Pandoc syntax for definition lists is indeed the Markdown Extra syntax, but with a small variation: ~ (tilde) is allowed as an alternate bullet character for definitions, as well as the original : (colon). This would allow for something more or less like the syntax suggested by @theory in https://github.com/tanoku/sundown/issues/10#issuecomment-1493581 (the colon after the term would not be required, but there is nothing preventing you from putting one there if you want to).