Subject: [Rfc-markdown] rfc-editor/to-be-removed

From: Michael Richardson <[email-masked]>
Date: Wed, 27 Oct 2021 17:58:12 -0400

I recently learn of the
   --- to_be_removed_note_Discussion_Venues

addition. (I usually learn of new stuff because I see Carsten use stuff.)

I don't see it at: https://github.com/cabo/kramdown-rfc2629/wiki/Syntax but
maybe it's hiding in some abuse of another mechanism.

I'm working on a document with a bunch of internal comments, to be removed by
RFC-editor, but useful for the WG to know about.

I thought I could use the above mechanism inside of "middle", but that
doesn't work.

Is there something I should use?  I know that we once had a discussion about
how to do comments, and I think we concluded that <!-- was the only real way,
that is, just let kramdown copy it into xml and let xml2rfc see it as a
comment.

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

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 28 Oct 2021 01:50:09 +0200

> maybe it's hiding in some abuse of another mechanism.

Thanks for reminding me to update the documentation…
(The “feature" is actually documented in:
Archived-At: <https://mailarchive.ietf.org/arch/msg/rfc-markdown/tFjsOz3cFfDxTyNXfFCaXsqfu2c>
But maybe people aren’t used to using the mail archive to unearth documentation...)

The special (and exceptionally ugly) syntax here is needed because notes are, like the abstract, a structural component outside the normal flow of markdown in middle/back.

(BTW: I plan to add some YAML structure that can be used to trigger generation of “Discussion Venue” notes.
A collection of specimens beyond Martin's .note.xml would help me getting this right.)

> RFC-editor, but useful for the WG to know about.

This then would go into the normal flow of middle/back.

> I thought I could use the above mechanism inside of "middle", but that

(See above.)

> Is there something I should use?  

RFCXMLv3 has an attribute called removeInRFC.
Apart from <note, this can be used in <section.

So you can write

> {:removeinrfc}
> ## Tempus fugit
> Goes away.

(The IAL is a short form of {: removeinrfc=“true”}, supported by the ALD
{:removeinrfc: removeinrfc="true”}
that is always included by kramdown-rfc.  
removeInRFC can be written removeinrfc because kramdown-rfc has a studlifier for known v3 studlycaps attribute names.)

> I know that we once had a discussion about

<!-- are comments only visible in the XML.  
If you want to render them, there are also <cref elements, which are supported using markdown’s (somewhat unwieldy) footnote syntax.

> Goes away.[^cabo1]
> 
> [^cabo1]: Carsten says that this goes away.

TXT rendering:
   Goes away.
   // Carsten says that this goes away.

<cref elements have attributes, which you can set using IALs.
       attribute source { text }?,
       [ a:defaultValue = "true" ]
       attribute display { "true" | "false" }?,

> Goes away.[^cabo1]
> 
> [^cabo1]: Carsten says that this goes away.
> {: source=“Michael"}

➔ TXT
   Goes away.
   // Carsten says that this goes away.
   //
   // — Michael

(The HTML rendering of source= is a bit broken, unfortunately, which I haven’t reported yet.)

Note that <cref elements don’t have a removeinrfc attribute, maybe because that is implied (!?).

Grüße, Carsten

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 28 Oct 2021 10:53:46 +1100

> On 28 Oct 2021, at 10:50 am, Carsten Bormann <[email-masked]> wrote:
> 

That would be excellent. A few:
  https://httpwg.org/http-extensions/draft-ietf-httpbis-cache-header.html
  https://mnot.github.io/I-D/binary-structured-headers/

FWIW, we already use 'github-issue-label' to drive the 'issues' links here:
  https://httpwg.org/http-extensions/

Cheers,

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

---

From: Michael Richardson <[email-masked]>
Date: Wed, 27 Oct 2021 21:04:08 -0400

>> Goes away.

How long does it extend?
Until the next ##? Or?
Would ### things be included?

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 28 Oct 2021 08:16:24 +0200

> Would ### things be included?

I think you are asking two questions here, only the first of which really is about markdown.

(1) How does kramdown-rfc create XML sections out of the markdown headings?

This does indeed work exactly as one would think, so if an h3 heading (###) follows a sequence of zero or more paragraphs that follow an h2 heading (##), an h3 section is created that is nested into the h2 section encompassing it.  The h2 section extends to the next h2 (##) or h1 (#) heading or the end of the “middle” or “back” division.

(2) How does the removeInRfc attribute of RFCXMLv3 operate on nested sections?

There is no answer to this in the RFCXMLv3 documentation [1], and it is a bit weird because the default value of removeInRfc is false, so an h3 section without further markup that is nested in an h2 section marked removeInRfc=“true” will seemingly contradict the outer h2 section.  The rendering is no help in interpreting this, as it just includes a paragraph at the start of any section marked removeInRfc=“true”.  AFAIU, the actual removal will happen manually during RPC processing, so we are speculating about how they will interpret the seemingly contradictory instruction.

But it is hard to remove a section without removing its subsections, and logically the h2 section to be removed does include its h3 sections, so I would expect the RPC to remove the entire h2 section, including its contradicting subsections.

Grüße, Carsten

[1]: https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#section-2.50.3

---

From: Julian Reschke <[email-masked]>
Date: Thu, 28 Oct 2021 09:08:26 +0200

Am 28.10.2021 um 08:16 schrieb Carsten Bormann:
> ...

Yes, the grammar should have defined a value of "inherit", and that
should be the default.

I *practice*, everyhing below a section labelled "to be removed" will
indeed be removed.

FWIW, the is part of the "RFC production mode" of the preptool
(<https://greenbytes.de/tech/webdav/rfc7998.html#rfc.section.5.6.1>).

> ...

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 28 Oct 2021 09:11:44 +0200

> (<https://greenbytes.de/tech/webdav/rfc7998.html#rfc.section.5.6.1>).

Ah, nice, 5.6.2 also answers my question about cref.

Grüße, Carsten

---

From: Michael Richardson <[email-masked]>
Date: Sun, 31 Oct 2021 18:57:21 -0400

> This does indeed work exactly as one would think, so if an h3 heading
    > (###) follows a sequence of zero or more paragraphs that follow an h2
    > heading (##), an h3 section is created that is nested into the h2
    > section encompassing it.  The h2 section extends to the next h2 (##) or
    > h1 (#) heading or the end of the “middle” or “back” division.

Yes, I guess I am asking that in the end.
Given that the containers in markdown are not explicit, it might be that it
only applied to the next paragraph, or something like that.

    > But it is hard to remove a section without removing its subsections,
    > and logically the h2 section to be removed does include its h3
    > sections, so I would expect the RPC to remove the entire h2 section,
    > including its contradicting subsections.

yes. true.