The article on the CSS float property lists several non-standard values as supported, with no explanation of what they are or where they came from

[DavidJCobb]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/CSS/float

What specific section or headline is this issue about?

Formal syntax

What information was incorrect, unhelpful, or incomplete?

The list of valid values for floats includes several values that were never formally adopted into any standards -- specifically, values from the CSS Page Floats draft, last updated in 2015, which isn't linked to or mentioned in the float article.

The following values from that standard are listed in this section but do not work in Firefox or, presumably, any modern browser:

• top
• bottom
• block-start
• block-end
• snap-block(...)
• snap-inline(...)
• footnote

The following values from the draft standard work in Firefox, but not Chrome or Edge. They are listed on the page with no mention that they're part of the draft standard, and they're not listed in the CSS 2 standard linked to by the page.

• inline-start
• inline-end

The browser support section mentions inline-start and inline-end, but not the others, and not the draft standard in general.

What did you expect to see?

Only values that are standardized should be listed.

Do you have any supporting links, references, or citations?

CSS Page Floats draft standard defines the values I'm referring to.

CSS 2 float values as linked from the article: no mention of the values I'm referring to.

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/css/float
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/float
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/css/float/index.md
• Last commit: fb2af1f
• Document last modified: 2022-09-27T02:27:51.000Z

[bsmth]

Hi @DavidJCobb thanks a lot for opening this issue. The section you are describing is generated here:

content/files/en-us/web/css/float/index.md

Lines 80 to 82 in df75ff2

	## Formal syntax
	{{csssyntax}}

And the source for this csssyntax macros can be found here.

I'm tagging @wbamberg who might be able to shed some more light on the use of https://github.com/w3c/webref and which spec versions this macro pulls information from.

[wbamberg]

There's a lot to unpack in here.

Excluding draft specs

Only values that are standardized should be listed.

As a rule and depending on what "standardized" means here, we should not do this. Features in draft specs are implemented by multiple browsers, sometimes for years. If we don't document them we become irrelevant.

Excluding unimplemented features

We do avoid documenting features that have no implementation, but only whole features, not particular values. It wouldn't be a bad idea to avoid documenting values with no implementation, but it would be really hard to automate and not practical to maintain manually. We might avoid including specifications that have no implementation, but that would also be hard to automate, and IIUC would still include Page Floats here, since Firefox implements inline-start and inline-end.

But also, note that even if a value is supported in some browser, it's not necessarily usable if that browser has a small market share. So you always have to look at the BCD, anyway. So I'm not sure how helpful it is to exclude values with no implementation.

Customised spec exclusions

At the moment, the macro that builds the formal syntax (CSSSyntax.ejs) gets values from the W3C's webref package, and assumes that if a spec is in webref it's valid. If we do want to exclude Page Floats (which, do we? given that Firefox apparently has partial support?) it would be pretty simple to exclude Page Floats from the formal syntax by making an explicit exception in the CSSSyntax macro. But we'd like to avoid this kind of manual curation as much as we can, because it has a maintenance cost.

See also w3c/webref#640, which seems like a similar request in webref.

MDN page self-consistency

I think a bigger problem you've identified here is that the page isn't self-consistent; it lists all the Page Floats values in formal syntax, but neither (1) describes these values in the "Values" section nor (2) lists the spec that defines them in the "Specifications" section.

For (1), the value descriptions: these are just manually updated and I suppose we should just treat this as a content bug to list these values (if we want to keep listing the spec). It might be nice, some day, to have a way to check that values in the formal syntax have a description in the page, but we are nowhere near that level of structure yet, and it would get hard for more complicated CSS properties.

For (2), I guess the underlying issue is that we have 2 different ways to get "the set of specs to look at" and they don't always agree. For the "Specifications" section we get the specs out of BCD. For the formal syntax we use webref and make a list of all specs that contain a definition for the property. In some ways this is better because we are getting the list from a source that is closer to the specs themselves. Maybe we should use webref to find specs for Specifications, instead of the BCD entry. I'm not sure what problems there would be with that.

[wbamberg]

MDN page self-consistency

I think a bigger problem you've identified here is that the page isn't self-consistent; it lists all the Page Floats values in formal syntax, but neither (1) describes these values in the "Values" section nor (2) lists the spec that defines them in the "Specifications" section.

For (1), the value descriptions: these are just manually updated and I suppose we should just treat this as a content bug to list these values (if we want to keep listing the spec). It might be nice, some day, to have a way to check that values in the formal syntax have a description in the page, but we are nowhere near that level of structure yet, and it would get hard for more complicated CSS properties

The new version of webref might offer a way to address this: w3c/reffy#1117.

[teoli2003]

Will's points are essential. We are closing this but in favor of the discussion in https://github.com/orgs/mdn/discussions/442