Description List

Extensions
21

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 … :wink: ).

Note that “definition lists” (I just can’t cope with the HTML5 renaming frenzy …) are not specific to HTML; similar elements exist

  • in DocBook as <variablelist>, or

  • in the NISO Journal Article Tag Set (JATS) as <def-list> (properly named “definition list” …),

  • also in the ISO Standards Tag Set (ISOSTS) as <def-list> too (since ISOSTS is an adaptation of NISO JATS), and

  • in ISO 12083:1994 there are similar <deflist>, <term>, <dd> elements (again described as a “definition list” …) with this content model:

    <!ELEMENT deflist - - ((head, ddhd)?, term, dd)>

  • and ISO/IEC TR 9573:1988, ISO/IEC TR 9573-11:1991 (<DL>, <DT>, <DD>), and ISO/IEC 9573-11:2004 (<tl>, <termdef>, <termdes>) are more examples.

So there is amply justification for having a dedicated and nice Markdown syntax for this kind of lists in my opinion.

22

Please note, that my suggestion is to allow either single-line term-definition-pairs or multiple terms and/or multiple definitions in new lines:

~ term 1
~ term 2
: definition of term 1 and 2
: another definition of term 1 and term 2
~ term 3 : single definition of term 3

The following might cause problems, so i’m not sure how to exactly treat them. I guess having more than one many-to-many pair in a line (as in term 8 & term 9) doesn’t contain much logic.

~ term 4 : definition of term 4
: another definition of term 4
~ term 5 ~ term 6 : definition of term 5 and 6
~ term 7 : definition of term 7 : another definition of term 7
~ term 8 : def 8 ~ term 9 : def 9
~ term 10 : definition 10
lazy continuation of definition 10
~ term 11 : definition 11
....
....another paragraph of definition 11 (dots are spaces)
~ term 12
: definition 12
....    
....another paragraph of definition 12 (dots are spaces)

What about empty terms and definitions? Skip them?

~ term 1 : {empty definition 1 on same line}
: definition 2
: {empt defintion on new line}

What about a definiton list starting with a definition? I suggest the following:

: not a definition, maybe needed for another syntax.

~ : definition for "empty term"

Have i missed anything :wink:

23

Please, after 2 years of discussion any of the widely discussed here is valid, just implement it please … normal people just want to have description list

When you search for an extension, official docs sends you here … what i must search here to get a working description list ?? I just found how people love to talk and talk around about a simple thing

You’re not sure? Implement 2 or 3 types and let the people use it and test it … but 2 years with no code and too much talking is all contraproducent, because as me there would be a lot of people just throwing the requirement and switching to a different one.

I want to follow specs, but this is a WAY slow spec dev … think about something more sofisticated than a simple description list … 10 years?

Thanks

1 Like
24

You can use markdown-it, which follows the CommonMark spec, along with it’s definition list plugin which uses the Markdown Extra syntax.

25

I don’t know whether you collect Spec suggestions for extensions yet, but i would suggest the following:

For simplicity i would suggest the following.

  • Define the description list items just like the other list items.
  • put a “special case” after the “basic case” that allows multiple items on the same line.
  • (Restricting the sequence of items to multiple “names” ~ name 1 ~ name 2 ~ name 3 ~ name 4 followed by only “values” : value 1 : value 2 : value 3 : value 4 would create more problems than it would solve: Would ~ name 1 : value 1 ~ name 2 : value 2 lead to value 1 literally containing the string value 1 ~ name 2?!)
  • Restrict the definition list to only begin with “names” → there might be another syntax that needs the colon as a marker. (There are already candidates.)

5.2 List items

A list marker is a [bullet list marker] or an [ordered list marker] or a [description list marker].

A [description list marker] is a ~ or : character. The ~ is the [description name marker] and the : is the [description value marker].

  1. Basic case: …
  2. *Special case for [description list items] on the same line:
    • A description list item may consist of multiple [description list items] that are on the same line.
    • Each description [description list item] is introduced with a [description list marker] surrounded by at least one space character.
    • *anything that follows modifies the last description list item. E.g. a paragraph that follows is appended to the last item.

5.3 Lists

Two list markers are of the same type if (a) they are bullet list markers using the same character (-, +, or *) or (b) they are ordered list numbers with the same delimiter (either . or )) or (c) they are description list markers with either character (~ or :).

A description list must begin with a [description name marker] (~). It cannot begin with a [description value marker] (:). // this frees the colon as a character for a different syntax!

26

