Subject: my action item on issue 52 (Sort 1.3 Terminology)

From: Julian Reschke <[email-masked]>
Date: Fri, 15 Jun 2007 14:29:50 +0200

See <http://www.w3.org/Protocols/HTTP/1.1/rfc2616bis/issues/#i52>.

There was an open action item for me to sort the terminology section, 
and to post the outcome over here for discussion (I'll add my opinion in 
a separate mail).

After sorting by terms, Section 1.3 would look like this:

-- snip --

1.3.  Terminology

    This specification uses a number of terms to refer to the roles
    played by participants in, and objects of, the HTTP communication.

    age

       The age of a response is the time since it was sent by, or
       successfully validated with, the origin server.

    cache

       A program's local store of response messages and the subsystem
       that controls its message storage, retrieval, and deletion.  A
       cache stores cacheable responses in order to reduce the response
       time and network bandwidth consumption on future, equivalent
       requests.  Any client or server may include a cache, though a
       cache cannot be used by a server that is acting as a tunnel.

    cacheable

       A response is cacheable if a cache is allowed to store a copy of
       the response message for use in answering subsequent requests.
       The rules for determining the cacheability of HTTP responses are
       defined in Section 13.  Even if a resource is cacheable, there may
       be additional constraints on whether a cache can use the cached
       copy for a particular request.

    client

       A program that establishes connections for the purpose of sending
       requests.

    connection

       A transport layer virtual circuit established between two programs
       for the purpose of communication.

    content negotiation

       The mechanism for selecting the appropriate representation when
       servicing a request, as described in Section 12.  The
       representation of entities in any response can be negotiated
       (including error responses).

    entity

       The information transferred as the payload of a request or
       response.  An entity consists of metainformation in the form of
       entity-header fields and content in the form of an entity-body, as
       described in Section 7.

    explicit expiration time

       The time at which the origin server intends that an entity should
       no longer be returned by a cache without further validation.

    first-hand

       A response is first-hand if it comes directly and without
       unnecessary delay from the origin server, perhaps via one or more
       proxies.  A response is also first-hand if its validity has just
       been checked directly with the origin server.

    fresh

       A response is fresh if its age has not yet exceeded its freshness
       lifetime.

    freshness lifetime

       The length of time between the generation of a response and its
       expiration time.

    gateway

       A server which acts as an intermediary for some other server.
       Unlike a proxy, a gateway receives requests as if it were the
       origin server for the requested resource; the requesting client
       may not be aware that it is communicating with a gateway.

    heuristic expiration time

       An expiration time assigned by a cache when no explicit expiration
       time is available.

    inbound/outbound

       Inbound and outbound refer to the request and response paths for
       messages: "inbound" means "traveling toward the origin server",
       and "outbound" means "traveling toward the user agent"

    message

       The basic unit of HTTP communication, consisting of a structured
       sequence of octets matching the syntax defined in Section 4 and
       transmitted via the connection.

    origin server

       The server on which a given resource resides or is to be created.

    proxy

       An intermediary program which acts as both a server and a client
       for the purpose of making requests on behalf of other clients.
       Requests are serviced internally or by passing them on, with
       possible translation, to other servers.  A proxy MUST implement
       both the client and server requirements of this specification.  A
       "transparent proxy" is a proxy that does not modify the request or
       response beyond what is required for proxy authentication and
       identification.  A "non-transparent proxy" is a proxy that
       modifies the request or response in order to provide some added
       service to the user agent, such as group annotation services,
       media type transformation, protocol reduction, or anonymity
       filtering.  Except where either transparent or non-transparent
       behavior is explicitly stated, the HTTP proxy requirements apply
       to both types of proxies.

    representation

       An entity included with a response that is subject to content
       negotiation, as described in Section 12.  There may exist multiple
       representations associated with a particular response status.

    request

       An HTTP request message, as defined in Section 5.

    resource

       A network data object or service that can be identified by a URI,
       as defined in Section 3.2.  Resources may be available in multiple
       representations (e.g. multiple languages, data formats, size, and
       resolutions) or vary in other ways.

    response

       An HTTP response message, as defined in Section 6.

    semantically transparent

       A cache behaves in a "semantically transparent" manner, with
       respect to a particular response, when its use affects neither the
       requesting client nor the origin server, except to improve
       performance.  When a cache is semantically transparent, the client
       receives exactly the same response (except for hop-by-hop headers)
       that it would have received had its request been handled directly
       by the origin server.

    server

       An application program that accepts connections in order to
       service requests by sending back responses.  Any given program may
       be capable of being both a client and a server; our use of these
       terms refers only to the role being performed by the program for a
       particular connection, rather than to the program's capabilities
       in general.  Likewise, any server may act as an origin server,
       proxy, gateway, or tunnel, switching behavior based on the nature
       of each request.

    stale

       A response is stale if its age has passed its freshness lifetime.

    tunnel

       An intermediary program which is acting as a blind relay between
       two connections.  Once active, a tunnel is not considered a party
       to the HTTP communication, though the tunnel may have been
       initiated by an HTTP request.  The tunnel ceases to exist when
       both ends of the relayed connections are closed.

    upstream/downstream

       Upstream and downstream describe the flow of a message: all
       messages flow from upstream to downstream.

    user agent

       The client which initiates a request.  These are often browsers,
       editors, spiders (web-traversing robots), or other end user tools.

    validator

       A protocol element (e.g., an entity tag or a Last-Modified time)
       that is used to find out whether a cache entry is an equivalent
       copy of an entity.

    variant

       A resource may have one, or more than one, representation(s)
       associated with it at any given instant.  Each of these
       representations is termed a `variant'.  Use of the term `variant'
       does not necessarily imply that the resource is subject to content
       negotiation.

