Subject: [rfc-i] contacts section?

From: Miek Gieben <[email-masked]>
Date: Fri, 26 Feb 2021 10:27:12 +0100

Hello,

I've recently added support for contacts in mmark and this allowed to play with it some
more. This showed it's very hard to discover that a person named as a contact is in fact a
<contact>. The txt and html rendering just show the full name of the person as if I typed
that directly.

I was (naively?) expecting a Contacts section, just like the "Author's Addresses' that
lists some more information, or another way to see that more information is available.

Prior discussion, but not exactly here (also closed):

* https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/81, which points to
https://tools.ietf.org/html/rfc7322#section-4.11 which makes it sound we can't auto generate
such a section?

And https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/185 to fully document
the <contact> element.

/Miek

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

---

From: Julian Reschke <[email-masked]>
Date: Fri, 26 Feb 2021 10:35:41 +0100

> <contact>. The txt and html rendering just show the full name of the

That's what happens when you use <contact> inside a text flow. This was
added relatively recently to allow non-ASCII characters in names.

The *original* intent was to <contact> to work exactly like <author>,
except that you place it as a child element of <section> (and you could
call that section anything you want). See
<https://greenbytes.de/tech/webdav/draft-iab-rfc7991bis-latest.html#element.contact>.

> lists some more information, or another way to see that more information

There is no auto-generated section (and AFAICT, it's not needed).

> ...

Best regards, Julian

---

From: Miek Gieben <[email-masked]>
Date: Fri, 26 Feb 2021 11:01:16 +0100

[ Quoting <[email-masked]> in "Re: [rfc-i] contacts section?..." ]
>added relatively recently to allow non-ASCII characters in names.

Ok...

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

So the process then is that I add all the contacts in the text (if I need to reference
them in the text somewhere) and then create a section and add a (sub)set of contacts that
are then rendered differently?

This also means I can't put attribution here? I.e. "Sam wrote section 5", because that
would need to be in a <t> ?

>There is no auto-generated section (and AFAICT, it's not needed).

Just generating such a section with all the given metadata would make the element more
useful (but IMO)

/Miek

---

From: Julian Reschke <[email-masked]>
Date: Fri, 26 Feb 2021 11:51:05 +0100

> would need to be in a <t> ?

You can do something like:

<section name="Contacts">
<contact fullname="Sam Whatever" ...>
</contact>
<t>Sam wrote <xref. .../>.</t>
</section>

> Just generating such a section with all the given metadata would make

The style guide does not mention a specific format for contact or
acknowledgements. Thus it's up to you. <contact> allows you to insert
information to be rendered the same way as for <author>; that's all.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 26 Feb 2021 13:18:03 +0100

V3 has a contributors section.
Kramdown-rfc can generate that from metadata that look exactly like author metadata (so it’s easy to shift back and forward).
What we don’t have is a way to add annotations to that (no extra RFCXML support needed, as the kramdown-rfc result would then look a lot like the below).

Grüße, Carsten

> On 26. Feb 2021, at 11:51, Julian Reschke <[email-masked]> wrote:
>

---

From: Miek Gieben <[email-masked]>
Date: Fri, 26 Feb 2021 13:28:21 +0100

>information to be rendered the same way as for <author>; that's all.

after private email exchange this is clearup. Direct <contact> elements as a child of
<section> are rendered as expected.

Remaining question (for me), is how to allow this in markdown.

---

From: Julian Reschke <[email-masked]>
Date: Fri, 26 Feb 2021 13:29:44 +0100

> V3 has a contributors section.

The xml2rfc grammar has no specific support for a "contributors" section.

You can use a regular appendix, and fill it with prose and <contact>
elements.

Note: from the RFC point of view, "authors" and "contributors" are very
different things. The former appear on the front page and participate in
AUTH48.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 26 Feb 2021 16:07:44 +0100

1.3.37: contributors to be listed in the contributor section can now be annotated with text that will be added to that section after their contact information.

The text is entered in the “contribution” entry of the contact information for a contributor.
It is markdown and can contain paragraph breaks and other markup, as shown below (with some author information as context, which is not shown in the rendering).
Note that YAML has the “|” syntax that is strongly recommended for entering markdown text into YAML entries.

author:
  - name: Carsten Bormann
    org: Universität Bremen TZI
    email: [email-masked]
contributor:
  - name: Peter Occil
    email: poccil14 at gmail dot com
    contribution: |
      Peter Occil registered tags 30, 264, 265, 268–270
      ({{advanced-arithmetic}}), 38, 257, 266 and 267
      ({{domain-specific}}), and contributed much of the text about
      these tags in this document.
  - name: Jane Doe
    org: To do
    contribution: |
      Further contributors will be listed here as text is added.

      Plase stay tuned.

➔ 

Contributors

   Peter Occil

   Email: poccil14 at gmail dot com

   Peter Occil registered tags 30, 264, 265, 268-270 (Section 6.1), 38,
   257, 266 and 267 (Section 7), and contributed much of the text about
   these tags in this document.

   Jane Doe
   To do

   Further contributors will be listed here as text is added.

   Plase stay tuned.

Note that the text rendition of the XML generated contains some spurious empty lines between contact and text; there is no obvious workaround until this is fixed in xml2rfc.  The HTML seems fine.

Grüße, Carsten

> On 2021-02-26, at 13:18, Carsten Bormann <[email-masked]> wrote:
>