I’d like to suggest an alternative syntax here which I think reads rather intuitively, although it’s probably not yet implemented anywhere.

? term, glossary entry, question
! description, definition, answer
1 Like
27

While this alludes nicely to the “question-answer-dichotomy”, I find the prefix use of question and exclamation marks—typographically—rather un-intuitive and resembling programming notations. Actually more intuitive (in this sense) would, for some folks, be

¿ term, glossary entry, question
¡ description, definition, answer

(Okay, just kidding!)

But in fact the main disadvantage is that this would just render as

? term, glossary entry, question ! description, definition, answer

in any Markdown implementation out there.

A slight variant of this idea would provide at least a readable fall-back rendering, exploiting the fact that we already have two different “unordered” list item markers:

* term:
* glossary entry:
* question:
-   description, definition, answer

And is not really less intuitive either in my opinion. (Using > instead of - for the <DD> element indication would produce even nicer results in the HTML default style, where <BLOCKQUOTE> is just rendered with narrower margins. Alas, this might go too far in mis-using existing syntax.)

Or you might find + / - more appealing:

+ term, glossary entry, question:
- description, definition, answer

[Edit:] In the apples-and-oranges discussion over there I came up with this syntax (using MIDDLE DOT · as a “visible SPACE” here):

term:··
glossary entry:··
question:··
····description, definition, answer

I think this looks best (in the typescript, without the distracting “·” characters), and still renders reasonably in unaware Markdown implementations. But it’s probably not for you if you hate the end-of-line SPACE rule of Markdown!

28

How about colon-equal := to start definitions?

This syntax speaks to programmers and to mathematicians.
Could be used either inline or starting a new line.

itemize := simplest kind of list (aka bulleted list)
enumerate := items are numbered in succession
description := think "glossary" or "dictionary"

But descriptions are “in the family” of lists, so perhaps their syntax should be similar as well. (Not sure whether this is a good idea, since numbered lists do not respect this convention.)
Either way, we could consider each new line in a description list starts with, say, a tilde ‘~’.

~ itemize := simplest kind of list (aka bulleted list)
~ enumerate := items are numbered in succession
~ description := think "glossary" or "dictionary"

A dash would also be possible.

- itemize := simplest kind of list (aka bulleted list)
- enumerate := items are numbered in succession
- description := think "glossary" or "dictionary"
3 Likes
29 
 - Term 1 := Description 1
 - Term 2 := Description 2

Best idea here!

I’d even suggest adding another option as well – if a list item ends with := then it is converted to <dt> and its sublist items are converted to <dd>.

 - Term 1 := 
   - Description 1
 - Term 2 := 
   - Description 2

This would allow a single term to have multiple descriptions…

 - Term 1 :=
   - Description 1a
   - Description 1b

…or multiple terms to share a single description.

 - Term 1a :=
 - Term 1b :=
   - Description 1

Terms and descriptions could also be paragraph-separated, similar to loose lists.

 - Term 1 := Description 1

 - Term 2 := Description 2

<dl>
<p>
<dt>Term 1</dt>
<dd>Description 1</dd>
</p>
<p>
<dt>Term 2</dt>
<dd>Description 2</dd>
</p>
</dl>

 - Term 1 :=

   - Description 1a

   - Description 1b

<dl>
<p>
<dt>Term 1</dt>
</p>
<p>
<dd>Description 1a</dd>
</p>
<p>
<dd>Description 1b</dd>
</p>
</dl>

And in non-extended Markdown, this syntax just falls back to regular lists and sublists.

30

I feel we are bikeshedding here. There’s already a widely used syntax for description lists, and CommonMark’s goal is to be a “strongly defined, highly compatible specification of Markdown”. Is the existing Markdown Extra syntax really such a problem that it must be replaced by a new syntax?

One other point of discussion is the question of whether it should be possible to nest description lists. Subdefinitions. This StackOverflow discussion suggests it’s valid to start a sub-description list inside a definition. Presumably, with the Markdown Extra syntax, similar indention rules can be used to CommonMark ordered and unordered lists for consistency.

2 Likes
31

Seems to me the primary motivation here for proposals that reinvent the wheel (bike wheel? I apologize for mixing metaphors…) is the need to simplify parsing.

When the parser reaches a line that starts with :, it must go back and include previous line(s) in the definition list. Backtracking 999 lines is not so convenient.

Hence, the idea of preceding a term with ~, ?, *, +, etc. This lets you know right away that a definition list starts at that point.

Alternatively, a colon might work as a preceding character, with indentation to distinguish definitions from terms:

