Re: [Rfc-markdown] new kramdown-rfc2629 feature in 1.5.13

[Carsten Bormann <[e-mail]>]

On 29. Oct 2021, at 15:27, Michael Richardson <[e-mail]> wrote:
> 
> Are there some other good examples in documents where this is useful and *appropriate*?

The original functionality, as provided by the upstream kramdown project, is to spot abbreviations in the source and to add titles (tooltips) that expand the abbreviation in every instance.

When I misappropriated that feature for kramdown-rfc, I used it for automatic indexing of terms.
Of course, you still want to add index entries manually as well.

(There is also the {::boilerplate bcp14-tagged} hack that uses the abbrev mechanism.)

Martin’s contribution is that, besides an index, you can now also use the abbrev feature to provide automatic glossary links.
Whether a glossary makes sense in a draft depends a lot on how many terms the reader has to juggle in their minds.
Instead of a glossary, you can also simply point back to the sections (or the ABNF/CDDL) defining the term.

BTW, in 1.5.15, I have introduced the pseudo attribute “noabbrev” that you can set to true to suppress abbrev processing for a paragraph or a span.
There is also an ALD “noabbrev” so you can leave out the »=“true”«:

Setup:

  *[florb]: #
  *[florbs]: #florb

Definition:

  A *florb*{:noabbrev} is the length of three corns of barley.
  {: #florb}

Application:

  Shoe sizes are measured in thirds of a florb.

(RFCXMLv3 does not seem to have neutral spans, so you can put the pseudo attribute on a paragraph or an em/strong span, but not create a plain one.  Duuh.
Also, you can provide an anchor for a paragraph, but not a span, hence the second IAL in the definition — could put the noabbrev there as well in this case, but in general definitions tend reference other definitions.)

Yes, this is a bit tedious to set up, but it then makes sure you have these glossary/definition links wherever you need them.
Also, keeps the application site clean (no [florb](#florb) xrefs all over the place.)

Grüße, Carsten