Subject: [Tools-discuss] When I have a draft that doesn't target a working group, I break things ...

From: Spencer Dawkins at IETF <[email-masked]>
Date: Thu, 23 Sep 2021 14:50:46 -0500

I'm happy to have the response be some version of "if it hurts when you do
that, don't do that", but ...

I'm working on a draft (hasn't been submitted to the datatracker yet) using
kramdown-rfc2629 in github, and the I-D template tools.

The draft name in MD is draft-dawkins-sdp-rtp-quic-questions-latest. These
are the weird things that I've noticed so far.

Without trying to dig out when this happened, except when I submitted a
similarly-named draft on September 8 (
https://datatracker.ietf.org/doc/draft-dawkins-sdp-rtp-quic/), it wasn't
happening then, I am now getting

Discussion Venues <#name-discussion-venues>

This note is to be removed before publishing as an RFC.¶ <#section-note.1-1>

Discussion of this document takes place on the mailing list (), which is
archived at .¶ <#section-note.1-2>

Source for this draft and an issue tracker can be found at
https://github.com/SpencerDawkins/sdp-rtp-quic-questions.

between the Abstract and "Status of This Memo".  I'm guessing that one of
the various tools is now inserting this, and is unable to figure out what
the right mailing list is, because there's not an SDP mailing list (or
working group/research group, or somewhere in between).

(Here's the funny part - my draft is about SDP, which WOULD be in scope for
MMUSIC, except that the RTP people in AVTCORE need to see it first, and I
COULD send it to AVTCORE, except that we now ALSO have a "Media Over Quic"
non-working group mailing list that was created after IETF 111 ... you see
my problem, right?).

This is probably somewhat related, but when I clone the I-D template repo
and rename the draft, my CONTRIBUTING includes this:

Other Resources

Discussion of this work occurs on the sdp working group mailing list
<https://mailarchive.ietf.org/arch/browse/sdp/> (subscribe
<https://www.ietf.org/mailman/listinfo/sdp>). In addition to contributions
in GitHub, you are encouraged to participate in discussions there.

Note: Some working groups adopt a policy whereby substantive discussion of
technical issues needs to occur on the mailing list.

You might also like to familiarize yourself with other working group
documents <https://datatracker.ietf.org/wg/sdp/documents/>.

So I'm thinking this was the result of a guess that "sdp'' was a working
group name, without checking to see if the working group exists. That's a
similar problem as the first one, but it's not the same.

Before I ask any more questions, should I be surprised by any of this?

Best,

Spencer

---

From: "Salz, Rich" <[email-masked]>
Date: Thu, 23 Sep 2021 22:44:01 +0000

Discussion Venues

This note is to be removed before publishing as an RFC.¶

Discussion of this document takes place on the mailing list (), which is archived at .¶

Source for this draft and an issue tracker can be found at https://github.com/SpencerDawkins/sdp-rtp-quic-questions<https://urldefense.com/v3/__https:/github.com/SpencerDawkins/sdp-rtp-quic-questions__;!!GjvTz_vk!HIb-NraWV9qFS00O4G9gxiFPGEZ_PMSBWw8TmNzu48AVjT0PySY_eA8aGTcd$>.

Did you (change to?) using Martin’s i-d-tempate tools?  It creates an initial .note.xml file which you should edit.

  *   Before I ask any more questions, should I be surprised by any of this?

As with many things, getting all the corner cases right depends on those corner cases showing up in the tool’s usage.  As for whether or not you should be surprised, that’s your call :)

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Thu, 23 Sep 2021 19:28:33 -0500

Hi, Rich,

On Thu, Sep 23, 2021 at 5:44 PM Salz, Rich <[email-masked]> wrote:

> Discussion Venues <#m_-4454017814563873597_name-discussion-venues>
>
> *This note is to be removed before publishing as an RFC.¶
> <#m_-4454017814563873597_section-note.1-1>*
>
> archived at .¶ <#m_-4454017814563873597_section-note.1-2>
>
> https://github.com/SpencerDawkins/sdp-rtp-quic-questions
> <https://urldefense.com/v3/__https:/github.com/SpencerDawkins/sdp-rtp-quic-questions__;!!GjvTz_vk!HIb-NraWV9qFS00O4G9gxiFPGEZ_PMSBWw8TmNzu48AVjT0PySY_eA8aGTcd$>
> .
>
>
>
> Did you (change to?) using Martin’s i-d-tempate tools?  It creates an
> initial .note.xml file which you should edit.
>

