Early Review of draft-hoffman-xml2rfc-04
review-hoffman-xml2rfc-04-genart-early-davies-2014-04-30-00

I am the assigned 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>.

This is an "early review" requested by Heather Flanagan as part of the 
development of xml2rfc version 3.
 
Document: draft-hoffman-xml2rfc-04.txt
Reviewer: Elwyn Davies
Review Date: 19 April 2014
IETF LC End Date: N/A
IESG Telechat date: (if known) N/A

Summary:

Major issues:

Minor issues:
s1.1/s1.1.1:
I think it would good to split up the text in s1.1 into two parts.  The
text from para 2 ("The design criteria of the changes..") up to and
including the para starting "The canonical RFCs will not have..." is
about the design rationale and probably deserves a separate section.
s1.1.1 should be a sub-section of this new section.  The remainder of
s1.1 is then *really* the change list.  

ss2.11, 2.37, 2.42, 2.47: <city> and other components of <postal>:
Should these elements be allowed to be any unicode characters with an
@ascii attribute as per fullname?

ss2.16, 2.17, 2.18 <dl> and components:  I think the definition list
needs a bit more work.
- <dd> doesn't seem to have a way of getting blank lines into a
definition.  I think it needs the same alternative 'sequence of one or
more <t>'s as allowed for <ol> and <ul>.
- <dd> should allow subsidiary <dl>'s as content.
- Is there any reason why a <dd> shouldn't include <texttable> (and
indeed any other type of list entry)?  Currently <texttable> only occurs
as a child of <section>. 
- Should the author be allowed any control over the amount of indent for
the definition part?  I realize that we are trying to avoid controlling
the formatting explicitly, but there may be aesthetic/readbility reasons
why the author may want the indent to be a controllable.  One reason is
where there are two or more logically related definition lists, maybe
in different sections or just separated by other text.  The author may
wish to have the same amount of indent in these lists so that the reader
is not distracted by the different amount of indent.  My suggestion
would be to allow the author to specify a text string whose length is
used to determine the indent - this avoids any need to specify units or
worry about line length.  Presumably the default would be 'a bit longer
than the longest definition term in the list' although I am not sure
what happens if you have a very long label/term and the definition start
on the same line.
- This brings me on to another issue.  A convention often used in
definition or dictionary lists is that if the label/term is longer than
the hanging indent, the label is allowed to run over the top of the
definition but the definition starts on the same line as the term.  I am
not clear if this can be achieved with the specification as is.  I would
like to be able to achieve this (see next point).
- The 'hanging' attribute is used to specify that the term is or is not
on a separate line.  If hanging is false is the intention that the
definition will be indented?  Or is this left up to the whim of the
formatter?  Currently all list entries are indented (although you could
perhaps use a zero indent - I have never tried!) so it would probably
worth being explicit about what is intended.  If the intention is not to
indent, then it might be useful to have an additional value for spacing
that also adds space between the label line and the definition.

s2.22.7 figure/@title attr:  There is currently no way to incorporate
font characteristic changes in the title (bold etc).  In v2 this has
never been an issue, but it might be desirable to be able to allow font
changes in future.  Maybe this could be done by allowing a <title>
element instead of the attribute and modify the title to allow font
changes - that would also allow the document title to include font
changes as well.  This would probably apply to <texttable> as well.

s2.33 <ol>: The <ol> element does not cater for the cases like 
<list style="format R(%d)" counter="req"> 
that allows ordered lists to be numbered across multiple
instances/sections without having to manually keep track of the counter
start value in each separate <ol>.  An example can be found in 
RFC 5772, s3.6.1 et seq.  This would need the counter attribute to
reappear on this element.  The discussion of the possibility of
specifying a hangIndent as per the comments on <dl> above is also
relevant because the length of the label is dependent on the number and
it is better to use the same indent for all related lists.  Having a
counter="variable-name" attribute would also alter the effect of start -
counter variable should be left unchanged if specified and start is not
specified.  'Default' counter (known as .COUNTER in v2) is reset to 1 if
neither counter nor start is specified. 

Nits/editorial comments:
========================
s1.1, 2nd set of bullets, 1st bullet: Expand RNG

