Use definition lists for glossary?

[timClicks]

Perhaps this is somewhat pedantic, but I wonder whether we should be move from an unordered list of terms to a definition list for the glossary?

This would be more semantically correct and would allow us to avoid manual hard breaks in our current source text, e.g.:

- allocate:\
  Dynamic memory allocation on [the heap](memory-management/review.md).
- argument:\
  Information that is passed into a function or method.
- associated type:\
  A type associated with a specific trait. Useful for defining the relationship
  between types.

Unfortunately, it looks as though current markdown processor does not support the extended syntax for dl, dt and dd tags.

That would mean that we would be required to hand-write HTML:

<dl>
  <dt>allocate</dt>
  <dd>Dynamic memory allocation on <a href="memory-management/review.html">the heap</a>.</dd>

  <dt>argument</dt>
  <dd>Information that is passed into a function or method.</dd>
  
  <dt>associated type</dt>
  <dd>A type associated with a specific trait. Useful for defining the relationship between types.</dd>

…which would unlock the ability to refer to the glossary from other parts of the course.

  <dt id="allocate">allocate</dt>
  <dd>Dynamic memory allocation on <a href="memory-management/review.html">the heap</a>.</dd>

[max-heller]

@mgeisler and I discussed this briefly in https://github.com/google/comprehensive-rust/pull/1572#issuecomment-1874754092:

Right, if we can include HTML, then things should be easier — however, I very much want to avoid HTML since it is hard to edit in the English version and it looks weird and complicated for the translators.

Newer versions of pulldown-cmark support parsing definition lists, but mdbook can't upgrade without making a breaking change so is stuck on v0.10 for v0.4.x.

We should be able to make this change whenever mdbook v0.5 comes out, it'd also help with styling in the generated PDFs.

[mgeisler]

Hey @timClicks and @max-heller,

Thanks for investigating this! I am all for better and more semantically correct markup here! I'm very much against HTML because it annoying to deal with for those who write it and even worse to deal with for people who translate the course (assuming it ends up in the .po files).

It's very important for me (and I think for the translators) that the glossary entries are separate entries in the .po files, like here.

The Markdown list is what ensures this. When there is support for definition lists, we'll be sure to expand mdbook-i18n-helpers to process them nicely too.