Support for abbreviations and definitions in Pandoc's Markdown

barriteau commented 11 months ago

Maybe Pandoc's Markdown could be extended to support inline abbreviations and inline definitions, this to improve the already requested feature of built-in support for indices (https://github.com/jgm/pandoc/issues/6415). The glossaries package (https://ctan.org/pkg/glossaries) could provide what's needed for a consistent Latex/PDF implementation of this.

An inline_abbreviations extension would provide support to the following markup (suggested syntax are just vague ideas):

**[ ... ] for simple abbreviations, equivalent to <abbr> ... </abbr> in HTML.

**[ ... ][ ... ] for expanded abbreviations, equivalent to <abbr title=" ... "> ... </abbr> in HTML.

An inline_definitions extension would provide support to the following markup:

:[ ... ] for simple definitions, equivalent to <dfn> ... </dfn> in HTML. If possible, nested abbreviations would be allowed, something like: :[ ... **[ ... ][ ... ]]

Examples:

Inline abbreviation

Entries like: Hypertext Markup Language (**[HTML]) is a markup language used to...

Will become: Hypertext Markup Language (<abbr>HTML</abbr>) is a markup language used to...

Inline abbreviation with expansion

Entries like: Hypertext Markup Language (**[HTML][Hypertext Markup Language]) is a markup language used to...

Will become: Hypertext Markup Language (<abbr title="Hypertext Markup Language">HTML</abbr>) is a markup language used to...

Inline definition

Entries like: :[Hypertext Markup Language] (HTML) is a markup language used to...

Will become: <dfn>Hypertext Markup Language</dfn> (HTML) is a markup language used to...

Inline definition and inline abbreviation in tandem

Entries like: :[Hypertext Markup Language (**[HTML])] is a markup language used to...

Will become: <dfn>Hypertext Markup Language (<abbr>HTML</abbr>)</dfn> is a markup language used to...

Inline definition and inline abbreviation with expansion, in tandem

Entries like: :[Hypertext Markup Language (**[HTML][Hypertext Markup Language])] is a markup language used to...

Will become: <dfn>Hypertext Markup Language (<abbr title="Hypertext Markup Language">HTML</abbr>)</dfn> is a markup language used to...

Reference

HTML definitions tag: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn

HTML abbreviation tag: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr

HTML definitions list tags (already supported in Pandoc's Markdown): https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt

anasram commented 11 months ago

Starting from this valid syntax in pandoc's markdown:

in markdown:

Also, [HTML](https://html.spec.whatwg.org/ "Hypertext Markup Language") is a markup language used to...

in HTML:

Also, <a href="https://html.spec.whatwg.org/" title="Hypertext Markup Language">HTML</a> is a markup language used to...

the result:

Also, HTML is a markup language used to...

An abbreviation with a title could be supported like this:

Also, [HTML]("Hypertext Markup Language") is a markup language used to...

Also, <abbr title="Hypertext Markup Language">HTML</abbr> is a markup language used to...

Simply, just a titled markdown link without a link!

I don't think it's worth it to mark an abbreviation tern as an abbreviation without a title.

barriteau commented 11 months ago

@anasram, that for sure would be a lot simpler and intuitive syntax :)

Same as you, I used to think it was pointless not using a title attribute in the abbr tag, but the standard has a clever and fair point about that:

Only include a title if expanding the abbreviation or acronym in the text is not possible. Having a difference between the announced word or phrase and what is displayed on the screen, especially if it's technical jargon the reader may not be familiar with, can be jarring.

(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr#accessibility_concerns)

It seems the tag is primarily intended to point "this is an abbreviation" and expanding to the meaning of it is optional.

Maybe just omitting the abbr tag is a solution when no title attribute is going to be used, but at least for the indices creation a not expanded abbr could be of use.

anasram commented 10 months ago

Will, in this case, it could be simply [HTML]() or [HTML]("").

jgm / pandoc