This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 21447 - [HTML] editorial: un-numbered algorithm steps
Summary: [HTML] editorial: un-numbered algorithm steps
Status: CLOSED WONTFIX
Alias: None
Product: WHATWG
Classification: Unclassified
Component: HTML (show other bugs)
Version: unspecified
Hardware: All All
: P2 minor
Target Milestone: Unsorted
Assignee: Ian 'Hixie' Hickson
QA Contact: contributor
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-03-31 03:06 UTC by Michael Dyck
Modified: 2013-04-20 00:42 UTC (History)
2 users (show)

See Also:


Attachments

Description Michael Dyck 2013-03-31 03:06:53 UTC
In 3.1.4 "DOM tree accessors",
under cssElementMap,
the 3 algorithms associated with the value of that IDL attribute
are presented as plain paragraphs.

Instead, they should perhaps be ordered lists of steps.
(Especially the second one, but all three for consistency.)
Compare to a similar trio of algorithms in 3.2.3.9.
Comment 1 Ian 'Hixie' Hickson 2013-04-01 18:38:57 UTC
Is it ambiguous? It seems like there'd only be one way to interpret these steps, and putting them into ordered lists, especially those with just one paragraph, wouldn't make things any clearer.
Comment 2 Michael Dyck 2013-04-02 02:42:45 UTC
(In reply to comment #1)
> Is it ambiguous?

Nope.

> It seems like there'd only be one way to interpret these steps, and
> putting them into ordered lists, [...] wouldn't make things any clearer.

True. However, it seems to me that you could go to almost any algorithm in the spec, change it from an ordered list to plain paragraphs (while retaining indenting for substeps), and say the same thing of the result: there'd still be only one way to interpret the steps, and putting them (back) to an ordered list wouldn't make things any clearer.

So, disambiguation/clarity doesn't seem to be the reason for formatting most algorithms as ordered lists. I'm not sure what *is* the reason (following ECMAScript's lead? providing an easy way for people to refer to a particular step?), but it seemed to me that whatever caused the trio of algorithms in 3.2.3.9 to be <ol>s would also apply to the trio in 3.1.4.

I don't mind if you want to leave 3.1.4 as is, but I am curious as to why some algorithms are <ol>s and some aren't -- what the deciding factor is.
Comment 3 Ian 'Hixie' Hickson 2013-04-10 22:16:20 UTC
The usual deciding factor is whether there's more than one step or not. (Note that steps can have multiple paragraphs.) A step is something where the order in which things are performed matters.

In this particular case, all three algorithms have just one step. The middle algorithm could arguably have two (The initialisation and the action), but since the other two algorithms aren't numbered, and since there's only one order that makes sense here, it's prettier to not use numbered lists.

There are certainly times where I've used lists where I don't need to, e.g. the definition of "advisory information" (since there's really only one step there). However, there's usually aesthetic reasons to go with a numbered list rather than straight paragraphs. For example, in the case of "advisory information", without using a list it would not be obvious where the algorithm started and where it ended. Also, sometimes algorithms used to have many steps and are simplified down to only one or two steps but I don't notice and so the list form remains. Other times I use paragraphs because as I'm writing it I don't think of it as a set of steps but more a set of constraints, and when the text evolves into a set of steps I don't think about changing it to a list.

In general, I like to avoid changing the style when that's the only problem: every change runs the risk of breaking something unintentionally, and there's no good way to run tests on these algorithms. Structural changes are especially prone to this kind of thing because the diffs are hard to read and the necessary changes (changing from the "UA must" style to the imperative style with an algorithm-invoking "must") are very invasive to the most sensitive parts of the algorithms.
Comment 4 Ian 'Hixie' Hickson 2013-04-19 23:28:19 UTC
WONTFIX for reasons described in comment 3.
Comment 5 Michael Dyck 2013-04-20 00:42:23 UTC
Okay.