[css-page] Consider making 'size' a legacy alias of a new descriptor ('page-size')?

[emilio]

This would clear confusion with #820 long term at least. See the minutes in that bug.

cc @fantasai @tabatkins

[mstensho]

This is a great opportunity to give it a more descriptive name.

See https://drafts.csswg.org/css-page-3/#page-size-prop (oh hai, it's already #page-size-prop , oh well).

This property specifies the target size and orientation of the page box’s containing block.

Although "page-size" is ambiguous (is it the page box size or the page area size?), it doesn't even set the page size. It sets the size of the containing block of the page box, which becomes interesting if the page area is sized with percentages (also if page margins use percentages, of course).

  @page {
    size: 300px;
    margin: 100px;
    width: 50%;
    background: cyan;
  }
  body {
    margin: 0;
    background: yellow;
  }

The page area width becomes 150px (50% of 300px). The page box width becomes 350px (150px + page margins). Further explanation: https://drafts.csswg.org/css-page-3/#page-model

The containing block of the page box is specified using the size property in the page context. The width and horizontal margins of the page box are then calculated exactly as for a non-replaced block element in normal flow. [CSS2] The height and vertical margins of the page box are calculated analogously (instead of using the block height formulas). In both cases if the values are over-constrained, instead of ignoring any margins, the containing block is resized to coincide with the margin edges of the page box.

I don't know what a good name would be. Just pointing out that page-size isn't great. But neither was size, of course. :)

[faceless2]

Although "page-size" is ambiguous (is it the page box size or the page area size?), it doesn't even set the page size. It sets the size of the containing block of the page box

Yes it does - the margin-box, in other words. Putting my PDF hat on, it sets the PDF trim box. Add the "bleed" property to that and you get the bleed box, which is typically the same as the content box, which is typically the same as or smaller than the media box, which is the physical size of the page. Naming things is hard 😄

Once you consider how size interacts with the bleed property, it's actually the only way it can be implemented - it's not ambiguous, just perhaps under-documented in css-page. And again want to stress this behaviour is fairly consistent across all (that I know of) PDF-focused layout engines and has been specified this way for many years.

[css-meeting-bot]

The CSS Working Group just discussed [css-page] Consider making 'size' a legacy alias of a new descriptor ('page-size')?, and agreed to the following:

• RESOLVED: make @page/size a legacy alias of @page/page-size, will get feedback from print formatters on this issue

The full IRC log of that discussion

<TabAtkins> florian: so we've decided we wanted 'size' as a shorthand for width/height. but we already have 'size' descriptor in @page.
<TabAtkins> florian: so to limit confusion, might make sense to make @page/size a legacy alias of a new better name. possible @page/page-size.
<TabAtkins> florian: tho it's not really the size of the page, PDF calls it the trim box. so naming is hard.
<TabAtkins> florian: but putting the name to the side, should we make it an alias?
<TabAtkins> astearns: in favor of the alias, but don't have better ideas on the naming
<TabAtkins> fantasai: i think page-size is fine, it's what the user is gonna think of. if you're printing on continuous paper it's interesting, but this is what the user will think of as "the page szie"
<TabAtkins> fantasai: my main concern is if this is compatible with css-to-pdf renderers
<TabAtkins> fantasai: if we're not gonna break anything, then sure, let's make the alias happen
<TabAtkins> fantasai: but that's not a question i know how to answer
<TabAtkins> florian: i'm not under the impression we'd break anything, we're not renaming anything. keepign the old name and makign it an alias to the new one.
<TabAtkins> florian: so just pages written with the new name and used on legacy tools would fail
<TabAtkins> florian: tho mike bemford was in the issue, he didn't have objections to the concept of an alias
<TabAtkins> astearns: i suggest we resolve on making it a legacy alias of page-size, and if people disagree they can weigh in
<TabAtkins> florian: we can prod people
<TabAtkins> florian: but can move ahead unless/until complains
<TabAtkins> PROPOSED: make @page/size a legacy alias of @page/page-size, will get feedback from print formatters on this issue
<TabAtkins> RESOLVED: make @page/size a legacy alias of @page/page-size, will get feedback from print formatters on this issue
<TabAtkins> (I also think "page size" is fine, I think "@page { size: ...; }" is colloquially "page size" already
<florian> s|@page/size|@page-size

[faceless2]

Feedback from us is we're fine with "size" being an alias for "page-size".

[liZe]

It’s OK for WeasyPrint too.