Subject: Re: [Rfc-markdown] Author listing in XML and Markdown?

From: Carsten Bormann <[email-masked]>
Date: Thu, 12 Mar 2020 00:20:48 +0100

On 2020-03-11, at 23:16, Alice Russo <[email-masked]> wrote:
> 
> Hi Eric,
> 
> [CC'ing Carsten because perhaps he can share some kramdown-rfc2629 magic.]

I might be able to cook up some such magic if needed.

> There is no role="contributor". There is the new <contact> element in the xml2rfc v3 vocabulary, which is essentially the same as <author>. (For the v3 vocabulary, the RelaxNG is here: https://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc)
> 
> So, two methods come to mind:
> 1) Copy & paste the desired output (from a text file) into an <artwork> element in the contributors section.

… which looks quite ugly.

> 2) If using xml2rfc w/ the v3 vocabulary, you can simply change <author> to <contact> and put those elements directly into the contributors section.

So you have to put in that section manually, while the “authors’ addresses” section is put in by XML2RFC based on the front matter information.  Not something I would have designed…

But it is a small matter of programming to support this.  
Might do that later today (CET today).

So the idea would be that you have an additional YAML section for contributors, like this:

author:
 - name: Henk Birkholz
 - name: Max Pritikin
 - name: Robert Moskowitz
contributor:
 - name: Carsten Bormann

(I stripped out all the other metadata, I hope you get the idea.)
That makes it minimally painful to move people around between the two, which happens a lot because of the straightjacket that the five-author rule is.

Now how do we get this info into the Contributors Section (RFC 7322, 4.11).
As I said, this section is not automatically inserted by XML2RFC.
In the authoring XML, it is the last section (unnumbered) of the main body (i.e., before the back matter), so kramdown-rfc could simply insert it automatically there, just like xml2rfc then does with authors’ addresses.

The problem with that is that Contributors also can be more like a free text section, as in acknowledgements.  I’m not sure how those would mix in practice; I haven’t seen a Contributors section that had both contact info and free text.
(And no, I don’t know why this isn’t “contributors’ addresses".)

Of course, all this only works with v3 processing rules.

I’m CCing rfc-markdown and removing some text to make this less of a violation of etiquette, apologizing in advance if it still is.

Grüße, Carsten

---

From: Eric Gray <[email-masked]>
Date: Thu, 12 Mar 2020 14:26:04 +0000

Carsten,

	That would be great.  I have a list of names in that way now, which I have left in because I only get a warning that "contributor ... is not included" (keeps me from having to document the list elsewhere).

	An alternative I had tried was trying to use the "role" attribute under "author" (which is what I had to do to list myself and another person as "Editors").

	Everything I tried (obviously, other than "editor") gave an error that the attribute value was not in the enumerated set.

	But I had not tried using "contact."  Okay, I get the same error using role: contact.  Sigh.

	Is there some place where I could look to see what "role" attribute values are in the enumerated set; are there other enumerated sets that might be useful?

--
Eric

-----Original Message-----
From: Carsten Bormann <[email-masked]> 
Sent: Wednesday, March 11, 2020 7:21 PM
To: Alice Russo <[email-masked]>
Cc: Eric Gray <[email-masked]>; RFC Editor <[email-masked]>; RFC Markdown <[email-masked]>
Subject: Re: Author listing in XML and Markdown?

> There is no role="contributor". There is the new <contact> element in 
> the xml2rfc v3 vocabulary, which is essentially the same as <author>. 
> (For the v3 vocabulary, the RelaxNG is here: 
> https://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3
> .rnc)
> 

author:
 - name: Henk Birkholz
 - name: Max Pritikin
 - name: Robert Moskowitz
contributor:
 - name: Carsten Bormann

(I stripped out all the other metadata, I hope you get the idea.) That makes it minimally painful to move people around between the two, which happens a lot because of the straightjacket that the five-author rule is.

Grüße, Carsten

---

From: Eric Gray <[email-masked]>
Date: Thu, 12 Mar 2020 14:37:50 +0000

Carsten,

	Because I am using the GitHub "make" approach to construct/compile to XML and Text, I need to have a local version of kramdown-rfc2629. 

	On the plus side, I could be a "beta" tester for whatever you come up with - if you want...

--
Eric

-----Original Message-----
From: Carsten Bormann <[email-masked]> 
Sent: Wednesday, March 11, 2020 7:21 PM
To: Alice Russo <[email-masked]>
Cc: Eric Gray <[email-masked]>; RFC Editor <[email-masked]>; RFC Markdown <[email-masked]>
Subject: Re: Author listing in XML and Markdown?

author:
 - name: Henk Birkholz
 - name: Max Pritikin
 - name: Robert Moskowitz
contributor:
 - name: Carsten Bormann

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 12 Mar 2020 17:45:23 +0100

> So the idea would be that you have an additional YAML section for contributors, like this:

Done in 1.3.1.

Please update your local system using:

  gem update

Or more specifically

  gem update kramdown-rfc2629

Then move the authors that should be listed as contributors from author: to contributor:, as in:

author:
- name: Henk Birkholz
  org: Fraunhofer SIT
  abbrev: Fraunhofer SIT
  email: [email-masked]
  street: Rheinstrasse 75
  code: '64295'
  city: Darmstadt
  country: Germany
contributor:
- 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]

