[Gen-art] Early review of draft-reschke-xml2rfc-08.txt

Tom Taylor <tom.taylor.stds@gmail.com> Thu, 19 June 2014 18:51 UTC

Message-ID: <53A3313F.6070902@gmail.com>
Date: Thu, 19 Jun 2014 14:51:43 -0400
From: Tom Taylor <tom.taylor.stds@gmail.com>
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Thunderbird/24.6.0
MIME-Version: 1.0
To: "Julian F. Reschke" <julian.reschke@greenbytes.de>, Gen Art <gen-art@ietf.org>, "Heather Flanagan (RFC Series Editor)" <rse@rfc-editor.org>, xml2rfc@ietf.org
Content-Type: text/plain; charset="UTF-8"; format="flowed"
Content-Transfer-Encoding: 8bit
Archived-At: http://mailarchive.ietf.org/arch/msg/gen-art/0PhqDS2EOgPOMeMtM_aib6q4Yg8
Subject: [Gen-art] Early review of draft-reschke-xml2rfc-08.txt
Precedence: list

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] Early review of draft-reschke-xml2rfc-0… Tom Taylor
Re: [Gen-art] Early review of draft-reschke-xml2r… Julian Reschke
Re: [Gen-art] Early review of draft-reschke-xml2r… Julian Reschke
Re: [Gen-art] Early review of draft-reschke-xml2r… Tom Taylor