Subject: [Tools-discuss] structured contributor section --- auto-reference to DT/Person?

From: Michael Richardson <[email-masked]>
Date: Thu, 29 Oct 2020 12:51:44 -0400

Some year or so ago I asked if our XML format could accomodate a structured
form of the contributor.  There was various discussion (ratholing, alas) on
how different WGs would use it differently, and how to game the system, etc.

It turns out that we already have this feature.
In the kramdown, one can do:

contributor:
  - name: Bugs Bunny
    email: [email-masked]

which results in XML like:

    <section anchor="contributors" numbered="false" toc="include" removeInRFC="false">
      <name>Contributors</name>
      <contact initials="B." surname="Bunny" fullname="Bugs Bunny">
        <organization/>
        <address>
          <email>[email-masked]</email>
        </address>
      </contact>

It occurs to me that it might be nice if we could connect the contributors
directly to a DT /Person/XYZ page.   That would sure make any kind of
mechanical collection of the data really really really easy.
It's right now, easy: take the email address and find it in the DT list of
emails for the people.

But, on my side, the authoring side, I often three things wrong:
 1) I don't know how to get the right accents and/or non-english UTF-8 right.
 2) My notion of <organization> could be obsolete.
 3) What if I credit the wrong person because names are similiar?

On the contributor side, it would be nice if they knew that their name was
there, in part so that they could object!

So I'm thinking that it would be cool if we could do something like:

  <?ietf-dt include="[email-masked]" ?>
  [Not sure how I'd do this in kramdown. New "ietfdtemail:" tag or something]

to get the contributor and/or author information sucked in documents.

Would this be helpful, or am I just trying to be too cute?
This is just stuff to code, no changes to the XML scheme required, AFAIK.

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

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 18:13:04 +0100

Am 29.10.2020 um 17:51 schrieb Michael Richardson:
 > ...

For some value of "already".

History in
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/81>...

> ...

In theory, the datatracker could have that as XML resource, and then you
could just do an <x:include>.

 > ...
> ...

Best regards, Julian

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 29 Oct 2020 19:06:58 +0100

> It turns out that we already have this feature.

https://www.ietf.org/archive/id/draft-ietf-anima-autonomic-control-plane-29.xml

    <contact fullname="Michael C. Richardson" initials="M." surname="Richardson">
      <organization abbrev="Sandelman">Sandelman Software Works</organization>
      <address>
        <email>[email-masked]</email>
        <uri>http://www.sandelman.ca/</uri>
      </address>
    </contact>

I had to go through the horrifying experience of changing from xmlv2 to v3,
as this is a new feature in v3. Really just to be able to add structured contributors *sigh*.
I guess RFC editor would have done the upgrade to v3 anyhow though, so maybe i will have
saved them time.

the v3 xml, at least the normalized version spit out by the conversion is now
even less human producable, so i will certainly be attempting to do kramdown
or the like on my next work. Too bad it can't be directly uploaded to
datatracker.

Note though, that the <contact> tag does not make it unambigous whether
the content describes a contributor or gives an acknowledgement. This is
the key difference to <author>. 

The role="..." option is not available for <contact> as opposed to <author>,
otherwise that would be an easy way (role="contributor", role="acknowledgemenet")

of course, it wouldn't be too difficult to assume well-known sections 
cacknowledgements/contributors, but thats still DPI and not real structure ;-)

>     email: [email-masked]

Which RFC is that ? ;-)

> mechanical collection of the data really really really easy.

Indeed i did wanted to have the structured contributor section to make
such automation easier. No idea if tools team or Jari actually do benefit
from it today though. Tools teal doesn't seem to capture contirbutors for
stats, and i guess Jari is doing lots of pattern matching.

So, are you suggesting that the tools team should add to the list of
RFC "authored" on a datatracker person page also the list of draft/RFC
contributed to ?

If yes, then +1. As a WG chair i think any incentives we can give to get
more contributors is highly desirable for IETF. Hence also me stressing
myself with xmlv3.

Do we have any RFCs like for pagination of RFCs that tell the tools
team what MUST be on the datracker person page which should also be
interpreted that NOTHING ELSE will be on it ?

> It's right now, easy: take the email address and find it in the DT list of

I guess this is how authors are mapped on the datatracker person page.

>  3) What if I credit the wrong person because names are similiar?

I think datatracker is only using sets of email addresses to identify
individuals and map them. Maybe just never let Mirja contribute to your
work (kidding of course, but her email address is the only one i remember
i repeatedly had problems with because at some point she used some non-acii
UTF-8 characters in it).

> there, in part so that they could object!

Except i don't buy the "they could object" part. I don't think one
should add contributors without having a good upfront understanding
that its a) true, and b) welcome. And then of course also send
email to explicitly tell that it was done. (i hope and think to remember
i did this in your case ;-)) But of course, if a contributor has an
email box like mine, it might be easier to find stuff on some automated
tools pages...

> to get the contributor and/or author information sucked in documents.

Would be good if this would equally work for acknowledgements, except
that only the name would show up in the rendered output.

> Would this be helpful, or am I just trying to be too cute?

Yes, yes.

The second yes is cynical as to the speed at which we seem to be able to adopt change
as well as the probems ... see below.

No idea about your formatting proposal, but getting stuff automatically from email addresses
would be great. Just lets make sure we don't eliminate support for non-email address
based acks/contributors. Heck, we even have authors for which we do not have
email addresses published (e.g.: retireees like Steve Deering, rfc8200).

A followup question would then be if/how we might want to render
hotlink capable output formats: Include URL to datatracker page of the person ?

> This is just stuff to code, no changes to the XML scheme required, AFAIK.

Is there an API on datatracker to look up a person from an email address
so a renderer could find a person that way ? Could be used both
from the kramdown script as well as from a later renderer.

