Add `.uname` and `.codepoint` to style characters inline

[aphillips]

Adds styles recommended by I18N in https://www.w3.org/TR/international-specs for the inline naming of characters and code points.

[I18N-ACTION-1257]

[aphillips]

@fantasai noted:

Please document any additions to the stylesheet in the README.

Thanks for the pointer! I will add that to a revision imminently.

It looks like you're trying to use smallcaps here, please actually use smallcaps.

Do you mean font-variant: small-caps? The problem with that is that the name generally is already uppercase and font-variant small-caps only affects the lowercase letters. (It's certainly the case that the code point notation U+BEEF is generally already uppercase). This style has the same effect as small-caps, but on mixed case and uppercase.

Of course, I'm probably missing a feature of CSS I don't know. Happy to change to the right thing.

[aphillips]

@fantasai:

Thanks for the pointer! I will add that to a revision imminently.

Hmm. The file src/README.html is static HTML. Am I supposed to edit the boilerplate stuff? Should I just add my stuff? Or worry about the "tragedy of the commons"?

[fantasai]

Do you mean font-variant: small-caps? The problem with that is that the name generally is already uppercase and font-variant small-caps only affects the lowercase letters.

• Option A: font-variant: all-small-caps https://www.w3.org/TR/css-fonts-4/#font-variant-caps-prop
• Option B: text-transform: lowercase; font-variant: small-caps

[fantasai]

Am I supposed to edit the boilerplate stuff?

Edit whatever needs editing. It's not generated, because this is the template against which the generators are designed. :)

[aphillips]

(The readme changes will take me some time. I'll update this PR again when we're ready. The change 244dd86 does not represent "done")

[aphillips]

@fantasai We're contemplating further changes to the styling itself. A question has some up about using color to set the character name apart from the text--and specifically which color to use. Is there any guidance on how to choose a color to match the general color scheme? Could you maybe suggest a color to use? Or should we avoid it?

[fantasai]

@aphillips I don't have a good sense of colors. :( What part of this were you planning to color? Can you post an example of the markup?

[xfq]

@fantasai We used teal initially, but since it is the same colour as the link colour in i18n articles, we changed it to brown later.

See https://w3c.github.io/bp-i18n-specdev/#example-example-of-a-character-reference for an example.

[r12a]

Actually, i think we're good on this now. We experimented with various alternatives before settling on brown.

[aphillips]

Thanks @fantasai, @xfq, and @r12a. When I get a chance, I will update this PR with our various modifications, including the updated readme.

[fantasai]

@r12a Color looks nice afaict :) The rule about not including a space between the character and the U+ code seems weird and counter-intuitive, though. I think it would be better to expect it. The font-size change is also a bit disturbing; could we just make it bold? Maybe something like:

.codepoint > bdi {
  font-weight: bold;
}
.codepoint > bdi:hover {
  transform-origin: center;
  scale: 130%;
}

Another question I have is whether that outermost span should be code.

And lastly, shouldn't <code> default to translate=no?

[xfq]

@r12a Color looks nice afaict :) The rule about not including a space between the character and the U+ code seems weird and counter-intuitive, though. I think it would be better to expect it.

I think so too. However, I think using styles to control is for the ease of customization (because it is difficult to change the width of U+0020).

The font-size change is also a bit disturbing; could we just make it bold? Maybe something like:

.codepoint > bdi {
  font-weight: bold;
}
.codepoint > bdi:hover {
  transform-origin: center;
  scale: 130%;
}

I think it's to make the character itself (rather than the code point and Unicode name) stand out. I don't have a strong preference here, let's see what others think. I made a comparison document here, so that people can see the rendered document easily.

Another question I have is whether that outermost span should be code.

I don't think the outermost span should be code, because the character is not code.

And lastly, shouldn't <code> default to translate=no?

I think code should default to translate=no, especially for the non-comment part of the code, but I didn't check if it's specified in the HTML Standard. If the code is translated, it may have an impact on the semantics of the code. Although variable names can be translated technically most of the time, it is not common to do so in practice. If translation is needed, we can add translate for those code elements.

[aphillips]

I think we would want to avoid font-weight: bold for a variety of reasons, not the least of which is that support for many scripts can be limited in terms of different weights/styles of fonts being available. It can also make certain characters look different or more difficult to read (or turn into tofu). This may not affect other people's specifications very much, but it might prove a bother for us. Plain styles/normal weights are generally available in fallback fonts or are the most available when it comes to complex things such as conjuncts in Indic scripts.

I do like the idea of using :hover for the size.

[aphillips]

I have updated the readme and the stylesheet to match the changes in specdev. Note that I needed to correct an error in the TOC of the readme.

