Problem in rule “headers.ol-toc”: missing sync with respec?

[iherman]

This is not really a "bug" but rather a missing sync with the respec guys...

The checker gives a warning, whereby:

The TOC should be an <ol class="toc"> inside the main navigation element (<nav id="toc">).

However, the document, including the TOC, is generated by respec. Either this warning should not be issued or respec developers should be contacted to settle this...

Found while checking http://w3c.github.io/web-annotation/admin/TR/annotation-protocol/Overview.html.

[deniak]

@tripu looking at the history of that rule I couldn't find where that requirement comes from. I remember this is something brought by the new TR design but I don't see where it was defined. Does it necessarily need to be a <ol>?

[tripu]

@deniak, I have traced the rule back to #284 and #267, but not any further… So I'm not sure where it comes from, either.

Either that was a “should” that I discussed privately with one of you, or I misinterpreted our list of requirements.

@fantasai, @plehegar: OK to drop this rule (check, message)?

[fantasai]

Why would we drop this rule? A W3C spec ought to have a table of contents, imho that should be a requirement. Requiring that it have particular markup is necessary for it to be styled consistently across all specs. This is one of the most important things to check for imho.

[fantasai]

(If you're wondering why it's <ol> and not <ul>, it's because a table of contents is an ordered list, not an unordered one. A lot of people seem to miss that distinction, so maybe that's what you're confused about?)

[plehegar]

Looking at
https://lists.w3.org/Archives/Public/spec-prod/2016JanMar/0036.html
we did not introduce a requirement to use <ol> at that time.
Some specifications do use more ... exotic markup, such as
https://www.w3.org/TR/2016/WD-exi-for-json-20160128/

As usual, I don't think we can change the rules without advance notice.
@caribouW3 , are you aware of this mismatch?

[caribouW3]

@plehegar Yes, and I have already hacked a version of xmlspec to produce a list-based TOC (but there's still an issue with the side "Editor's draft" banner when the TOC is in sidebar mode).
See https://www.w3.org/XML/EXI/docs/format/exi.html

[iherman]

I am just a poor end-user who happens to use respec... what is really important for me (and for other respec users, I guess) is that respec would generate a code that is accepted by specberus with the lowest number of warnings.

(That being said, because I did some postprocessing on respec-generated documents, I would also have to update my EPUB generator, but that is on me...)

Cc: @halindrome @marcoscaceres

[tripu]

I think you are right about the need for consistent styling, @fantasai. I'm OK to keep it. I just think that it should have been announced in advance, at least to spec-prod, to prevent the kind of discrepancies @iherman is reporting here. AFAIK, we never decided explicitly to introduce it.

[halindrome]

I'm just a poor respec user and maintainer.

1. I would appreciate some advance notice when something as basic as this is going to change. It effects every single spec generated with respec. Actually, having said that... why has anyone been able to publish anything?

2. can we please relax this requirement for a couple of months if we actually want it at all?

3. I don't need a vote or anything, but in the future it would be nice if we were kept in the loop. How can we achieve that? (And if I was in the loop all along and just completely missed it, I apologize)

[caribouW3]

My guess:

1. because we use the old pubrules checker, not specberus, yet
2. specberus will be the only pubrules checker on August 1st.
3. there was no intent that markup changes were necessary for TR2016 styling, but it was obviously not tested against at least one spec generated from each toolchain in use (xmlspec.xsl is still one of these!!)

[tripu]

@halindrome, my take:

1. I completely agree with the need to announce in advance. We were all able to publish because this rule emits a warning instead of an error.

2. Being a warning, we don't need to change anything. It will scream a bit, but not prevent publication.

3. Be in the loop by following w3c/tr-design and the spec-prod ML. (But in this case, it was our fault.)

[fantasai]

Wow, the markup for exi-for-json is astoundingly bad. I can't believe that was ever allowed.

[fantasai]

The banner problem is due to the extra <div class="toc"> around the <nav id="toc">. Remove that, and it should work.

[marcoscaceres]

Filed ReSpec bug: w3c/respec#835

We should be able to automatically pick up these changes to specberus once I implement integrating it into our test framework. Then, by all means, break whatever you want and make ReSpec upset: We will get the warnings automatically and can fix them there.

However, there should be some kind of grace period with breaking changes... they should initially appear as warnings that are time-bombed (such as the ToC one).

[caribouW3]

@fantasai, thx, it works now
(and I agree that some of the markup is just horrible - also for the EXI format spec, but now valid html5)

[tripu]

(Description edited for clarity.)

[tripu]

I wanted to drop this rule, since apparently I made it up on my own, somehow.

But @fantasai likes it, time has passed, it's not preventing publication for anybody, and @marcoscaceres already filed w3c/respec#835.

So… OK to leave things as they are, and close this issue?

[fantasai]

Works for me.

[tripu]

ReSpec adapted (w3c/respec#835, w3c/respec#909).