Subject: [Tools-discuss] contributors section & tools

From: Toerless Eckert <[email-masked]>
Date: Wed, 15 Jul 2020 19:40:47 +0200

Is there any tool from e.g.: the IETF or Arkko publishing houses that actually deparses names
in a contributors section and does something with that information ?
(aka: allows recognition stats like they are done for authors) ?

I could not find anything in RFC 7749 that would allow me semantic tagging of contributors,
Am i wrong ?

If not, then parsing would have to be difficult and heuristic, and i therefore fear the answer to my
above question is NO ?

Wasthere not a time when we wanted to make contirbutors better recognizeable ?

Thanks
    Toerless

---

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 15 Jul 2020 19:04:35 +0100

I believe Jari's script attempts to do this and counts Contributors in the
author stats it generates

The script is very vulnerable to formatting errors and since the
Contributors section is usually hand-crafted, the script often misses people
or documents.

Jari always welcomes fixes to the scripts. Last I looked there were lots of
"IF RFC=abcd THEN make this special exception"

A
-----Original Message-----
From: rfc-interest <[email-masked]> On Behalf Of
Toerless Eckert
Sent: 15 July 2020 18:41
To: [email-masked]; [email-masked]
Subject: [rfc-i] contributors section & tools

Is there any tool from e.g.: the IETF or Arkko publishing houses that
actually deparses names
in a contributors section and does something with that information ?
(aka: allows recognition stats like they are done for authors) ?

I could not find anything in RFC 7749 that would allow me semantic tagging
of contributors,
Am i wrong ?

If not, then parsing would have to be difficult and heuristic, and i
therefore fear the answer to my
above question is NO ?

Wasthere not a time when we wanted to make contirbutors better recognizeable
?

Thanks
    Toerless
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: 'Toerless Eckert' <[email-masked]>
Date: Wed, 15 Jul 2020 20:12:33 +0200

Thanks, Adrian

Any example XML for which you're aware that the contributor section was correctly parsed, then
i will just clone that formatting. I do like the idea to format with all the same contact
info as if the contributors where authors, but thats just for emphasizing for human readers,
not for a poor script.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 15 Jul 2020 19:23:51 +0100

I just looked at RFC 8663.
Long list of Contributors. Jari appears to extract them OK.

The XML for 8663 is available in the datatracker.

I see that the RPC elected to use my magic formatting which has the whole
section presented as <artwork> to get the format correct.

Not sure whether xml2rfc v3 has special tags for contributors. If so, that
would solve the problem.

A

-----Original Message-----
From: 'Toerless Eckert' <[email-masked]> 
Sent: 15 July 2020 19:13
To: Adrian Farrel <[email-masked]>
Cc: [email-masked]; [email-masked]
Subject: Re: [rfc-i] contributors section & tools

Thanks, Adrian

Any example XML for which you're aware that the contributor section was
correctly parsed, then
i will just clone that formatting. I do like the idea to format with all the
same contact
info as if the contributors where authors, but thats just for emphasizing
for human readers,
not for a poor script.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: 'Toerless Eckert' <[email-masked]>
Date: Wed, 15 Jul 2020 20:50:23 +0200

> The XML for 8663 is available in the datatracker.

Thanks!
> section presented as <artwork> to get the format correct.

Sounds like Jari is probably scraping the txt output. Fine.

> Not sure whether xml2rfc v3 has special tags for contributors. If so, that

Scanning through rfc7991 there seems to be no enhancements in this respect.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Jul 2020 20:54:44 +0200

> On 2020-07-15, at 20:50, Toerless Eckert <[email-masked]> wrote:
> 

It does.  They are not very well documented.

Kramdown-rfc supports them by adding a YAML entry like the authors entry:

author:
  - name: Carsten Bormann
    org: Universität Bremen TZI
    street: Postfach 330440
    city: Bremen
    code: D-28359
    country: Germany
    phone: +49-421-218-63921
    email: [email-masked]
