Subject: [Gen-art] review: draft-hoffman-xml2rfc-04

From: "Joel M. Halpern" <[email-masked]>
Date: Tue, 08 Apr 2014 05:32:51 -0400

I am one of the requested Gen-ART reviewer for this draft. For background on
Gen-ART, please see the FAQ at
< http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Please wait for direction from your document shepherd
or AD before posting a new version of the draft.

Document: draft-hoffman-xml2rfc-04
     The 'XML2RFC' version 3 Vocabulary
Reviewer: Joel M. Halpern

Summary: This review focuses on readability rather than on XML details.
     In that light, this document could use some improvement.

Major issues:
     The explanation in section 1.1 seems to bounce from topic to topic 
losing the reader repeatedly.  The explanation of the intended 
compatibility before the list of changes is confusing.  Either there are 
v2 features that don't work, or all v2 works, with some deprecated.
     It seems that discussion of the RFC Editor handling of v2 documents 
and this grammar belongs somewhere other than the definition of the 
grammar.  I was surprised to find discussion of canonical RFCs here. 
That set of text was probably the most confusing aspect of section 1.1.

     In section 2.5.6 on the 'type' attribute of the <artwork> element, 
it talks about the processor.  Since that appears to be a reference to 
the internal RFC Editor processor, rather than to the tools readers or 
writers will use, I would think that confusing text should be removed. 
(The processor will throw errors in certain cases, but consumers should 
not throw errors in any text cases?)

Minor issues:
     The question of how the grammar is generated is not a substantive 
difference between v2 and v3, and tells the reader nothing about what 
will follow.  If it should be mentioned at all, it would seem better in 
some other section of the document than 1.1

     Does <artwork> section 2.5 still need to be enclosed in the cdata 
construct to actually have the formatting preserved?  If so, should 
section 2.5 say that?  (Or am I just confused and issuing useless 
incantations in my current docs?)

     In section 2.5, and probably elsewhere, some of the attributes are 
"ought to be avoided", and one is "Deprecated".  The author apparently 
means something specific by "ought to be avoided", but this reader is 
confused.

     In section 2.22.6 on the suppress-title attribute for the <figure> 
element, the text is either confusing or incorrect.  THe text talks 
about figures that have anchor attributes getting autogenerated titles. 
  And that if one wants to suppress that, one should set this to 
"false".  It seems pretty odd that setting suppress to false (which is 
the default) would suppress the autogenerated title.  If it will, the 
attribute name is just wrong.  More likely, you suppress the 
auto-generated title by setting this attribute to "true".
     This also seems to occur in 2.49.4 in the suppress-title for <table>.

     Since <format> is defined (in section 2.23) it ought to be lsited 
as part of the valid content model for <reference> in section 2.40.

    In section 2.40 on <reference>, it might be useful to explain what 
will happen with the short form references.  It seems that how they get 
rendered will depend upon whether the processing engine has the ability 
to find additional data to use?  Or maybe not?

     Also, since <reference> allows <front>, <innerRefContent>, ... it 
seems that <reference> has a content model.  So I presume it is an error 
for it to say that it does not have a content model?

    I would have expected the values of the 'series' attribute of the 
<reference> element to be described in the attribute section (2.40.3) 
rather than in the base element section (2.40).

Nits/editorial comments:
     It would be nice if the deprecated elements were marked as 
deprecated both in their definition and in the places where they can 
appear.  (for example, marking <facsimile> as deprecated in the content 
model listing for <address>).  On the other hand, that may be a pain to 
get right.

     In the description of <date> in section 2.15, the text correctly 
notes that it can appear either as a document date or as a reference 
date.  And then correctly notes that the only legal parent for this is 
<front>.  Is there any way to remind the reader that <front> is used in 
long form references?

---

From: Julian Reschke <[email-masked]>
Date: Tue, 08 Apr 2014 12:15:12 +0200

On 2014-04-08 11:32, Joel M. Halpern wrote:
> ...

There is no need (and never was) to use CDATA unless you want to avoid 
escaping "<" and "&".

> as part of the valid content model for <reference> in section 2.40.

It currently states "Content model: this element does not have any 
contents." which indicates a bigger problem :-)

> ...

Best regards, Julian

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 8 Apr 2014 08:30:44 -0700

> or AD before posting a new version of the draft.

Neither of those exist today, but that topic is under discussion.

>    The explanation in section 1.1 seems to bounce from topic to topic losing the reader repeatedly.  

I figured doing the list in alphabetical order by element would allow comparison more easily. It sounds like you would prefer the list grouped by type of change?

