[css-view-transitions-1] Spec formatting

[jakearchibald]

I think we should decide on:

• Indenting level in code samples
• Indenting level in the spec
• Wrapping system

Indenting level in the spec

We're mostly using 4 spaces right now.

The flexbox and grid specs seem to use tabs.

Recommendation: Happy to follow working group preference here. Is that tabs?

Indenting level in code samples

Currently, we're inconsistent. Sometimes it's 2 spaces, 4 spaces, or even 6 spaces.

For comparison, https://drafts.csswg.org/css-flexbox-1/ is mostly 2 spaces, but sometimes 4 and even sometimes 3.

Recommendation: I'd rather do whatever we do for general spec indenting. I'm happy to use tabs for block indenting and spaces for alignment. If we use tabs, I'd like to use tab-size: 2 in the spec CSS.

Wrapping system

Currently, we're inconsistent.

https://github.com/w3c/csswg-drafts/blob/main/css-grid-3/Overview.bs is mostly no-hard-wrapping.

https://github.com/w3c/csswg-drafts/blob/main/css-flexbox-1/Overview.bs seems to be semantic line breaks.

Recommendation: My personal preference is no-hard-wrapping, and keep paragraphs short. However, I'm happy with semantic line breaks too. My only strong feeling is we should avoid breaking at an arbitrary char count, especially if that breaks referenced terms across lines, making it hard to search for particular terms.

@fantasai happy for you to lay down the law here.

[jakearchibald]

oh wow, what a waste of a lovely round issue number

[fantasai]

@tabatkins and I follow the source code formatting outlined in https://lists.w3.org/Archives/Public/spec-prod/2018OctDec/0011.html

• Phrase-based semantic line breaks
• Tabs for indentation, spaces for alignment
• Indent the entire spec one level except for headings, so sections are easy to pick out
• Further indent the contents of block-level HTML elements except P, per standard HTML indentation practice
• Empty lines between blocks
• No optional end tags, because they're noisy.

We don't particularly care whether someone else's spec is using spaces or tabs for indentation, so long as it's consistent. We understand that some people don't know how to use tabs vs spaces properly, or have bad text editors, so using spaces only makes sense for them even though it's an inferior system. :P However using tabs for alignment is not acceptable, since that breaks if someone else's text editor sets them to a different value. Likewise mixing tabs and spaces for indentation.

We care a lot about using semantic line breaks. You'll see that in the source code of every modern spec we edit: Grid, Flexbox, Alignment, Text, Box, Selectors, Values, Cascade, etc. etc. etc.

Note: css-grid-3 was drafted by Mats Palmgren as a masonry layout proposal; if you want to see how Grid is formatted, look at level 1 or 2.

[fantasai]

Wrt code samples... I agree we're not very consistent, I think I usually use 2-space indent because it's enough to distinguish but works better on narrower screens. I would avoid using tabs for code samples, because of the inconsistency in rendering.

[jakearchibald]

• Phrase-based semantic line breaks
• Tabs for indentation, spaces for alignment
• Indent the entire spec one level except for headings, so sections are easy to pick out
• Further indent the contents of block-level HTML elements except P, per standard HTML indentation practice
• Empty lines between blocks
• No optional end tags, because they're noisy.

I'm happy with all that.

We understand that some people don't know how to use tabs vs spaces properly

😈 haha, but I agree.

I would avoid using tabs for code samples, because of the inconsistency in rendering.

Ohh, I thought tab-size was well supported now?

[tabatkins]

Use whatever you want in code samples. Bikeshed auto-converts tabs to two spaces for display.

[jakearchibald]

Using tabs sounds like the right thing then!