[rfc-i] List aesthetics and run-on numbering [was Re: Gen-art early review of draft-hoffman-xml2rfc-04.txt]

Paul Hoffman paul.hoffman at vpnc.org
Mon Apr 21 08:13:21 PDT 2014

On Apr 21, 2014, at 4:38 AM, Elwyn Davies <elwynd at folly.org.uk> wrote:

> Hi, Paul.
> A suggestion that might cover both the issues below I  highlighted in my
> review and do it at a 'higher level' of abstraction.
> On Sat, 2014-04-19 at 09:23 -0700, Paul Hoffman wrote:
>> 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:
>>> - 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.
> <<snip>>
>>> 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.
> Abstracting my view of the requirements from the resulting formatting, I
> think the following would be useful:
> 1. Authors being able to indicate that several lists are related and so
> should be displayed in the same way as far as possible.
> 2. That the identification field (numbering, etc.) should run on across
> lists as per the example above.

Thanks! This seems like a tractable solution to the problems. I'm don't know if (1) is actually doable, but having grouped lists would at least let the processor try if it was possible.

> This could be achieved by adding the concept of a 'list group'.  A list
> would specify which list group it was part of.  The group would specify
> the style to be used (ordered, unordered, etc), the format for the
> identification, if needed, and whether the counter, if relevant, should
> be restarted for each new instance from a particular value or left to
> run-on from where it finished in the last list in the same group.

And that may be over-engineering the solution. We could have grouped lists without going as far as having a generic list type: the grouping could be an optional group name in the list start element.

> The formatter could then use the list group as a hint to ensure that the
> indentation and other display features were common across all list
> entries in the group so far as was possible/relevant (e.g., if a user
> turns their tablet from landscape to portrait or some such between lists
> then all bets are off).
> To make the whole thing a bit cleaner, the new <ol> and <ul> could be
> handled with built in groups which would reduce the duplication we now
> have.  Personally I would like to see if the lists could revert to a
> single element as introducer rather than the three we now have.

Again, I don't think we need to go that far, and the HTML world seems to like having different list types. I'll add the "list group" idea in the next draft.

--Paul Hoffman

More information about the rfc-interest mailing list