Early Review of draft-hoffman-xml2rfc-04

Request Review of draft-hoffman-xml2rfc
Requested rev. no specific revision (document currently at 23)
Type Early Review
Team General Area Review Team (Gen-ART) (genart)
Deadline 2016-11-12
Requested 2014-03-21
Authors Paul Hoffman
Draft last updated 2016-11-12
Completed reviews Genart Early review of -04 by Elwyn Davies (diff)
Genart Early review of -04 by Joel Halpern (diff)
Genart Early review of -04 by Ben Campbell (diff)
Assignment Reviewer Joel Halpern
State Completed
Review review-hoffman-xml2rfc-04-genart-early-halpern-2016-11-12
Reviewed rev. 04 (document currently at 23)
Review result Ready
Review completed: 2016-11-12


I am one of the requested Gen-ART reviewer for this draft. For background on
Gen-ART, please see the FAQ at


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 


    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?