Working Draft-like rendering of the wording

[Endilll]

I have a downstream with a bunch of changes that bring HTML render quite close to the Working Draft PDF as produced by WG21 editors (but not eel.is version — it is quite different from the PDF). See P4176R1 for an example. Downstream changes include:

1. Embedding some Latin Modern ("LM") fonts (2 MB total).
2. A bunch of CSS styles.
3. A new syntax for grammar productions.
4. Handling of comments in code blocks, so that they are rendered using a serif font.
5. Special handling of double plus, so that "C++" doesn't look ugly.
6. Automatic handling of [stable.reference] to make it less tedious to have cross-references.

If you're interested, I should be able to find time to rebase on top of the changes you made in the past couple of months, and submit those features one by one. It's perfectly understandable if you feel that two megabytes of fonts is a wrong trade-off — unfortunately, they are a key to get the layout right, so I'll resort to maintaining my downstream in this case.

[mpark]

Hi Vlad! Your paper looks quite nice. Well done. I am interested in the changes you've made. Some questions/comments for each:

1. Does embedding the fonts mean that they get embedded into each HTML that gets produced? Of course, I like beautiful documents in general so I am interested, and don't see a reason to be immediately be against it. At the same time, I don't see an obvious benefit from an authorship and reviewing perspectives. So I'm on the fence about this one.
2. Can't comment much since I'm not sure what the CSS changes are, but I'd guess that they're useful.
3. I've actually thought about this recently! I was considering introducing a grammar code block like: ```grammar that gets rendered appropriately. I'm curious what you ended up doing for it.
4. Hm, yeah. I haven't thought much about this one. Looks like eel.is uses Noto Serif for comments. I've mainly just stuck to what skylighting provides, but anyway. I don't see why not.
5. Sounds good
6. Yep, sounds interesting.

I'm not sure if the source markdown file is public, but if it is, please send me a link to it. I'm curious how some of the elements are written in your doc.

There are other elements I like as well:

• The grey boxes with a slight border with paragraph numbers to the side, is something that @brevzin has as well, looks quite clean.
• Right-aligned stable refs on the titles is nice.

Anyway, thanks for the offer to help make these improvements!

[Endilll]

Does embedding the fonts mean that they get embedded into each HTML that gets produced?

Yes. Latin Modern fonts are not available on e.g. Google Fonts to be easily referenced, and I wanted the papers to look correctly even in offline contexts, like on an airplane. The motivation is that there are three different fonts that can be mixed together: a serif for the main text, a monospace for inline code, and a sans-serif for grammar productions. This poses a problem that all of them have to have the same x-height, otherwise you could end up with something like this (screenshot taken on my machine):

Latin Modern fonts are apparently designed with different line thickness (one could say "optical size") for different sizes: "LM Roman 10" for 10pt text, "LM Roman 9" for 9pt text, etc. This results in 900 KB of embedded fonts (sorry, I misremembered the 2 MB figure I mentioned earlier). There is certainly a middle ground here: we could use e.g. "LM Modern 10" for serif text of all sizes. This should reduce the size of embedded fonts down to 350 kilobytes. To me 900 KB of embedded fonts is not that different from 350 KB, but it might be different for you.

Can't comment much since I'm not sure what the CSS changes are, but I'd guess that they're useful.

Together with the fonts, they get me like 90% there — Markdown sources should look very similar to yours. I dumped all my downstream changes in a single commit. Of course it's not my intention to do the upstreaming by simply dumping it on you — but this is the fastest way to show you what the CSS changes are.

I've actually thought about this recently! I was considering introducing a grammar code block like: ```grammar that gets rendered appropriately. I'm curious what you ended up doing for it.

I ended up with e.g. #postfix-expression#, but I think you're right that they don't really have to be delimited on both sides. However, the wording occasionally says postfix-expressions, where the last s is in regular font, which means you'll need to put the delimiter at the end of a grammar term and not in the front.

Hm, yeah. I haven't thought much about this one. Looks like eel.is uses Noto Serif for comments. I've mainly just stuck to what skylighting provides, but anyway. I don't see why not.

It's quite useful when you have long comments: serif takes half as much width, reducing the overflow quite a bit.

The grey boxes with a slight border with paragraph numbers to the side

Yes, this was inspired by P2996 that was rendered with Barry's styles.