> The explanation of the intended compatibility before the list of changes is confusing.  Either there are v2 features that don't work, or all v2 works, with some deprecated.

Both are true. Some v2 features are described in the v2 document as not working; in addition, some v2 features are deprecated in v3 because they are replaced by something better.

>    It seems that discussion of the RFC Editor handling of v2 documents and this grammar belongs somewhere other than the definition of the grammar.  I was surprised to find discussion of canonical RFCs here. That set of text was probably the most confusing aspect of section 1.1.

Some felt that it was important to list the design criteria to explain the changes. Those design criteria are the ones that you are calling confusing. Are you proposing that they not be listed? Or listed elsewhere?

>    In section 2.5.6 on the 'type' attribute of the <artwork> element, it talks about the processor.  Since that appears to be a reference to the internal RFC Editor processor,

Arrgh, no. Good catch. It is about private processors. I'll make that explicit.

> rather than to the tools readers or writers will use, I would think that confusing text should be removed. (The processor will throw errors in certain cases, but consumers should not throw errors in any text cases?)

Got it; I'll clarify that as well.

> Minor issues:
>    The question of how the grammar is generated is not a substantive difference between v2 and v3, and tells the reader nothing about what will follow.  If it should be mentioned at all, it would seem better in some other section of the document than 1.1

Done.

>    Does <artwork> section 2.5 still need to be enclosed in the cdata construct to actually have the formatting preserved?  If so, should section 2.5 say that?  (Or am I just confused and issuing useless incantations in my current docs?)

The latter, and I say that as someone who was doing that much longer than I needed to. As Julian said, you only need that incantation if there are "<" and "&" characters. Of course, if you have those characters and you don't do CDATA, the error message you get seems unrelated to the problem at hand...

>    In section 2.5, and probably elsewhere, some of the attributes are "ought to be avoided", and one is "Deprecated".  The author apparently means something specific by "ought to be avoided", but this reader is confused.

Fixed.

>    In section 2.22.6 on the suppress-title attribute for the <figure> element, the text is either confusing or incorrect.  THe text talks about figures that have anchor attributes getting autogenerated titles.  And that if one wants to suppress that, one should set this to "false".  It seems pretty odd that setting suppress to false (which is the default) would suppress the autogenerated title.  If it will, the attribute name is just wrong.  More likely, you suppress the auto-generated title by setting this attribute to "true".

Correct. Fixed.

>    This also seems to occur in 2.49.4 in the suppress-title for <table>.

Ditto and ditto.

>    Since <format> is defined (in section 2.23) it ought to be lsited as part of the valid content model for <reference> in section 2.40.

As Julian said, we have a bigger problem with this section. As you probably noticed the sub-sections are automatically generated. The tooling for that (and deep bows to Julian for doing that tooling) is having a problem with my proposed format right now. This will be resolved.

>   In section 2.40 on <reference>, it might be useful to explain what will happen with the short form references.  It seems that how they get rendered will depend upon whether the processing engine has the ability to find additional data to use?  Or maybe not?

Good point, yes.

>    Also, since <reference> allows <front>, <innerRefContent>, ... it seems that <reference> has a content model.  So I presume it is an error for it to say that it does not have a content model?

Exactly.

>   I would have expected the values of the 'series' attribute of the <reference> element to be described in the attribute section (2.40.3) rather than in the base element section (2.40).

We might move them there, depending on whether we keep these as attributes. This is still under discussion.

> Nits/editorial comments:
>    It would be nice if the deprecated elements were marked as deprecated both in their definition and in the places where they can appear.  (for example, marking <facsimile> as deprecated in the content model listing for <address>).  On the other hand, that may be a pain to get right.

This has been suggested many times. We'll see if we can add this to the tooling, but it might be very difficult to do reliably.

>    In the description of <date> in section 2.15, the text correctly notes that it can appear either as a document date or as a reference date.  And then correctly notes that the only legal parent for this is <front>.  Is there any way to remind the reader that <front> is used in long form references?

Done.

Thanks!

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Tue, 08 Apr 2014 17:41:54 +0200

> The latter, and I say that as someone who was doing that much longer than I needed to. As Julian said, you only need that incantation if there are "<" and "&" characters. Of course, if you have tho…

You *never* "need" CDATA. CDATA is just a syntactic construct that can 
make it easier to escape things.

Basically, you trade the need to replace "<" by "&lt;" and "&" by 
"&amp;" by the need not to have certain character sequences inside the 
CDATA section.

Best regards, Julian