Subject: [xml2rfc] New xml2rfc release: v2.22.3

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 08 Apr 2019 04:18:44 -0700

Hi,

This is an automatic notification about a new xml2rfc release, 
v2.22.3, generated when running the mkrelease script.

Release notes:

xml2rfc (2.22.3) ietf; urgency=medium

  This release brings further tweaks and imporvements to the v3 text
  format output in the area of Table of Content formatting, and fixes a
  number of bugs.

  * Tweaked the handling of ToC page numbers in the v3 text format.

  * Tweaked the xml inserted by the preptool for the ToC to give ToC
    indentation and spacing which better match the legacy text format
    (and also looks better).

  * Added a rewrite of <svg> viewBox values to the simplest acceptable
    format, to make sure it will be understood by our pdf generation libs.

  * Added a test case for <xref section=...>

  * Tweaked the section label for fragment <xref> rendering to say
    'Appendix' instead of 'Section' for appendix references.

  * Added a pre-rfc1272 reference to elements.xml to test the author
    initials handling for early RFCs.

  * Tweaked the get_initials() code for use on <reference> authors.
    Refactored part of the text.render_reference() code to support
    get_initials() properly.

  * Added special initials handling for RFCs 1272 and below, to apply the
    single initials handling enforced at that time.

 -- Henrik Levkowetz <[email-masked]>  04 Apr 2019 15:12:43 +0000

The preferred way to install xml2rfc is by doing 'pip install xml2rfc',
and 'pip install --upgrade xml2rfc' to upgrade.  If there are system-
installed python modules which pip will not upgrade, you may have to
use 'pip install --upgrade --no-deps xml2rfc' and install dependencies
manually.

The new version is also available through SVN checkout, with
  'svn checkout http://svn.tools.ietf.org/svn/tools/xml2rfc/tags/cli/2.22.3'

Regards,

	Henrik
	(via the mkrelease script)

---

From: Julian Reschke <[email-masked]>
Date: Mon, 8 Apr 2019 13:50:52 +0200

On 08.04.2019 13:18, Henrik Levkowetz wrote:
> ...

Shouldn't the initials handling depend on what RFC the reference appears
in (as opposed to what RFC is being cited)???

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Apr 2019 13:21:44 +0200

Hi Julian,

> in (as opposed to what RFC is being cited)???

The RFC-Editor has requested that the rendering should match the front page
of the RFC in question, and provided the information that RFC 1272 and
earlier should be limited to one initial, irrespective of what's given in
the <reference> entry.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Apr 2019 13:37:39 +0200

> earlier should be limited to one initial, irrespective of what's given in

Wow, a nice new requirement.

It would be great if changes like these would be communicated by the RFC
Editor. (Or did I miss something?)

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Apr 2019 13:47:00 +0200

> Editor. (Or did I miss something?)

This came up as a difference between the legacy rendering and the v3 rendering.
I haven't dug into exactly which heuristics the legacy rendering used to
make the distinction.  The idea that the reference entries should reflect
what was actually published isn't new; if anything it's been a consistent
expectation for a long long time.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Apr 2019 14:11:03 +0200

> expectation for a long long time.

...but in that case the information would need to be present in the
<reference>s (files). Otherwise the knowledge needs to be hard-wired
into the renderer which IMHO doesn't make any sense.

Best regards, Julian

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Tue, 9 Apr 2019 12:11:19 +0000

On 4/9/19, 7:47 AM, "Rfc-markdown on behalf of Henrik Levkowetz" <[email-masked] on behalf of [email-masked]> wrote:

How is the requirement to generate a single initial communicated within the XML? By looking at the RFC number? Or by a different attribute specified somewhere? While using the RFC number might seem simpler, I think it's better to be transparent and use an attribute.

	Tony

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Apr 2019 14:19:08 +0200

> How is the requirement to generate a single initial communicated within the XML? By looking at the RFC number? Or by a different attribute specified somewhere? While using the RFC number might seem…

Yes.

But we really should ask the RFC Editor whether they are sure about
this. After all, it seems to be a violation of the style guide:
<https://tools.ietf.org/html/rfc7322#section-4.8.6.2>.

Best regards, Julian

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Tue, 9 Apr 2019 15:37:04 +0000

