Subject: [rfc-i] AUTH48 workflow [was [Rfced-future] Welcome to the RFC Editor Future Development Program]

From: Brian E Carpenter <[email-masked]>
Date: Thu, 2 Apr 2020 16:32:50 +1300

On 02-Apr-20 16:14, Larry Masinter wrote:
> I think what I'm calling the "AUTH48" problem was greatly exacerbated by the format switch, making the normal publishing process of reviewing "galley proofs" to be too onerous for those familiar with the material vs. the RFC Editor who has enough to worry about without knowing what might or might not be significant elements of typography, spacing, emphasis in formats that the author didn't even review (text, html, pdf)
> 
> IMHO, the "real problem" from a publishing workflow point of view  is that there is a workflow task that is not explicitly assigned, namely to validate that the to-be-published RFC, in all its published formats, reflects the intent of the author and the body that approved it.

That's *exactly* the purpose of AUTH48, and that's why AUTH48 sometimes lasts much longer than 48 hours. In my experience, ADs and WG chairs are often involved in discussion of whether certain changes are editorial or substantive.

I have no experience of AUTH48 for the v3 format, but I find reviewing v3 HTML documents much easier than txt. (For only reviewing diffs, txt remains better. But at AUTH48 one is explcitly asked to review the whole document.)

In any case, I am sure this is off topic for the rfced-future list, so I switched lists.

    Brian
> 
> It's easy to imagine the results would be a lot of unmet expectation and finger pointing, and arguments about what the "real problem" was.
> --
> https://LarryMasinter.net
> 
>   
> 
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Eric Rescorla <[email-masked]>
Date: Wed, 1 Apr 2020 21:14:54 -0700

On Wed, Apr 1, 2020 at 8:32 PM Brian E Carpenter <
[email-masked]> wrote:

> > I think what I'm calling the "AUTH48" problem was greatly exacerbated by
> the format switch, making the normal publishing process of reviewing
> "galley proofs" to be too onerous for those familiar with the material vs.
> the RFC Editor who has enough to worry about without knowing what might or
> might not be significant elements of typography, spacing, emphasis in
> formats that the author didn't even review (text, html, pdf)
> >
> > IMHO, the "real problem" from a publishing workflow point of view  is
> that there is a workflow task that is not explicitly assigned, namely to
> validate that the to-be-published RFC, in all its published formats,
> reflects the intent of the author and the body that approved it.
>
> That's *exactly* the purpose of AUTH48, and that's why AUTH48 sometimes
> lasts much longer than 48 hours. In my experience, ADs and WG chairs are
> often involved in discussion of whether certain changes are editorial or
> substantive.
>
> I have no experience of AUTH48 for the v3 format, but I find reviewing v3
> HTML documents much easier than txt. (For only reviewing diffs, txt remains
> better. But at AUTH48 one is explcitly asked to review the whole document.)
>

FWIW, I usually find it necessary to review both the diffs and the whole
document: the diffs to highlight what changes have been made in processing
and the whole document as a final sanity check. Indeed, I would find it
helpful to review multiple stages of diff that reflected different types of
transformation, such as (a) rfc styling (b) copy-edit, etc.

-Ekr

>     Brian
> >
> > It's easy to imagine the results would be a lot of unmet expectation and
> finger pointing, and arguments about what the "real problem" was.
> > --

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 06 Apr 2020 11:42:35 +1000

Moving over to a more appropriate venue.

On Sat, Apr 4, 2020, at 07:32, Brian E Carpenter wrote:
> > The (canonical, published) XML never ever should be adjusted to work
> > around a bug. Is this happening?
>  
> <heresyAlert>It should be happening. 

Hooray for sensible conclusions!  The how part is tricky though if we believe that there is a point in time at which a document becomes immutable.

> Obviously we must not update the substantive content, 

It is not clear to me that this is so different than an obvious editorial error.

Take this erratum for example: https://www.rfc-editor.org/errata/eid5031

That's not a substantive, nor do I think it would be hard to get people to agree that it is wrong.  However, it would require a change to text and not markup.  In some versions of document production, this sort of error is the result of not using semantic markup correctly, as you will see sometimes.

So you might infer from this that it is acceptable to change the way in which XML elements are structured in a way that does not change text, but instead only changes the types of elements and their attributes.  But it is sometimes the case that XML attributes carry semantics.

Take this example of the v2 XML:

<list style="hanging">
  <t hangText="Name:">Value</t>
  <t hangText="Key:">Semantic</t>
</list>

As an aside, I often see this instead, which is much worse, especially when you render to HTML (I've also seen people use <artwork> for this stuff):

<t>Name: Value</t>
<t>Key: Semantic</t>

Ideally, this becomes v3 XML:

<dl newline="false" spacing="normal">
  <dt>Note:</dt><dd>Value</dd>
  <dt>Key:</dt><dd>Semantic</dd>
</dl>

Here, we added attributes with values.  But we also converted attributes that carry meaning into elements.  So it's not a simple rule.  And maybe we altered whitespace in ways that might not be good, especially if we converted from the semantic-free form.

That is a long way of saying that the lines are necessarily crisp.  From here we might take a number of paths, but I think that you identify the most important baseline:

> and we should have an audit trail, 

Absolutely.  I think that improving the audit trail should always be a goal.  The requirements for clear and discoverable audit history increases as documents pass crucial control points in our processes.  That includes WGLC, and just about the entire path from there forward.

> but only by doing such updates can we have a reasonable situation at the end.

That seems like the right goal.

> If there isn't a v3.n sub-version number in the XML files today, there 
> certainly should be.</heresyAlert>

Is the date insufficient?  That is, we could decide to process a document by pretending that we have the limited knowledge and tools of the date of publication.

I realize that means we will have to learn that RFC XXXX is insufficiently precise a reference and that RFC XXXX at date Y is probably better, but you will find that most documents that cite RFCs have their own publication dates that can be used to provide a value for Y.

That would be a good outcome.

--Martin

---

From: "John Levine" <[email-masked]>
Date: 5 Apr 2020 22:58:13 -0400

In article <[email-masked]> you write:
>So you might infer from this that it is acceptable to change the way in which XML elements are structured in
>a way that does not change text, but instead only changes the types of elements and their attributes.  But
>it is sometimes the case that XML attributes carry semantics.

What I had in mind in that case was that the semantics however expressed wouldn't
change.  I completely agree that there are lots of markup changes that have semantic
meaning.

However, ...

>Is the date insufficient?  That is, we could decide to process a document by pretending that we have the
>limited knowledge and tools of the date of publication.

If we're going to bite the bullet and join the world of updatable
documents, we might as well use version numbers like everyone else
does.

Who knows, we might even be like the IEEE and do revisions (not just
errata) where they keep the document number and update the version
number.  Seems to work OK.

R's,
John

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 6 Apr 2020 08:54:02 +0200

> documents, we might as well use version numbers like everyone else

Well, everybody else is struggling to move from EcmaScript 6 to EcmaScript 2015.
This of course works best when the publishers have established a rhythm (e.g., every year, as in this case, or maybe twice a year).

(Date of publication ≠ date of tool interface in use, though.)

((There is an ongoing discussion of protocol versions, protocol features, and document revisions in T2TRG right now, so I couldn’t resist.  Oh, and for ECMAScript the number counts “editions”, a term I didn’t have in active use in that discussion yet.))

Grüße, Carsten