Subject: [Tools-discuss] auth48 diffs?

From: Jeffrey Hutzelman <[email-masked]>
Date: Tue, 01 Dec 2009 21:14:08 -0500

It's really useful that the HTML id/rfc interfaces let you flip between 
versions, perform diffs, and follow the lifetime of a document through 
multiple filenames and eventual publication as an RFC.  I use these 
capabilities a lot in reviewing documents, especially in managing WG 
documents to insure issues have been resolved as they approach WGLC and 
then make their way through the process.  I can't imagine handling such 
tasks without these features.

For documents in AUTH48, it would be terribly convenient for the version 
progression to extend into the RFC-to-be, so it is easy to examine 
differences between the last I-D version and the RFC-Editor's proposed 
final document.

-- Jeff

---

From: Julian Reschke <[email-masked]>
Date: Wed, 02 Dec 2009 09:41:56 +0100

Jeffrey Hutzelman wrote:
> ...

A simple way to achieve this would be the post the proposed final 
document as Internet Draft.

Best regards, Julian

---

From: Joe Touch <[email-masked]>
Date: Wed, 02 Dec 2009 07:16:11 -0800

Julian Reschke wrote:
> Jeffrey Hutzelman wrote:
>> It's really useful that the HTML id/rfc interfaces let you flip
>> between versions, perform diffs, and follow the lifetime of a document
>> through multiple filenames and eventual publication as an RFC.  I use
>> these capabilities a lot in reviewing documents, especially in
>> managing WG documents to insure issues have been resolved as they
>> approach WGLC and then make their way through the process.  I can't
>> imagine handling such tasks without these features.
>>
>> For documents in AUTH48, it would be terribly convenient for the
>> version progression to extend into the RFC-to-be, so it is easy to
>> examine differences between the last I-D version and the RFC-Editor's
>> proposed final document.
>> ...
> 

That would be sufficient for 6 months ;-)

Joe

---

From: Julian Reschke <[email-masked]>
Date: Wed, 02 Dec 2009 16:23:05 +0100

> That would be sufficient for 6 months ;-)

I thought we were talking about the services offered by tools.ietf.org, 
which indeed keeps the copies of expired drafts.

BR, Julian

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Wed, 02 Dec 2009 10:27:59 -0500

> document as Internet Draft.

That gets messy...  Posting a new I-D version requires cooperation of the 
document author, and will likely confuse the RFC-Editor.  Also, the "final" 
version tends to change frequently; posting each version as a new I-D could 
significantly increase the number of I-D versions on file for a document.

-- Jeff

---

From: Julian Reschke <[email-masked]>
Date: Wed, 02 Dec 2009 16:39:10 +0100

Jeffrey Hutzelman wrote:
> ...
> That gets messy...  Posting a new I-D version requires cooperation of 
> the document author, and will likely confuse the RFC-Editor.  Also, the 
> "final" version tends to change frequently; posting each version as a 
> new I-D could significantly increase the number of I-D versions on file 
> for a document.
> ...

Oh, I didn't realize that you wanted diffs for every single change.

In which case another obvious suggestion would be to have all changes 
being done in a revision control system with public read access.

Best regards, Julian

PS: I still think it would be good to post the the "final" text as an 
I-D for tracking purposes

---

From: Joe Touch <[email-masked]>
Date: Wed, 02 Dec 2009 07:47:42 -0800

> which indeed keeps the copies of expired drafts.

Hmm. The ISOC is allowed to keep copies for IPR reasons, but I wasn't
aware that they authorized the public posting of them after they have
expired.

There is a reason they expire. If this behavior continues, we should
either just publish IDs and skip the RFCs altogether, or just stop
writing IDs.

Joe

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Wed, 02 Dec 2009 10:50:58 -0500

> Oh, I didn't realize that you wanted diffs for every single change.

Well, I don't think we need to keep every (or any) intermediate version, 
but yes, it would be nice for an author or shepherd or AD to be able to see 
at any time during AUTH48 what the current differences are between the last 
I-D and the edited document, especially when the author and copy editor 
have had a long discussion about changes.

Note that AUTH48 can last a long time; for one recently published RFC, it 
took nearly 9 months.

> being done in a revision control system with public read access.

Yes, that would be useful.  How much ability do we have to influence the 
way the RFC Production Center does its work?

> PS: I still think it would be good to post the the "final" text as an I-D
> for tracking purposes

I'm not sure why -- it's the same as the published RFC, and the tools 
already provide convenient access to that.

---

From: Julian Reschke <[email-masked]>
Date: Wed, 02 Dec 2009 17:00:09 +0100

> already provide convenient access to that.

The main reason I can think of is that publication as an ID would 
potentially *prevent* something to be published as RFC; so it would be 
for community review, albeit for a very short time (a few days)?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 2 Dec 2009 17:26:50 +0100

On Dec 2, 2009, at 16:50, Jeffrey Hutzelman wrote:

> Well, I don't think we need to keep every (or any) intermediate version, but yes, it would be nice for an author or shepherd or AD to be able to see at any time during AUTH48 what the current differences are between the last I-D and the edited document, 

I'm a bit confused by this discussion.
The RFC editor tends to put out files like

http://www.rfc-editor.org/rfc/authors/rfc5756-diff.html

