The spec language for enumerated attributes is not consistent

[mfreed7]

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

[annevk]

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.

[domenic]

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]

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

[domenic]

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]

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. 😄