fix(manifest): Update manifest member pages to follow the same format

[dipikabh]

Description

Issue: At the moment, the manifest member pages lack consistency: some list values in a table, while in some others, the "Values" section appears after "Examples" or uses a longer section name like "launch_handler item values".

Goal: Before updating the content of individual manifest member pages, I want to align them all so that they have the same sections in the same order and follow the same format.

Changes in this PR:

• Removed the "Type" table from the top of the page (this info will get covered in the "Values" section).
• Added a "Syntax" section to all pages.
• Replaced the table formats in the "Values" section with a definition list format, where applicable.
• Renamed sections where needed to ensure that they are called "Values" and "Examples".
• Moved the "Values" section to the correct place on the page, before "Examples", where needed.

Next steps: I haven't made any content updates yet (except for adding the Syntax section), so some pages do not have a "Values" section at this point. I'll tackle this in my next iteration.

Motivation

To standardize the structure and format across manifest member pages

Related issues and pull requests

• Tracking issue: [Project] Improve web/manifest docs mdn#560
• display page PR: docs(manifest): Improve display member page #34386
• icons page PR: docs(manifest): Improve icons member page #34725

[github-actions]

Preview URLs (14 pages)

• /en-US/docs/Web/Manifest/background_color
• /en-US/docs/Web/Manifest/categories
• /en-US/docs/Web/Manifest/description
• /en-US/docs/Web/Manifest/display_override
• /en-US/docs/Web/Manifest/file_handlers
• /en-US/docs/Web/Manifest/id
• /en-US/docs/Web/Manifest/launch_handler
• /en-US/docs/Web/Manifest/orientation
• /en-US/docs/Web/Manifest/protocol_handlers
• /en-US/docs/Web/Manifest/scope
• /en-US/docs/Web/Manifest/screenshots
• /en-US/docs/Web/Manifest/serviceworker
• /en-US/docs/Web/Manifest/share_target
• /en-US/docs/Web/Manifest/shortcuts

Flaws (2)

Note! 12 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/Manifest/categories
Title: categories
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: html.manifest.categories

---

URL: /en-US/docs/Web/Manifest/screenshots
Title: screenshots
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: html.manifest.screenshots

External URLs (1)

URL: /en-US/docs/Web/Manifest/categories
Title: categories

• https://github.com/w3c/manifest/wiki/Categories (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-09-17 18:21:39)

[pepelsbey]

It looks very nice! Much more consistent and readable now 😍

I have a small concern, though.

```json
"screenshots": [
  {
    "form_factor": "narrow" | "wide"
  }
]
```

Presenting values in the code examples separated by pipes looks clear if you know how JSON works, how strict it is, etc. But when you’re learning about manifest for the first time, you might just copy-paste the sample and have a hard time figuring out why your manifest doesn’t work. Browsers won’t show you any warnings if your manifest is malformed.

I searched for true | false kind of cases, and they’re not very common, apart from XSL docs, for example. We can fix this, too. I’ll bring this up on the next content sync. Or you can do it while I’m away :)

I wonder if it would be better to show some sort of obviously non-fitting placeholder with the value type and list values below? These are pretty common on MDN. Something like:

```json
"screenshots": [
  {
    "form_factor": <string>
  }
]
```

- `"narrow"` some desc
- `"wide"` some desc

[dipikabh]

Thanks for reviewing, @pepelsbey!

You've highlighted how we approach Syntax sections across different technology areas on MDN. :)

Some background on how I went about the syntax on these pages: I wanted to add a "Syntax" section that provides a quick, sort of a scannable, template that lists all available values or property-value pairs, including any keyword values, so readers can get an overview at a glance. For style, I aligned it with the JS and API areas, using camelCase variables in the syntax, rather than following the approach in the CSS area of using examples to demonstrate the syntax.

I see your point about the potential confusion from using the | notation. It's a really good and nuanced observation!
You're right, it might lead to unexpected outcomes if copied and used directly. Even though our guideline says that "Syntax sections are not meant to show runnable code.", I would lean towards reducing the confusion if possible by avoiding the |. And as you've pointed, it's true that this is not a common practice in our documentation for writing syntax.
(I'm probably trying to cram too much information by spelling out the keywords in the syntax. It would have been easier if I could add comments to the JSON 🙂.)

If we skip the keywords in the syntax, we could use the variable name to suggest that specific keywords are expected as values for the said member/property. Combining this idea with your suggestion, we could use:

```json
"screenshots": [
  {
 
    "form_factor": "keywordValue",
    "platform": "keywordValue"
  
  }
]
```

and booleanValue instead of true | false. The subsequent "Values" section will list and explain the possible keyword values in detail. What do you think about this approach?

I'd considered using placeholders like "<image>", "<urlString>", etc. for values, but again, these kind of uses in Syntax in our docs are rare (as in If-None-Match: "<etag_value>").

Update: In CSS, we do use the < > nomenclature to denote date types like <color> as values for properties.

Another update: Resorting to use the < > style with hyphens, as discussed in #35643 (comment). This is basically inline with your initial suggestion 🙂, just not indicating the type.

[dipikabh]

@pepelsbey, I've suggested these changes to remove the pipe notation and streamline some other variable names.

[github-actions]

This pull request has merge conflicts that must be resolved before it can be merged.

[dipikabh]

Update all placeholder values to follow the same format

[dipikabh]

remove invalid JSON

[dipikabh]

Hi Vadim, this is ready for you to take another look. Thanks!

[dipikabh]

Moving this to draft until we decide on a format in #34725

[github-actions]

This pull request has merge conflicts that must be resolved before it can be merged.

[dipikabh]

Hi @pepelsbey, we reached a consensus in #34725 (comment) about the format of "Syntax" blocks. It will contain use cases, similar to the "Syntax" blocks in CSS properties, not placeholder variables. icons and theme_color manifest pages just landed with these changes to the "Syntax".

What you need to know for reviewing this PR:

• Since adding examples to the "Syntax" block will be a bit more involved now, I've subtracted "Syntax" blocks from this PR.
• I've also removed the files name, short_name, start_url (35847), related_applications, and prefer_related_applications (35906) from this PR because they're part of other ongoing PRs.

[pepelsbey]

Looks good :) Thank you!

[dipikabh]

Thanks for reviewing, Vadim!