I am one of the assigned Gen-ART reviewers for this draft. For
background on Gen-ART, please see the FAQ at
<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.
Please resolve these comments along with any other comments you may
receive.
Tom Taylor
Summary
This draft is basically ready for publication, but has nits that should
be fixed before publication. I have identified one very minor issue as
shown below. The documentation in general is excellent and clarifies
some points I was never clear on with Marshall Rose's guide.
As a meta-comment, we need some document like Marshall Rose's guide that
shows how everything fits together. One possibility is to put out a
document explaining and presenting the general I-D template, and another
that explains and presents the MIB template. I'm prepared to author
these if others agree on the need and are not interested in doing the work.
Major Issues
------------
None.
Minor Issues
------------
In the description of the 'year' attribute of <date>, the number of
digits is not specified. (Also true of 'day', but doesn't matter unless
processors will glitch on encountering leading zeroes.)
Nits and Editorial Improvements
-------------------------------
Given that this is an early review, I did not run IDnits. I did check
all the internal cross-references (I think), and they were all correct.
I'd be interested in how that was achieved. I end up flipping back and
forth in my documents to find the value of the anchor for the section I
want to refer to.
s/only text content/text content only/g
-- sounds better to the English-speaking ear.
2.5.1 Expand descriptive sentence slightly? "... horizontal alignment of
... on the page."
2.13 s/first case/boilerplate case/
s/second case/case of bibliographic references/
OLD:
When "year", "month" or "day" are
left out, the processor will attempt to use the current system date
if the attributes that are specified do match the system date.
NEW:
When one or more of "year", "month", or "day" are left out, the
processor will attempt to use the current system date if the
attributes that are present are consistent with that date.
2.17.1 "... horizontal alignment of ... on the page."
2.36 typo in verb bullet: s/usign/using/
2.39.1 "... on the page."
3. First line typo: s/can not/cannot/
4. Last line above page break and XML declaration:
s/like that/like this/
5. Second line: s/it's/its/
6. Second paragraph, third line: s/role/rule/.
Next line: s/US-ACSII/US-ASCII/
7. Suggest dropping "Furthermore" from beginning of third paragraph
because it is redundant with "as well" later in the sentence.
8.1:
Applications that use this media type: delete "either".
Fragment identifier considerations: s/uses/used/ in middle line.
Appendix B. You might note that while v1 is documented in RFC 2629, the
version of XML2RFC documented in Marshall Rose's guide "Writing I-Ds and
RFCs using XML (revised)"
<http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html> is
closer to v2 (or is it identical to v2?).
_______________________________________________
Gen-art mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/gen-art