The section about the character template is slightly different from the section in specdev in that it points to specdev (the one in TR) in a couple of places. I also relaxed the wording about not including a space between bdi and span class=uname. Ready?

[fantasai]

(Filed https://github.com/whatwg/html/issues/9364 fwiw.)

[aphillips]

We discussed this in the I18N teleconference of 2023-06-01 and decided that using :hover and making the inline size consistent with the core text was not the right approach. @r12a noted that we want to emphasize the characters rather than the Unicode names and that the styles proposed have been experimented with fairly extensively.

Note that we're working on automation via ReSpec and Bikeshed so that most spec authors won't use these styles directly. They'll use a much more compact notation.

In the change 0aeea32 I also modified text quoted from a CSS spec to use the character template (the better to demonstrate usage). @fantasai have a look at that and see if these are changes that might go upstream 🙂.

[aphillips]

@fantasai @r12a Pinging for another look.

[fantasai]

@aphillips Please enable maintainer edit permissions

[aphillips]

@fantasai It already is enabled?

[fantasai]

@aphillips OK, I figured it out. :) I've pushed three things here for you to take a look:

1. Rebased on top of the latest origin repo state. (This was a force-push. You'll need to pull again from your own repo to get the new state locally, I hope it doesn't cause too much problems...)
2. Cleaned up the README to follow the style of the rest of the README, fixed indentation, added subheadings, etc.
3. Tweaked the styling a bit to add a background around the BDI, because the font size change is hard to interpret without something to set it apart from the main text.

Take a look and let me know what you think.

I don't think the outermost span should be code, because the character is not code.

Should the inner span be code?

(I do think the bdi should be samp, but BDI + SAMP seems a bit excessive...)

font-variant-numeric: oldstyle-nums;

What are you trying to do with this? Capital letters + oldstyle numbers is a very weird, and generally unintended, combination...

[aphillips]

@fantasai Thanks. I'll pull again and we'll see if I survive the merge 😀

span class=uname might be code class=uname. The Unicode name is kind of code-ish.

I agree that BDI+SAMP would be excessive. An alternative might be <samp dir=auto lang=??> on the theory that every character or short character sequence's base direction is probably pretty indicative. @r12a any thoughts?

The oldstyle-nums was something I introduced with the current crop of edits. When we use all-small-caps, the ASCII digits remain their non-small-cap larger selves (because digits are unicameral). This looks clunky and somewhat ransom-note-like:

Whereas "oldstyle" numerals are meant to appear with a similar x-height:

Admittedly this is weird styling, because the name is "code" and old style numerals are.... yeah. But functionally the height matching works, making it more attractive?!?!?

[fantasai]

@aphillips Worst case, if you don't have anything local, you can delete your local copy of the repo and re-clone from git@github.com:aphillips/tr-design.git? :)

Wrt oldstyle nums... that's funny, because I thought all-small-caps was supposed to compensate for that. :) https://www.w3.org/TR/css-fonts-4/#example-06f22977 But maybe not. I should raise this question with Myles Maxfield... I suppose that might be an argument for using text-transform + font-size instead of proper small caps. :/

[fantasai]

on the theory that every character or short character sequence's base direction is probably pretty indicative

Well, whether it is nor not, <bdi> defaults its dir attribute to auto anyway, so it's functionally the same either way!

[aphillips]