Oh no, we're creating another perpass attack...

Especially if we wanted to be able to use the scheme when there is no public
email address and we would invent pseudo-emails like [email-masked]
as a form of ID, upon which i am sure i would get a double rejection both
from perpass AND email AD, even though effectively this is i think how a person
is also tracked as an author in datatracker, but psssst... we can not talk about that,
can't use email because there shall be no noreply email addresses and we we can not
come up with other IDs because that would be even more egregious to anti-perpass folks.

*sigh*

Cheers
    toerless

> ___________________________________________________________
> Tools-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-discuss
> 
> Please report datatracker.ietf.org and mailarchive.ietf.org
> bugs at http://tools.ietf.org/tools/ietfdb
> or send email to [email-masked]
> 
> Please report tools.ietf.org bugs at
> http://tools.ietf.org/tools/issues
> or send email to [email-masked]

-- 
---
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 19:25:33 +0100

> or the like on my next work. Too bad it can't be directly uploaded to

v3 xml in general is *easier* to author than v2 xml. Depending on the
size of your source, it might easier to do the conversion "by hand". (In
general, the only thing that *requires* changes are the <list> elements).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 19:30:59 +0100

> general, the only thing that *requires* changes are the <list> elements).

...and <texttable>s (sorry, forgot that one).

Best regards, Julian

PS: these are "deprecated" in v3, and the idea was that they would be
supported by processors until we actually *remove* them in a future
version. However, I don't think xml2rfc's v3 mode accepts them.

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 29 Oct 2020 19:58:20 +0100

> general, the only thing that *requires* changes are the <list> elements).

Hmm. Maybe i may be a victim of the conversion script on the IETF web age which seem
so have converted a lot of stuff into longer variants. But  thin that
you now always need two lines to a title (separate <name> tag if i am not mistaken).

The worst part was that i couldn't find a replacement for the perfectly simple
form of references in v2:

 <?rfc include='reference.RFC.4941'?>

I ended up having to figure out the crappy &rfc4941 methods, which wasn't documented
for v3 on the xml2rfc pages.

Why does the 'include' method not work anymore ?

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 20:23:12 +0100

> you now always need two lines to a title (separate <name> tag if i am not mistaken).

No, the title attribute is still supposed to work.

> Why does the 'include' method not work anymore ?

It was never a part of the official v2 vocabulary; processing
instructions are essentially a hack, and specific to a concrete
implementation.

RFC 7991 has x:include, with an example in
<https://greenbytes.de/tech/webdav/rfc7991.html#includingexternal>.

Best regards, Julian

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 29 Oct 2020 20:33:04 +0100

On Thu, Oct 29, 2020 at 08:23:12PM +0100, Julian Reschke wrote: (on prior thread on tools-discuss)
> No, the title attribute is still supposed to work.

Ok. victim of the v2 -> v3 conversion script then. Would be great
if that conversion script would overall use the most compact & easily
human editable version of encoding options.

> instructions are essentially a hack, and specific to a concrete

Thanks.

> <https://greenbytes.de/tech/webdav/rfc7991.html#includingexternal>.

Excellent. Who could replace or amend the "Use the XML external entity mechanism"
section on the https://xml2rfc.tools.ietf.org/ page with that IMHO mch better
method ?

Cc'ing [email-masked] which hopefully has someone who is responsible for the page.
> Best regards, Julian

Thanks a lot!
    Toerless

---

From: Michael Richardson <[email-masked]>
Date: Thu, 29 Oct 2020 18:33:27 -0400

> stats, and i guess Jari is doing lots of pattern matching.

Yes, he is.

    > RFC "authored" on a datatracker person page also the list of draft/RFC

I dunno: there were lots of objections last year, but a major one was what
about the previous 8000 RFCs?  So, it would be nice if could fix this for the
next 8000.

    > more contributors is highly desirable for IETF.

That's what I hope.

    > that its a) true, and b) welcome. And then of course also send

With such strong connection, I could get a notice when my name goes in.
That would allow errors to be corrected.
It could be that they got the wrong person. (Do you who actor "Michael Richards" is?)

There have been cases where people have inserted co-authors to attempt to
imply approval!

    > that only the name would show up in the rendered output.

Exactly.

    > email addresses published (e.g.: retireees like Steve Deering, rfc8200).

Of course, you can just write out the full contributor part as we do now
instead of using the include magic.

    > hotlink capable output formats: Include URL to datatracker page of the person ?

Nobody lets me do UX since I started using Dark Golden Rod as my background.

    > from the kramdown script as well as from a later renderer.

Yes, I think that there is already.
And I think the DT has some GDRP controls on it already.

---

From: Toerless Eckert <[email-masked]>
Date: Fri, 30 Oct 2020 18:54:26 +0100

On Thu, Oct 29, 2020 at 06:33:27PM -0400, Michael Richardson wrote:
> about the previous 8000 RFCs?

that is a great argument. Translatef from german it is the manslaughter argument.

"das haben wir noch nie so gemacht"         - "we have never done that"
"das haben wir immer schon anders gemacht"  - "we have always done it differently"
"da koennte ja jeder kommen"                - "who are you ?"

>  So, it would be nice if could fix this for the next 8000.

Note that the (I) in IETF does not stand for Innovation.

>     > more contributors is highly desirable for IETF.

But who wants to revive the IETF.

> It could be that they got the wrong person. (Do you who actor "Michael Richards" is?)

;-) 

> There have been cases where people have inserted co-authors to attempt to

Yes indeed. I guess what i wanted to say is that automatic tooling should not
be used as an excuse NOT to also reach out explicitly to folks who you
think deserve to be contributors and let them know.

Cheers
    Toerless

-- 
---
[email-masked]