Subject: [Xml-sg-cmt] Pressing question for (at the latest) Monday's call

From: Robert Sparks <[email-masked]>
Date: Thu, 25 Mar 2021 13:43:46 -0500

All:

There is a decision we need to (re) make wrt what is included in the 
canonical xml by the preptool.

Please review

https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/460

and

https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/607

The essence is whether the ToC, Index, and "authors" sections should be 
included in the canonical xml.

The argument against is that these things are derived from other parts 
of the document already, and should not be repeated.

The argument for is that, for better or worse, there are assumptions 
being made in the creation of these things that need to be captured in 
the canonical form so that it would be possible to render a new format 
reflecting what the other formats already say. These are hard to see and 
make explicit because they are "obvious" to everyone right now. They may 
not be so obvious when we recognize issues with them in the future.

Many of the past discussions of this have been couched in the 
implementation details. There is an argument over whether having the 
calculation once in the preptool vs repeating the computation in the 
formatters is the right design choice. This group should be aware of 
that tension, but not focus on it. We should focus on the value or harm 
of having information like this added to the canonical format without 
regard to how the current tooling works.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 25 Mar 2021 20:52:56 +0100

> regard to how the current tooling works.

A few more thoughts:

- for the boilerplate, the design team added a special element with
well-defined processing
- the toc started as a regular <note> element, but was (thankfully)
later moved into a specific element
- the authors section is currently "prepped" into a regular appendix;
formatters that run on preptool output need special logic to remove it
again; also, <author> was added as a child element of <section> which
doesn't make any sense at all
- formatting attributes ("bare") were added for the sole purpose of
rendering these autogenerated parts

All of this "bleeds" into the authoring format (see, for instance,
<https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/547>). These
changes do not belong there.

I understand that the canonical format currently is used as intermediate
format to feed the renderers. Don't. The audience for the grammar is for
*authoring*, not for internal workflows in xml2rfc.

Yes, having an intermediate format before the final rendering step is a
valid design; it just should not affect the authoring nor the archival
format.

Best regards, Julian

---

From: "John R Levine" <[email-masked]>
Date: 25 Mar 2021 17:55:30 -0400

> The argument against is that these things are derived from other parts of the 
> document already, and should not be repeated.

I think that Julian is clearly correct, and the canonical version should 
not have stuff that is mechanically generated from other parts of the XML. 
It's not good design -- if the two don't match, which one do you believe?

The practical problem is how far that is from the way that xml2rfc work 
now and how hard would it be to get there.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly