Subject: draft-steidl-newsml-urn-rfc3085bis-00

From: Alfred Hönes <[email-masked]>
Date: Thu, 24 Sep 2009 12:17:37 +0200 (MESZ)

Hello,
I apologize for the belated review, but hopefully the remarks
below still help further improving the draft.

These all address editorials and/or straighforward clarifications.

(1)  General -- citations

I suggest that you adopt the common style in IETF documents to
provide inline citations using the tags defined in the
References section(s), at least at the first occurrence of
a citation in the text, but even better at all 'important'
occurrences.

For instance, in the 1st para of Section 1:

   NewsML 1 and the G2-Standards specify XML formats for packaging
   multimedia news resources and items representing knowledge. [...]
---
   NewsML 1 [1] and the G2-Standards [2] specify XML formats for
   packaging multimedia news resources and items representing knowledge.
   [...]

More examples are included below without further explanation.

An Informative ref. entry for the RFC being obsoleted should be added;
I assume '[8]' being the outcome.  Then, in the 3rd para of Section 1:

|  This document obsoletes RFC 3085. The reasons for updating RFC 3085
   are:
---
|  This document obsoletes RFC 3085 [8].  The reasons for updating
   RFC 3085 are:

(2)  References

I suggest to make use of the recommended complete Reference entries
(including STD designations where appropriate) from rfc-ref.txt
(or the XML version thereof, if applicable to your drafting tools)
available from the RFC Editor web/ftp site.

Ref. [6] is outdated and should be replaced by a pointer to the
Full Standard version, RFC 5234.

In the prose, according to long-standing practice RFCs should always
be quoted with a single space between "RFC" and the RFC number.
So, if not using rfc-ref, please take care to manually
   s/RFC1035/RFC 1035/  in entry [7].

(3)  Section 1

In the last sentence of the 4th paragraph, I suggest to drop "RFC",
because the template is mainly for use by, and archival at, the IANA:

                              [...]. This includes meeting the formal
|  requirements of the new RFC template for URN registrations issued by
|  the IETF (RFC 3406).
---
                              [...].  This includes meeting the formal
|  requirements of the new template for URN registrations issued by the
|  IETF (RFC 3406 [5]).

(4)  Section 1 --> 2

I propose to move the final paragraph of Section 1 into Section 2,
where it gives an important (and unfortunately frequently omitted)
detail for the registration:

 2. Specification Template
|
|  This namespace specification is for a formal namespace.

The initial, 'identifying' clause in the template might be
simplified, dropping the unnecessary double-quotes and joining
the lines:

|  Namespace ID:
|
|     "newsml"
---
|  Namespace ID: newsml

(Doing so allows full text search operations with simple tools like
`grep` reveal more relevant key information from the memo at once.)

(5)  Section 2 -- ABNF related issues

The draft contains the ABNF line:

      month = ( 0 posdig ) / ( "1" ( "0" "1" "2" ) )

This would be equivalent to (by joining adjacent literal strings):

      month = ( 0 posdig ) / ( "1" ( "012" ) )

and hence

      month = ( 0 posdig ) / "1012"

... which certainly isn't what you want.  :-)

So please insert the alternation characters to make the line read

|     month = ( 0 posdig ) / ( "1" ( "0" / "1" / "2" ) )

Alternatively, and perhaps easier to comprehend for the human reader,
the alternatives could be spelled out fully (as for <day>), saving
lots of parentheses as well:

|     month = ( 0 posdig ) / "10" / "11" / "12"

To enhance the readability, I suggest to use columnar alignment
in the presentation of the ABNF.
For instance, incorporating the above change:

      NSS = ProviderId ":" DateId ":" NewsItemId
             [":" RevisionId][Update]
      ProviderId = string
      DateId = date
      NewsItemId = string
      RevisionId = posint
      Update = 0*1( "A" / "U" )
      date = century year month day
      century = ( "0" posdig ) / ( posdig DIGIT )
      year = 2DIGIT
      month = ( 0 posdig ) / ( "1" ( "0" "1" "2" ) )
      day = ( 0 posdig ) / ( ( "1" / "2" ) DIGIT ) / "30" / "31"
      string = 1*char
      char = ALPHA / DIGIT / symbol / escape
      symbol = "(" / ")" / "+" / "," / "-" / "." / "=" / "@" / ";" /
        "$" / "_" / "!" / "*" / "'"
      escape = "%" HEXDIG HEXDIG
      posint = posdig *DIGIT
      posdig = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
