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

From: "Martin Thomson" <[email-masked]>
Date: Fri, 29 Oct 2021 12:58:03 +1100

Hey folks,

With Carsten's help I've added a new feature to kramdown-rfc2629 that supports auto-linking of key concepts.

If you have a special term, it is already possible to (ab)use kramdown's "abbreviations" syntax to have that term indexed.  For example:

```
*[IMPORTANT CONCEPT]:
```

This turns all uses of the string "IMPORTANT CONCEPT" in the text to be marked with an <iref> element.  The result is that all instances of the concept are put into your index for easy reference.

The feature that I've added also turns those uses into links like so:

```
*[KEYWORD]: #
```

All instances of KEYWORD then become:

```
<xref target="KEYWORD" format="none">KEYWORD</xref><iref item="KEYWORD"/>
```

If you have an anchor in the document, all instances of "KEYWORD" will now be linked to that anchor.  This uses the format="none" decoration on links so that hyperlinks will be added to HTML, but you won't pollute your document with " (Section 4.7)" throughout.

You can control the target of the link by targeting an anchor as follows:

```
*[KEYWORD]: #sec-keyword
```

Note that the keyword will still be indexed, but you can control that indexing using the existing syntax for abbreviations and indexing.
```
<!-- "CONCEPT A" is indexed as item="idea" subitem="alpha" -->
*[CONCEPT A]: #concept-a (((idea,alpha)))
<!-- "IMPORTANT" is indexed as item="important" subitem="note" -->
*[IMPORTANT]: #sec-important note
```

These "abbreviation" instructions can be added to a new line anywhere in the body of a document, so you can put them next to their definition or at the end as you see fit.

---

From: Michael Richardson <[email-masked]>
Date: Fri, 29 Oct 2021 09:27:00 -0400

> If you have a special term, it is already possible to (ab)use
    > kramdown's "abbreviations" syntax to have that term indexed.  For
    > example:

It's cool.

I'm not sure when I'll need:

    > This turns all uses of the string "IMPORTANT CONCEPT" in the text to be
    > marked with an <iref> element.  The result is that all instances of the
    > concept are put into your index for easy reference.

this to happen, except maybe for "MUST".

Are there some other good examples in documents where this is useful and *appropriate*?

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 30 Oct 2021 17:01:22 +1100

IIRC this should enable things like:
  https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#rfc.index

> On 30 Oct 2021, at 12:27 am, Michael Richardson <[email-masked]> wrote:
> 
> 
> _______________________________________________
> Rfc-markdown mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/rfc-markdown

--
Mark Nottingham   https://www.mnot.net/

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 30 Oct 2021 09:25:43 +0200

> 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

---

From: Michael Richardson <[email-masked]>
Date: Sun, 31 Oct 2021 14:27:56 -0400

> (There is also the {::boilerplate bcp14-tagged} hack that uses the

Oh, is that what -tagged does :-)

    > 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.

I do like it.  Particularly for drafts that use a lot of terms in a specific
way.   draft-ietf-rats-architecture might benefit from it.

    > 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.

okay.

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        |    IoT architect   [
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [