search

w3c / ttml2

Timed Text Markup Language 2 (TTML2)
https://w3c.github.io/ttml2/
Other
41 stars 16 forks source link

Improve anonymous span prose, clarify rule ordering (#1139). #1179

Closed skynavga closed 4 years ago

skynavga commented 4 years ago

Closes #1139.

Implement https://github.com/w3c/ttml2/issues/1139#issuecomment-526928441 modulo the following:

skynavga commented 4 years ago

@palemieux

In what way does replacing instances of specific language with a general rule constitute a "significant change"?

In what way does this remove an important clarification?

skynavga commented 4 years ago

Moving this PR (and related Issue) to 3ED, as this is clearly going to become another philosophical debate about editorial style, and only serve to delay 2ED publishing schedule.

nigelmegitt commented 4 years ago

I agree with @palemieux here - it is clearer to state that the steps need to be executed in the specified order every time that is the case than to state exceptions where it is not the case.

skynavga commented 4 years ago

@nigelmegitt that's letting the cart drive the horse; i'm not sure there are any exceptions to the rule

nigelmegitt commented 4 years ago

i'm not sure there are any exceptions to the rule

@skynavga that "I'm not sure" is the strongest argument yet for retaining the qualification locally to each list. If you as the editor are not sure if there are any exceptions, I reckon it's likely that most other readers will not be sure in the opposite direction, i.e. they will be unclear if the list of steps must be executed in the specified order or in any order.

skynavga commented 4 years ago

@nigelmegitt if there is an exception (and I very much doubt it), then you can darn well be sure there is very explicit language pointing out that exception; but I would say the burden of proof is on someone who presumes there is an exception to the rule that would require us to explicitly state in each instance that rules are ordered (as opposed to stating that it is always the case for numbered steps/rules);

skynavga commented 4 years ago

I should also note that the underlying semantic markup is olist vs ulist, which makes it explicit, so I never would have used olist if I intended the list to be unordered.

nigelmegitt commented 4 years ago

I thought about the difference between olist and ulist and realised that even with steps that can be executed in any order we would still need to use olist in the specification, otherwise we would find it difficult to refer to individual steps. I don't know if there is a good semantic match in HTML for a list that has unique numbers for referencing but whose members are not sorted.

My preference here remains not to make the change.

skynavga commented 4 years ago

At present the spec is inconsistent because we have inadvertently added explicit language about ordering in some but not all places where we should have not done so and stated a general rule or should have done so everywhere. It is redundant to fix this by taking the latter approach IMO when the former is safer (since we would not need to worry about forgetting to add explicit language in every new ordered list in the future as the general convention would cover it).

nigelmegitt commented 4 years ago

some but not all places

which places have a list of steps but don't say if they must be executed in order?

skynavga commented 4 years ago
nigelmegitt commented 4 years ago

Thank you for the analysis @skynavga . Given https://github.com/w3c/ttml2/pull/1179#issuecomment-542314468 I currently believe the best solution to this would be:

  1. Use olist throughout so that steps may be explicitly referenced, AND:
  2. Explicitly state prior to each list of steps if they must be executed in the specified order or in any order.

Point 2 above could be simplified perhaps by defining terms for:

and using the applicable term as a shortcut for describing the list of steps with fewer words. We'd end up with language like "Execute the following any-order steps:".

skynavga commented 4 years ago

@nigelmegitt I don't follow you. In none of the cases in my analysis is it the case that numbered items can be evaluated in any order other than the numbered order. In particular, in none of the cases does the text admit evaluation in any order.

To be very clear, numbered lists are always performed in the numbered order whenever they represent rules/steps/etc (as opposed to criteria/cases). The only distinction is whether (1) evaluation stops when the first rule/step is successfully evaluated or (2) evaluation conditions to the last numbered item regardless of whether a rule/step is successfully evaluated. The latter being the default, and the former being the exceptional case and explicitly marked in the text.

nigelmegitt commented 4 years ago

In none of the cases in my analysis is it the case that numbered items can be evaluated in any order

I am proposing that the fact that items are numbered should not be taken to imply that the steps are ordered. Numbering does two things: 1. it suggests some position within an order that may or may not be important for processing, 2. it facilitates external reference of the step, so we can say "step 3 does that job" or "there's a problem with step 5".

In your analysis @skynavga you include, for example:

  • §13.1.3 set
    • olist should be ulist since no order is implied

If we do this, then we will no longer have an easy way to refer to the steps. However this would then mean that we need to be explicit in the text that no order is implied.

Hope that helps explain my thinking?

skynavga commented 4 years ago

I am proposing that the fact that items are numbered should not be taken to imply that the steps are ordered.

And I am saying that in all cases where numbered lists state rules or steps (of a procedural nature), then they are intended to be ordered (whether so stated or not).

In your analysis @skynavga you include, for example:

§13.1.3 set olist should be ulist since no order is implied

If we do this, then we will no longer have an easy way to refer to the steps. However this would then mean that we need to be explicit in the text that no order is implied.

And in all of these cases (where olist was used when ulist should have been used), the items are not rules or steps (of a procedure) but are (unordered) criteria or constraints.

The correct (and logical) response is to change these latter to ulist, to add a general convention for numbered lists of rules/steps, and to remove references to "in the specified/indicated order (etc)".

nigelmegitt commented 4 years ago

the items are not rules or steps (of a procedure) but are (unordered) criteria or constraints.

Regardless of this, it is still useful to be able to reference those criteria or constraints.

css-meeting-bot commented 4 years ago

The Timed Text Working Group just discussed Improve anonymous span prose, generalize ordered rule convention (#1139). ttml2#1179, and agreed to the following:

The full IRC log of that discussion <nigel> Topic: Improve anonymous span prose, generalize ordered rule convention (#1139). ttml2#1179
<nigel> github: https://github.com/w3c/ttml2/pull/1179
<nigel> Glenn: Before we start this, just to point out that this and the next issue today are marked for 3rd Ed so if we keep
<nigel> .. them there then we don't have to deal with them right now.
<nigel> Nigel: Thank you, that's useful. If we have agreement now we can implement it, otherwise we don't need to stress too
<nigel> .. much about it.
<nigel> Glenn: To summarise the situation, part of this was about prose to do with anonymous span concerning ordering
<nigel> .. that was possibly vague and we need to be clear about ordering of rules.
<nigel> .. There are two ways to do this. One is to add text directly about ordering like we have in some places,
<nigel> .. or prescribe a general rule about ordered lists and I chose to take the latter route because I realise that everywhere
<nigel> .. we have ordered lists in the text, and where the underlying XML document uses the `<olist>` syntax and it was
<nigel> .. used to define procedural steps it was always intended to be ordered sequentially and we could apply generic text.
<nigel> .. After analysing all the document I found that everywhere that the ordered lists were used for procedures it was
<nigel> .. always intended to be sequential, but that in a number of places where it was enumerating cases that were not
<nigel> .. procedures or steps that no order was implied, i.e. an unordered list of bullets could be used but I had used olist
<nigel> .. in order to allow referring to specific cases as opposed to steps. For example in the list of criteria under
<nigel> .. processor or document conformance we have items that are listed 1 through 3 and so forth that could have been
<nigel> .. bulletted items but then I would have no way to refer to each criterion as a numbered item.
<nigel> .. My proposal was to have a rule that said wherever ordered lists appear in procedures as ordered steps then they
<nigel> .. are always in the indicated order and we can take out any text in the inline prose that talks about it being ordered
<nigel> .. and use the general rule instead. But Nigel I think you have a slightly different opinion that you want it to be defined
<nigel> .. inline instead.
<nigel> Nigel: Yes, I want to keep the current approach so as to avoid promoting use of unordered lists that lead to a list
<nigel> .. of steps that we cannot then reference. It's useful to know that there's already a case there.
<nigel> Pierre: My preference is to make fewer changes and just add the "this is an ordered list" text to the one specific list
<nigel> .. that gave rise to the issue and do nothing else. If that's not acceptable then defer this.
<nigel> Glenn: I was just counting the number of places where there is an ordered list missing the language of ordered steps,
<nigel> .. 31, and the number that could be unordered lists, 10. There's a case that the default rule could apply to ordered
<nigel> .. lists being ordered always, numerically. One option would be to change everything to unordered lists that are criteria
<nigel> .. or cases which would remove the ability to refer to specific cases or criteria unless we name them, which is somewhat
<nigel> .. of a negative.
<nigel> Nigel: It's a blocker for me.
<nigel> Glenn: Maybe the best thing is to do as Pierre suggests, to handle this one case specifically by adding the language
<nigel> .. about "ordered" and move this general issue into 3rd Edition.
<nigel> .. Then we can deal with that later.
<nigel> Cyril: I would like this last proposal, we should not do major changes at this stage. We should not change parts that
<nigel> .. are not broken because we think it would be better.
<nigel> Glenn: I'm fine with that, it would deal with the immediate issue about span processing.
<nigel> Nigel: Works for me.
<nigel> Glenn: OK I will create a new issue regarding the ordering and point at this and create a new PR dealing with just the
<nigel> .. original issue. OK?
<nigel> Nigel: Any objections?
<nigel> group: [no]
<nigel> Glenn: And I'll deal with the original issue in 2nd Ed CR.
<nigel> SUMMARY: @skynavga to add ordering language to deal with original scope of issue, and raise new issue for general ordering of steps, targeted at 3rd Ed.
skynavga commented 4 years ago

@palemieux I believe the above commits should address your comments. Let me know if otherwise.

skynavga commented 4 years ago

@palemieux see https://github.com/w3c/ttml2/pull/1179/commits/54355ab2c4480d34c9ac7778d46088367894b9c8

css-meeting-bot commented 4 years ago

The Timed Text Working Group just discussed Improve anonymous span prose, clarify rule ordering (#1139). ttml2#1179.

The full IRC log of that discussion <nigel> Topic: Improve anonymous span prose, clarify rule ordering (#1139). ttml2#1179
<nigel> github: https://github.com/w3c/ttml2/pull/1179
<nigel> Glenn: Final tweak awaiting approval from Pierre, when you can take a look at it.
<nigel> Pierre: Thanks
<nigel> Nigel: OK ping to Pierre completed!
palemieux commented 4 years ago

@skynavga In the case of p, why wouldn't a child text node not always result in an anonymous span?

skynavga commented 4 years ago

@palemieux I give up. I removed the text under p as well.