---
      NSS        = ProviderId ":" DateId ":" NewsItemId
                   [":" RevisionId] [Update]
      ProviderId = string
      DateId     = date
      NewsItemId = string
      RevisionId = posint
      Update     = 0*1( "A" / "U" )
      date       = century year month day
      century    = ( "0" posdig ) / ( posdig DIGIT )
      year       = 2DIGIT
      month      = ( 0 posdig ) / "10" / "11" / "12"
      day        = ( 0 posdig ) / ( ( "1" / "2" ) DIGIT ) / "30" / "31"
      string     = 1*char
      char       = ALPHA / DIGIT / symbol / escape
      symbol     = "(" / ")" / "+" / "," / "-" / "." / "=" / "@" / ";"
                 / "$" / "_" / "!" / "*" / "'"
      escape     = "%" HEXDIG HEXDIG
      posint     = posdig *DIGIT
      posdig     = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"

The ABNF RFCs, from the old RFC 2234 through the current
Full Standard revision, RFC 5234, recommend to disambiguate
(non-terminal) ABNF rule names when used in the prose by
enclosing them in angle brackets (as it was required in the
original BNF for the formal specification as well).
In particular, in a close vicinity to ABNF, is is confusing to
enclose some instances of rule names in qouble-quotes, which are
used to denote case-insensitive string literals in ABNF.

Thus the explanations in the draft below the ABNF should be modified
following the pattern shown below.  More instances to be addressed
appear in later clauses of the template.

(Note: After this kind of uniform 'markup' has been applied,
 as an additional step, it might be considered to downcase
 the rule names -- this is now performed below.)

|     ProviderId must be a registered Internet domain name [...]
---
|     <ProviderId> must be a registered Internet domain name [...]

|     DateId is a date in ISO 8601 Basic Format (CCYYMMDD), and must
         correspond to a date at which the organisation allocating the
         URN was the registered owner of the domain name specified in
|        the ProviderId.
---
|     <DateId> is a date in ISO 8601 Basic Format (CCYYMMDD), and must
         correspond to a date at which the organisation allocating the
         URN was the registered owner of the domain name specified in
|        the <ProviderId>.

...
...

|     Update: when associated with NewsML 1 news items, if the news item
|       contains one or more NewsML 1 "Update" elements, then Update
        must be set to "U".  If the news item consists only of a
|       replacement set of NewsML 1 NewsManagement data, then Update
        must be set to "A". If neither of these is the case, or if the
|       URN is not associated with a NewsML 1 news item, then Update
        must be omitted.
---
|     <Update>: when associated with NewsML 1 news items, if the news
        item contains one or more NewsML 1 "Update" elements, then
|       <Update> must be set to "U".  If the news item consists only of
|       a replacement set of NewsML 1 NewsManagement data, then <Update>
        must be set to "A".  If neither of these is the case, or if the
|       URN is not associated with a NewsML 1 news item, then <Update>
        must be omitted.

...
etc.
...

(6)  Section 3

The explanatory texts for all four examples are full sentences.
Thus, I recommend to add a trailing period (full-stop) to the end
of these sentences.

Kind regards,
  Alfred Hönes.

-- 

+------------------------+--------------------------------------------+
| TR-Sys Alfred Hoenes   |  Alfred Hoenes   Dipl.-Math., Dipl.-Phys.  |
| Gerlinger Strasse 12   |  Phone: (+49)7156/9635-0, Fax: -18         |
| D-71254  Ditzingen     |  E-Mail:  [email-masked]                     |
+------------------------+--------------------------------------------+