[ietf-nntp] Extension documents

[Clive D.W. Feather]

I'd like to make a recommendation for some general wording for extension
documents, including both AUTHINFO, TLS, and anything to follow. The idea
is to encourage consistency. Opinions?

Here are my proposals:

In the introduction, include:

    This specification is to be read in conjunction with the NNTP base
    specification [NNTP]. Except where specifically stated otherwise, in
    the case of a conflict between these two documents [NNTP] takes
    precedence over this one.

If only one extension is described in the document:

    A server MAY provide this extensions, independently of any other
    extension defined elsewhere. If the server provides the extension, it
    MUST include the [XXXXXXX] extension label in the response to LIST
    EXTENSIONS. If it does not provide it, it MUST NOT include the extension
    label. The remainder of this specification is written as if the
    extension is provided.

    If the server provides this extension, it MUST implement all of the
    commands in this document except for those marked as optional. If it
    does not provide this extension, it MUST NOT implement any of the
    commands.

If more than one extension is described in the document:

    A server MAY provide each of these extensions, independently of any
    other. If the server provides the extension, it MUST include the
    appropriate extension label in the response to LIST EXTENSIONS. If it
    does not provide it, it MUST NOT include the appropriate extension
    label. The descriptions of facilities in each section are written as
    if the extension is provided. If it is not provided, the entire section
    should be ignored.

    If the server provides an extension, it MUST implement all of the
    commands in the specification of the extension except for those marked
    as optional. If it does not provide an extension, it MUST NOT implement
    any of the commands in the specification of that extension.

Wherever notation is discussed:

    The notational conventions used in this document are the same as
    those in [NNTP] and any term not defined in this document has the same
    meaning as in that one.

In the syntax, have sections corresponding to those in the base document.
So:

    X.   Augmented BNF Syntax for the XXXXXXXX extension

    This section describes the syntax of the XXXXXXXX extension.
    It extends the syntax in [NNTP], and non-terminals not defined in
    this document are defined there.

    X.1  Commands

    This syntax extends the non-terminal "command", which represents an
    NNTP command.

        command /= xxxxxxxx-command

[etc.]

    X.2  Command continuation

    This syntax extends the non-terminal "command-continuation", which
    represents the further material sent by the client in the case of
    multi-stage commands.

        command-continuation /= xxxxxxxx-continuation

[etc.]

    X.5  LIST EXTENSIONS responses

    This syntax defines the specific LIST EXTENSIONS responses for the
    XXXXXXXX extension.

        extension-descriptor /= xxxxxxxx-extension

        xxxxxxxx-extension = %x58.58.58.58.58.58.58.58  ; "XXXXXXXX"

If it's felt helpful, then:

    X.8  Imported non-terminals

    These definitions are copied from [NNTP]. Any difference between the
    documents is an error in this one.

then any non-terminals that are felt vital to understanding the syntax of
the extension.

Finally, there should be an analogue to Appendix C:

    Appendix C.   Summary of response codes

    The text "Also generated by" indicates that the code is also defined
    in [NNTP]. Generic response codes are not listed in this section.

    Response code 266
       Generated by: XXXXXXXX
       Meaning: it worked

    Response code 423
       Also generated by: XXXXXXXX

-- 
Clive D.W. Feather  | Work:  <clive at demon.net>   | Tel:    +44 20 8495 6138
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            |                            |