Subject: RFC 2616, partitioned

From: "Roy T. Fielding" <[email-masked]>
Date: Tue, 16 Oct 2007 19:03:40 -0700

I spent much of the last month fiddling with RFC 2616 and the
various ways that it could be partitioned into the original design
layers of the protocol.  The result is at

   http://labs.apache.org/webarch/http/draft-fielding-http/

and demonstrates that the protocol can be described in smaller
documents without requiring cross-references all over the place.
In fact, the only cross-references left are editorial in nature
or places where caching tries to redundantly define other
aspects of the protocol.

However, it is far from being readable at this stage.  In fact,
it shows how little of the operational aspects of the protocol
were described in 2616 due to the pressure not to make the big
document any bigger, and how frequently the cross-references
in 2616 point to sections that have little (if any) relevance
to the discussion.

I was trying to minimize changes from RFC 2616, so haven't
rearranged the sections where they would logically belong (aside
from one example of chunked decoding pseudocode that was moved
from an appendix to the one section that referred to it).
Before doing any further structural changes, I want to commit all
of the editorial changes from the errata (as tracked under the
link to DF_Issues).  I will be too busy over the next 2.5 weeks
due to travel and an office move, so now would be a good time
to poke holes in the concept, criticize the structural breakdown,
or point out additional errata that apply to both this and the
rfc2616bis document that Julian is editing.

BTW, Julian also has write access to Apache Labs stuff, though
he may not know it yet.  If anything is changed, please be sure
to follow the previous examples in commit logs and jira issues.

....Roy

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 17 Oct 2007 20:15:31 +1000

Without having more than skimmed it, I like the feel so far.

Is there any way to get some sort of diff from 2616 to the current  
text? Having that was critical for Julian's draft IMO.

Cheers,

--
Mark Nottingham     http://www.mnot.net/

---

From: Julian Reschke <[email-masked]>
Date: Wed, 17 Oct 2007 19:33:41 +0200

> Without having more than skimmed it, I like the feel so far.

Modularization obviously can have advantages, such as better future 
maintainability. On the other hand it can make people nervous because 
things aren't where they used to be.

> Is there any way to get some sort of diff from 2616 to the current text? 
> Having that was critical for Julian's draft IMO.
> 
> Cheers,

That is probably hard to do, as the various parts do not always have 
continuous counterparts in RFC2616...

That being said -- it may be worthwhile trying to make the process of 
generating the modularized spec automatic. This will require assigning a 
part# to every piece of the original text, plus maybe some conditional 
stuff.

That would allow us to focus on the monolithic version for now, while 
having the option to produce a modularized version later.

Best regards, Julian

---

From: "Roy T. Fielding" <[email-masked]>
Date: Wed, 17 Oct 2007 11:09:28 -0700

> text? Having that was critical for Julian's draft IMO.

That was the idea, but it did not come out as well as I wanted:

http://labs.apache.org/webarch/http/draft-fielding-http/diffs.html

Each part started as rfc2616.xml, so if you follow the changelog
with subversion you can see what content is changed.  What you can't
see is where each deleted section ended up in a different partition,
unless you go back to the RFC outline and jump from there.

http://labs.apache.org/webarch/http/draft-fielding-http/outline2616.html

I considered using the ins/del marks for changes, but that would
become unreadable very fast and my focus is on readability (one
of the main reasons 2616 had so many errors is that nobody read
the submitted document -- all they did was look at the changes
doc created by word).

I have not tried using the rfcdiff tool yet.  Which of the various
diff methods do you think would be best?

....Roy

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 18 Oct 2007 12:22:09 +1000

Well, rfcdiff of draft-lafon-00 to p1-messaging gives this:
   <http://www.mnot.net/test/p1-messaging-from-draft-lafon- 
rfc2616bis-00.diff.html>
...which is pretty good at showing one change.

It would be nice to show them all side-by-side, but I don't see any  
easy way to do that.

On 18/10/2007, at 4:09 AM, Roy T. Fielding wrote:

> outline2616.html

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 18 Oct 2007 16:58:46 +1000

Having looked at this a bit more closely, I think that

1) generating an rfcdiff from draft-lafon-00 and each of the  
partitioned specs, and
2) verifying the text's stability manually, and
3) checking section by section to make sure that no text has been  
dropped (shouldn't be too bad, as most things are in section-sized  
chunks).

would be a viable process for generating the paper trail from RFC2616  
to a partitioned spec.

I say draft-lafon-00 because there's already a paper trail from  
RFC2616 to it, and doing it this way will result in less noise in the  
diffs (e.g., spacing, capitalisation in section heads). I did notice  
a few places where small resolutions had been inserted (against the  
original errata?); would there be a better draft of Yves' and  
Julian's to use as a base?

If people agree with that, it seems like the relevant questions are

a) Is a partitioned specification desirable?
b) If so, is this the right partitioning?

Cheers,

P.S. Roy, are you able to use any version of rfc2xml to generate a  
text I-D from these? I've had several problems, and it's still not  
perfect.

On 18/10/2007, at 12:22 PM, Mark Nottingham wrote:

>>> Is there any way to get some sort of diff from 2616 to the  
>>> current text? Having that was critical for Julian's draft IMO.
>>

---

From: Julian Reschke <[email-masked]>
Date: Thu, 18 Oct 2007 09:57:37 +0200

Mark Nottingham wrote:
> ...
> P.S. Roy, are you able to use any version of rfc2xml to generate a text 
> I-D from these? I've had several problems, and it's still not perfect.
> ...

You can generate TXT from these by first applying clean-for-DTD.xslt 
(<http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#clean-for-dtd>), 
and by running the result through MTR's xml2rfc processor.

BR, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Oct 2007 16:34:54 +0200

Mark Nottingham wrote:
> <http://www.mnot.net/test/p1-messaging-from-draft-lafon-rfc2616bis-00.diff.html> 
> 
> It would be nice to show them all side-by-side, but I don't see any easy 
> way to do that.

A better comparison may be 
<http://greenbytes.de/tech/webdav/p1-messaging-from-rfc2616.diff.html>, 
as it seems Mark had problems running xml2rfc on the "enhanced" XML 
source (which uses extension elements ignored by xml2rfc).

Anyway: I believe we don't necessarily need to decide the #-of-documents 
question right away. If people think that would be useful, I'm willing 
to look into automating the process of splitting up the spec; some 
additional markup + conditional text can make this work.

Best regards, Julian