Subject: [Rfc-markdown] 1.5.26: Initials

From: Carsten Bormann <[email-masked]>
Date: Thu, 10 Feb 2022 02:30:36 +0100

I have just pushed kramdown-rfc version 1.5.26 (see discussion about Ruby versions).

This release mainly focuses on author information (both for the document itself and in references), and in particular provides access to the asciiXXX attributes that RFCXMLv3 provides to be able to render Latin (not necessarily ASCII) variants of non-Latin names used in author info, contributor info, and in references.  This support is unfortunately hobbled by a few xml2rfc bugs; I’ll announce the feature more properly when we have progress on these.

The change that was long overdue and was forced due to the above changes is better support for generating initials.

As discussed in various fora, we really should get rid of the habit of shortening names into initials.  But it is what we have in RFCXML, the references database, as well as in the most recent style guide RFC 7322, so we need to work with them.

Today, many people provide both the initials and the fullname in a construct like:

authors:
  - ins: C. Bormann
    name: Carsten Bormann

kramdown-rfc2629 now takes care to generate the “ins” from the “name”, so it is no longer necessary to put in the ins:

authors:
  - name: Carsten Bormann

The heuristics can handle hyphenated names:

  - name: Jean-Pierre Paul

The heuristics need help with complex last names:
Just separate the first names from the last name with a pipe:

  - name: Jean-Pierre | Paul de Vera

(Note that “Paul de Vera” is the last name; this is needed often for Spanish last names, but also for “van der Stok” and “von Schneider” etc.
The pipe of course doesn’t make it through to the fullname attribute.)

As far as I can see, the heuristics now work very well.  

However, there is one snag:

  - name: Richard L. Barnes

Leads to a full set of initials on the front page:

                           R. L. Barnes

(And “Richard L. Barnes” in the authors’ addresses section, as it should.)

This initialization is as it should be, but not the current practice (*).
So in this case, if you really want/need to emulate current practice, you have to play the “ins” game or explicitly give the “initials” attribute to override the heuristic for the frontpage.

  - ins: R. Barnes
    name: Richard L. Barnes

  - name: Richard L. Barnes
    initials: R.

Grüße, Carsten

(*)
RFC 7322 says:

4.1.1:
   The author's name (initial followed by family name) appears on the
   first line of the heading.  Some variation, such as additional
   initials or capitalization of family name, is acceptable.  Once the
   author has selected how their name should appear, they should use
   that display consistently in all of their documents.

4.8.6.2:
      [RFCXXXX] Last name, First initial., Ed. (if applicable),
                "RFC Title", Sub-series number (if applicable),
                RFC number, Date of publication,
                <http://www.rfc-editor.org/info/rfc#>.

There are enough cases that look somewhat different, so I was not able to really derive a rule here:

RFC 7693:
   Markku-Juhani O. Saarinen (editor)
   Jean-Philippe Aumasson
➔
7693 The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC).
     M-J. Saarinen, Ed., J-P. Aumasson. November 2015. (Format: TXT,
     HTML) (Status: INFORMATIONAL) (DOI: 10.17487/RFC7693) 

RFC 8585:
   Jordi Palet Martinez     [a Spanish name]
   Hans M.-H. Liu           [Chinese name with “English” given name added?]
➔
8585 Requirements for IPv6 Customer Edge Routers to Support
     IPv4-as-a-Service. J. Palet Martinez, H. M.-H. Liu, M. Kawashima.
     May 2019. (Format: TXT, HTML) (Status: INFORMATIONAL) (DOI:
     10.17487/RFC8585)

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 10 Feb 2022 13:45:10 +1100

Thanks for doing this Carsten.  I would like to suggest that the solution here might be less necessary if we didn't have publication formats that insisted on using initials.

What this change means is that now that I have stopped adding "ins", it will be added for me.  I'd rather it not exist at all.

On Thu, Feb 10, 2022, at 12:30, Carsten Bormann wrote:
> This release mainly focuses on author information (both for the 
> document itself and in references), and in particular provides access 
> to the asciiXXX attributes that RFCXMLv3 provides to be able to render 
> Latin (not necessarily ASCII) variants of non-Latin names used in 
> author info, contributor info, and in references.  This support is 
> unfortunately hobbled by a few xml2rfc bugs; I’ll announce the feature 
> more properly when we have progress on these.
>
> The change that was long overdue and was forced due to the above 
> changes is better support for generating initials.
>
> As discussed in various fora, we really should get rid of the habit of 
> shortening names into initials.  But it is what we have in RFCXML, the 
> references database, as well as in the most recent style guide RFC 
> 7322, so we need to work with them.
>
> kramdown-rfc2629 now takes care to generate the “ins” from the “name”, 
> so it is no longer necessary to put in the ins:
>
> authors:
>   - name: Carsten Bormann
>
> (Note that “Paul de Vera” is the last name; this is needed often for 
> Spanish last names, but also for “van der Stok” and “von Schneider” etc.
> So in this case, if you really want/need to emulate current practice, 
> you have to play the “ins” game or explicitly give the “initials” 
> attribute to override the heuristic for the frontpage.
>
>   - ins: R. Barnes
>     name: Richard L. Barnes
>
> _______________________________________________
> Rfc-markdown mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/rfc-markdown

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 10 Feb 2022 07:14:23 +0100

> Thanks for doing this Carsten.  I would like to suggest that the solution here might be less necessary if we didn't have publication formats that insisted on using initials.

Indeed.  But this is a discussion for rfc-interest (or, really, for the new RSWG mailing list).

> What this change means is that now that I have stopped adding "ins", it will be added for me.  I'd rather it not exist at all.

Note that kramdown-rfc had heuristics for this before, they just weren’t quite as good.
If you want to circumvent the kramdown-rfc heuristics, just access the fullname attribute directly instead of using the name: construct:

  — fullname: Martin Thomson

Then you'll get the xml2rfc heuristics, applied during rendering.
(And/or later the RFC-Editor’s heuristics, applied during editing…)

Grüße, Carsten