Add a template for CSS functional notation #28953

wbamberg · 2023-09-05T19:28:27Z

We don't have a template for CSS functions (or CSS types, see #26881), and the way we document them is quite inconsistent:

https://developer.mozilla.org/en-US/docs/Web/CSS/basic-shape/polygon
https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix
https://developer.mozilla.org/en-US/docs/Web/CSS/sign
https://developer.mozilla.org/en-US/docs/Web/CSS/min
https://developer.mozilla.org/en-US/docs/Web/CSS/pow
https://developer.mozilla.org/en-US/docs/Web/CSS/var

Some choices I've made here:

the syntax example only includes the function itself, not a complete declaration (i.e. https://developer.mozilla.org/en-US/docs/Web/CSS/var#syntax , not https://developer.mozilla.org/en-US/docs/Web/CSS/pow#syntax
uses "Parameters" and "Return value", not "Values" (i.e. https://developer.mozilla.org/en-US/docs/Web/CSS/pow#parameters, not https://developer.mozilla.org/en-US/docs/Web/CSS/var#values)

The reasoning for 1 is that including declarations leads us into conversations like #28873 (review), and I wonder if this will be confusing when we inevitably omit some of the properties that the function can provide a value for.

Happy to discuss though. @yarusome , what do you think?

github-actions · 2023-09-05T19:31:43Z

Preview URLs

External URLs (2)

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_function_page_template
Title: CSS function page template

https://www.npmjs.com/package/@webref/css (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_property_page_template
Title: CSS property page template

https://www.npmjs.com/package/@webref/css (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-09-19 14:54:11)

yarusome · 2023-09-06T07:32:30Z

The overall structure presented in this template looks good, but I have one explicit usage doubt: For oklch(), where should the invocation pattern oklch(L C H[/ A]) go?

In the template, the "Syntax" section first lists example uses of the functions, then lists paramaters in the "Parameters" subsection, but parameters are usually order-dependent, and there is no easy way to indicate if any literal tokens like commas and slashes are needed in between.

Comparing to JSON.stringify(), the "Syntax" section there is used to show the invocation patterns. So the issue lies in the different roles of the "Syntax" sections on CSS and JavaScript pages.

A smaller issue is that, I think, example uses in the "Syntax" section should not have a comma at the line end as they are not complete value declarations. JavaScript pages don't have such commas, either.

Maybe the "Syntax" section can show the pattern in comments:

/* var( <custom-property-name> , <declaration-value>? ) */

/* Without a fallback */
var(--custom-prop)

/* With fallback */
var(--custom-prop,) /* empty value as fallback */
var(--custom-prop, initial) /* initial value of the property as fallback */
var(--custom-prop, #FF0000)
var(--my-background, linear-gradient(transparent, aqua), pink)
var(--custom-prop, var(--default-value))
var(--custom-prop, var(--default-value, red))

Then custom-property-name and declaration-value are listed as paramters in the "Parameter" subsection.

A few notes:

The pattern in the comment can be in a form that better explains the production in the spec, e.g. for oklch():
```
/* oklch( <L> <C> <H> [/ <A> ]? ) */
```
(There could be a linter rule for space normalization.)
The comment showing each invocation pattern should be followed by exactly one empty line. (Some color functions have legacy invocation patterns, but fortunately they're demoted now.
Any comment at the end of line that contains an example use should be preceded by exactly one space. (This could be done by linter or Prettier?)

An alternative format is to list several patterns to reduce the use of quantifiers:

/* Without a fallback */

/* var( <custom-property-name> ) */
var(--custom-prop)

/* With fallback */

/* var( <custom-property-name> , ) */
var(--custom-prop,) /* empty value as fallback */

/* var( <custom-property-name> , <declaration-value> ) */
var(--custom-prop, initial) /* initial value of the property as fallback */
var(--custom-prop, #FF0000)
var(--my-background, linear-gradient(transparent, aqua), pink)
var(--custom-prop, var(--default-value))
var(--custom-prop, var(--default-value, red))

But this format has the risk that some productions may contain a lot of quantifiers to expand.

PS: CSS type pages seem to a deeper hole to fall into 😬

wbamberg · 2023-09-06T15:49:51Z

Thanks for your thoughtful response, @yarusome !

The overall structure presented in this template looks good, but I have one explicit usage doubt: For oklch(), where should the invocation pattern oklch(L C H[/ A]) go?

In the template, the "Syntax" section first lists example uses of the functions, then lists paramaters in the "Parameters" subsection, but parameters are usually order-dependent, and there is no easy way to indicate if any literal tokens like commas and slashes are needed in between.

Yeah, this is a good point, and before I'd read the second part of your post I'd also thought we could use comments in the "syntax example" block to express this.

Comparing to JSON.stringify(), the "Syntax" section there is used to show the invocation patterns. So the issue lies in the different roles of the "Syntax" sections on CSS and JavaScript pages.

The general point is also right though, and it is a bit worrying that it might be misleading to call these things "Parameters" when they are rather different to JS parameters. We could call if "Values" instead, but still have "Return value"? Not sure. I think I still like "Parameters" better.

A smaller issue is that, I think, example uses in the "Syntax" section should not have a comma at the line end as they are not complete value declarations. JavaScript pages don't have such commas, either.

Do you mean semicolon?

Maybe the "Syntax" section can show the pattern in comments:
/* var( <custom-property-name> , <declaration-value>? ) */

/* Without a fallback */
var(--custom-prop)

/* With fallback */
var(--custom-prop,) /* empty value as fallback */
var(--custom-prop, initial) /* initial value of the property as fallback */
var(--custom-prop, #FF0000)
var(--my-background, linear-gradient(transparent, aqua), pink)
var(--custom-prop, var(--default-value))
var(--custom-prop, var(--default-value, red))
Then custom-property-name and declaration-value are listed as paramters in the "Parameter" subsection.

A few notes:

The pattern in the comment can be in a form that better explains the production in the spec, e.g. for oklch():
css /* oklch( <L> <C> <H> [/ <A> ]? ) */

I'm not sure the extra syntax is a good idea. They seem to be signalling that this is formal syntax, but this is pseudo-formal syntax. And I'm worried it might confuse people that say / is meant to appear literally but < isn't, leading to people thinking it's like: oklch(<1> <2> <3> / <4>).

In general, formal syntax is hard enough for people without adding something else that is kind of like formal syntax, but isn't.

If we can I would prefer a more literal/duplicated approach:

/* oklch( L C H) */
oklch(40.1% 0.123 21.57)

/* oklch( L C H / A) */
oklch(59.69% 0.156 49.77 / .5)

...and the things in the brackets are either literals or things we explain in "Parameters".

An alternative format is to list several patterns to reduce the use of quantifiers:

/* Without a fallback */

/* var( <custom-property-name> ) */
var(--custom-prop)

/* With fallback */

/* var( <custom-property-name> , ) */
var(--custom-prop,) /* empty value as fallback */

/* var( <custom-property-name> , <declaration-value> ) */
var(--custom-prop, initial) /* initial value of the property as fallback */
var(--custom-prop, #FF0000)
var(--my-background, linear-gradient(transparent, aqua), pink)
var(--custom-prop, var(--default-value))
var(--custom-prop, var(--default-value, red))

Oh, this is what I said up there I think :).

But this format has the risk that some productions may contain a lot of quantifiers to expand.

Yes, this is a worry, but I think it is better in most cases.

PS: CSS type pages seem to a deeper hole to fall into 😬

Ha, well feel free to start something there if you want :).

yarusome · 2023-09-07T08:21:05Z

Do you mean semicolon?

Yes, my head must be contorted at that time.

If we can I would prefer a more literal/duplicated approach:
/* oklch( L C H) */
oklch(40.1% 0.123 21.57)

/* oklch( L C H / A) */
oklch(59.69% 0.156 49.77 / .5)
...and the things in the brackets are either literals or things we explain in "Parameters".

This looks much better than the angled notations! (But why /* oklch( L C H) */ instead of /* oklch(L C H) */ or /* oklch( L C H ) */?)

wbamberg · 2023-09-07T14:41:00Z

(But why /* oklch( L C H) */ instead of /* oklch(L C H) */ or /* oklch( L C H ) */?)

No reason, just a typo.

OnkarRuikar · 2023-09-08T05:28:46Z

I'd also thought we could use comments in the "syntax example" block to express this.

:) Calling it "Syntax" is confusing. It makes readers start looking for syntax patterns in these usage examples. This is somewhat frustrating cos real syntax comes much later on the page. We could have order like syntax, formal syntax, parameters, and return values.
Also, on CSS pages this is not the same as JS or API syntax sections which breaks the readers understanding of the overall site's structure. We could call the section "Usage", "Usage Examples".

If we can I would prefer a more literal/duplicated approach:

We are already doing this so we could put this in the template.

wbamberg · 2023-09-08T16:22:24Z

:) Calling it "Syntax" is confusing. It makes readers start looking for syntax patterns in these usage examples. This is somewhat frustrating cos real syntax comes much later on the page. We could have order like syntax, formal syntax, parameters, and return values.

All our research says that (unfortunately) most people don't understand formal syntax or even look at it. And I do think the intention of this section is to show the syntax, it just does it "by example" rather than using a formal notation.

We could call the section "Usage", "Usage Examples".

This seems like a very vague name. How is "usage examples" different from "examples"? How is someone expected to understand that distinction? An example is different to this block, because an example would show complete code and explain what the specific values chosen do.

There's a long discussion about all this here: https://github.com/orgs/mdn/discussions/218 FWIW I do think (as I said in that discussion) that we ought to reunite "formal syntax" and "values", but there didn't seem to be consensus for it.

Anyway: please, let's keep this to functions in this discussion. I don't think we should only rename "Syntax" for CSS functions, and I would like to get towards some consistency for those pages.

wbamberg · 2023-09-12T17:25:25Z

I pushed a new commit including the changes requested by @yarusome , more or less. I removed from the syntax block the inline comments like /* initial value of the property as fallback */ because I think it is better to explain things in prose.

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

OnkarRuikar · 2023-09-13T01:56:16Z

@wbamberg could you comment on concerns raised in the PR fix(css): update 'drop-shadow()' page #29013? Would be great if you review the PR to align the changes to these guidelines.

Should "Parameters" section follow the formal syntax order? or we put optional pramas last in the list?
Is it mandatory to use only the params mentioned in formal syntax? Same name and same number of times?
About comments in "Syntax" section, should it be only explanations?

…css_function_page_template/index.md Co-authored-by: Onkar Ruikar <[email protected]>

estelle

a couple suggestions and a couple edits.

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

estelle · 2023-09-13T18:20:58Z

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

+
+## Description
+
+This is an optional section to include a description of the function and explain how it works. Use this section to explain related terms and add use cases for the function.


Suggested change

This is an optional section to include a description of the function and explain how it works. Use this section to explain related terms and add use cases for the function.

Include a description of the function and explain how it works. Use this section to explain related terms and add use cases for the function.

Prefer to have this semi-required.

I'm happy to recommend it but this edit makes it required, not semi-required. At the moment many of our pages don't have description sections, and if we make it mandatory we are likely to get low-value edits just to tick boxes in the template.

We could say "While this section is optional, we highly recommend you to add a description..."

Or just "We highly recommend you include a description..."

I think if it is optional, we should say it is optional. It's just clearer that way. I've pushed an update along the lines of Dipika's suggestion.

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md

Co-authored-by: Estelle Weyl <[email protected]>

wbamberg · 2023-09-13T20:50:08Z

@wbamberg could you comment on concerns raised in the PR fix(css): update 'drop-shadow()' page #29013? Would be great if you review the PR to align the changes to these guidelines.

Should "Parameters" section follow the formal syntax order? or we put optional pramas last in the list?

I think following the formal syntax order would be better.

Is it mandatory to use only the params mentioned in formal syntax? Same name and same number of times?

Ideally we would have synchronization between the "syntax example code block", the "values" list, and the formal syntax. That way people can cross-reference from one to the other.

As I said in the other PR, that would mean things like:

/* drop-shadow( <length> <length> <length> ) */

...which is not that far from @dipikabh 's suggestion of:

/* Three length values */

...only it maps more explicitly to the <length> listed in the other 2 sections.

About comments in "Syntax" section, should it be only explanations?

I'm not sure what "only explanations" means here. From @yarusome 's comment at #28953 (comment), I'm not too keen on:

var(--custom-prop, initial) /* initial value of the property as fallback */

...because (1) I think the value and meaning of initial should be documented in "Values", and (2) if we allow comments like this, what's the rationale for not having comments like:

var(--my-background, linear-gradient(transparent, aqua), pink) /* Set a gradient as a fallback */

I think the function of the "syntax example code block" is to describe the syntax of the thing, and the semantics ought to be explained in prose.

Anyway, this is just my opinion, and maybe there are cases where it wouldn't work. But even if we can't agree on all these details, I would love to have something we can use to get at least a minimal amount of consistency between pages here.

dipikabh

Thanks for taking this up, Will! I've added a few suggestions and questions.

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

dipikabh · 2023-09-14T16:45:06Z

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

+
+```css
+/* Without a fallback */
+


As pointed in previous comment, I think we should not have an empty line here

dipikabh · 2023-09-14T16:47:22Z

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

+/* var( <custom-property-name> , ) */
+var(--custom-prop,)
+
+/* var( <custom-property-name> , <declaration-value> ) */


For consistency, we would need to add a descriptive comment here as well?

Which makes me wonder - is it optional or mandatory to add two comments for each syntax use case. We would need to be more specific in the instructions. At the least, a syntax use case should be preceded by a descriptive comment.

I don't really know how prescriptive we need to be in general.

I have 2 main concerns:

people should be able to cross-reference between this code block, the "Values" list, and the formal syntax. So we should if at all possible use the same names for things in all three places.

we should use the code block as a place to show the syntax, not to describe the syntax.

Agree, it can be a guideline instead of a requirement and authors and reviewers can take a call based on the context.

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

dipikabh · 2023-09-14T16:59:45Z

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

+
+## Description
+
+This is an optional section to include a description of the function and explain how it works. Use this section to explain related terms and add use cases for the function.


We could say "While this section is optional, we highly recommend you to add a description..."

dipikabh · 2023-09-14T17:13:07Z

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md

+
+### Add a descriptive heading
+
+Each example must have an H3 heading (`###`) naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.


I always thought that in addition to making an H3 heading mandatory in "Examples", we also had some guidance to include a few words about the example. It might make more sense now if we get rid of the language H4 headers as well as "Result". We need to convey that the H3 should be followed by a description of the example scenario/setup or what we're trying to demo. And ideally, after the result frame, explain the output as a result of what we did in the example codes.

I realize that this would need to be updated across all the template files that have the "Examples" section and I can take that up we agree on the general idea to include that instruction.

CSS property page template, just as an example, also has a "Note" block (I remember you added that across templates :) ). Are we going to add that here?

CSS property page template, just as an example, also has a "Note" block (I remember you added that across templates :) ). Are we going to add that here?

I've added this.

I always thought that in addition to making an H3 heading mandatory in "Examples", we also had some guidance to include a few words about the example. It might make more sense now if we get rid of the language H4 headers as well as "Result". We need to convey that the H3 should be followed by a description of the example scenario/setup or what we're trying to demo. And ideally, after the result frame, explain the output as a result of what we did in the example codes.

I realize that this would need to be updated across all the template files that have the "Examples" section and I can take that up we agree on the general idea to include that instruction.

Can we split proposals for how to change the way we examples across all pages off from this request to add a template for a specific page type? This seems really out of scope for my PR here.

Can we split proposals for how to change the way we examples across all pages off from this request to add a template for a specific page type? This seems really out of scope for my PR here.

Fair enough, better to discuss this separately

Co-authored-by: Dipika Bhattacharya <[email protected]>

wbamberg · 2023-09-15T17:57:39Z

OK, I've made most of the updates and argued with a couple.

dipikabh

Thanks a lot for the updates, @wbamberg! Leaving my +1.

Add a template for CSS functional notation

2f15a0c

wbamberg requested a review from a team as a code owner September 5, 2023 19:28

wbamberg requested review from Elchi3 and removed request for a team September 5, 2023 19:28

github-actions bot added the Content:Meta Content in the meta docs label Sep 5, 2023

Updated template following review comments

9ce23e0

OnkarRuikar reviewed Sep 13, 2023

View reviewed changes

.../en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md Outdated Show resolved Hide resolved

OnkarRuikar mentioned this pull request Sep 13, 2023

fix(css): update 'drop-shadow()' page #29013

Merged

wbamberg and others added 2 commits September 12, 2023 19:52

Update files/en-us/mdn/writing_guidelines/page_structures/page_types/…

fd5d5f5

…css_function_page_template/index.md Co-authored-by: Onkar Ruikar <[email protected]>

Merge branch 'main' into page-template-css-function

11eb10c

estelle requested changes Sep 13, 2023

View reviewed changes

Apply suggestions from code review

69cd0d8

Co-authored-by: Estelle Weyl <[email protected]>

dipikabh requested changes Sep 14, 2023

View reviewed changes

wbamberg and others added 3 commits September 15, 2023 10:00

Apply suggestions from code review

a8df7d8

Co-authored-by: Dipika Bhattacharya <[email protected]>

Description should be optional but recommended

d5c04f4

Update syntax example and Values to match

7ae1fe3

wbamberg requested review from estelle and dipikabh September 15, 2023 17:57

dipikabh approved these changes Sep 19, 2023

View reviewed changes

Elchi3 removed their request for review September 19, 2023 13:04

Merge branch 'main' into page-template-css-function

6446f0e

estelle approved these changes Sep 20, 2023

View reviewed changes

estelle merged commit fcf8683 into mdn:main Sep 20, 2023
6 checks passed

wbamberg mentioned this pull request Sep 22, 2023

Fix 28866: Clarify polygon() syntax #28873

Merged

wbamberg mentioned this pull request Nov 25, 2023

polygon() Formal Syntax is an error mdn/yari#10099

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a template for CSS functional notation #28953

Add a template for CSS functional notation #28953

wbamberg commented Sep 5, 2023 •

edited

Loading

github-actions bot commented Sep 5, 2023 •

edited

Loading

yarusome commented Sep 6, 2023 •

edited

Loading

wbamberg commented Sep 6, 2023 •

edited

Loading

yarusome commented Sep 7, 2023

wbamberg commented Sep 7, 2023

OnkarRuikar commented Sep 8, 2023

wbamberg commented Sep 8, 2023

wbamberg commented Sep 12, 2023

OnkarRuikar commented Sep 13, 2023

estelle left a comment

estelle Sep 13, 2023

wbamberg Sep 13, 2023

dipikabh Sep 14, 2023

estelle Sep 15, 2023

wbamberg Sep 15, 2023

wbamberg commented Sep 13, 2023 •

edited

Loading

dipikabh left a comment

dipikabh Sep 14, 2023

dipikabh Sep 14, 2023 •

edited

Loading

wbamberg Sep 15, 2023

dipikabh Sep 19, 2023

dipikabh Sep 14, 2023

dipikabh Sep 14, 2023

wbamberg Sep 15, 2023 •

edited

Loading

dipikabh Sep 19, 2023

wbamberg commented Sep 15, 2023

dipikabh left a comment •

edited

Loading


		## Description

		This is an optional section to include a description of the function and explain how it works. Use this section to explain related terms and add use cases for the function.

	This is an optional section to include a description of the function and explain how it works. Use this section to explain related terms and add use cases for the function.
	Include a description of the function and explain how it works. Use this section to explain related terms and add use cases for the function.


		### Add a descriptive heading

		Each example must have an H3 heading (`###`) naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.

Add a template for CSS functional notation #28953

Add a template for CSS functional notation #28953

Conversation

wbamberg commented Sep 5, 2023 • edited Loading

github-actions bot commented Sep 5, 2023 • edited Loading

yarusome commented Sep 6, 2023 • edited Loading

wbamberg commented Sep 6, 2023 • edited Loading

yarusome commented Sep 7, 2023

wbamberg commented Sep 7, 2023

OnkarRuikar commented Sep 8, 2023

wbamberg commented Sep 8, 2023

wbamberg commented Sep 12, 2023

OnkarRuikar commented Sep 13, 2023

estelle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg commented Sep 13, 2023 • edited Loading

dipikabh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dipikabh Sep 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg Sep 15, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg commented Sep 15, 2023

dipikabh left a comment • edited Loading

Choose a reason for hiding this comment

wbamberg commented Sep 5, 2023 •

edited

Loading

github-actions bot commented Sep 5, 2023 •

edited

Loading

yarusome commented Sep 6, 2023 •

edited

Loading

wbamberg commented Sep 6, 2023 •

edited

Loading

wbamberg commented Sep 13, 2023 •

edited

Loading

dipikabh Sep 14, 2023 •

edited

Loading

wbamberg Sep 15, 2023 •

edited

Loading

dipikabh left a comment •

edited

Loading