[rfc-i] Gen-art early review of draft-hoffman-xml2rfc-04.txt

Paul Hoffman paul.hoffman at vpnc.org
Sat Apr 19 09:23:27 PDT 2014

Thanks for the thorough review! I was about to turn in a new draft (particularly spurred by the two earlier GenArt reviews), so the timing was good.

--Paul Hoffman

On Apr 18, 2014, at 4:37 PM, Elwyn Davies <elwynd at folly.org.uk> wrote:

> 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?

This needs to be answered first in the review of draft-flanagan-nonascii; please bring it up there. I have left a note in my comments to check this later.

> 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>.

Good catch; fixed.

> - <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>. 

I did not include <texttable> in <dd> or others for that reason: is a section-level item. There is a proposal to add HTML-style tables in v3, and those would probably work in many more containers.

> - 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.

The output of the v3 format (particularly HTML output) is meant to work on many devices, including small-screen hand-helds. This is the reason we removed all of the suggestions on horizontal spacing. While I agree that a reader might be a bit disturbed to see two parallel <dl>s with different column width, they would be much more disturbed to not have a list readable on a device they are using due to this type of setting.

> - 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?  

The latter. Given the new capabilities in v3, we expect that the community will find new uses for them and have preferences for how they be displayed, but we won't find all of those out immediately.

> 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.

Again, this will probably be worked on over time, and we can see whether or not a new attribute is needed. I suspect that a lot of <dl> will possibly change after we have experience with it.

> 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.

A few things here:

- This applies to <section> titles as well.

- It is not clear if we want to all font characteristics, particularly because an author doesn't know for sure what formatting is already going to be applied to the title.

- Having said that, the most common needed case is monospace for protocol element names.

- Adding this also allows references in titles.

Done for <figure>, <texttable>, and <section>

> 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. 

There is a significant question about what the semantics mean for lists across sections that have numbering changes. This needs to be discussed more, and I'll start a separate thread about it.

> Nits/editorial comments:
> ========================

All were done except as noted here.

> 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.

And yet others want exactly the opposite: no camelCasing in names. The next draft will have a mixture of the two; this will have to be discussed again. (And, unfortunately, that's not a nit...)

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

See above for discussion about v3 and its intended use on small screens.

> 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.

Yes, they are meant to be cumulative. I need to think more about where to say this. It won't go in the next draft, but I've noted it.

> 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"

This is a major problem with the current <blockquote>, and will be discussed.

> 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.

We are probably deprecate <texttable> in a later draft, and whatever replaces it will certainly have alignment options.

> 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.

That is already in the Style Guide; it is not part of the format.

> 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.

That is an issue for the Style Guide.

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

Style Guide issue.

> 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?

This seems excessive for the lead-in to figures and tables. Editorially, I would expect almost anything about the figure/table to be in the text referring to it. Thus, I don't think we need to allow multiple paragraphs here.

More information about the rfc-interest mailing list