Specification Markup and CSS Workshop for Editors and Team Contacts

13 September 2023


caribou, jyasskin
Elika Etemad
fantasai, jyasskin

Meeting minutes

<fantasai> [planning to start 5min late, take your time]

<fantasai> https://www.w3.org/StyleSheets/TR/2021/README

<astearns> (fantasai walks us through the document)

<astearns> r12a: unicode code point stuff is not quite complete

<spectranaut_> can someone share a link that fantasai is shows us?

<astearns> https://www.w3.org/StyleSheets/TR/2021/README

<fantasai> https://www.w3.org/StyleSheets/TR/2021/README

<spectranaut_> thanks!

<fantasai> <fantasai>the CSS file hasn't been updated onto the server yet to support unicode codepoint markup

<fantasai> r12a: planning to build in support for expanding out this markup into respec/bikeshed

khushal: I always trip over referencing things in other specs, especially when the same keyword is used across multiple specs. I just use an <a> tag.

fantasai: Bikeshed's autolinking isn't part of the stylesheet.

fantasai: Stylesheet is mostly CSS, with a bit of Javascript.

fantasai: Respec and Bikeshed do a bunch of processing and spit out an HTML file that uses the stylesheet.
… WGs should review their custom styling and see about upstreaming it.

<spectranaut_> what about all of these tables: https://w3c.github.io/core-aam/#mapping_role_table

fantasai: Or check if there's already something in the stylesheet to adopt.
… We got an issue seeing if we can upstream it.

jyasskin: There will be a discussion about how to improve things when upstreaming, and that's good.

fantasai: We want to align things with the current visual pattern. Or check if it's super-specific and turn it into something that most of our WGs would find useful.

fantasai: The blue boxes for properties were originally CSS-only, but we realized they were a structural definition and made them useful for more groups.

spectranaut_: We have these mapping tables (https://w3c.github.io/core-aam/#mapping_role_table) that define a ton of things, with custom CSS. It's annoying because in PR-Preview you don't have custom CSS.

fantasai: I think these could use the "dfn" class, or a data table.

spectranaut_: I tried the data table. It looked wrong. Maybe I'm just used to the current way.

spectranaut_: Where should we put custom CSS?

spectranaut_: We have a directory, and PR-Preview doesn't work.

fantasai: Use colgroup for these.
… to identify the first column of headings.

fantasai: <explains how the stylesheet uses table markup>

fantasai: I put custom CSS into an external stylesheet or in the <head>

spectranaut_: We have a bunch of specs that use the same format.

fantasai: Then external, or consider class=def

spectranaut_: I like class=def

<florian> example of test boxes can be found in this spec for instance https://drafts.csswg.org/css-text-3/#text-transform-property

florian: I worked with Tab to include a feature that adds test annotation boxes.
… On the right, you have little >TESTS boxes. The styling isn't in tr-design; it's injected in every spec.

fantasai: It makes sense to upstream it.

jyasskin: Upstream it.

<Zakim> jyasskin, you wanted to explain PR-Preview and bikeshed boilerplate.

jyasskin: <explains how PR-Preview loses adjacent files and isn't really maintained. Suggests using bikeshed boilerplate to include group-wide CSS.>

spectranaut_: I think we use Respec.

jyasskin: I can't help you then. ;)

spectranaut_: What's the difference?

[group]: Discusses several ways Respec and Bikeshed differ, and shows what Bikeshed source looks like.

<fantasai> https://speced.github.io/bikeshed/

<fantasai> https://respec.org/docs/

Marcelo: I was noticing the green and red dots. Does that come from CSS?

<florian> Documentation for that feature in bikeshed: https://speced.github.io/bikeshed/#testing

fantasai: Bikeshed is maybe using Javascript to generate that. Bikeshed source is a <wpt> element.

Marcelo: Do they consider colorblindness?

fantasai: Tab themself is colorblind, so hmm.

johanneswilm: Events? For attribute values, we have quotations marks for the different possible values.
… I can't see that in the stylesheet overview page. Is it ok to use that style?
… I'm just using the previous practice.

fantasai: This stylesheet doesn't provide anything for inline code.
… Specs want to distinguish a lot of things for inline code, and there wasn't a strong enough pattern.
… Specs with respec and bikeshed use consistent style because they generate specialized markup.
… Bikeshed generates something specific for ''css-markup''.
… 'single-quoted propertes' generate something a bit different.
… It's not pulled up into the W3C-wide stylesheet.
… We could do that, but we'll need to do a survey of all the code patterns.

johanneswilm: I'm not sure about this, but we use different styling in different specs in the same WG. Is there a spec we should follow? We'd like to copy other WGs.

fantasai: If you have some styling that another group is using, and they're defining a significantly different technology, we should upstream that concept to the main stylesheet.
… If it's specific to that technology, then maybe use a shared stylesheet.
… If it's a broad enough category, we should upstream it.
… CSS had default.css before a bunch of it got upstreamed.
… It's a bit of a judgement call. Do you have particular examples?

johanneswilm: We and the editing WG don't have a consistent style. But we could try to copy another WG that's consistent.

jyasskin: What are you actually styling?

johanneswilm: No actual styles.

jyasskin: most of the specs I write don't need that much custom stuff

caribou: We were using grammars, and we had to style productions. That could happen in another group.

<astearns> bikeshed railroad diagrams?

caribou: The problem is that when there are changes to the main CSS, it might affect the group's styling.

caribou: So you have to restrict the group's styling to the minimum.

fantasai: We had some similar styling.

<spectranaut_> thanks for this useful and productive session @fantasai :) w3c/core-aam#193