-- snip --

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 15 Jun 2007 14:37:21 +0200

Julian Reschke wrote:
> ...

I personally think we should not do this change:

(1) Sorting paragraphs makes it very hard to verify the changes; in 
essence, a reviewer would either need to trust us, or re-do the 
shuffling to control whether it's correct (nothing lost, no change in 
the definitions).

(2) In the RFC2616 ordering, things that belong together (such as 
"client", "user agent", "server" ...) are close to each other.

(3) Contrary to RFC2616, the text version of new spec will contain an 
alphabetical index section anyway (unless it's removed upon publication :-).

Best regards, Julian

---

From: Travis Snoozy <[email-masked]>
Date: Fri, 15 Jun 2007 08:54:31 -0700

On Fri, 15 Jun 2007 14:37:21 +0200, Julian Reschke
<[email-masked]> wrote:

> > There was an open action item for me to sort the terminology
> > section, and to post the outcome over here for discussion (I'll add
> > my opinion in a separate mail).
> > ...
> 

It's fairly trivial to verify: pick the original, copy the first
definition, go to the modified version, and search for those exact
contents. If the exact contents are present, move to the second
definition in the original; if they're not, reject it. Take a second
pass on the destination to verify that the alphabetical ordering is
correct. It's O(N), and a 45 minute editorial job at absolute tops;
5-15 if you have any skill with a good text editor. The only trip-up
would be page breaks, and that's easy to take care of by first removing
the page breaks/headers/footers from both the source and destination
(working on copies, of course).

> "client", "user agent", "server" ...) are close to each other.

The topical-closeness of the entries is very much subject to opinion.
Alphabetical ordering is unambiguous and objective; there is no
confusion as to whether "content negotiation" should be closer to
"origin server" or "cache" when sorted alphabetically. Furthermore,
all entries in the glossary are "close to each other" versus the
entirety of the document -- three full contiguous pages isn't a lot,
proportionally, but having to look up specific definitions over and
over and over again in an unsorted list gets _very_ obnoxious.

