Description List

How can I help this feature request move forward?

I remember reading somewhere that the CommonMark specification is frozen in the sense that no new features will be added, but I cannot find any official announcement or discussion. Frozen or not, there are three people listed as making decisions as of now — John, Martin and Jeff. This is not a big committee. Thee people can agree on a feature.

why are description lists needed

the feature is orthogonal to existing features

Description lists are the way to denote finite maps from strings to strings. What is life if you cannot denote a finite map?

I can think of other ways to denote such finite maps, but they are contrived. For example, say we have a finite set {dog; cat; rat; mouse} of labels. We can define a canonical enumeration of this set — a one to one function onto the first few natural numbers:

  1. dog
  2. cat
  3. rat
  4. mouse

Now we can write a finite map from these canonical numerical identifiers.

  1. likes to run about
  2. likes to sleep
  3. likes to scamper
  4. likes to scamper

The latter can be composed after the inverse of the former in the evident way to get the desired map from {dog; cat; rat; mouse} to favourite behaviour. For example, rat is 2 and 2 is likes to scamper. But I await the reader will agree that this is absurd. So are all other alternative representations I can think of.

the feature is not going to be supported at large until it is supported in the CommonMark standard

You wanted to be a standard — you succeeded, congratulations. Now people will hide behind your authority when you ask features of them. See example.

why the current de facto standard is just fine

  • There is historical precedent. I believe Merriam Webster dictionaries were using colons to introduce bodies of definitions since time immemorial. Here is how it looks on their web site:

    Though I admit the Merriam Webster syntax is way more complicated and will not line up with markdown exactly, this is still in principle a precedent, and it is widely accepted.

  • It has been battle tested for years in Pandoc and other implementations — everything works. One can even denote nested description lists by indenting with 4 spaces or a tab character.

  • The complexity of backtracking is not an insurmountable problem. Practically, no one is going to be defining a million topics to one definition — this is not a use case of Markdown. A security conscious parser will simply limit the number of topics allowed — for example, if it sees 100 lines in a row it can assume no definition will be forthcoming. This is what, for example, HTTP clients and servers already do — if you try to give an infinite stream of data to a security conscious HTTP program it will cut you off at some point. At the time of writing, Pandoc limits the number of topics allowed to 1.

Yes, there may be better syntax eventually. But there is good enough syntax now.

what I should like to happen

I hope someone who makes decisions in CommonMark will actually see this message and give it a moment’s thought.

  • If this will never be a part of CommonMark then say it, let people know that there is no hope.
  • If something needs to be done — writing, testing — tell us. Maybe I can help, maybe someone else will be interested. There are a lot of people that want this to happen.

It’s at the top of this page unless you dismissed it. If you did, clear cookies for this website or reopen in a private browsing window.

They rarely visit this website these days. It’s been over ten years. Also, it is @jgm that has always owned the final decisions. If you want to be heard you are better off submitting an issue against the spec on GitHub.

John is more focused on Djot these days. It supports definition lists:

It is also much fuller-featured than commonmark, with support for definition lists, footnotes, tables, several new kinds of inline formatting (insert, delete, highlight, superscript, subscript), math, smart punctuation, attributes that can be applied to any element, and generic containers for block-level, inline-level, and raw content. The project began as an attempt to implement some of the ideas I suggested in Beyond Markdown.

There are countless requests for features. Everyone believes theirs is a must-have.

This is categorically not true. GFM is the prime example. They are adding features left and right. Pandoc is a better example, as it does it without being hegemonic like Microsoft/GitHub. It supports many flavors of Markdown, including CommonMark supersets. I’m pretty sure you can configure it to do CommonMark+definition lists.

I don’t think it is fair or kind to say the folks in your linked example are “hiding” behind anything. Every project has priorities and resource constraints.

But if they are “hiding”, it’s not on CommonMark. It’s on them. As the latest comment on that thread says,

I get that supporting CommonMark is important, but that doesn’t mean you can’t support any other features on top of it.

Finally, Obsidian isn’t open source, nor is it parser-pluggable at the moment. CommonMark’s reference implementations and Pandoc are open source, and there are CommonMark implementations that are extensible and already have definition list support. With closed source tools, you are always at the mercy of its owners.

The banner at the top of this page does say it. You can get it to show again as I explained.

1 Like

Thank you, Vas.

whether there is an official announcement

I do recall seeing a blue bubble with the word «frozen» in it at the top of the page. But this may just be a bug of some sort, or it may be obsolete, or it may be in error. What I was looking for is a page that anyone can see at any time, that can be linked to, that is signed by specific people and has a date on it. I reckon neither of us is aware of any such.

how to get in touch with the curators of the specification

Ah, this is good to know. Actually I pinged them by electronic mail. But maybe I should also open an issue as you suggest. I think it is best to wait for a week or so before doing anything else.

other considerations

You have made a lot of statements, some of them very deep and general, but you have not said straight what you want. I have brought specific evidence, and I have interpreted this evidence in a specific way, all to support the case that it is important to put description lists into CommonMark. It seems you want to say that my interpretation is wrong. Say it straight then!

The conversation I linked proceeds like so:

users We want description lists!
developers We are following CommonMark. Description lists are not in CommonMark. Therefore, no description lists.

If CommonMark had description lists, this conversation could not happen.

I am not ready to accept the philosophical framework you seem to be imposing, but I think it would be better for everyone else if we talk about it privately. You are welcome to send me a private message.

I suggest we find out if the authors of GitHub Flavored Markdown, a superset of CommonMark, would be interested in adding description lists as an extension. They have already adopted some other common extensions to Markdown such as tables. It seems more likely that GFM would add description lists than CommonMark, with others then adopting what is defined in GFM.