Introduce HTML Processor

[abhansnuk]

No description provided.

[github-actions]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[codente]

Trac: https://core.trac.wordpress.org/ticket/58517

But mentioned in another trac ticket that this one needs one https://core.trac.wordpress.org/ticket/58961#comment:9 so I commented there asking about it

newly identified dev note

Owned by: dmsnell

[nalininsbs]

Draft shared on ticket. Adding on tracker to make more visible. Please highlight in core for tech review.

[codente]

Draft: https://make.wordpress.org/core/?p=109160&preview=true

The dev note looks good to me. The only comments I have are that based on review of other dev notes, I think when tags are mentioned like div and img, we typically use inline code tag so it appears like <div> and <img>.

Also, would you agree this should go in the field guide?

[bph]

Just reviewed:

• removed tag: #dev-noteshtml-api
• did minimal grammatical updates (ie)
• • " element inside of a surrounding DIV." is now: " element inside a surrounding DIV.
• • "in order to avoid" is now "to avoid"
• • "it can read any and all possible HTML documents" is now: "it can read all possible HTML documents."
• Added excerpt
  - Enabled public preview

[bph]

@codente Yes should go into the Field Guide.

[dmsnell]

based on review of other dev notes, I think when tags are mentioned like div and img, we typically use inline code tag so it appears like

and .

seems fair, though for context I adopted that expression style based on a combination of WordPress requiring it internally and based on the nomenclature in the HTML literature.

it's been a hard call determining which conflicting styles to follow. I'm not sure why the tag syntax isn't allowed inside WordPress, unless it has to do with preventing rendering issues when generating documentation.

more importantly but tangentially, and something I've been trying to do consistently with the HTML API is speak of elements when talking about the DOM nodes or what is in a page, e.g. an IMG element, and of tags only when talking about the text/strings in HTML. whereas there's an <img> tag, a <p> opening tag and a </p> closing tag, and possibly a <ARTiclE> tag, there are only IMG, P, and ARTICLE elements to which they refer (similarly there can be tags with no corresponding elements, such as stray tag closers). again, thanks for reviewing this and bringing in the other considerations - this stuff is complicated because of the wide semantic overlap of terms, and the context of these wordings is to try and avoid more conflation of terms through consistent and precise language.

whatever people want here is fine with me, though if there's doubt about the requirement, I would like to see broader adoption of "DIV element" phrasing in WordPress literature.

[dmsnell]

@bph I added dev-notes+html-api based on the dev notes guidelines. that was surely a misreading of the guidelines, but maybe we could clarify on that page what should happen.

based on the fact that this is a dev note for a release and for something in a specific component I understood the guidelines to indicate that both tags should be there, as the example links to dev-notes+rest-api.

it was also confusing whether I should add 6.4 or dev-notes-6.4 or both. the guidelines didn't suggest dev-notes-6.4 but I saw that on others so followed their example.

this is unrelated to the dev note for the HTML Processor, but I wasn't sure where else to leave this feedback.

[dmsnell]

Another question I had is whether it will be possible to link to the docs for this class before the dev note publishes. I'd really like to send people to the class documentation as that's more comprehensive and full of examples to follow.

Is that going to be available or do we have to skip the docs link for this one?

[nalininsbs]

I have just asked your question on tags to @abhansnuk. Below is her reply:
Yes for this one we would be adding a component dev note tag. Thank you @dmsnell .
We also use the tags dev-notes, dev-note-releasenumber. This allows people to search by either of three tags.

Where a dev note is a mixed dev note, eg performance, and covers a number of components, it is unclear whether we need to tag all the components or not use the component tag. We have added this to the documentation tracker to find the definitive answer, and then apply this to all published dev notes where this query applies. Also to the documentation for those doing the release, and updating the page on dev notes in the Core Handbook.

Thanks Dennis for highlighting that it is unclear in the Handbook.

[nalininsbs]

Is there a particular description you think would be useful for developers for this in the Field Guide?

If there is more information on the class documentation and full examples to follow, then it would be a useful link to add to this dev note.

Thank you @dmsnell

[nalininsbs]

Copying for Abha:
Finished second review.

• the main tweak is the sentence above CSS helpers, have turned the sentence for easier flow to: "In WordPress 6.4, however, the only new feature is the concept of breadcrumbs."
• we can use the excerpt as the text for the Field Guide if this is to go into the list of bullet points. However, I think as this is something that has a clear path for ongoing improvements and will be very useful to devs and I would suggest it features higher in the guide. What are your thoughts @bph and @dmsnell , and if so, is there a particular aspect or text you would want to hone in on, and add anything about ongoing developments on it?

Really enjoyed reading this dev note, clear and easy to follow. Thanks so much @dmsnell, and to @bph and @codente too. I think it would make a good follow up in the dev blog showing its usage too.

[nalininsbs]

#1200 (comment)
@codente could you take the question later to the tracker as a follow-up query for the documentation on the process? It can be added to the questions list to follow up in a docs meeting after all the deadlines. Thank you.

[dmsnell]

Is there a particular description you think would be useful for developers for this in the Field Guide?

there's no list of examples, just a few links to existing dev notes. I think a single list of a few cases with all appropriate tags could go a long way.

moreover, two specific things that confused me:

• the link is to dev-notes+rest-api which I interpreted as the tag name, but looking over it now I think it's actually forming a query requiring both the dev-notes tag and also the rest-api tag. this makes dev-notes-6.4 seem redundant and suggests that we should have dev-notes and 6.4 but not dev-notes-6.4.
• the one example given, using 5.5 as a version number, contradicts the tag seen in the links and existing dev notes, which use 5-5. I think that WordPress automatically converts the . to a -, but it would be helpful if those were consistent. the block editor shows dev-notes-6.4 yet the post renders with dev-notes-6-4.

