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

From: Tom Taylor <[email-masked]>
Date: Thu, 19 Jun 2014 14:51:43 -0400

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

---

From: Julian Reschke <[email-masked]>
Date: Thu, 19 Jun 2014 21:27:25 +0200

On 2014-06-19 20:51, Tom Taylor wrote:
> ...
> ...

Many of the links in the document have been autogenerated from the RNG 
file (see the SVN repo for the tool set that was used).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 20 Jun 2014 12:08:34 +0200

Hi Tom,

thanks for the review.

I've applied most of the changes, see 
<http://greenbytes.de/tech/webdav/draft-reschke-xml2rfc-latest-from-previous.diff.html> 
for the diffs.

Some comments inline:

On 2014-06-19 20:51, Tom Taylor wrote:
 > ...
> 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.)

So how is this different from date? Do you think we need to say it's the 
actual year, not only two digits?

> 2.5.1 Expand descriptive sentence slightly? "... horizontal alignment of

It's currently: "Controls whether the artwork appears left (default), 
centered, or right." -- and I believe that's sufficient.

> 2.17.1 "... horizontal alignment of ... on the page."

See above.

> closer to v2 (or is it identical to v2?).

I added a reference to the abandoned draft. (and no, it's not 
*identical* to v2 as it hasn't been maintained since 2009, thus was 
incomplete).

Best regards, Julian

-- 
<green/>bytes GmbH, Hafenweg 16, D-48155 Münster, Germany
Amtsgericht Münster: HRB5782

---

From: Tom Taylor <[email-masked]>
Date: Fri, 20 Jun 2014 11:21:00 -0400

On 20/06/2014 6:08 AM, Julian Reschke wrote:
>> digits is not specified. (Also true of 'day', but doesn't matter
>> unless processors will glitch on encountering leading zeroes.)
>
[PTT] Yes. I suppose I should have been explicit.
...