Vanishing notes

[cabo]

From Archived-At: https://mailarchive.ietf.org/arch/msg/opsawg/BgJkHaj2vOJmz0IX44on0s5JY14:

I had some challenges getting the MT makefiles to actually produce version -04, so I invoked kdrfc -3 directly and uploaded that. So the bit at the top about the WG and github got deleted.

I think it would be useful to have a way to include this note that is not "transparent" (a monkey patch to the completed XML) but is actually visible in the source so manual generation does generate the note, too.

[cabo]

(Probably this is easiest to do with a parallel change in kramdown-rfc.)

[martinthomson]

It's fairly trivial to push a change into the source. I worry less about kramdown-rfc than I do mmark and org-mode versions. Reducing to XML means that the note insertion isn't bothered by the vagaries of different formats.

More work is always possible. Inserting notes into kramdown source is doable. I've completely avoided touching source thus far, but that doesn't need to be an absolute position.

Frankly, I'm more concerned that @mcr wasn't able to do what he needed to do. I thought the tagging thing wasn't THAT magical, but I'm obviously incapable of seeing the problems from where I sit.

[cabo]

It's fairly trivial to push a change into the source. I worry less about kramdown-rfc than I do mmark and org-mode versions. Reducing to XML means that the note insertion isn't bothered by the vagaries of different formats.

I understand that, but it also creates some inflexibility. If you could create a .note.md, authors could {::include} that or paste it in and edit it if that is needed. (Of course, you’d need to detect that it’s there before falling back to .note.xml .)

More work is always possible. Inserting notes into kramdown source is doable.

Well, that should be done manually, I think (with the .note.xml inclusion as a fallback if it is not done).

I've completely avoided touching source thus far, but that doesn't need to be an absolute position.

I think you should stick with that.

Frankly, I'm more concerned that @mcr wasn't able to do what he needed to do. I thought the tagging thing wasn't THAT magical, but I'm obviously incapable of seeing the problems from where I sit.

It is mostly opaque to people who are trying to use it. We can’t really do extensive tests to see which of our behavior works and which doesn’t. So we submit manually.

But my point here really is that there are many reasons to format locally, kdwatch 1 being the most important one for me.

BTW,

https://tools.ietf.org/rfcdiff?url1=https://tools.ietf.org/id/draft-bormann-cbor-edn-literals.txt&url2=https://cabo.github.io/edn-literal/draft-bormann-cbor-edn-literals.txt

shows that there are differences in how the submission tools formats and how I-D-template formats, creating some noise in the diffs.

(Kudos for the template repo, BTW!)

Grüße, Carsten

[martinthomson]

Curious to see what happens, I tried {::include .note.xml}. It almost works, though it ends up putting the XML into the <abstract> section. That worked out better than {::include note.md}, which fed --- note_Note_to_Readers straight into the same <t> element as the text that followed.

How does one use {::include } safely again?

[cabo]

On 7. Oct 2021, at 03:37, Martin Thomson @.***> wrote:

Curious to see what happens, I tried {::include .note.xml}. It almost works, though it ends up putting the XML into the section.

If you put the element into the abstract, that’s what happens…

Unfortunately, there is no safe place to put the element in the current “section” structure; that’s why there is the special code for (to_beremoved)?note_(.*) (this one should be a to_be_removednote… probably).

That worked out better than {::include note.md}, which fed --- note_Note_to_Readers straight into the same element as the text that followed.

Not sure what was in the note.md, but blank lines around the “---" lines are necessary.

How does one use {::include } safely again?

Mostly, you need to make sure that what results from the include is the input you want...

Grüße, Carsten

[martinthomson]

Ah, that will do it. The blank lines need to be inside the include, not outside. The effect is not that the content is included in place of the directive, but that the content is parsed anew. Subtle. Thanks for the tip.

[cabo]

Well, the code in bin/kramdown-rfc2629 simply replaces the {::include ...} by the result of reading the file (and some optional processing that was recently added) before any further parsing. So these observations surprise me. But it probably is more robust to provide the blank lines in the included file, as the {::include ...} would be added manually with less control over how exactly this is done.

[martinthomson]

kramdown-rfc2629 has a change in 1.5.15 that inserts something into the source:

venue:
  group: JSON Path
  mail: jsonpath@ietf.org
  github: ietf-wg-jsonpath/draft-ietf-jsonpath-base

I will add this to the template files (with a complete set of keys) so that this will be updated correctly. This issue can track an automated update of those fields from template values. I can use the logic I use to generate .note.xml to update these fields based on the draft name and the choice of repository.

[martinthomson]

I've made some changes to the template repo that will ensure that drafts are updated. This is a one-off during setup that should help people populate these fields with sensible information. It does touch draft source, but I'm doing that for other reasons at that stage, so I'm going with that being OK in the name of usability.