ietf-nntp Section 4

[Clive D.W. Feather]

> Command lines MUST NOT
> exceed 512 octets, which includes the terminating US-ASCII
> CRLF pair. Arguments MUST NOT exceed 497 octets.

Could we please have a parenthetical comment explaining the origin of 497 ?
I can't suggest one because I don't know the reason.

> Each response MUST start with a three-digit response code that
> is sufficient to distinguish all responses. Unless
> specifically specified as one of the valid responses for a
> command (such as those described later in this document), each
> response is contained in a single line. However, certain
> responses from commands may be multi-line.  All multi-line
> responses MUST ...

Better:

  Each response MUST start with a three-digit response code that
  is sufficient to distinguish all responses. Certain valid responses
  are defined to be multi-line; for all others, the response is
  contained in a single line. All multi-line responses MUST ...

Note, a response either *is* or *isn't* multi-line, and your use of "may
be" is confusing.

> The
> keywords that support multi-line responses have the format of
> those responses described in the responses section.

Better:

  Where a response is multi-line, the description of the command will
  define the format of the response before "byte-stuffing" takes place.

> 4.1 Response Codes

I'm sorry, but I find much of this text hard to read. Rather than address
it line by line, here's a proposed replacement text. Comments in
[brackets] point out particular changes.

  4.1 Response Codes

  Each response MUST begin with a three-digit status indicator.
  These are status reports from the server and indicate the
  response to the last command received from the client.
 
  The first digit of the response broadly indicates the success,
  failure, or progress of the previous command.
 
  1xx - Informative message
  2xx - Command ok
  3xx - Command ok so far, send the rest of it.
  4xx - Command was correct, but couldn't be performed for some
        reason.
  5xx - Command unimplemented, or incorrect, or a serious
        program error occurred.

  The next digit in the code indicates the function response
  category.
 
  x0x - Connection, setup, and miscellaneous messages
  x1x - Newsgroup selection
  x2x - Article selection
  x3x - Distribution functions
  x4x - Posting
  x8x - Nonstandard (private implementation) extensions
  x9x - Debugging output

[Start with the generic format]

  Certain responses contain parameters such as numbers and names
  in addition to the status indicator. In those cases, the number
  and type of such parameters is fixed for each response code to
  simplify interpretation by the client (any extension MUST follow
  this principle as well). In all other cases, the client MUST only
  use the status indicator itself to determine the nature of the
  response.

  Parameters MUST be separated from the numeric status indicator
  and from each other by a single US-ASCII space. All numeric
  parameters MUST be in base 10 (decimal) format, and MAY have
  leading zeros. String parameters MUST contain at least one character
  and MUST NOT contain US-ASCII spaces, CR, LF, or tab). The server
  MAY add any text after the response code or last parameter as
  appropriate, and the client MUST NOT make decisions based on this
  text.

[I *strongly* suggest that we do not include trailing text in the command
descriptions, though of course we can and should do so in the examples.]

[Now talk about generic responses.]
 
  A server MUST respond to an unrecognized, unimplemented, or
  invalid command with a negative response code as follows. An
  unrecognised command, or an optional command or extension that
  is not implemented by the server, MUST be given a 500 response.
  A syntax error in a recognised command MUST be given a 501
  response. A command that is valid but not permitted because of
  the current internal state of the server MUST be given a 4XX or
  5XX response.

[Question: should this be restricted in some way, or are *all* of the
codes from 400 to 599 really permitted ? In particular, this text
appears to contradict the text that follows. I will write new text if
someone can answer the issue.]

[Now the bit about what responses are permitted; the present stuff has
this spread around two or three separate places.]

  Each recognised command MUST return 501 (as above) or one of the
  response codes specifically listed in its description or in an
  extension. A server MAY provide extensions to this specification,
  including new commands, new features of existing commands, and other
  ways of changing the internal state of the server. However, the
  server MUST NOT produce any other responses to a client that does
  not invoke any of the additional features. (Therefore a client that
  restricts itself to this specification will only receive the responses
  that are listed).

[New paragraph; I hope it's reasonable.]

  If a client receives an unexpected response, it SHOULD use the first
  digit to determine what action to take. In most cases, a reasonable
  action would be that taken for a valid response with the same first
  digit.

[I've tried to simplify the debugging stuff to what a conforming client
needs to know.]

  Where additional responses are provided as part of a private
  extension, the server SHOULD restrict them to the x8x or x9x patterns
  as appropriate. Debugging output is a particular case of additional
  responses, and MUST only be produced once enabled, as above; there is
  no requirement in this specification for debugging output. Where a
  server wishes to generate debugging output as well as the normal
  response to a command, it SHOULD return a 19x response line and then
  wait for the client to request the actual response (e.g. using the
  DEBUG ACK command in section 11.2). Other x9x responses should be
  used as appropriate (for example, 290 would be a reasonable response
  for a request to change the debugging level).

-- 
Clive D.W. Feather  | Work:  <clive at demon.net>   | Tel:  +44 20 8371 1138
Internet Expert     | Home:  <clive at davros.org>  | Fax:  +44 20 8371 1037
Demon Internet      | WWW: http://www.davros.org | DFax: +44 20 8371 4037
Thus plc            |                            | Mobile: +44 7973 377646