ietf-nntp Command description layout

[Clive D.W. Feather]

Reading draft 15, I've been thinking about the layout of command
descriptions. At present, in general, we have:

    99. MUMBLE

    MUMBLE count

    MUMBLE causes the server to mumble to itself a number of times. This
    command is not streamable.

    99.1 Responses

        277     mumbled the requested number of times
        278 n   mumbled only n times
        479     unable to mumble

    99.2 MUMBLE examples

    Example of a successful mumble

        [C] MUMBLE 20
        [S] 277 I mumbled 20 times

    Example of a truncated mumble

        [C] MUMBLE 2000
        [S] 278 25 I'm too busy, so I skipped 1975 mumbles

I think it would aid the eventual user of this document if there was a
slightly more formal structure. What I'm thinking of is that every command
has three numbered subsections:

    X.1 Description
        Gives an informal description of the command and its specific
        responses. Certain specifics would be deferred to X.2.
    X.2 Usage
        Gives the formal syntax, lists all the responses, defines the
        meaning of any parameters for both command and response, and
        notes when the command is not streamable.
    X.3 Examples
        Gives examples of each form of use and each specific response.

So, for example:

    99. MUMBLE

    99.1 Description

    The MUMBLE command causes the server to mumble to itself a number of
    times. The server MAY mumble less times than requested.

    99.2 Usage

        Syntax
            MUMBLE n

        Responses
            277     mumbled the requested number of times
            278 m   mumbled some lesser number of times
            479     unable to mumble

        Parameters
            n = the number of mumbles requested
            m = the number of mumbles actually performed

        This command is not streamable.

    99.3 Examples

    Example of a successful mumble

        [C] MUMBLE 20
        [S] 277 I mumbled 20 times

    Example of a truncated mumble

        [C] MUMBLE 2000
        [S] 278 25 I'm too busy, so I skipped 1975 mumbles

Note that the subsections always have exactly those one-word titles; we
seem to be inconsistent at the moment.

The format of Usage would always be the same.
  - alternative syntaxes on successive lines
  - one-line response descriptions
  - parameters described separately
  - any other notes following.

To give a real example:

    9.2.1 ARTICLE
    [...]
    9.2.1.2 Usage

        Syntax
            ARTICLE <message-id>
            ARTICLE [number]

        Responses
          First form (message-id specified)
            220 0 id   article follows (multiline)
            430        no article found with that message-id

          Second form (optional article number specified)
            220 n id   article follows (multiline)
            412        no newsgroup selected
            420        no current article selected [1]
            423        no such article in this newsgroup

        Parameters
            message-id = id of message to retrieve
            number     = article number of message to retrieve
            id         = message ID of article actually retrieved [2]
            n          = article number of message actually retrieved

        [1] The 420 response can only occur if no article number is
            specified.
        [2] If the article does not contain a message-id header line,
            the message-id "<0>" MUST be used (without the quotes).

Do people think this is worth doing ? If so, Stan, I'm willing to do much
of the actual work if you'll tell me how to provide new text.

-- 
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 4037
Demon Internet      | WWW: http://www.davros.org | Mobile: +44 7973 377646
Thus plc            |                            |