which I have used a lot during AUTH48.
(Yes, these go away when the RFC has been published, so I'm pointing to a random current one.)

What would a tools implementation add?

Gruesse, Carsten

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Wed, 02 Dec 2009 11:45:25 -0500

--On Wednesday, December 02, 2009 05:26:50 PM +0100 Carsten Bormann 
<[email-masked]> wrote:

>> but yes, it would be nice for an author or shepherd or AD to be able to
>> see at any time during AUTH48 what the current differences are between
>> the last I-D and the edited document,
>

- colored diffs (the "diff2" link) which IMHO are much more usable
- easy reference from the hTML I-D page
- all of the usual bells and whistles on the HTML I-D page

-- Jeff

---

From: Adam Roach <[email-masked]>
Date: Wed, 02 Dec 2009 10:55:20 -0600

On 12/2/09 10:45 AM, Jeffrey Hutzelman wrote:
>> (Yes, these go away when the RFC has been published, so I'm pointing 
>> to a
>> random current one.)
>>

http://tools.ietf.org//rfcdiff?url1=draft-ietf-pkix-rfc4055-update-02&url2=http://www.rfc-editor.org/rfc/authors/rfc5756.txt

/a

---

From: Alice Hagens <[email-masked]>
Date: Wed, 2 Dec 2009 13:00:00 -0500

As Carsten pointed out, the AUTH48 notification message from the RFC  
Editor includes a link to the diff file (e.g., http://www.rfc- 
editor.org/authors/rfc5687-diff.html). Also, there is a link to the  
diff file from the AUTH48 status page, e.g., http://www.rfc- 
editor.org/auth48/rfc5687.

The AUTH48 diff files are provided for the authors' convenience.  
IMHO, the intermediary versions between approved Internet-Draft and  
published RFC are for author review, not for posting as I-Ds.

> - colored diffs (the "diff2" link) which IMHO are much more usable

As for using rfcdiff (a.k.a. Diff2) instead of htmlwdiff (a.k.a.  
Diff1) for AUTH48 purposes, one reason we prefer htmlwdiff is because  
it shows the document as a whole, not just the portions containing  
changes. The htmlwdiff file contains the whole document, thus  
providing the context of the changes. (For example, this is needed  
when reviewing changes made for consistency within a document.)

Although if you want the rfcdiff file, as Adam pointed out, it is  
easy to view:
> http://tools.ietf.org//rfcdiff?url1=draft-ietf-pkix-rfc4055- 
> update-02&url2=http://www.rfc-editor.org/rfc/authors/rfc5756.txt

We welcome suggestions, and we'll investigate the issue more post- 
transition.

Thank you.

Alice
for the RFC Editor

On Dec 2, 2009, at 11:26 AM, Carsten Bormann wrote:

>> Well, I don't think we need to keep every (or any) intermediate  
>> version, but yes, it would be nice for an author or shepherd or AD  
>> to be able to see at any time during AUTH48 what the current  
>> differences are between the last I-D and the edited document,
>
> _______________________________________________
> Tools-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-discuss

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Wed, 02 Dec 2009 13:56:53 -0500

--On Wednesday, December 02, 2009 01:00:00 PM -0500 Alice Hagens 
<[email-masked]> wrote:

> The AUTH48 diff files are provided for the authors' convenience. IMHO,
> the intermediary versions between approved Internet-Draft and published
> RFC are for author review, not for posting as I-Ds.

I agree.

> As for using rfcdiff (a.k.a. Diff2) instead of htmlwdiff (a.k.a. Diff1)
> for AUTH48 purposes, one reason we prefer htmlwdiff is because it shows
> the document as a whole, not just the portions containing changes. The
> htmlwdiff file contains the whole document, thus providing the context of
> the changes. (For example, this is needed when reviewing changes made for
> consistency within a document.)

This is a matter of taste.  The rfcdiff output uses a color scheme that, at 
least for me, makes changes stand out more.  As you note, htmlwdiff shows 
the entire document, which can be very useful, except, perhaps, when the 
document is NFSv4. :-)

In addition, the two tools use slightly different algorithms for 
identifying word-level differences.  In a document with complicated 
changes, sometimes one does a better job than the other at calling out the 
real changes without lots of spurious garbage.  I've had at least one 
document where I actually used both, because it was the only way to wrap my 
head around the changes while retaining my sanity (IIRC, that was in 
dealing with post-last-call changes, rather than AUTH48).

> We welcome suggestions, and we'll investigate the issue more
> post-transition.

Thanks.  Over the past several years, the various tools available (both 
official and unofficial) and the level of user interface integration has 
gone way up, which I think makes things easier for everyone.  This is, or 
at least I thought it was, a suggestion for something hopefully relatively 
simple the tools team could do (in their copious free time) to improve 
integration of existing tools.

-- Jeff

---

From: <[email-masked]>
Date: Thu, 3 Dec 2009 10:11:32 +0100

Jeffrey Hutzelman wrote:

> This is a matter of taste.  The rfcdiff output uses a color scheme
> that, at least for me, makes changes stand out more.  

Not only taste! The htmlwdiff output assumes that red text stands out
very clearly from green text, and vice versa.

This is not the case for ~7% of male RFC authors, who have genes that
"moderately affect red-green hue discrimination" (to use a phrase from
http://en.wikipedia.org/wiki/Color_blindness -- you can tell red and
green apart, but red text doesn't immediately stand out from green
text, or vice versa).

The color scheme used in rfcdiff relies much less on red-green hues. 

Best regards,
Pasi

---

From: Lars Eggert <[email-masked]>
Date: Thu, 3 Dec 2009 14:08:10 -1000

> That would be sufficient for 6 months ;-)

Drafts don't time out anymore during and after IESG evaluation, so this would actually work fine IMO.

Lars