caribou: I'd love to have special styling for the diff markers. You have <ins> and <del>, but I'm not sure we use that for WebRTC for marking REC candidate changes. Big green and red boxes.

<johanneswilm> https://github.com/w3c/input-events/blob/gh-pages/index.html <-- We don't seem to be using any respec shortcodes for <code>"value"</code>. It's just directly like that in our source code.

fantasai: That's probably the WG styling.

caribou: So we have some trouble between the main and WG styling, because the colors conflict.

fantasai: Let's look over that.
… We still don't have good practices for the amendments. In a way that's reasonably easy.
… The spec mainly just supports <ins> and <del>. They have very flexible markup models, so you can wrap lots of things in them.

fantasai: <shows how the candidate corrections work, with buttons that enable/disable embedded <ins> and <del>s.>
… Marking things up so that JS works is a bit of extra work. Because you have to associate the <ins> and <del>s with the annotation.

caribou: We're using that, with 3 toggles. But our boxes follow the candidate correction boxes. Because our changes are much bigger.
… 20-30 lines changed.

florian: I can give an example of a spec with a box that does that, and it's not too bad.

<florian> https://www.w3.org/TR/css-contain-1/#c3

florian: In CSS contain, there are some proposed corrections, some of which are small and use <ins> and <del> But another replaces a whole a paragraph. Then it's just a proposed correction box that describes the text to insert. You have to make sure the change is understandable, but you don't have to have inline <ins> and <del> all over the place.

fantasai: The main requirement in the Process is that you can understand what text is there.

florian: Another example in section 2 has the change outside the Correction box, but the buttons still work.

florian: Proposed Correction 2 is a bigger change.

caribou: I'd like a list of the proposed corrections for the recommendation.

florian: In this one, I made an index myself, but a bikeshed feature would be better.

caribou: Is it possible to have that as part of the table of contents?

<astearns> +1 to putting it at the top

fantasai: In the Status of this Document, we could have a link to proposed corrections index from the place where it mentions them already.


<caribou> https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters

fantasai: We work on the TR spec stylesheets on https://github.com/w3c/tr-design/issues
… It's a side project and not extremely responsive.

jyasskin: can ping me by email if something needs attention though

fantasai: From an auditing perspective, look at what custom style you're using, and see if that should be replaced from something from the standard, or upstreamed, or stay.

<astearns> audit checklist w3c/tr-design#327

Minutes manually created (not a transcript), formatted by scribe.perl version 221 (Fri Jul 21 14:01:30 2023 UTC).


Succeeded: s/??/khushal/

Succeeded: s/???/jwilm/

Succeeded: s/jwilm/johanneswilm/

Succeeded: s/.../jyasskin:

Succeeded: s/Carine/caribou/

Succeeded: s/have/could have/

Succeeded: s/corrections/corrections index from the place where it mentions them already/

No scribenick or scribe found. Guessed: jyasskin

Maybe present: [group], fantasai, florian, johanneswilm, khushal, Marcelo, spectranaut_

All speakers: [group], caribou, fantasai, florian, johanneswilm, jyasskin, khushal, Marcelo, spectranaut_

Active on IRC: astearns, caribou, fantasai, florian, johanneswilm, jyasskin, spectranaut_, tidoust