I've been using Martin's i-d-template for a while (measured in years), and
started using it CORRECTLY (cloning that repo, instead of creating a new
one and copying in stuff from another one of my repos) about five or six
repos ago. Like I said, I didn't get the inserted "Discussion Venues"
section in another recent draft, so apparently this is new, and I had poked
around for a while trying to find this, but wasn't looking in the right
place. Thank you very much for that.

So, I guess that this isn't also used in the CONTRIBUTING.md file, since
the weirdness is different (it guesses at the working group name and
mailing list, but it guessed "sdp", which was wrong). But that's not going
to prevent me from submitting the draft, and the problem you solved for me
was.

Best,

Spencer

>
>    - Before I ask any more questions, should I be surprised by any of
>    this?
>
>
>
> As with many things, getting all the corner cases right depends on those
> corner cases showing up in the tool’s usage.  As for whether or not you
> should be surprised, that’s your call :)
>

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 24 Sep 2021 10:42:08 +1000

On Fri, Sep 24, 2021, at 10:28, Spencer Dawkins at IETF wrote:
> So, I guess that this isn't also used in the CONTRIBUTING.md file, 
> since the weirdness is different (it guesses at the working group name 
> and mailing list, but it guessed "sdp", which was wrong). But that's 
> not going to prevent me from submitting the draft, and the problem you 
> solved for me was. 

Hi Spencer,

These are, as you note, relatively new features and not completely good.

I've only recently started using the datatracker API for getting mailing list information and haven't standardized its usage, so things are still a bit uneven.

The eventual goal is to fill in the information when it is available, but omit information when it is not.  The weird note is a bug and I can fix that.  I'll see if I can't fix the contributing doc at the same time.

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Thu, 23 Sep 2021 23:22:17 -0500

Hi, Martin,

On Thu, Sep 23, 2021, 19:42 Martin Thomson <[email-masked]> wrote:

> I've only recently started using the datatracker API for getting mailing
> list information and haven't standardized its usage, so things are still a
> bit uneven.
>
> The eventual goal is to fill in the information when it is available, but
> omit information when it is not.  The weird note is a bug and I can fix
> that.  I'll see if I can't fix the contributing doc at the same time.
>

As Rich said, the corner cases are easier to find when they show up on
their own, and you know you can count on me for corner cases (not just with
the toolset, either!)

The "might be targeting any of several working group mailing lists but is
actually targeting some random non-WG mailing list" case has to be the
worst - maybe that's something that should be in optional attributes, so
you don't have to get every corner case right, and the 15 percent of drafts
that don't match the usual pattern could be manually repaired?

Thanks for your work on making things work more automagically.

I've been adding "venues for contribution and discussion" sections to my
own drafts, but I still see drafts (including WG drafts) that don't have
any pointers to mailing lists or to GitHub, so adding that, automatically
generated, is very helpful.

I did have one question - it seems reasonable to generate the same text for
the new section in the draft and for the CONTRIBUTING.md file, since they
contain the same information. Is that possible? I can pretty trivially put
the information from my notes.xml file in my CONTRIBUTING.md file, but
having one of those in XML and the other in Markdown seemed odd ...

Best,

Spencer

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 24 Sep 2021 14:37:59 +1000

On Fri, Sep 24, 2021, at 14:22, Spencer Dawkins at IETF wrote:
> their own, and you know you can count on me for corner cases (not just 
> with the toolset, either!) 

It's a talent, for sure.  That you take the time to write up what you learn is greatly appreciated.

In this case, I've revised the process somewhat and you should find that the broken information is no longer being added.  Rather than add bad information, I've chosen to remove the relevant sections.  The datatracker API has a few unexpected quirks that I failed to account for.

> I did have one question - it seems reasonable to generate the same text 
> for the new section in the draft and for the CONTRIBUTING.md file, 
> since they contain the same information. Is that possible? I can pretty 
> trivially put the information from my notes.xml file in my 
> CONTRIBUTING.md file, but having one of those in XML and the other in 
> Markdown seemed odd ...

