Description lists are already implemented by many processors. It would be nice to see them featured in standard markdown.
Python-Markdown, Kramdown, Maruku, php-markdown/extra and pandoc all use the following syntax
topic
: description 1
: description 2
Kramdown allows multiple topics
topic 1
topic 2
: description
> with nested markup
Pandoc raises an interesting point about lazy wrappings:
To see why laziness is incompatible with relaxing the requirement of a blank line between items, consider the following example:
bar
: definition
foo
: definition
Is this a single list item with two definitions of “bar,” the first of which is lazily wrapped, or two list items? To remove the ambiguity we must either disallow lazy wrapping or require a blank line between list items.
The nice thing about this syntax for definition lists is that processors that do not understand it natively will produce a single paragraph with a colon in the middle:
Just wanted to point out that parsing multiple topics is not easy without backtracking. Consider this example:
term1
term2
...
term999
: definition
In the above case a parser needs to consume 999 lines to detect a definition list. While in this case:
term1
term2
...
term999
next paragraph
the parser consumed 999 lines and detected that there is no definition list and it needs to backtrack and reparse the whole block element as something else (possibly a plain text paragraph).
AFAIK Pandoc also requires that a definition line is indented four spaces. Such as:
term1
:···definition
because otherwise it is all too easy to make an unintended definition list.
The definition line must start with a colon. For reference, here is the definition list documentation for Markdown Extra. This syntax is also used in Pandoc, Kramdown, and other implementations. Having the colon on the same line would cause issues as many sentences use literal colons.
I found myself often typing single line description like this (when I want to remind myself that “this sentence defines the latter”):
Dog :~ An animal with two legs
Personally I think this apply to this as maybe we can do a description list like
Animals
:~ Cat rocks
:~ Dog bark
:~ Bird race
Dog :~ An animal with two legs
Cat :~ Master specie
Empty :~
Not Empty :~ it has something
Benefit of :~ over : is that it is very distinctive, and carries an explicit visual directionality.
Hmmm… i wonder if there is a way to reference or link to the description. Imagine being able to hyperlink to a definition. It will be very useful for formula list etc… or symbol definition
In this discussion we should be clear about the goal: to provide a syntax for describing HTML definition lists in Markdown. The Markdown Extra syntax does that well; indeed if you look the way browsers render definition lists by default they line up with Markdown syntax surprisingly well:
Dog
An animal with two legs
Notice how the definition description is indented like in the Markdown Extra syntax?
Dog
: An animal with two legs
In writing it’s also common to see data terms and descriptions on the same line, separated by a colon. This is makes borrowing the colon as a marker appropriate for the Markdown syntax. Whether definition lists should be described on a single line in Markdown questionable though (even if CSS is used to render it that way). Although some writers expect to write definition lists this way, there might be a selection bias. If you asked another group of writers they might prefer putting the description indented on the next line. It’s the line break issue all over again.
The use of the ~ character does not look like either approach to formatting definition lists though, so it’s hard to see a clear reason to change from the well established Markdown Extra syntax.
The idea of creating a hyperlink to the definition is interesting. If the description is close to the term, what is the advantage? If it is not close by, perhaps using footnotes is the way to go? Or figures. In either case it is beyond the scope of the standard description list syntax.
is that it is too bloated for single definitions. If I am doing quick list of words and definitions, I want each term to take only a single line. Preferrably I wanted
Perhaps a compromise could be made, in that we support both forms below. Thus allowing the first form that takes more lines but is more flexible, but at the same time support a more compact notation.
Dog
: An animal with two legs
dog :~ 4 legged friend
cat :~ feline daemon
bird :~ hungry flying fellow
(I think the context for me. Is that I tend to have a “symbol” list or a legends of mathematical symbols, thus the current form you are proposing will double my list by 2x . Thus bloating my list too much. So i guess in terms of audience, the people this matter most to is not typical writers, but to academics.)
Tooltip definition hyperlink
In terms of hyperlink. I would preferred if the behaviour was more of a tooltip. E.g. you hover over, and get the summary definition, but when you click, you jump to the full definition. How is it implemented. (e.g. hovering over word hydrogen gets a brief description of what hydrogen is, but clicking it jumps you to definition list) Well I haven’t thought that far ahead.
Spreading out text is in line with the philosophy of Markdown, for example using line breaks instead of wrapping text is encouraged. I can see a potential issue on small screens, for example if you’re comparing lots of key/value pairs on a mobile phone screen. I don’t think :~ is the right marker to use here, maybe -> instead:
Dog -> An animal with two legs
I’m not entirely convinced of the need though. Presumably you would want to reuse the marker for multiple definition lists. That creates an inconsistency if : is used as a marker (as well) as it cannot be used on the same line, potentially causing confusion for writers. It might be better to stick with a single marker, but if a marker other than : is chosen we’re going to break a lot of existing implementations. I think the Markdown Extra syntax is quite widely used (I’ll look into compiling a list), so changing the syntax may an uphill battle.
This sounds like a job for CSS/JavaScript. HTML (and thus Markdown)'s role is describing the content, rather than specific presentation or behaviour. Maybe some post processing would be needed to add anchor tags to the rendered HTML, but there shouldn’t be a need to change the Markdown syntax if there is a general pattern.
but -> is fine for me as well. Basically I don’t mind any options, as long as there is also a ‘compact’ option for single key:value description list entry,
The <DL> are calle “description lists” in HTML5 instead of “definition lists”. The scope of them also changes a little. I don’t see them as only suitable for glossary or an alphabetically sorted technical terms list anymore.
That means that I see the “term” as being more like a list symbol, just like “1.”, “a)”, “i.” or bullets and dashes.
I would suggest the following as an alternative for the description list syntax:
~ term1 : definition 1
~ term2
: definition 2
As an example i would like to show you a medical menemonic for coma reasons. The initial letters of the word “smashed” hint to the conditions that can be the reason for the coma. But obviously this list is not a “definition list” in the sense that the “term” (letters) are “defined” by the “definition”.
~ S : stroke
~ M : meningitis
~ A : alcohol
~ S : seizures
~ H : hypoglycaemia
~ E : epilepsy
~ D : drugs
The tilde is indeed similar to the dash in visually representing a
new list item, but there would be no ambiguity about whether you want an
unordered list item or a description list item.
The tilde would also remove the need for a look-back when parsing an detecting a defintion list.
The combination would probably make the whole thing quite distinct. The possibility of an unintended definition lists is nearly wiped out that way.
When using the tilde the ambiguity of lazy wrapping is eliminated.
Both the tilde and the colon could still be easily used for other
purposes, because they would only be a description list in combination.
To get a empty description use ~ term : to get an empty term use ~ : description.
I like this better than the PHP Markdown Extra syntax. Not only does it solve the look-ahead problem, but I always found placing the colon at the beginning of a line awkward (a notation that only Forth programmers can love … ).
Note that “definition lists” (I just can’t cope with the HTML5 renaming frenzy …) are not specific to HTML; similar elements exist