contributor:
  - name: Peter Occil
    email: poccil14 at gmail dot com
  - name: Many More
    org: To do

Grüße, Carsten

---

From: Toerless Eckert <[email-masked]>
Date: Wed, 15 Jul 2020 21:02:24 +0200

> It does.  They are not very well documented.

Can you point me to a place so i can understand it ? Any pointer into rfc7991 
(i could  not find anything) or an actual XMLv3 RFC that does this 
(your latest published RFC with contributors section does not use anything new).
> Kramdown-rfc supports them by adding a YAML entry like the authors entry:

Don't have the toolchain installed, so it would be ugly to be trying to figure
out what XML it generates. If its easy for you to send me the XML generated
from this, i would appreciate.

Thanks!
    Toerless

-- 
---
[email-masked]

---

From: Jari Arkko <[email-masked]>
Date: Wed, 15 Jul 2020 22:59:24 +0300

> in a contributors section and does something with that information ?

My tools actually do this. For the sake of listing documents or counting authorship, explicitly listed people in the contributor section get counted equally to those in the author section.

My choice, of course. There are some rationales, basically about me creating those tools initially to understand who is making these standards, and contribution counts for that. May not fit everyone’s model of things. 

In a perfect world one could control what information one wants to show. Or even be able to show who is acknowledged.

Jari

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Jul 2020 22:03:24 +0200

> On 2020-07-15, at 21:02, Toerless Eckert <[email-masked]> wrote:
> 
> Can you point me to a place so i can understand it ?

Use the source, Luke.

> Any pointer into rfc7991 

(RFC 7991 is a description of a snapshot in the development of RFCXMLv3.
The current version is described in the source of xml2rfc; partially also in draft-levkowetz-xml2rfc-v3-implementation-notes-10.txt (expired).

RFC 8799 does use new XML in the contributors section.

> Don't have the toolchain installed,

A mistake :-)

> so it would be ugly to be trying to figure

https://www.ietf.org/id/draft-bormann-cbor-notable-tags-02.xml

Grüße, Carsten

---

From: Alice Russo <[email-masked]>
Date: Wed, 15 Jul 2020 16:37:59 -0700

Hi Toerless,

There's a <contact> element with the same structure as the <author> element.
From the current schema (https://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc):

   contact =
     element contact {
       attribute xml:base { text }?,
       attribute xml:lang { text }?,
       attribute anchor { xsd:ID }?,
       attribute initials { text }?,
       attribute asciiInitials { text }?,
       attribute surname { text }?,
       attribute asciiSurname { text }?,
       attribute fullname { text }?,
       attribute asciiFullname { text }?,
       organization?,
       address?
     }

For more info:
https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html#using_contact

Thanks,
Alice

> On Jul 15, 2020, at 12:02 PM, Toerless Eckert <[email-masked]> wrote:
> 
> ___________________________________________________________
> 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]
>

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 16 Jul 2020 03:30:48 +0200

Nice. Who'd know v3 had undocumented features ;-))

Thanks!
    Toerless

-- 
---
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Thu, 16 Jul 2020 12:03:20 +0200

On 16.07.2020 03:30, Toerless Eckert wrote:
> ...

There are undocumented features, but this one actually *is* documented in

https://greenbytes.de/tech/webdav/draft-iab-rfc7991bis-latest.html#element.contact

Best regards, Julian

---

From: Michael Richardson <[email-masked]>
Date: Thu, 16 Jul 2020 17:00:52 -0400

> email: poccil14 at gmail dot com

Thank you, I very much like this.
I also noticed today that there was an IESG todo item:
    Warren Kumari to work on acknowledging shepherds, directorate
    reviewers in a more standardized/formal way.
    - Added 2019-10-10 (18 telechats ago)

so, I tried this.

I had a section called "Contributors" already, in the old textual form.
And it actually details some major contributions, so I didn't want to remove
it, so I have slightly renamed it. ("Notable Contributions")