---

The dev note tags make it possible to filter Make posts to see all dev notes, updates to a particular WordPress release, or updates to a particular component.

Examples:

• All dev notes posts should have the dev-notes tag.
• If the dev note pertains to a specific component, it should have the corresponding tag. For example, an update to the REST API should have the rest-api tag.
• If the dev note is part of a WordPress release, it should have a tag corresponding to the version number of that release. For example, an update that arrives with WordPress 6.4 should have the 6.4 tag.

[bph]

I am learning every day :-) I didn't retain the information from the guidelines as to a specific component being tagged. But I would think those are the components from this page only.
Does the HTML Processors does really belong to any specific component from that list?

The devnotes-[version] might have been from my rookie dev notes wrangling days. I used in 6.0, I think, and that stuck around. Back then I didn't know about that you could to daisy-chain of tags to /tag/devnotes+[version]

Now devnotes-[version] actually feels redundant.

[nalininsbs]

My interpretation is that if we miss out the tag with both dev notes and the 6.4 tag, then people clicking on 6.4 will have a list of everything tagged 6.4, so much more than the dev notes. To me the combination of these tags allow the person to get a filter of dev notes relating to 6.4 only. This is useful if they are interested in dev notes wider than a single component. In that case, the dev notes query with the component name would not be sufficient.

Equally there may be a person who wants to only see dev notes by a particular component.

[nalininsbs]

"The one example given, using 5.5 as a version number, contradicts the tag seen in the links and existing dev notes, which use 5-5. I think that WordPress automatically converts the . to a -, but it would be helpful if those were consistent. the block editor shows dev-notes-6.4 yet the post renders with dev-notes-6-4."

The answer to this can go in the documentation gathering from this release relating to docs. This can also support updating the dev notes and Field Guide pages in the core handbook. Thank you for highlighting.

Can I clarify, @dmsnell you are suggesting when typing in the tag, dev-notes-6-4 should be used instead of the point in the version number? This would then give consistency. Thank you.

[codente]

@dmsnell in the Field Guide, we usually put a short description with the embed/link to the dev note.

Something like:

"WordPress 6.4 includes continued development of the HTML API, including the introduction of a minimal HTML Processor with the concept of breadcrumbs and makes it possible to, for example, search for images that are direct children of a DIV.

Also included in 6.4, is the addition of a couple of CSS/class helpers in the Tag Processor which will make it possible to search for a tag containing more than one class name, or to search for a tag not containing a given class name."

What are your thoughts on the above? Feel free to provide your own short description instead if you think something else would be more beneficial.

[aurooba]

To me the combination of these tags allow the person to get a filter of dev notes relating to 6.4 only. This is useful if they are interested in dev notes wider than a single component. In that case, the dev notes query with the component name would not be sufficient.

Here to add a +1 to this comment from @nalininsbs. Daisy-chaining is helpful, but being able to click on a single tag for release specific dev notes is super helpful, since there's no intuitive visual way to daisy chain that I'm aware of in the Make blogs.

[dmsnell]

Does the HTML Processors does really belong to any specific component from that list?

I'm not sure I totally understand what you're asking, but the HTML Processor definitely belongs to the HTML API, one of the components in that list.

I am learning every day

I expect we all are. I sure am. These are all my own observations and interpretations, by the way. I have no idea what's right or if the documentation is out of date.

are suggesting when typing in the tag, dev-notes-6-4 should be used instead of the point in the version number?

on this point I'm not sure. all I'm saying is that it's a bit confusing to be instructed to enter dev-notes-6.4 but then see dev-notes-6-4 in the rendered page. I think this relates to a tag's name vs. its slug. at a minimum, this could be noted in the documentation as an aside: "Are you curious why 6.4 appears as 6-4?"

What are your thoughts on the above?

@codente sounds great! thanks for putting that together.

Daisy-chaining is helpful, but being able to click on a single tag for release specific dev notes is super helpful, since there's no intuitive visual way to daisy chain that I'm aware of in the Make blogs.

Some drive-by observations on this: I hear the value statement of doing this, and it may be warranted in this very limited case, but precomputing this daisy-chaining can also lead to confusion, which I believe it has in this case. I wonder if there's a more valuable approach to making it easier to learn how to limit the posts in the Make blog so that it's less confusing - teach people as they use the site.

Obviously it's not practical to create tags for every combination of tags one might want to daisy-chain. Maybe this is a very rare and unique special case though 🤷‍♂️

---

@nalininsbs just to ensure we're on the same page, in the example snippet I shared above, my goal was to communicate that these tags are additive. a dev note would have one, two, or three tags depending on if it's generic, part of a release, part of a component, or part of a release and a component. with three tags we get four different searches: all dev notes, all dev notes for the REST API, all dev notes for 6.4, all dev notes for 6.4 that are part of the REST API. my wording was only suggestive for the concept and is probably unclear.

[abhansnuk]

Thank you for the answers, appreciated. @dmsnell . On one aspect, is the rest of the dev blog now ready to be published? The tag issue can be resolved later on the post. The Field Guide will Georgie from its inclusion at this stage.

Thank you for all your input on the tag issue and the last clarification too.

[dmsnell]

is the rest of the dev blog now ready to be published?

Perhaps if other people think it is; I'm content with it, but I don't know where the review left it.

[nalininsbs]

Tags issue will be further discussed post Field Guide.

Published link: https://make.wordpress.org/core/2023/10/21/updates-to-the-html-api-in-6-4/

[dmsnell]

Thank you @nalininsbs !