(returning to oldstyle-nums) I removed that from the style. It appears that this non-matching of digits in all-small-caps is a gap/bug in Chrome (I didn't test extensively, FF does it correctly), so it's probably better to ask for fixes there than go "olde skool" with the digits.

[aphillips]

@r12a Can you review and ensure I didn't miss anything from telecon here? I'd like to merge this per our discussion.

Also, mentioning: w3c/i18n-actions#15

[r12a]

Ok, i updated the text at https://www.w3.org/International/i18n-activity/guidelines/editing#codepoints

I also added some CSS to deal with img tags.

.codepoint img {
    height: 2em;
    margin-inline: 0.25em;
        vertical-align: bottom;
    }

[aphillips]

Okay, something is wrong here. I pushed a new commit to my fork, but it doesn't show in the PR.

https://github.com/w3c/tr-design/compare/gh-pages...aphillips:tr-design:gh-pages?expand=1

[aphillips]

@r12a This should do it.

• Changed span to code for the uname
• Added back font-family: Arial, monospace for uname
• Removed the merge conflict
• Added the image example.

Have a look and I'll ensure that spec dev mirrors this.

[aphillips]

@r12a pinging for approval 😸

[aphillips]

@fantasai @r12a I think this is ready to merge? I can't do so myself, either because I don't have an approval from @fantasai or possibly I don't have permission.

[r12a]

/me could do this, but thinks he should leave this for @fantasai, since it's not his repo.

[aphillips]

@fantasai Can you approve? Thanks!!

[aphillips]

@fantasai Pinging to bring to the top of your inbox 😉

Can we please merge this? I'm blocked on pushing the next version of our best practices for spec authors doc on this.

[aphillips]

@fantasai Thanks for the review.

Over the course of the many revisions in this PR, I18N reverted some of the styling suggestions made above (while keeping some others, such as the use of code in place of span). Notably, we got rid of small caps, old-style numerals, and text transformations to better ensure that the underlying text is copy-ready (because mixed case will show in the page and thus prompt fixes to the underlying text). This is documented by the template text thusly:

<code class="uname">U+XXXX UNICODE_CHARACTER_NAME_ALL_IN_CAPS</code>

The text you find here is verbatim from our best practices doc. I can adjust indentation there to match this document if necessary. I think it is important to keep these in sync. That text is staged as this PR (preview).

[xfq]

@deniak? Any comments on this PR?

[r12a]

In our last CCS<->I18n meeting, Fantasai repeated her preference for a space between the bdi and .uname tags. Although i had argued that in properly semantic markup it would be better to omit the space, so that the gap could be styled accurately, i can see that people are likely to get this wrong quite often. Therefore, i don't object to adding the space as part of the canonical markup.

[deniak]

@deniak? Any comments on this PR?

The PR looks good to me but I'll defer to @fantasai who's much more knowledgeable than me on these topics

[aphillips]

@r12a Fair enough, although I suspect most people will generate the markup using the shorthands we're adding to respec and bikeshed.

I considered making the space optional by rephrasing the sentence about spaces thusly:

Spacing and presentation is controlled by styling, so you do not need to include line breaks or a space between the closing bdi and the following code element, although you can if you wish.

But then decided to just make a clean break. I added spaces and removed the spacing from the style sheet. While typing this I realize that I didn't fix the examples, but will add one more push in a few seconds and then we should hopefully be done?

[fantasai]

@aphillips What's the benefit of adding images for invisible characters? Is it really worth the cost to a) creating the images b) tracking the images with the specification text c) complicating the stylesheet and markup patterns and d) disrupting the paragraph line spacing?

[fantasai]

@aphillips So... I broke something. Can you give me write access to your repo so I can try to fix it? :)

[aphillips]

@fantasai I invited you to my fork... have at it 👍

Regarding images, @r12a has been using them for some time and feels that they provide better usability. The images helps make invisibles clearer, at least in some cases. An argument can be made that the sometimes detract from the page and that it is a maintenance headache (especially with regard to echidna configuration), but it is somewhat optional. We might make it clearer that it is up the discretion of the author to use images if they so desire and to spell out the maintenance tradeoff.

@r12a, @xfq any additional thoughts?

[aphillips]

@fantasai

The diff got super icky on the pushes you made, so I'm not sure what you changed, but as far as I can tell this looks good. Okay to merge?

[aphillips]

@fantasai Argh. Never mind: you already did merge it. A little blind today.

[xfq]

@aphillips What's the benefit of adding images for invisible characters? Is it really worth the cost to a) creating the images b) tracking the images with the specification text c) complicating the stylesheet and markup patterns and d) disrupting the paragraph line spacing?

It is not only useful for invisible characters, but also useful for combining characters. If the font doesn't support display with a dotted circle (U+25CC DOTTED CIRCLE), then an image is needed.

[xfq]

@deniak Since we have merged this, I wonder if there is anything we need to do to ship it to /TR specs?

[deniak]

@deniak Since we have merged this, I wonder if there is anything we need to do to ship it to /TR specs?

The TR stylesheet has been updated already. See:

• https://www.w3.org/StyleSheets/TR/2021/base.css
• https://www.w3.org/StyleSheets/TR/2021/README.html

[xfq]

Great. Thank you all!

[r12a]

The section at https://www.w3.org/StyleSheets/TR/2021/README.html#unicode-codepoints looks out of date to me.

It says:

For invisible characters (such as control characters) or for whitespace, the character and its surrounding bdi element should be omitted:

but the latest guidelines should suggest using a graphic, eg.

For invisible characters (such as control characters) or for whitespace, use an image instead of the character; or you may also omit the character and its surrounding bdi element. <span class="codepoint" translate="no"><img alt="..." src="..."><span class="uname">U+XXXX UNICODE_CHARACTER_NAME_ALL_IN_CAPS</span></span>

I haven't checked other bits, but it suggests to me that we probably should to make sure that is the latest copy, throughout.

[xfq]

That's because @fantasai reverted that part, but it did make tr-design inconsistent with the recommendation of the i18n specdev document, and it's something we should try to avoid.