> alphabetical index section anyway (unless it's removed upon

I was working off a hard-copy at the time I requested this change, and
let me tell you -- I'd sooner go look at the un-sorted glossary than
take *two* skips, one from my reading spot to the index, and then from
the index to the glossary. In this case, I'd completely avoid the index
for another reason: because the glossary is merely three (and a
half) pages long, I could bookmark the first page and find the entry I'm
looking for by scanning the whole list. It would be faster than looking
the term up in the index, finding the one-in-five pages the definition
could be on, and then scanning through the dozen entries on that page
to find the one I'm looking for. Indexing does not increase the speed
with which I find the information; alphabetizing would.

Alphabetizing is a well-established method for ordering glossaries,
indexes, and other data intended for quick retrieval. I believe that
alphabetizing the glossary will make the document much friendlier for
users, especially ones who want to ensure that they are stringently
following the meaning of these special words throughout the document.
It is a relatively cheap fix, and the work will result in a massive
savings of time, when aggregated over the number of lookups across all
readers.

-- 
Travis

---

From: Julian Reschke <[email-masked]>
Date: Fri, 15 Jun 2007 18:03:38 +0200

> (working on copies, of course).

Sure. But every reviewer who is serious about checking for unintended 
changes from RFC2616 will need to do that (or just trust us).

I guess the terminology section has two distinct purposes; one being to 
introduce the terms for a first time reader (in which case the current 
ordering makes sense), the other one being a reference. I personally 
don't look up these terms very often, but may be I should

Anyway: would an (automatically generated) alphabetical glossary in an 
appendix work for you?

Best regards, Julian

---

From: Henrik Nordstrom <[email-masked]>
Date: Fri, 15 Jun 2007 22:59:52 +0200

> shuffling to control whether it's correct (nothing lost, no change in 

Not a concern to me. It's trivial to detect in a review, and almost as
trivial to resort (but not even needed for a full review).

> "client", "user agent", "server" ...) are close to each other.

Sure, but also makes a specific definition quite hard to find without
searching for it.

It's a definition of terms, not a description of operations.

> alphabetical index section anyway (unless it's removed upon publication :-).

Which works well for an HTML version, but not so well in the authorative
ascii version..

In other words I am for having the terminology definitions sorted
alphabetically. If there is need for relation between the terms outside
what is said elsewhere in the text then I propose to expand the terms as
needed. Some references to the main text may be in place.

Regards
Henrik

---

From: Julian Reschke <[email-masked]>
Date: Sat, 16 Jun 2007 10:27:11 +0200

> Sure, but also makes a specific definition quite hard to find without

But then, this is a problem for the plain text format of RFCs in 
general. Personally, I haven't looked at a text version when an HTML 
version was around for years (well, except for LC).

> It's a definition of terms, not a description of operations.

Yes, but it's sitting in a section called "Introduction", not 
"Glossary". There's a reason for the order the terms are in.

I don't say that having alphabetical ordering wouldn't be nice as well, 
but I'm not convinced that it's the right thing to do it *there*. Thus I 
would argue that unless there's strong consensus for a change, we 
shouldn't fix what's not broken.

> needed. Some references to the main text may be in place.

I'd argue that if an alphabetical glossary is needed, it should go into 
an appendix. That's additional spec text, but it could be generated 
automatically.

Best regards, Julian

---

From: Henrik Nordstrom <[email-masked]>
Date: Sun, 17 Jun 2007 14:01:08 +0200

> version was around for years (well, except for LC).

For standards track the text version is the authoritative version.

> "Glossary".

Right. Should be in a "Definitions" secion of it's own, like used in
several other RFCs.

> There's a reason for the order the terms are in.

Sure, but I question how much of that reason really makes sense. Would
be better replaced with a true introduction referencing the definitions
I think.

> shouldn't fix what's not broken.

Not convinced. The subsection is called Teminology. Text explaining how
the terms in the terminology binds together is better explained in the
actual introduction of the operations of the protocol and the protocol
description itself than in the sorting of the terminology.

But I don't have a strong opinion either way. Just saying that having
them sorted would help anyone using the document as reference and not
leisure lecture, and also that sorting the terms would have negligible
impact on my ability to review the changes.

Regards
Henrik