This only works under v3 processing rules, as v2 does not have the <contact> element needed for that; so you have to run kdrfc with -3 (or use Martin Thomson’s template).

You also (or alternatively) can add some text in the front of the contributors section (before the contacts are listed) by marking it with --- contributor, e.g. before --- abstract:

--- contributor

Because of the straightjacket 5-authors rule, the following co-authors
are not listed under the front page co-authors:

--- abstract

…

Enjoy, and please report any weirdness.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 12 Mar 2020 17:56:48 +0100

On 12.03.2020 17:45, Carsten Bormann wrote:
> ...

Um.

*Is* there a "straightjacket 5-authors rule"? Last time I checked
(admittedly a few years ago), it was just a recommendation, to be
negotiated with the powers-that-be?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 12 Mar 2020 18:13:40 +0100

> negotiated with the powers-that-be?

The straightjacket indeed is not made from Kevlar (see RFC 3095, or 8323 for a more recent example).  I’d still prefer a world where the RFC editor wouldn't have to enforce arbitrary rules like this just to push off all the honorary “authors” that would land on RFCs otherwise.  Or, in other words, this world does need straightjackets now and then, and I’m happy that there is *some* flexibility.  (I’ll use better example text in the documentation.)

Grüße, Carsten

---

From: Miek Gieben <[email-masked]>
Date: Thu, 12 Mar 2020 22:14:27 +0100

[ Quoting <[email-masked]> in "Re: [Rfc-markdown] Author listing i..." ]
>As I said, this section is not automatically inserted by XML2RFC.

Is this planned?

How do you tie a contact to a <section> or <t> in markdown ?

/Miek

--
Miek Gieben

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 12 Mar 2020 22:20:59 +0100

>> As I said, this section is not automatically inserted by XML2RFC.

Support for the contributors section is now in kramdown-rfc ≥1.3.1, please see
https://mailarchive.ietf.org/arch/msg/rfc-markdown/noq-4H1GeNMmIy0FYrfQWC1elfM
Documentation will be added RSN :-)

> How do you tie a contact to a <section> or <t> in markdown ?

You can use <contact> approximately everywhere, AFAIK; I don’t think it is documented outside mailing list messages.  Content model is like <author>.
Just use the XML inside the markdown.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 12 Mar 2020 22:23:06 +0100

> Done in 1.3.1.

And while I was hacking this, two more improvements in 1.3.2:

* kdrfc now has a -h/—-html flag that generates html alongside the txt (use --no-txt to suppress the latter).

So a typical thing you might do now is:

   kdrfc -3h foo.md
   open foo.html

I still need to hack the remote xml2rfc support, though, -rh gives an error at the moment.

* There is now experimental support for generating artsets.

Try

~~~~ goat
.---.
|o o|
| | |
| - |
|___|
~~~~

In markdown, this is a code block of type “goat”.
Special-casing this type, kdrfc then calls goat and svgcheck (which both must be in the path(*)) to generate SVG for use in the HTML, keeping the UTF-8 art (“ascii-art”) for use in the TXT.

Until I have learned how to properly shut up svgcheck (which seems to ignore its -q option), this will be a bit chatty.

If you want support for other ascii-art-to-SVG processors, please tell us.

I really want to do a version of mscgen (what UML calls sequence diagrams) next; if you have a favorite that can generate SVG that svgcheck groks and is reasonably easy to install, I’d like to know.

UML Flow charts?  Hand-drawn diagrams?  DOT/Graphviz?  Gantt diagrams?  Music?
Railroad charts?  You name it, you got it (as long as an SVG processor exists).

Grüße, Carsten

(*) The gem install will not try to find and install that for you.
Thomas has documented in his svg-test draft how to get these:

$ go get github.com/blampe/goat
$ pip install svgcheck

Of course you need go and python, which you might get via:

$ brew install go
(do read the hints output after install)
$ brew install python

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 13 Mar 2020 13:43:12 +0100

1.3.3: kdrfc now has a -p/—-prep flag that generates prepped XML alongside the other outputs

  kdrfc -ph3 foo.md
  open foo.html
  (Submit the foo.prepped.xml only.)

Grüße, Carsten