Early Review of draft-reschke-xml2rfc-08
review-reschke-xml2rfc-08-genart-early-taylor-2015-12-31-00

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?).