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

Elwyn Davies elwynd at folly.org.uk
Mon Apr 21 04:38:34 PDT 2014


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.

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.

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.

Regards,
Elwyn




More information about the rfc-interest mailing list