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: and other components of : Should these elements be allowed to be any unicode characters with an @ascii attribute as per fullname? ss2.16, 2.17, 2.18
and components: I think the definition list needs a bit more work. -
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 's as allowed for
    and
      . -
      should allow subsidiary
      's as content. - Is there any reason why a
      shouldn't include (and indeed any other type of list entry)? Currently only occurs as a child of
      . - 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 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>.