I'm not sure if the source markdown file is public, but if it is, please send me a link to it. I'm curious how some of the elements are written in your doc.

I guess I can't kick this can down the road any longer: https://github.com/Endilll/wg21-papers/blob/a1458c1bcb5e2d67dd0b3c109deef7f863d8a644/P4176R1.md?plain=1#L54

[mpark]

Re: fonts: Yeah, I think it's... somewhat of a can that I'm not sure I'm ready to commit to open 😅 The size of the document is, eh. I'm not sure to what extent that matters. But rendering in general is just a big pain as it is. I see for example that the strikeouts over the different fonts don't go through straight:

Maybe it has to do with the x-height thing? The status quo also doesn't, so it's not a regression or anything:

I just think I might be more motivated if it solved some existing problems 🤔

Together with the fonts, they get me like 90% there — Markdown sources should look very similar to yours. I dumped all my downstream changes in a single commit. Of course it's not my intention to do the upstreaming by simply dumping it on you — but this is the fastest way to show you what the CSS changes are.

Cool, thanks for sharing! Yeah, the CSS as it is can certainly be improved. It's challenging since I don't really have much of a web dev expertise 😅 I'm relying on an eel.is CSS from a long time ago, which I'm sure has evolved as well... so anyway, it's an area that needs some love.

I ended up with e.g. #postfix-expression#, but I think you're right that they don't really have to be delimited on both sides. However, the wording occasionally says postfix-expressions, where the last s is in regular font, which means you'll need to put the delimiter at the end of a grammar term and not in the front.

Ah, I see. That's for like, "inline grammar". By ```grammar I meant for bigger grammar blocks. e.g.
Rather than what I describe in Grammar Changes and what you have in your doc like:

> | _selection-statement:_
> |     `if constexpr`_~opt~_ `(` _init-statement~opt~_ _condition_ `)` _statement_
> |     `if constexpr`_~opt~_ `(` _init-statement~opt~_ _condition_ `)` _statement_ `else` _statement_
> |     `switch (` _init-statement~opt~_ _condition_ `)` _statement_

Maybe we can just write:

```grammar
$selection-statement$:
    if constexpr$~opt~$ ( $init-statement~opt~$ $condition$ ) $statement$
    if constexpr$~opt~$ ( $init-statement~opt~$ $condition$ ) $statement$ else $statement$
    switch ( $init-statement~opt~$ $condition$ ) $statement$
```

$foo$ is fairly new, but it's essentially just a short-hand for @*foo*@ which italicizes foo within a code block.
So even without the grammar part, in a regular code block this does most of what we want.
But I think the grammar part can indicate that the font is to be rendered with proper serif fonts and such,
rather than just italicized monospace fonts. It could even automatically form the link to the grammar rules, e.g. selection-statement

At the markdown-level, I've tried hard to avoid any manual parsing of strings within Markdown. That is, aside from the embedded markdown in code blocks syntax using @ (and the $ short-hand for italics), I don't touch any markdown elements outside of code blocks manually. I understand the attractiveness of succinct syntax like #postfix-expression#, but I'll most likely want to avoid that still.

What does #postfix-expression# do differently than *postfix-expression* by the way? I'm guessing it's a font thing? I think I'd prefer either handling it via an attribute on inline code `postfix-expression`{.grammar} or a bracketed span: [postfix-expression]{.grammar}

You could still keep a small downstream change that transforms #postfix-expression# to one of those forms... Anyway, I'm not sure. Supporting implicit linking of [stable.name] also will involve parsing a raw string, so maybe I'll end up letting go of that constraint in general... but for now I still feel more comfortable hijacking elements actually recognized by Pandoc.

It's quite useful when you have long comments: serif takes half as much width, reducing the overflow quite a bit.

Ah, fair enough. Sounds good to me.

Yes, this was inspired by P2996 that was rendered with Barry's styles.

Cool, I'm told by @brevzin that he stole it from @Bekenn 😄.

I guess I can't kick this can down the road any longer:

You didn't have to share if you didn't want to! 😅

[Endilll]

I see for example that the strikeouts over the different fonts don't go through straight:
Maybe it has to do with the x-height thing?

