HTML terminology: Description List vs Definition Lists

[jaredmorgs]

I was showing a developer colleague the easy-to-use https://asciidoctor.org/docs/user-manual/#description-list feature as a simple replacement for short tabular data.

He quipped:

definition lists are a pretty standard thing - I’ve used them in HTML before as well as in asciidoc (edited)

Ah I see they call them something different. righto

It got me thinking that we may need to add some additional words into this section to help folks find the Definition lists https://www.w3.org/MarkUp/html3/deflists.html as well as Description lists (which also seems to be valid).

The short name for these cited in the introductory para is apparently referred to as dl and not dlist according to the linked page.

[mojavelinux]

The HTML committee deprecated the term "definition lists" several years ago because it was overly specific. The correct term is "description lists", which is why we use that term in the Asciidoctor documentation. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl

[mojavelinux]

I'm open to having a statement like "You may know them as definition lists. The preferred term is now description lists, which matches the terminology used by the HTML specification."

[mojavelinux]

It's interesting to note that DITA still uses the term definition list (though that spec is over a decade old now...the world has moved on). https://docs.oasis-open.org/dita/v1.2/os/spec/langref/dl.html

[mojavelinux]

https://www.w3.org/MarkUp/html3/deflists.html

this is a link to HTML 3 :eyes: that should tell you something ;)

[mojavelinux]

I have updated the documentation to acknowledge that this list variation was once known as a "definition list". See https://docs.asciidoctor.org/asciidoc/latest/lists/description/