: Term
: Another term
  : Description
  : Another description

Again, that would make parsing easier.

Although yes it is a different syntax and a breaking change… In existing definition list syntax, the above source produces nested definition lists and a literal colon before the first term. (Tested on https://markdown-it.github.io/)

32

Parsing CommonMark is already quite a complex endeavour because of the goal of preserving compatibility (see discussion in Beyond Markdown). It might be worth the added complexity and performance cost if enough documents already use the existing description list syntax.

1 Like
33

I think we’ve got somewhat more leeway to make changes to extensions, since they aren’t yet strictly specified.

That said, CommonMark wouldn’t be CommonMark if it didn’t have wide compatibility. :slight_smile:

So here’s a more compatible proposal:

Each description term ends with whitespace plus :, and each subsequent description begins with : plus whitespace.

Term : 
: Description

Term : 
Another term :
: Description
: Another description

This makes it immediately clear where the list starts, so Markdown parsers – and human eyes – don’t need to backtrack.

In MultiMarkdown / Kramdown / Markdown Extra this syntax creates a valid description list, though with an extra space and : following each description term.

Conversely, old documents with description lists could be converted to the new syntax by appending a space and : to each term.

34

I would like to revive this old topic by putting in the front an even older principle of markdown. The idea (as I understand it) was for markdown to be widely compatible with the variety of usages people had when typing in plain text, such as lists, emphasis, and so on. It would then infer the intent of the writer from there. And it would only marginally impose its own markup for things like links and such.

Therefore when discussing an extension such as the “correct” syntax for descriptions lists, I think we should think of how such things are actually typed down. It seems to me that the primary, immediate, way to type description lists would be like this:

word: my description
another key: a longer description
    perhaps spanning multiple lines.

maybe: one would separate its items with newlines.

At least that’s how I would write down such definition lists in a mail in plain text. I’m not sure I would try to assign the same description to multiple keys. Would I want to put multiple descriptions to the same key, I probably would write it like this:

my key:
  - a first description.
  - a second one,
    spanning multiple lines for good measure.

So that would be the kind of syntax I’d expect to be understood by a smarter markdown. In the mean time I think it degrades gracefully when it’s written like this today.

35

The problem is that the intention must be recognized by machine, not a human. And : is used quite often for other (also very common) purposes. So the parser would have to distinguish somehow:

word: my description

e.g. from

Johny said: "Hello to everybody." (where different or no quotes at all could be used)

or from:

The train arrives at 20:00.

or from

Fill here your name: .......................................

or from

Dear Sir:

at the beginning of a letter

and possibly from bazillion other use cases, some in different cultures and languages with different typographic rules.

Similarly, your 2nd example matches the syntax of an ordinary unordered list. And yes, it’s very common to use some preceding paragraph ended with a : to introduce it.

Buy list:
 - bread
 - milk
 - some fruit
1 Like
36

You are right. It is a machine that parses markdown.

Nevertheless, markdown is an attempt to interpret human typing in plain text without forcing unnatural conventions, or not much of it. That is why there are often many ways to achieve the same thing in markdown. That would normally be considered a bad thing, but in markdown it’s a consequence of this attempt to be non intrusive.

Therefore I think we should strive to respect this principle as much as possible when discussing extensions. Therefore we should start from what we human tend to type in plain text and go from there.

So in a way, it is also wrong to think markdown is for machines. It is for humans to communicate with each others, and for the machines to help us do so. We engineers often take it backward and up with XML.

37

Linking Caption - python extension in here which is using 'Table: ’ and 'Listing: ’ to identify captions. There is almost no chance of misinterpretation and it readily satisfies:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

38

It’s not satisfying the goal of language neutrality, though.

1 Like
39

@Crissov - I assume this is in response to my post above.

Thanks for your comment. Wouldn’t that be achieved by using a category description in the required language?

40

Well, that certainly wouldn’t be neutral. Hower there is something to be said for this strategy imho.

True, the markdown syntax can be considered neutral because there is no keyword in it. But it is certainly not neutral when you consider that there are many linguistic assumptions behind the usage of, say, emphasis, or long quotes. There are languages where it is not natural, even though these conventions may have been imported with time.

And if we assume that markdown strives to interpret “natural” conventions as much as possible, it sounds logical to start interpreting the language of writing. With the huge caveat that it is not practical to implement this for each possible languages… It sounds hard to maintain over time.

That said, I fail to understand how it would help us for description lists… In plain text I would simply input my keys and my values, separeted by some kind of markers.