ietf-nntp Reorganising the document

[Clive D.W. Feather]

I feel that the current arrangement of sections 9 to 12 is confusing to the
reader. The current order (ignoring "Responses" and "Examples" subsections)
is:

  9. The NEWS EXCHANGE Step
  9.1 Article Retrieval
  9.1.1 Article Retrieval by News Group Name and Article Number
  9.1.1.1 GROUP
  9.1.1.2 LAST
  9.1.1.3 NEXT
  9.2 Retrieval of Articles and Article Sections
  9.2.1 ARTICLE
  9.2.2 HEAD
  9.2.3 BODY
  9.2.4 STAT
  9.3 Article Posting
  9.3.1 POST
  9.3.2 IHAVE
  9.4 The LIST Keyword
  9.4.1 LIST
  9.4.2 LIST ACTIVE.TIMES
  9.4.3 LIST DISTRIBUTIONS
  9.4.4 LIST DISTRIB.PATS
  9.4.5 LIST NEWSGROUPS
  9.5 Standard extensions
  9.5.1 LISTGROUP extension
  9.5.1.1 The LISTGROUP Command
  9.5.2 The OVER Extension
  9.5.2.1 LIST OVERVIEW.FMT
  9.5.2.2 OVER
  9.5.3 The PAT Extension
  9.5.3.1 PAT
  10. The CONCLUSION Step
  10.1 QUIT
  11. Other Keywords
  11.1 DATE
  11.2 The HELP Command
  11.3 NEWGROUPS
  11.4 NEWNEWS
  12. Framework for NNTP Extensions
  12.1 Initial IANA Registry

This has the following problems:

(1) Section 9.1 is called "Article Retrieval", yet it actually talks about
the arrangement of articles on the server, and none of the commands in 9.1
actually retrieve articles. The article retrieval stuff is in 9.2.

(2) There's no particular need for the extra level of 9.1.1.

(3) The additional commands provided by all servers other than retrieval and
posting are not classified in any logical way. Rather, they are in 9.4 if
they begin LIST and 11 if they don't. This leads some implementers to
(wrongly) think that the commands in section 11 don't need to be supported
either efficiently or, in some cases, at all.

(4) Though the extensions concept is described in section 12, the standard
extensions are in section 9.5 instead.

Here is how I suggest things are reorganised. See below the list for
further notes about the text. Where the section number is preceded by *,
the text would be changed as described at the end. For all other sections,
the text remains unchanged apart from the renumbering.

* 9. Article posting and retrieval
* 9.1 Group and article selection
  9.1.1 GROUP
  9.1.2 LAST
  9.1.3 NEXT
  9.2 Retrieval of Articles and Article Sections
  9.2.1 ARTICLE
  9.2.2 HEAD
  9.2.3 BODY
  9.2.4 STAT
  9.3 Article Posting
  9.3.1 POST
  9.3.2 IHAVE
* 10. Information commands
  10.1 DATE
  10.2 The HELP Command
  10.3 NEWGROUPS
  10.4 NEWNEWS
  10.5 The LIST Keyword
  10.5.1 LIST
  10.5.2 LIST ACTIVE.TIMES
  10.5.3 LIST DISTRIBUTIONS
  10.5.4 LIST DISTRIB.PATS
  10.5.5 LIST NEWSGROUPS
  11. The CONCLUSION Step
  11.1 QUIT
  12. Framework for NNTP Extensions
  12.1 Initial IANA Registry
* 12.2 Standard extensions
  12.3 LISTGROUP extension
  12.3.1 The LISTGROUP Command
  12.4 The OVER Extension
  12.4.1 LIST OVERVIEW.FMT
  12.4.2 OVER
  12.5 The PAT Extension
  12.5.1 PAT

The text at the start of the old 9.1 ("Article Retrieval") describes the
organisation of articles on the server. It isn't specifically to do with
the GROUP/LAST/NEXT commands; it applies equally to other commands like
NEWNEWS. Therefore I would do one of the following:

(A) Delete the old 9.1 heading, so that the text becomes part of the
introduction to section 9.

(B) Take the view that this is "basic concepts" material. In that case,
move the first sentence to the end of the introduction of section 9 and
move the rest to a new section "4.2 Article organisation and indexing".

The new heading "9.1 Group and article selection" is followed by the text
that was in 9.1.1, unchanged; only the numbering level and the heading is
changed.

The heading "10. Information commands" replaces "11. Other keywords". I
believe that the text can remain unchanged.

The new sections 12.2 to 12.5 hold the standard extensions stuff that is
currently in 9.5. I felt it looked better to reduce the depth of
subsectioning, but it could all be part of 12.2 if people preferred. The
introduction text can remain, though it could perhaps be rewitten to fit
its new context better.

The only other question is whether section 8 (LIST EXTENSIONS) fits better
as part of this new 12 (it would be 12.2, with the remaining sections moved
down one). To do this would require more extensive renumbering.


I haven't produced a version of the draft with this reordering. I can do so
if there's interest.

-- 
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