Subject: [xml2rfc] comments on draft-reschke-xml2rfc-02

From: Alice Russo <[email-masked]>
Date: Wed, 4 Dec 2013 12:02:29 -0500

Hi Julian,

Thanks for your work on this. Comments below on draft-reschke-xml2rfc-02 (not including Appendix D).

-Alice

1) Section 1 or 1.1

>   It obsoletes the original version ("v1") [RFC2629], which contained
>   the original language definition, and which was subsequently extended
>   ("v2").
...
>   The XML vocabulary here is defined in prose, based on the Relax NG
>   schema ([RNC]) contained in Appendix C (specified in Relax NG Compact
>   Notation, "RNC").

Could a pointer to the existing DTD be added? e.g.,
The v2 XML vocabulary is also defined in a DTD, as available from
<foo>. (where foo is http://svn.tools.ietf.org/svn/tools/xml2rfc/spec-v2/02/xml2rfcv2.dtd or otherwise)

Rationale: For documenting the chain of vocabularies, it seems useful to point to where the v2 DTD lives. Suggest being clear about:
- RFC 2629 contains the v1 vocabulary in a DTD.
- <foo> is the v2 vocabulary in a DTD.
- This document contains the v2 vocabulary in a Relax NG schema.

2) Section 1.1

>   Each element description also contains the RNC fragment for that
>   specific element in a slightly simplified form (for instance, leaving
>   out defaults).  This is included as alternative for readers who
>   prefer formal syntax over prose. [[anchor2: This information is
>   redundant with the prose *and* repeated in the index; I'd like to
>   hear feedback whether it's more useful than distracting.]]

Fine w/ me to go to Appendix C to see the syntax.

3) Section 2.6.1.2

>   Initials should be provided as a whitespace separated list of pairs
>   of a letter and a dot.

The period is optional because the output is correct whether or not it's present.

4) Section 2.11

> Gives the country in a postal address.

Perhaps mention that this statement from RFC 2629 has been intentionally removed?
"Finally, the value of the "country" element should be a two-letter code from ISO 3166."
(In practice, authors use various forms.)

Side note: The future RFC style guide (draft-flanagan-style) makes a specific recommendation ("the English short name as maintained by the ISO 3166 Maintenance Agency").

5) Section 2.44

>   This element is used to specify the Working Group the document
>   originates from, if any.  The recommended format is the official name
>   of the Working Group (with some capitalization), plus the string
>   "Working Group".

For I-Ds or RFCs, this element can also be used by documents in the IRTF stream.

Specifically for RFCs, when submissionType="IRTF" and consensus is set to yes or no, <workgroup> gets inserted into the boilerplate ("Status of This Memo"). The template already includes "Research Group", so the element should contain the string without "Research Group" to prevent output such as
"This RFC represents the consensus of the Delay-Tolerant Network Research Group Research Group".

6) The titles of A.2.1.2 and A.2.1.3 are reversed. Also, the note should state that noModificationTrust200902 doesn't apply to any RFCs (not just Standards Track).

Current:

A.2.1.2.  noModificationTrust200902

  This produces additional text from Section 6.c.i of the TLP:

     This document may not be modified, and derivative works of it may
     not be created, except to format it for publication as an RFC or
     to translate it into languages other than English.

     Note: this clause is incompatible with RFCs that are published on
     the Standards Track.

A.2.1.3.  noDerivativesTrust200902

  This produces the additional text from Section 6.c.ii of the TLP:

     This document may not be modified, and derivative works of it may
     not be created, and it may not be published except as an Internet-
     Draft.

     Note: this clause is incompatible with RFCs that are published on
     the Standards Track.

----------
Should be:

A.2.1.2.  noDerivativesTrust200902

  This produces additional text from Section 6.c.i of the TLP:

     This document may not be modified, and derivative works of it may
     not be created, except to format it for publication as an RFC or
     to translate it into languages other than English.

     Note: this clause is incompatible with RFCs that are published on
     the Standards Track.

A.2.1.3.  noModificationTrust200902

  This produces the additional text from Section 6.c.ii of the TLP:

     This document may not be modified, and derivative works of it may
     not be created, and it may not be published except as an Internet-
     Draft.

     Note: this clause is incompatible with RFCs.

7) B.3
>   <t>: The "anchor" attribute can now be used as well, however there
>    are restrictions on how they can be referred to.  (Section 2.38)

What are these restrictions? 

8) nits
old: Note that not the vocabulary contains 
new: Note that the vocabulary contains 

old: This is included as alternative
new: This is included as an alternative

9) suggestions for a few missing desc. (reusing some text from 2629)

[[element.vspace.missing: element description missing]]

   Used to insert vertical whitespace. 

[[element.vspace.attribute.blankLines.missing: attribute description
   missing]]

   Indicates the number of blank lines that should be inserted.  A 
   line break is specified by using the default value, "0".

[[element.xref.missing: element description missing]]

   Used to cross-reference sections, figures, and references.  Additionally, it can be used to cross-reference a <t> element.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 05 Dec 2013 19:50:14 +0100

> Thanks for your work on this. Comments below on draft-reschke-xml2rfc-02 (not including Appendix D).

OK; thanks for the feedback!

> - This document contains the v2 vocabulary in a Relax NG schema.

Will do.

> Fine w/ me to go to Appendix C to see the syntax.

Ok.

> The period is optional because the output is correct whether or not it's present.

...for some processors.

> (In practice, authors use various forms.)

I didn't remove it intentionally; but yes, the change should be noted.

> Side note: The future RFC style guide (draft-flanagan-style) makes a specific recommendation ("the English short name as maintained by the ISO 3166 Maintenance Agency").

Ack. I'll be happy to link to that document as much it's feasible.

> "This RFC represents the consensus of the Delay-Tolerant Network Research Group Research Group".

Good point.

This indicates that we should recommend just to include the WG name, and 
that we should fix the processors to append "Working Group" or "Research 
Group" in the upper left corner.

> 6) The titles of A.2.1.2 and A.2.1.3 are reversed.

I checked by XSLT code and I think the titles are correct. Needs more 
checks, apparently.

 > Also, the note should state that noModificationTrust200902 doesn't 
apply to any RFCs (not just Standards Track).

Do you have pointers to back this up?

> What are these restrictions?

TBD.

> new: Note that the vocabulary contains

Ack.

> new: This is included as an alternative

That text is gone.

>     Used to cross-reference sections, figures, and references.  Additionally, it can be used to cross-reference a <t> element.

Best regards, Julian

---

From: Alice Russo <[email-masked]>
Date: Tue, 10 Dec 2013 18:33:37 -0800

Hi Julian,

You replied:
> I checked by XSLT code and I think the titles are correct. Needs more checks, apparently.

I tested it again using xml2rfc 2.4.3 -- and agree they are correct. My mistake.

> 
> > Also, the note should state that noModificationTrust200902 doesn't apply to any RFCs (not just Standards Track).
> 

It's the text itself that states "it may not be published except as an Internet-Draft". I see you made the update in draft-reschke-xml2rfc-03.

Thanks,
Alice

---

From: Julian Reschke <[email-masked]>
Date: Wed, 11 Dec 2013 08:34:36 +0100

> It's the text itself that states "it may not be published except as an Internet-Draft". I see you made the update in draft-reschke-xml2rfc-03.

Yup; I realized that myself and fixed it in -03.

Best regards, Julian