ss1.1, 2.36, 2.37, App B: s/postalline/postalLine/ (this has been
discussed on the mailing list and does make it more comprehensible.

s1.1:  I think it would be worth giving an overview of what is being
done to list handling here, probably as a new subsection to go with with
the rebranded s1.1.1.  It is IMO the other really major change that
users will have to get their heads round.

s2.2 <author>:  Probably worth  mentioning that it is not used when
<author> is used in <reference>.  Maybe also worth flagging that
<facsimile> is deprecated.

s2.4 <area>: s/this document applies to/to which this document relates/
Should probably mention that the areas/names might change over time.
(Are there any historical areas that need to be considered?  I don't
think so but I can't be sure.)

s2.5 <artwork>: Could be useful to mention use of CDATA here.  I would
be inclined to add 'accessed via a URI' to the discussion of the src
attribute.

s2.5.5 src attr: Are there any restrictions on the URI to be used?  In
particular is file: allowed? 

s2.5.5 src attr: Does this need an associated 'scale' attribute so that
the graphic can be displayed as intended?

s2.5.6 type attr, last para: s/mainatin/maintain/

s2.5.6 type attr: I think 'xml' would be an essential extra.  Also
probably 'message-flow' and maybe 'protocol-format' or some such as a
variant on ascii-art specifically identifying one of the many wire
format descriptions. 

s2.6.3 initials attr: An example would help ... say 'e.g., for J. Edgar
Hoover initials="J. E."'

ss2.7, 2.25, 2.52 <b>, <i>, <tt>:  I presume the intention is that the
effects of these font characteristic specifiers should be cumulative
(i.e., <i> just italic text <b> bold italic text </b> italic text</i>)
etc.  Whatever is intended should be explained (maybe a common section
back at the beginning?) I assume that  <i><b><i></i></b></i> would be
legal but that the inner <i> would have no additional effect in each
case.  Maybe processors could issue a warning.

s2.8 <back>: Worth noting that <sections> are appendices here.

s2.9 <blockquote>/s2.9.2 cite attr: I am not keen on requiring the cite
value to be a URL.  Wouldn't it be more natural for it to be a reference
anchor with an optional attribute specifying the location within the
reference, thus:
   <blockquote anchor="bq1" cite="RFC1918" location="Section 2.5 -or-
page 3">Some quoted text........</blockquote>

[I am not sure about the attribute name 'location' but nothing better
springs to mind just now.]

Would this then come out (in ASCII) as:

... previous text with quoted lines indented after it:
   Some quoted text.......
           ([RFC1918], Section 2.5)
Followed by text after the @blockquote.  The reference should probably
be right justified.

How would the anchor be referenced?  Maybe "[RFC1918], Section 2.5"

s2.10 <c>: I have suggested further on that @ttcol should have an align
attribute.  If this is agreed, my idea would be that the alignment
applies to all the cells in the column headed by the relevant @ttcol.

s2.13 <country>:  Once upon a time I thought that we were supposed to be
using two letter country codes from ISO 3166. As per RFC 2629, s2.2.2.

s2.15 <date>: Where do we put 'vague date' strings? Must say I have
never tried a vague date in a reference.  

s2.15.1 day attr:  Note that it is the day *number*. 

s2.15 <date>/s2.15.2 month attr: Is there any reason why we can't allow 
month numbers here as an official alternative?  I think we can still do
the calculation! Better check the style guide to see how dates are
printed out: Presumably the intention is we stick with 16 April 2014
etc.

s2.16 <dd>: I think this should be able to have 

s2.18 <dt>, para 1:  Cut and paste error, I think. Replace with 
'The term being defined by an entry in a definition list.' 

s2.15.3 year attr: Should probably reinforce that it is a 4 digit year
number (or explicitly that it can be 2 digit?)

s2.20 <eref>: Might be worth mentioning that the content and the @target
attr would be combined if the output format can represent hyperlinks.

s2.22 <figure>, para 1: s/postamable/postamble/

s2.22.6 suppress-title attr:  Reversing the meaning of the true/false
values would make more sense (as discussed elsewhere).  Comment also
applies to s2.49.4.

s2.22.7 title attr:  The autogenerated title is combined with the
contents of the attribute  in v2 - I think this could be clarified (I
misread it): Try s/the title gets an/the title is combined with an/.
Also applies to s2.49.5.

s2.23 <format>:  I like 'depredated'!  Unfortunately I guess we have to
s/Depredated/Deprecated/.

s2.29 <li>:  Should one or more <texttable>'s be allowed in the content?

s2.33.3 style attr: It would be useful to specify  what happens after
z/Z in the letter cases (I *think* v2 does aa, ab, ac etc.).  Somewhere
there is an RFC that exercises this.  I believe that if you go back far
enough in the xml2rfc mailing list (say about 2005) there is some
discussion of this.

s2.33.3 style attr: It would probably be very occasionally useful to be
able to specify the field width of the % formats.

s2.37 <postalline>: As suggested on the mailing list it would be more
readable if this were <postalLine>.  As suggested previously this might
need an ascii equivalent.

ss2.38/2.39 <postamble>/<preamble>: Is there ever a need for multiple
paras in a pre-/postamble?  I think I have seen <vspace> in some cases.
Should multiple <t>'s be allowed?

s2.40 <reference>: This is, I believe, still under discussion.  One
point is that the id case may want to specify the version of the id
explicitly (defaulting to the most recent).  The content model is not
right: It is either empty or one <front> plus optional <seriesInfo>,
<format>, <innerRefContent>, <annotation>'s.  <innerRefContent> is
defined but hasn't made it into <reference yet>.
In para 6: s/refernence/reference/

ss2.40.2/2.40.3 series/document attrs:  These are specified as mandatory
but this doesn't work if the <front> specification option is used.

ss2.43.7/2.43.10 obsoletes/updates attrs: Probably ought to specify
whether or not white space is allowed.

s2.44 <section>: Might be worth saying explicitly that it can be empty.

s2.48 <t>: Should <texttable> be allowed within <t>?  As mentionaed
above there are some other places where <t> might be a child (<dd> and
maybe <note>).

s2.49 <texttable>: See previous discussion as to whether <texttable>
should be used elsewhere.  See also comments on s2.22.6 and s2.22.7.

s2.50 <tindent>: Could <tindent>'s appear inside list elements?

s2.51 <title>: Could this be allowed <b>, <i> and <tt>in the content?

s2.53 <ttcol>:  The content model should probably allow for <b>, <i> and
<tt>.

Appendix B looks to match OK except for <reference>.