With just name:/email:, I get many complaints from xml2rfc:
 <string>: Line 1655: No declaration for element contact
 <string>: Line 1655: No declaration for attribute initials of element contact
 <string>: Line 1655: No declaration for attribute surname of element contact
 <string>: Line 1655: No declaration for attribute fullname of element contact

I obviously know how to solve this by putting more stuff in.
But, the bigger problem seems to be:

<string>: Line 1614: Element section content does not follow the DTD,
expecting ((t | figure | texttable | iref)* , section*), got (name contact
contact contact contact contact contact contact contact contact contact
contact contact contact)

kramdown-rfc2629-1.3.8
xml2rfc 2.23.1
... upgrading to 2.46.0.
    same result.

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 17 Jul 2020 00:37:03 +0200

You need the -3 flag in kdrfc

Sent from mobile, sorry for terse

> On 16. Jul 2020, at 23:01, Michael Richardson <[email-masked]> wrote:
> 
>

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 17 Jul 2020 00:44:57 +0200

Or - - v 3 in XXL rfc if you call that directly

Sent from mobile, sorry for terse and autocorrect

> On 17. Jul 2020, at 00:37, Carsten Bormann <[email-masked]> wrote:
>

---

From: tom petch <[email-masked]>
Date: Fri, 17 Jul 2020 10:33:22 +0100

> In a perfect world one could control what information one wants to show. Or even be able to show who is acknowledged.

Tweaking the subject slightly for a related question which is bugging 
me, what about all those editors who appear in YANG modules, modules 
which must be plain text so that they can be extracted and used outside 
the IETF environment?

Tom Petch

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 17 Jul 2020 20:23:55 +0200

On 2020-07-17, at 11:33, tom petch <[email-masked]> wrote:
> 
> what about all those editors who appear in YANG modules

Yeah, what about them?

Er, this is a bit undirected for a question.

I believe you should avoid sugared carbonated drinks before editing YANG modules, but maybe that wasn’t your question.

Grüße, Carsten

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 17 Jul 2020 23:14:12 +0200

Hi Toerless, Carsten, Adrian,

On 2020-07-15 22:03, Carsten Bormann wrote:
> (RFC 7991 is a description of a snapshot in the development of
> RFCXMLv3. The current version is described in the source of xml2rfc;
> partially also in
> draft-levkowetz-xml2rfc-v3-implementation-notes-10.txt (expired).

In connection with updating draft-levkowetz-xml2rfc-v3-implementation-notes
over the couple of weeks, I've also added documentation to xml2rfc, generated
from:

   - the actual XML schema distributed with the tool
   - the differences between the current schema and the RFC7991 schema
   - the code's settings for which elements and attributes are deprecated
   - text snippets describing the schema parts and how the code handles them.

It will have new --doc/--docfile and --man/--manpage switches; the first will
generate documentation in the form of a v3 XML document that can then itself
be processed to generate the various supported formats. The second, --man, will
generate the documentation XML internally and then process it to text output
which is shown with a pager, like 'man'.

I hope this will help overcome the painful lack of documentation.  It is part
of the 2.47.0 release I've just uploaded.

Best regards,

	Henrik

---

From: Michael Richardson <[email-masked]>
Date: Sun, 19 Jul 2020 00:42:00 -0400

> You need the -3 flag in kdrfc

It was being invoked from Martin Thompson script.
I think that I must have debugging it wrong after getting the update, because
now it works great.

---

From: tom petch <[email-masked]>
Date: Sun, 19 Jul 2020 21:22:45 +0100

> I believe you should avoid sugared carbonated drinks before editing YANG modules, but maybe that wasn’t your question.

The question I had in mind was

actually deparses names
 > in a contributors section and does something with that information ?

and was asking whether by default or by option the names that are listed 
in a YANG module in an IETF I-D are treated in the same way as 
contributors section names are bearing in mind that YANG modules must be 
plain text?

Tom Petch

> .