polygon() Formal Syntax is an error
sidewayss opened this issue · comments
MDN URL
https://developer.mozilla.org/en-US/docs/Web/CSS/basic-shape/polygon
What specific section or headline is this issue about?
Formal Syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/basic-shape/polygon#formal_syntax
What information was incorrect, unhelpful, or incomplete?
What did you expect to see?
Something other than an error. I was looking for the space/comma formal syntax, which is unusual relative to other functions.
Do you have any supporting links, references, or citations?
No response
Do you have anything more you want to share?
No response
The formal syntax is retrieved from w3\webref repo. And it does have definition for polygon().
@bsmth We need to move this issue to mdn/yari.
I notice that other <basic-shape> doesn't display the formal syntax section, so maybe the solution here is to remove that section. @wbamberg will know for sure.
Yes, the path() function's page has no Formal Syntax section. And again I am looking for the comma vs space syntax, which is lenient in SVG but strict in CSS polygon(). Here it is in webref.repo.
This line in particular:
"value": "path( [<'fill-rule'>,]? <string> )"
If I read the spec correctly, there is no CSS-specific syntax enforced at all for <string>, it is validated using SVG 1.1 rules. SVG allows any combination of comma and space anywhere in <string>. No specific pattern or regularity is required, but the most widely used pattern for the points property in a polyline or polygon, and x/y pairs in the d property in path, is:
x1,y1 x2,y2
The SVG-ish examples on the path() page use this same pattern. The CSS examples on that page use separators similarly to CSS polygon(), which is strict x1 y1, x2 y2, .
I say all of that so that you might understand my desire to have the Full Syntax information visible on these pages. The CSS syntax for polygon() is strict and differs from its SVG counterparts, and it's not explained in any DOM error, AFAICT. Meanwhile CSS path() uses syntax identical to SVG. At a minimum, a working Formal Syntax section is desirable. At a maximum, there would be an explanation written into either the Syntax or Formal Syntax sections explaining these comma/space separator rules. This is relatively new stuff in CSS, but it has been around in SVG for well over a decade.
I substantially rewrote the page for polygon() recently (mdn/content#28873), in the process adding formal syntax. In the course of that, since we didn't have a page template for functional notation, I filed mdn/content#28953 to write one, and that does ask pages like this to include formal syntax.
At the time mdn/content#28873 was merged the formal syntax for this page certainly worked (or we wouldn't have merged it) so this is probably a Yari regression, maybe caused by the update to webref/css 6. See also #9715.
At a maximum, there would be an explanation written into either the Syntax or Formal Syntax sections explaining these comma/space separator rules.
Yes, I also think it would be good to have a sentence after the "Syntax" code block, but before the "Parameters" H3, that describes this informally, something like:
The parameters to
polygon()are an optional<fill-rule>value followed by a comma, followed by one or more coordinate pairs separated by commas. Each coordinate pair is given as two<length-percentage>values separated by a space.
Or something like that. It's hard to express syntax unambiguously in words, which is why we have formal syntax of course.
Or something like that. It's hard to express syntax unambiguously in words, which is why we have formal syntax of course.
It ends up sounding like the small print in a legally binding contract. IMO comparing to the SVG syntax in places where it is analogous, such as CSS polygon() and path(), is useful too.
Looks like this issue will be closed and reopened in the yari project. I'll take a crack at editing these two pages to incorporate a version of your legalese in a new PR. I'll link to this issue when I do. I'll attempt to copy the Formal Syntax format from polygon() into the path() page, assuming it will be fixed in yari.
Has there been an issue created for this on mdn/yari? I don't know enough about Yari - I see the Formal Syntax on the <position> page, no error. That syntax matches the text in the spec here: https://drafts.csswg.org/css-values/#position.
Except that the format in the docs page is not the same as the format in the spec, and in this case, IMO, it makes a real difference to understanding the way x/y values are spread across the 4 parameters when you are using <length-percentage>. The way the lines are broken in the spec is much more readable. Should I submit an issue for that? Would it be related to this one?
Has there been an issue created for this on
mdn/yari? I don't know enough about Yari - I see the Formal Syntax on the<position>page, no error. That syntax matches the text in the spec here: https://drafts.csswg.org/css-values/#position.Except that the format in the docs page is not the same as the format in the spec, and in this case, IMO, it makes a real difference to understanding the way x/y values are spread across the 4 parameters when you are using
<length-percentage>. The way the lines are broken in the spec is much more readable. Should I submit an issue for that? Would it be related to this one?
There is an issue for the fact that some formal syntax items are not being rendered, which I linked to already: #9715. I don't know if it's worth filing another issue for polygon specifically. Maybe add a comment to #9715 ?
But most of your comment here seems to be about position, which is a whole new thing which this issue is not the subject of at all.
the format in the docs page is not the same as the format in the spec
OK, so I guess you mean, in the MDN page formal syntax for position is rendered like:
...but in the spec it is rendered like:
...and you like the second version better.
The formal syntax pretty-printing on MDN uses a relatively simple algorithm, but it's still a bit fiddly, and I think it would be quite hard to find an algorithm which will be optimal for all the different syntaxes in CSS. For example, one reason the MDN algorithm only pretty-prints at the top level is to prevent the formal syntax for getting excessively long. But I'm not saying it's impossible, so feel free to file a Yari issue for it.
I think that the formal syntax has much bigger problems than this though, such as #9715, and it would be better to address those first.
Yes. I like the second (original spec) version. The line breaks have intent that is lost in translation. Sorry for the confusion, but I didn't know where to ask this question and at least it was related to this PR's topic of Formal Syntax rendering. I imagined that there were bigger issues, which was among the reasons I hesitated to submit a bug report without asking somewhere first.
Is there a way to tell Yari to specifically not pretty-print something? That would solve it for the position_value page.
...and now that I look at your screenshots together on the screen, they don't match in content, not just format. So maybe this is part of #9715?
MDN:
<position> =
[ left | center | right ] || [ top | center | bottom ] |
spec:
<position> = [
[ left | center | right | top | bottom | <length-percentage> ]
|
[ left | center | right ] && [ top | center | bottom ]
|
Below that it's the lack of line breaks that just make the MDN version harder to read, but which is a lesser offense.
Is there a way to tell Yari to specifically not pretty-print something? That would solve it for the position_value page.
Would it? Wouldn't it just wrap wherever the edge of the pre block was, without any regard to presentation? The syntax value is just a single string: https://github.com/w3c/webref/blob/8939c39b3192628acaf255c8fc865a68a0a3b606/ed/css/css-values.json#L465.
I mean you could, technically, have a parameter to the csssyntax macro that gets passed into the rendering code. But I'm not that keen on adding extra bits of complexity into the authoring experience for quite niche cases. MDN authoring is already fiercely complicated.
The syntax value is just a single string: https://github.com/w3c/webref/blob/8939c39b3192628acaf255c8fc865a68a0a3b606/ed/css/css-values.json#L465.
As I said, I know too little about it. I don't want to make anything here more complicated.
OK, now that I click on your link I see that position_value's Formal Syntax content can be fixed by editing that css-values.json entry in the W3C/webref repo. Can anyone submit a PR there? I see a page for submitting issues: https://github.com/w3c/webref/issues
OK, now that I click on your link I see that position_value's Formal Syntax content can be fixed by editing that css-values.json entry in the W3C/webref repo. Can anyone submit a PR there? I see a page for submitting issues: https://github.com/w3c/webref/issues
No, that repo is scraped from the specifications themselves, see https://github.com/w3c/webref. When you say "fix" do you mean the formatting or the content? For the formatting, I think how the syntax is formatted is a matter for the renderer: the content in webref/css is just data. For the content: the data in webref matches the spec of course. I don't know why the content in MDN doesn't match webref - could you file a separate issue for that in this repository, and I will look into it?
The content. I just filed an issue for it here: #10098