docs(fix): Improve <source> element page for consistency and clarity

[dipikabh]

Description

This PR aims to improve the <source> element documentation by making the following updates:

• Refines the introductory paragraph in the "Attributes" section by adding the lead-in sentence, "In addition, the following attributes can be used with it." (This addition could potentially be added to the HTML reference page template.)
• Aligns attribute descriptions by first explaining "what it is", followed by whether or not it is allowed.
• Replaces the numbered list in srcset with a bulleted list.
• Moves the last two paragraphs in the "Attributes" section to the "Usage notes" section for better placement.
• Updates example headings to adopt a gerund form and to eliminate the redundant use of "example".
• Updates link texts to guides to match the titles of those pages.
• Replaces "user agent" with "browser" for consistency.

Motivation

To improve the readability and consistency

Additional details

Doc issue tracker: #29788

[github-actions]

Preview URLs

• /en-US/docs/Web/HTML/Element/source

(comment last updated: 2023-11-07 15:25:17)

[chrisdavidmills]

@dipikabh great work, nice one Dipika. This is much better. I've left you a few content suggestions.

[chrisdavidmills]

Suggested change

	- An optional width descriptor—a positive integer directly followed by `"w"`, such as `300w`. If not specified, the value used by default is infinity.
	- An optional width descriptor—a positive integer directly followed by `"w"`, such as `300w`. If not specified, the value used by default is `infinity`.

[dipikabh]

This suggestion led me to check the spec (should have checked earlier). I did not find a reference either in the source element page or in the linked srcset attribute page.

This section in the spec from "srcset attribute" does not mention any default values for the width and pixel density descriptors. I am not sure if we should mention them in our docs. What do you think?

4. Zero or one of the following:

   • A width descriptor, consisting of: ASCII whitespace, a valid non-negative integer giving a number greater than zero representing the width descriptor value, and a U+0077 LATIN SMALL LETTER W character.

   • A pixel density descriptor, consisting of: ASCII whitespace, a valid floating-point number giving a number greater than zero representing the pixel density descriptor value, and a U+0078 LATIN SMALL LETTER X character.

[chrisdavidmills]

Hrm, this is a good point. The default value descriptions aren't that helpful and probably confuse more than they inform. About the closest there is to a default value description in the spec is on the srcset page:

For the purpose of this requirement, an image candidate string with no descriptors is equivalent to an image candidate string with a 1x descriptor.

A bigger issue, in my mind, is that the text here doesn't really describe the purpose of srcset/sizes, or how you would use them.

I would suggest:

1. Removing the default value descriptions, or perhaps just say something afterwards to the effect that, if a ...w or ...x is not included, it is equivalent to specifying 1x. I think that is what the spec is saying?
2. Include some more description and usage examples on the page, or link to some somewhere else. I did attempt to provide this in my learning area Responsive Images article, but I don't know how bulletproof that actually is. It seems to make sense to me, but we've had quite a few tickets filed in the past querying whether the code is correct. It was challenging to figure this stuff out.

[dipikabh]

Thanks for taking the time and for offering suggestions!

1. Agree, removed the default value statement from each descriptor and added a common one in the subsequent para (c96683a).
2. Should we tackle this outside this PR? :)

[dipikabh]

Thanks a lot @chrisdavidmills for taking the time to review this PR. Great feedback, I've accepted your suggestions.
I could use your help with a question I've added here: #29946 (comment)

[chrisdavidmills]

@dipikabh Thanks, this is looking nearly perfect now. There is just the question of what to do about the srcset description. I have provided some suggestions.

[dipikabh]

@chrisdavidmills, I've accepted your suggestion for the descriptor default values. Thanks!
Maybe we do a follow up PR to improve on srcset?

[chrisdavidmills]

Sure thing @dipikabh, that sounds like a very sensible way to tackle this. Approving.

[dipikabh]

Thanks, @chrisdavidmills!