[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
draft-steidl-newsml-urn-rfc3085bis-00
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: ah at TR-Sys.de |
+------------------------+--------------------------------------------+