On 4/9/19, 8:19 AM, "Julian Reschke" <[email-masked]> wrote:

    Yes.

For re-rendering old RFCs that were originally written using a previous style guide? The interesting thing about style guides is that they do change over time.

I know that we've had various means of doing these stylistic machinations through the years, such as code that says "if rfc number < some value, do this special stylistic processing" or "if public date is before some value, do this special stylistic processing ". The reason I asked my question was that I don't know how the current V3 code is making its decisions for these stylistic issues. My suggestion above is that instead of having code like that, it should instead be "if some <rfc> attribute is set, do this to the initials". 

	Tony

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Apr 2019 18:01:00 +0200

> For re-rendering old RFCs that were originally written using a previous style guide? The interesting thing about style guides is that they do change over time.

Yes, but in that case the rendering depends on the RFC the reference
appears in, not on the referenced document.

FWIW, it would be great if revisions to the style guide also defined a
precise start date from which the rules apply.

Best regards, Julian

---

From: Heather Flanagan <[email-masked]>
Date: Tue, 9 Apr 2019 10:34:38 -0700

> On Apr 9, 2019, at 09:01, Julian Reschke <[email-masked]> wrote:
> 

Hi all,

I’m discussing this with Sandy and Alice now; a response to the list may take a day or so as I’m traveling at the moment.

-Heather

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 11 Apr 2019 08:06:12 -0700

> On Apr 9, 2019, at 10:34 AM, Heather Flanagan <[email-masked]> wrote:
> 
> 
> 

And coming back to this:

A longstanding principle for referencing RFCs is to make the reference match what is on the front page of the RFC itself, over what information is in any other location. This is something we should be clearer about in the Style Guide, but it is a practice we’ve enforced for quite a long time. 

Changing the tool to match this longstanding practice is not ideal, but it is expedient given that the proper way to handle this is an extensive data cleanup of the citation library. I’ve asked the RPC to prioritize getting documents published and format implementation over this kind of data cleanup for now. 

-Heather Flanagan

---

From: Julian Reschke <[email-masked]>
Date: Thu, 11 Apr 2019 17:10:44 +0200

On 11.04.2019 17:06, Heather Flanagan wrote:
> ...
> And coming back to this:
>
> A longstanding principle for referencing RFCs is to make the reference
> match what is on the front page of the RFC itself, over what information
> is in any other location. This is something we should be clearer about
> in the Style Guide, but it is a practice we’ve enforced for quite a long
> time.
>
> Changing the tool to match this longstanding practice is not ideal, but
> it is expedient given that the proper way to handle this is an extensive
> data cleanup of the citation library. I’ve asked the RPC to prioritize
> getting documents published and format implementation over this kind of
> data cleanup for now.
> ...

FWIW, this indeed is *not* a change in the style, as far as I can tell.

Rather than that, it just highlights an inconsistency between the
published <reference> elements and the actual RFCs.

The fix IMHO is to fix the <reference> files when the problem shows up.

Putting extra logic into the formatter seems to be clearly the wrong
approach.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Apr 2019 07:23:47 +0200

> in the Style Guide, but it is a practice we’ve enforced for quite a long

If you're not planning a revision anytime soon, you may want to document
this in detail at <https://www.rfc-editor.org/styleguide/part2/> or file
an erratum.

> getting documents published and format implementation over this kind of

I still don't get this. Is there a well-defined algorithm to decide the
detailed format? I guess so, otherwise it could not be placed into the
formatter. In this case, please publish it. And if there is one, just
get the <reference> files updated accordingly. (And yes, I volunteer, if
the algorithm is clear).

Best regards, Julian

---

From: Heather Flanagan <[email-masked]>
Date: Mon, 22 Apr 2019 07:35:23 -0700

> this in detail at <https://www.rfc-editor.org/styleguide/part2/> or file

I agree - I’ll work with the RPC on updating the web portion of the style guide.

> get the <reference> files updated accordingly. (And yes, I volunteer, if

Ah, volunteering! I love that! Let me talk to Sandy and Alice to see how best to move this forward.

-Heather

---

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Apr 2019 20:31:05 +0200

> best to move this forward.

Can we start with a precise problem statement? How exactly is the rule
for initials for author names different in these ancient RFCs?

Best regards, Julian