Add a "domintro" style

[jyasskin]

speced/bikeshed#1222 discusses the "domintro" class used by WHATWG specs and several W3C specs. It would be nice if TR-Design's stylesheets would provide the appropriate styles so we could more easily include these documentation blocks in more specifications.

I'd have no objection to the editors here picking a better name for the class.

[fantasai]

I'd have no objection to the editors here picking a better name for the class.

Hmm, yeah, I think “domintro” is not helpful generically. :)

It seems like these are informative summaries, that we want in a green box? Is that a correct understanding?

[jyasskin]

Yes, usually summaries of WebIDL interfaces, dictionaries, and operations, with dictionary arguments broken out into separate descriptions of each member.

[fantasai]

Suggested base.css addition:

• Add an “informative summary” class. ("informative summary"? "informative-summary"? "infosum"? "isummary"? not sure what to call it :)
• Style it like .note, but with “Informative Summary” as the label instead of “Note”.

Documents could use it for argument lists and the like, or for other things, depending on what they're speccing. Thoughts?

[jyasskin]

@domenic was worried in the WHATWG Matrix chat that the "informative summary" class might be too different from domintro to allow us to stop copying the domintro styles around. I'm not sure exactly what parts he and the other WHATWG editors consider critical, but it's important that we be able to easily merge these blocks from W3C CG specs to WHATWG standards. Naively, I'd expect that it's easy enough to change the class name and to have the block's label get a different string, but that we'd want the <dl>s to look equivalent?

[fantasai]

@jyasskin I can't address the concerns of someone who won't state what they are.

[fantasai]

I'm reading through a spec with these boxes now, and I have to say the green text on a green background is really obnoxious. If WHATWG wants that styling specifically, they can have it, but I'm definitely not copying it to W3C.

[annevk]

This seems okay to me. As long as folks writing APIs continue to use the <dl> markup pattern including all the specifics for descendants all we'd have to do when going back-and-forth is change a class name. That seems reasonable. I suspect we wouldn't want to directly reuse the style sheet anyway. Not entirely sure what @domenic meant by that.

[domenic]

In general it seems like what we have here is completely different from what I was asking for and what people are using in their specs:

• It uses different verbiage, "Informative Summary" instead of "For web developers (non-normative)"
• It uses different styling, the note styling instead of the domintro styling
• It uses different colors, apparently for reasons of personal taste.
• It attempts to be general, instead of solving the specific "API documentation for web developers" pattern.

In general I was sad about how this went: we asked for a feature, and got something completely different as a result. It felt like the maintainers of base.css are not willing to take input from the community by paving existing cowpaths, but instead want to redesign the ecosystem's existing best practice to fit their personal tastes.

Given such a working mode, I think it's best if we continue to add inline stylesheets that meet the community's needs.

[tabatkins]

• It uses different verbiage, "Informative Summary" instead of "For web developers (non-normative)"
• It attempts to be general, instead of solving the specific "API documentation for web developers" pattern.

Yes, that's one of the topics brought up for discussion. It would be good to discuss it, rather than just reject any possible changes. For example, if WHATWG is married to the existing wording, but the W3C would prefer a different wording, there are ways we can accommodate that. But we shouldn't reject the possibility of using the same wording (whether the existing or something new). At the moment the wording in WHATWG domintro blocks is applied via a ::before pseudo, which means it would be trivial for WHATWG and W3C to use different wording, if that's deemed best. (But if we bake the text into the markup, Bikeshed can differentiate between the groups and insert different verbiage.)

It's similarly worthwhile to discuss if it is useful to generalize slightly, or whether it's more effective for spec readers (and possibly for spec authors) to have a very dedicated "this is for documenting methods/attributes of interfaces, and should use X markup pattern precisely".

• It uses different styling, the note styling instead of the domintro styling
• It uses different colors, apparently for reasons of personal taste.

In WHATWG specs, the domintro styling is the (WHATWG) note styling. They're precisely identical. Thus, when used in a W3C spec, it probably makes sense to similarly use the W3C note styling. I'm not sure why this is a point of contention.

In general I was sad about how this went: we asked for a feature, and got something completely different as a result. It felt like the maintainers of base.css are not willing to take input from the community by paving existing cowpaths, but instead want to redesign the ecosystem's existing best practice to fit their personal tastes.

I'm not certain what you believed was the intent here. It was noted that the "domintro" block markup pattern from several WHATWG specs would probably be useful to carry over to W3C API specs as well (several specs are already doing so), so it might make sense to include default styles in the W3C's stylesheet so that spec authors would automatically get well-styled blocks without having to manually copy/paste from the WHATWG stylesheet. They already get these styles when building specs in the WHATWG group in Bikeshed, so this would be removing some of the manual work when starting a spec in a CG/etc.

It looks like you might be suggesting that the preferred resolution, for you, is that authors of W3C specs continue to use inline styles to make domintro blocks that exactly match WHATWG styling conventions? Could you elaborate on why you think this optimal, versus each standards body continuing to have its own house style? Do you intend to pursue greater confluence between WHATWG and W3C styles, or do you think it acceptable that this is the only place where the two use identical styling and other shared types of blocks (like notes, examples, etc) continue to use different house styling?

[jyasskin]

The current text dates from whatwg/whatwg.org#115, where apparently implementers were confusing these descriptions with the normative specifications. I think "Informative Summary" is about as clear on that point as "... (non-normative)". They were just "Note" before that, so we wouldn't be ignoring a whole lot of cow exploration by picking a different string.

Also +1 on matching the note style, since that's what the WHATWG stylesheet does: https://github.com/whatwg/whatwg.org/blob/ff13f4e11ad02f8e3aa69e2b83bfa4ab16e62c0d/resources.whatwg.org/standard.css#L191-L236 and https://github.com/whatwg/whatwg.org/blob/ff13f4e11ad02f8e3aa69e2b83bfa4ab16e62c0d/resources.whatwg.org/standard.css#L254-L281. WHATWG undoes their note's italics for this, but tr-design doesn't make notes italic anyway.

Other possible names:

• summary
• section-intro
• api-summary
• dev-intro
• summary-note

informative-summary is long, and infosum and isummary will probably be unclear after I forget this thread existed. But I also don't care a whole lot and am happy for someone to make an executive decision.

[annevk]

I'm not sure why you omitted "For web developers" from that quote, but I think that is the part that makes it very clear it's not for implementers.

[jyasskin]

Ooooh, I skipped it because I routinely ignore it when trying to figure out what an algorithm is trying to do, but I see how it could be effective for some people. Thanks!