Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: tweak spelling, make punctuation and wording consistent #7154

Closed
wants to merge 6 commits into from
Closed

docs: tweak spelling, make punctuation and wording consistent #7154

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4f33b30
docs: incorporate spec review notes
j9t Sep 25, 2021
09e5177
docs: incorporate spec review notes
j9t Sep 25, 2021
3ead5e1
Merge branch 'whatwg:main' into main
j9t Sep 28, 2021
318748b
docs: revert transparent images edit
j9t Sep 30, 2021
26c4ba7
Merge branch 'whatwg:main' into main
j9t Oct 1, 2021
0b678fa
docs: tweak spelling, make punctuation and wording consistent
j9t Oct 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 24 additions & 23 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69478,7 +69478,7 @@ dictionary <dfn dictionary>ValidityStateFlags</dfn> {

<h4 id="rel-up">Bread crumb navigation</h4>

<p>This specification does not provide a machine-readable way of describing bread-crumb navigation
<p>This specification does not provide a machine-readable way of describing breadcrumb navigation
menus. Authors are encouraged to just use a series of links in a paragraph. The <code>nav</code>
element can be used to mark the section containing these paragraphs as being navigation
blocks.</p>
Expand Down Expand Up @@ -70203,14 +70203,14 @@ Demos:
<ul>
<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-checkbox">Checkbox</span> state and whose <span
data-x="concept-fe-checked">checkedness</span> state is true</li>
data-x="concept-fe-checked">checkedness</span> state is true.</li>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how authoritative it is, but according to https://www.imperial.ac.uk/brand-style-guide/writing/grammar/punctuation/bullet-points/ the more "correct" way in this case would be

The :checked pseudo-class must match any element falling into one of the following categories:

  • input elements whose type attribute is in the Checkbox state and whose checkedness state is true;
  • input elements whose type attribute is in the Radio Button state and whose checkedness state is true;
  • option elements whose selectedness is true.

That is, a semi colon between each item and a full stop after the last one.
If going this route, :hover section above would also need an update.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a fair point. For context, and as I describe in the description of the PR, all other sentences seem to use periods, so I used those for consistency.

If you and the other editors now like to use different punctuation I suggest this is handled elsewhere, that is, feel free to dismiss this consistency update to accomplish the consistency you prefer.


<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-radio">Radio Button</span> state and whose <span
data-x="concept-fe-checked">checkedness</span> state is true</li>
data-x="concept-fe-checked">checkedness</span> state is true.</li>

<li><code>option</code> elements whose <span
data-x="concept-option-selectedness">selectedness</span> is true</li>
data-x="concept-option-selectedness">selectedness</span> is true.</li>
</ul>
</dd>

Expand All @@ -70222,15 +70222,15 @@ Demos:
<ul>
<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-checkbox">Checkbox</span> state and whose <code
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute is set to true</li>
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute is set to true.</li>

<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-radio">Radio Button</span> state and whose <span>radio button
group</span> contains no <code>input</code> elements whose <span
data-x="concept-fe-checked">checkedness</span> state is true.</li>

<li><code>progress</code> elements with no <code data-x="attr-progress-value">value</code>
content attribute</li>
content attribute.</li>
</ul>
</dd>

Expand All @@ -70245,10 +70245,10 @@ Demos:

<li><code>input</code> elements to which the <code data-x="attr-input-checked">checked</code>
attribute applies and that have a <code data-x="attr-input-checked">checked</code>
attribute</li>
attribute.</li>

<li><code>option</code> elements that have a <code data-x="attr-option-selected">selected</code>
attribute</li>
attribute.</li>
</ul>
</dd>

Expand Down Expand Up @@ -70278,16 +70278,16 @@ Demos:
<ul>
<li>elements that are <span data-x="candidate for constraint validation">candidates for
constraint validation</span> and that <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
constraints</span>.</li>

<li><code>form</code> elements that are not the <span>form owner</span> of any elements that
themselves are <span data-x="candidate for constraint validation">candidates for constraint
validation</span> but do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
constraints</span>.</li>

<li><code>fieldset</code> elements that have no descendant elements that themselves are <span
data-x="candidate for constraint validation">candidates for constraint validation</span> but do
not <span data-x="concept-fv-valid">satisfy their constraints</span></li>
not <span data-x="concept-fv-valid">satisfy their constraints</span>.</li>
</ul>
</dd>

Expand All @@ -70299,17 +70299,17 @@ Demos:
<ul>
<li>elements that are <span data-x="candidate for constraint validation">candidates for
constraint validation</span> but that do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
constraints</span>.</li>

<li><code>form</code> elements that are the <span>form owner</span> of one or more elements
that themselves are <span data-x="candidate for constraint validation">candidates for constraint
validation</span> but do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
constraints</span>.</li>

<li><code>fieldset</code> elements that have of one or more descendant elements that themselves
are <span data-x="candidate for constraint validation">candidates for constraint
validation</span> but do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
constraints</span>.</li>
</ul>
</dd>

Expand All @@ -70335,13 +70335,14 @@ Demos:
any element falling into one of the following categories:</p>

<ul>
<li><code>input</code> elements that are <i data-x="concept-input-required">required</i></li>
<li><code>input</code> elements that have a <code data-x="attr-select-required">required</code>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a normative change that does not match with the current implementations.
The mere presence of the required attribute does not make the element's required. For instance

<input type="button" required>

will not match :required.

Maybe https://html.spec.whatwg.org/multipage/input.html#concept-input-required should call out explicitly that when an element is barred from constraint validation it can not be required, but that would be for an other issue.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh and I missed it, but your link was wrong too, it should have been data-x="attr-input-required".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe https://html.spec.whatwg.org/multipage/input.html#concept-input-required should call out explicitly that when an element is barred from constraint validation it can not be required, but that would be for an other issue.

I had reviewed that section and to me it suggests “being required” and “having the required attribute [set]” is the same thing? What do I miss—or is there something that we could make more clear in the respective section.

Oh and I missed it, but your link was wrong too, it should have been data-x="attr-input-required".

What is “my link”? Also, I copied from the two list items below, for consistency.

Copy link
Member

@Kaiido Kaiido Oct 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well that's the thing of normative changes, we can't really stop at what things "suggest". Changing when a rule applies is a normative change, it needs to be done thoroughly and checked with implementers.
As I said, I agree that https://html.spec.whatwg.org/multipage/input.html#concept-input-required should specifically tell that "barred from constraint validation" does prevent "is required" (or the other way around), if that's really what does prevent it, but that requires its own issue and investigation.

What is “my link”? Also, I copied from the two list items below, for consistency.

data-x attributes do link to definitions, you were gonna link to https://html.spec.whatwg.org/#attr-select-required which is specifically for <select> elements, the correct link would have been https://html.spec.whatwg.org/#attr-input-required that you set through data-x="attr-input-required". But anyway, this change should be reverted.

attribute.</li>

<li><code>select</code> elements that have a <code data-x="attr-select-required">required</code>
attribute</li>
attribute.</li>

<li><code>textarea</code> elements that have a <code
data-x="attr-textarea-required">required</code> attribute</li>
data-x="attr-textarea-required">required</code> attribute.</li>
</ul>
</dd>

Expand All @@ -70352,13 +70353,13 @@ Demos:

<ul>
<li><code>input</code> elements to which the <code data-x="attr-input-required">required</code>
attribute applies that are not <i data-x="concept-input-required">required</i></li>
attribute applies that are not <i data-x="concept-input-required">required</i>.</li>

<li><code>select</code> elements that do not have a <code
data-x="attr-select-required">required</code> attribute</li>
data-x="attr-select-required">required</code> attribute.</li>

<li><code>textarea</code> elements that do not have a <code
data-x="attr-textarea-required">required</code> attribute</li>
data-x="attr-textarea-required">required</code> attribute.</li>
</ul>
</dd>

Expand Down Expand Up @@ -70388,14 +70389,14 @@ Demos:
<li><code>input</code> elements to which the <code data-x="attr-input-readonly">readonly</code>
attribute applies, and that are <i data-x="concept-fe-mutable">mutable</i> (i.e. that do not
have the <code data-x="attr-input-readonly">readonly</code> attribute specified and that are not
<span data-x="concept-fe-disabled">disabled</span>)</li>
<span data-x="concept-fe-disabled">disabled</span>).</li>

<li><code>textarea</code> elements that do not have a <code
data-x="attr-textarea-readonly">readonly</code> attribute, and that are not <span
data-x="concept-fe-disabled">disabled</span></li>
data-x="concept-fe-disabled">disabled</span>.</li>

<li>elements that are <span data-x="editing host">editing hosts</span> or <span>editable</span>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we really choose to go with a full stop after each item (see previous comment), then at least "elements" should be capitalized.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(See an earlier point on consistency. This is a good point, but the whole section may need reworking if both case and punctuation are changed.)

and are neither <code>input</code> elements nor <code>textarea</code> elements</li>
and are neither <code>input</code> elements nor <code>textarea</code> elements.</li>
</ul>

<p>The <code data-x="selector-read-only">:read-only</code> <span>pseudo-class</span> must match
Expand Down