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.

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

The spec language for enumerated attributes is not consistent #9832

Open
mfreed7 opened this issue Oct 4, 2023 · 6 comments
Open

The spec language for enumerated attributes is not consistent #9832

mfreed7 opened this issue Oct 4, 2023 · 6 comments
Labels
editorial Changes that do not affect how the standard is understood good first issue Ideal for someone new to a WHATWG standard or software project

Comments

@mfreed7
Copy link
Contributor

mfreed7 commented Oct 4, 2023

What is the issue with the HTML Standard?

This is a spec-only issue, nothing related to behavior.

The spec has a number of <span>enumerated attribute</span>s, and there are three things that are not consistent:

  1. Some definitions use a <table> of attribute values, while others use prose. Preferred: use a table.
  2. Of the definitions using <table>s, most do not have closing tags (e.g. </tr>) while some do. Preferred: use closing tags.
  3. The introductory text for the table differs. Preferred: "is an enumerated attribute with the following keywords and states:". Others have no text or use things like "The following table lists...".

See the data below for which attributes fall into which camps.

Data

No closing tags
  • CORS settings attribute ("The following table...")
  • lazy loading attribute ("The following table...")
  • fetch priority attribute ("The following table...")
  • kind ("The following table...")
  • preload ("The following table...")
  • shape ("The following table...")
  • hidden ("The following table...")
  • inputmode (no introductory text at all)
  • popovertargetaction ("is an enumerated attribute with the...")
  • marquee/behavior ("is an enumerated attribute with the...")
  • marquee/direction ("is an enumerated attribute with the...")
Has closing tags
  • dir ("The following table...")
Doesn't use a table
  • referrer policy attribute
  • translate
  • href
  • scope
  • wrap
  • contenteditable
  • spellcheck
  • draggable
@keithamus keithamus added the editorial Changes that do not affect how the standard is understood label Oct 4, 2023
@annevk
Copy link
Member

annevk commented Oct 5, 2023

Thanks for filing this. For anyone wanting to get some editing experience this would be a great issue to work on. Not everything has to be fixed in one go either, it's fine to tackle this one attribute at a time, say.

For those coming here through "good first issue": note that we don't assign issues and you don't have to ask if this is still available. Just provide a PR.

@annevk annevk added the good first issue Ideal for someone new to a WHATWG standard or software project label Oct 5, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 5, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 5, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 5, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 5, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 5, 2023
annevk pushed a commit that referenced this issue Oct 5, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 6, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 6, 2023
annevk pushed a commit that referenced this issue Oct 6, 2023
@domenic
Copy link
Member

domenic commented Oct 7, 2023

Thanks for filing this, and thanks @keithamus for your work here!

It seems like the format we're settling on is similar to the following:

... is an enumerated attribute with the following keywords and states:

followed by a table with the columns "Keyword", "State", and "Brief description" (in that order). The table does not use closing tags, and the brief description does not have <p> wrappers. The brief descriptions do end in periods.

Some like shape or http-equiv will need an additional "Notes" column to note the non-conforming ones.

After the table should come the definition of invalid value default and missing value default, as well as any canonicalization needed for reflection. The form of that should be something like

The attribute's missing value default and invalid value default are both the auto state.

or

The missing value default is the subtitles state. The invalid value default is the metadata state.

Some notes on the ones that don't use a table currently: referrer policy attributes and as seem good as-is; because of the 1:1 relationship and dependency on the referrer policy / potential destination concepts defined elsewhere, the table wouldn't add anything.

type on input is also very special and might be best to leave as-is.

keithamus added a commit to keithamus/html that referenced this issue Oct 9, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 9, 2023
annevk pushed a commit that referenced this issue Oct 9, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 10, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 10, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 10, 2023
annevk pushed a commit that referenced this issue Oct 10, 2023
mfreed7 pushed a commit to mfreed7/html that referenced this issue Oct 11, 2023
mfreed7 pushed a commit to mfreed7/html that referenced this issue Oct 11, 2023
mfreed7 pushed a commit to mfreed7/html that referenced this issue Oct 11, 2023
mfreed7 pushed a commit to mfreed7/html that referenced this issue Oct 11, 2023
keithamus added a commit to keithamus/html that referenced this issue Oct 12, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 5, 2023
annevk pushed a commit that referenced this issue Dec 8, 2023
keithamus added a commit to keithamus/html that referenced this issue Dec 8, 2023
keithamus added a commit to keithamus/html that referenced this issue Dec 8, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Dec 14, 2023
rubberyuzu added a commit to rubberyuzu/html that referenced this issue Dec 21, 2023
Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: Remove old FinishDynamicImport reference

Restore early return for history.go(0)

This accidentally was lost in 0a97a81.

Editorial: add enumerated attribute table for draggable

Helps with whatwg#9832.

Editorial: add enumerated attribute table for form/autocomplete

Helps with whatwg#9832.

Fix PromiseRejectionEvent's promise attribute

As discovered in whatwg/streams#1298 (comment), Promise<T> is actually not an appropriate type for it.

Navigation API: add navigation.activation

Closes whatwg#9760.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.
annevk pushed a commit that referenced this issue Jan 9, 2024
@keithamus
Copy link
Contributor

I think this issue can now be closed? Would anyone care to double check that we've got them all? (perhaps @mfreed7 😄)

@domenic
Copy link
Member

domenic commented Jan 10, 2024

Amazing work; thank you!!

Biggest easy thing I'd like to see fixed: inconsistent empty string keywords. We have one The empty string, many (The empty string), and one (the empty string). I think (the empty string) is my favorite.

I'd also like to see the empty string keyword/state be consistently the first in the table, and the order be real keyword then (the empty string).

Other minor issue: for dir there's a note between the table and the missing/invalid value default sentence.

Un-updated attriutes:

  • method and formmethod. Would be pretty simple to update I think.
  • enctype and formenctype. Would require making up state names and referencing them appropriately throughout the spec. I suggest URL encoded, form data, and plain text.
  • inputmode and enterkeyhint. Not clear that updating them buys us much since the processing model is encapsulated and so there's no other parts of the spec that would reference the states.

Finally, we're inconsistent on whether state names are capitalized or lowercase. This is probably not worth fixing, but I could see it causing confusion in the future for people introducing new enumerated attributes and being unsure which to use. I was leaning toward lowercase but https://html.spec.whatwg.org/#the-button-element:enumerated-attribute

If the type attribute is in the Submit Button state, the element is specifically a submit button.

would be pretty confusing lowercased.

@mfreed7
Copy link
Contributor Author

mfreed7 commented Jan 10, 2024

I think this issue can now be closed? Would anyone care to double check that we've got them all? (perhaps @mfreed7 😄)

Thanks for taking care of this! Much appreciated. I'd add more comments, but @domenic got there first and his comments are more thorough than mine would ever be. 😄

domenic pushed a commit that referenced this issue Jan 12, 2024
Helps with #9832, by consistently using "(the empty string)" and placing such rows in the same place in the enumerated attribute tables.
rubberyuzu pushed a commit to rubberyuzu/html that referenced this issue Jan 12, 2024
Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

wip - failing

wip

so far

c

no parse error

buildable

buildable-success

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

c

fix main document

Editorial: remove closing tags on the dir attribute table

Helps with whatwg#9832.

add hr

mc

mc

fix id and src desc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
editorial Changes that do not affect how the standard is understood good first issue Ideal for someone new to a WHATWG standard or software project
Development

No branches or pull requests

6 participants
@keithamus @domenic @annevk @mfreed7 @rose2221 and others