ietf-nntp HDR replacement text

[Clive D.W. Feather]

Russ Allbery said:
> 9.5.3  The HDR Extension

Here are some proposed changes to allow metadata.

I think it's important that HDR, OVER, and LIST OVERVIEW.FMT are consistent
about the metadata they provide. Therefore descriptions of what metadata
there is belongs somewhere else, not here.

>   The HDR command retrieves specific headers from a specified range of
>   articles in the currently selected group or an article specified by
>   message-id.
> 
>   The required header parameter is the name of a header (e.g. "subject")
>   in an article and is case-insensitive.

Break paragraph here and replace the above text by:

  The HDR command retrieves specific headers from a specified range of
  articles in the currently selected group or an article specified by
  message-id. It can also return certain metadata about the article(s).
  The required header parameter is the name of a header (e.g. "subject")
  in an article, or the name of a metadata item, and is case-insensitive.
  Names of metadata items always include a colon.

  Except where stated otherwise, metadata items are treated as if they
  were header values, and references to headers in this description
  apply equally to metadata items.

[Given that last paragraph, the changed marked "[OPT]" could be left out,
but I think they provide some clarity. On the other hand, I don't think we
want to replace *every* use of "header" with "header or metadata item".]

>   A successful response consists of a 225 response followed by the
>   requested list of headers.

"... of headers or metadata." [OPT]

>   This list is returned as a multiline
>   response, with each line consisting of the article number, a US-ASCII
>   space, and the contents of the header (without the header name or the
>   colon and space that follow it).

"... follow it) or the metadata for that article."

>   The contents are modified as follows:

"The header contents are modified ..." [OPT]

>   all US-ASCII CRLF pairs are removed, and then each remaining US-ASCII
>   NUL, TAB, CR, or LF character is replaced with a single US-ASCII space.
>   (Note that this is the same transformation as is performed by the OVER
>   extension.)
> 
>   The header content is in all cases taken from the article.  This means
>   that, for example, a request for the header "Lines" returns the contents
>   of the "Lines" header of the specified articles, not the Lines field
>   returned by the OVER extension or any other server-generated value.

"... not the line:count metadata item or any other ...".

>   A server MAY only allow HDR commands for a limited set of headers (such

"... headers and metadata items (such ..." [OPT]

>   as those present in the overview database).  If it does so, it MUST
>   respond with a 503 error response to attempts to request other headers
>   rather than returning erroneous results such as a successful empty
>   response.

> 9.5.3.1.2  Examples

>   Example of a successful retrieval of line counts from a range of
>   articles:
> 
>       [S] 200 NNTP Service Ready
>       [C] GROUP misc.test
>       [S] 211 1234 3000234 3002322 misc.test
>       [C] HDR line:count 3000234-300238
>       [S] 225 Headers follow
>       [S] 3000234 42
>       [S] 3000237 11
>       [S] 3000238 2378
>       [S] .

-- 
Clive D.W. Feather  | Work:  <clive at demon.net>   | Tel:  +44 20 8371 1138
Internet Expert     | Home:  <clive at davros.org>  | Fax:  +44 870 051 9937
Demon Internet      | WWW: http://www.davros.org | Mobile: +44 7973 377646
Thus plc            |                            | NOTE: fax number change