Yeah, when you have special constraints, this is what you get.  It makes sense to do the common stuff, like drafts targeted at a working group.  Beyond that, it's hard.

The reason that I use XML for the note is that - unless things have changed - you can't mark sections as "removeInRfc" in markdown.  If you have special text, then adding the information to both is a little more work, but I'm sure that your readers and contributors will appreciate the effort.

I could automatically add a link to the CONTRIBUTING.md file in the note to readers if you would prefer to just edit the one location.

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 24 Sep 2021 06:56:08 +0200

{: removeinrfc=“true”}

(There also is an ALD, which I forget, and I don’t have useful IT with me.)

Sent from mobile, sorry for terse

> On 24. Sep 2021, at 06:38, Martin Thomson <[email-masked]> wrote:
> 
> ___________________________________________________________
> Tools-discuss mailing list - [email-masked]
> This list is for discussion, not for action requests or bug reports.
> * Report datatracker and mailarchive bugs to: [email-masked]
> * Report tools.ietf.org bugs to: [email-masked]
> * Report all other bugs or issues to: [email-masked]
> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 24 Sep 2021 15:04:27 +1000

> {: removeinrfc=“true”}

$ grep -B1 removeInRfc draft-thomson-notagroup-rot13.md
--- note_Please_Note
{: removeInRfc="true"}
--
# Introduction
{: removeInRfc="true"}
$ make
...
draft-thomson-notagroup-rot13.xml(33): Error: Invalid attribute removeInRfc for element t, at /rfc/front/note/t
draft-thomson-notagroup-rot13.xml(37): Error: Invalid attribute removeInRfc for element section, at /rfc/middle/section[1]

And I realize that I forgot https://github.com/cabo/kramdown-rfc2629/issues/71 which means using to_be_removed_note_Please_Note instead.

The latter seems to be a bug in xml2rfc because the resulting XML is clearly permitted by RFC 7991.

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 24 Sep 2021 15:09:30 +1000

> clearly permitted by RFC 7991.

Correction: no bug.  Y just have to get the case precisely correct.  The attribute has to be removeInRFC="true" (or removeInRFC="1", because the value can be any number of things as long as the attribute name is 100% correct).

Another win for the authoring format that hates authors.

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 24 Sep 2021 07:58:27 +0200

Yep, I included to_be… because the grammar gets in the way (and the whole way kramdown-rfc handles <note>s is an ugly hack, ugh).  

BTW, kramdown-rfc has a studlifier for known attribute names, so if you write removeinrfc, that will be converted to the studlycaps du jour.

> On 24. Sep 2021, at 07:05, Martin Thomson <[email-masked]> wrote:
>

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Fri, 24 Sep 2021 19:20:01 -0500

Hi, Martin,

On Thu, Sep 23, 2021 at 11:38 PM Martin Thomson <[email-masked]> wrote:

> In this case, I've revised the process somewhat and you should find that
> the broken information is no longer being added.  Rather than add bad
> information, I've chosen to remove the relevant sections.  The datatracker
> API has a few unexpected quirks that I failed to account for.
>
> Yeah, when you have special constraints, this is what you get.  It makes
> sense to do the common stuff, like drafts targeted at a working group.
> Beyond that, it's hard.
>

You definitely started on the 80 percent case, which means that 80 percent
of your users thank you :😉

> The reason that I use XML for the note is that - unless things have
> changed - you can't mark sections as "removeInRfc" in markdown.  If you
> have special text, then adding the information to both is a little more
> work, but I'm sure that your readers and contributors will appreciate the
> effort.
>
> I could automatically add a link to the CONTRIBUTING.md file in the note
> to readers if you would prefer to just edit the one location.

ISTM that getting that information right, and by "right", I mean "not
wrong", is more likely if it's only in one place.

It did take me a while to notice the automatically-generated section,
because I was looking at the abstract and then skipping down to the
Introduction.

It happens that I try to get the CONTRIBUTING.md file right, because I know
it is referenced on the front page of the Github repo, for what that's
worth.

So, for Spencer, pointing to the CONTRIBUTING.md file would have been a
win, especially if you can do that as a fallback, if you see that the draft
filename doesn't seem to point to an active working group mailing list.

Does that make sense?

Best,

Spencer