Yes, x-height (which is just the height of glyph x) of sans serif font on your screenshot is definitely bigger than that of serif font. Also, I see that strikethrough line is not centered vertically (w.r.t. x-height), so I assume you tried embedded fonts on your master, where IIRC you recently added a CSS property to raise the strikethrough line, and now I'm not sure what's going on in your rendering.

If you see this on P4176R1 as published in the mailing, let me know and I'll look into it.

I just think I might be more motivated if it solved some existing problems 🤔

Well, mismatch in x-height between fonts is a real problem for me that tight control over the fonts addresses.

By ```grammar I meant for bigger grammar blocks.

First, I don't think you can get rid of leading >, because that would separate grammar from wording. Second, I don't think code blocks in the right way, because grammar is not code. I don't think that margins of definitions are expressible in the glyph width of a monospace font, but that aside, I don't see how you'd be able to correctly render regular font in grammar, which happens ([lex.name], [lex.key]).

It could even automatically form the link to the grammar rules, e.g. selection-statement

Having links for existing grammar productions would be very nice, yes, but I'm not convinced that we need to wrap grammar in code blocks to achieve that.

What does #postfix-expression# do differently than postfix-expression by the way? I'm guessing it's a font thing?

Yes, using oblique sans serif font is the reason. As someone who spends a lot of time in core language wording, I very much appreciate when I don't need to guess whether something is a grammar production or not.

I think I'd prefer either handling it via an attribute on inline code postfix-expression{.grammar} or a bracketed span: [postfix-expression]{.grammar}

This is what I initially did, but somewhere in the middle of writing P4176 I got sick of writing {.grammar} everywhere and of how noisy it was in the Markdown sources, so I implemented the custom syntax

I understand the attractiveness of succinct syntax like #postfix-expression#, but I'll most likely want to avoid that still.

I understand the sentiment, but it was a matter of practicality: being able to easily pull wording from the draft into a paper is important. I find it unfortunate that @...@ syntax is limited to code blocks, because the wording is more diverse.

Also, don't you have special handling for e.g. CWGnnnn? I tried to understand how that works, but wasn't able to. I don't care too much about any particular syntax (I might even hold my nose for [new-expression]{.g}) as long as it's not "heavy".

Supporting implicit linking of [stable.name] also will involve parsing a raw string, so maybe I'll end up letting go of that constraint in general... but for now I still feel more comfortable hijacking elements actually recognized by Pandoc.

Likewise, if I'd need to wrap stable names in a "lightweight" syntax, that would be fine by me.

You didn't have to share if you didn't want to! 😅

No worries, I intended to do that ever since I started writing real papers (as opposed to slides).

[Endilll]

If it makes it easier to swallow, we can limit parsing raw strings to block of wording. I'm not concerned about the prose too much.

[mpark]

If you see this on P4176R1 as published in the mailing, let me know and I'll look into it.

Yeah, I'm referring exactly to the "not centered vertically" issue:

is from the published version of P4176R1: https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2026/p4176r1.html#pnum-2

Another example from https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2026/p4176r1.html#pnum-0

Well, mismatch in x-height between fonts is a real problem for me that tight control over the fonts addresses.

So as far as what I see in P4176R1, it doesn't seem to address it? But as I said, if it does, please let me know and I think that's a good benefit for sure.

Re: grammar stuff, perhaps ::: grammar would be a better region for it. The details of it I think we can work out elsewhere.

As someone who spends a lot of time in core language wording, I very much appreciate when I don't need to guess whether something is a grammar production or not.

Ah, that's good feedback. I essentially have two goals with the framework which are to ease (1) authorship and (2) reviewing, not necessarily in that order. So if proper selection of fonts help wording reviewers in LWG/CWG, I'm more incline to help with that. e.g. LWG request to change colors in code blocks: #111

Re: {.grammar} yeah, I understand the verbosity for sure. yeah, maybe we hold our nose for {.g} or something... but it's not great. Will think more. The special syntax for CWGnnnn you're thinking of is probably [@CWGnnnn] which is Pandoc's citeproc syntax for references and things.

Likewise, if I'd need to wrap stable names in a "lightweight" syntax, that would be fine by me.

👍

If it makes it easier to swallow, we can limit parsing raw strings to block of wording. I'm not concerned about the prose too much.

Hm... yeah, limiting it to ::: wording and dash-separated words surrounded by # may be scoped enough to feel comfortable