rewrite html notes: partial

book/CH00_Introduction.adoc

@@ -147,16 +147,31 @@ ____
 
 
 
-[.design-note]
-.HTML Notes: Why Effective HTML?
+[.html-note]
+.HTML Note: Practicing Hypermedia
 ****
-At the end of each chapter you will find tips and best practices for writing effective HTML.
+At the end of each chapter you will find tips and best practices for writing HTML well.
 
-It's very easy (and sometimes acceptable) to produce mediocre HTML that _seems to_ work,
-and many websites settle with _seeming to_ work.
+It's very easy (and sometimes acceptable) to produce mediocre HTML that, within a purview limited to one particular application, works -- this seems to be enough for most websites.
+But our websites, like men, are not islands.
+That is, they are not applications of a _platform_,
+but constituents of a _system_.
 
+In a systems view of the web, the purpose of writing HTML is not just to develop a particular application, but also to play along with other members of the Web.
+Thankfully for us hypermedia advocates, a few components, most prominently search engines and assistive technologies, have enough sway to keep people caring about HTML.
+Less fortunately, lack of awareness around hypermedia means that these components are seen as annoyances to get out of the way, demons to appease, or worse, legacy leftovers to ignore.
+
+After all, web development is so much easier without all this Web stuff.
+
+So why resist the tide? Why shouldn't we discard hypermedia and rewrite the web into the application platform it can clearly be?
+That's what the rest of this book will try to answer, in a practical, non theory-addled way.
+And at the ends of chapters, these HTML Notes will connect the concepts of hypermedia we discuss and the code samples we present to day-to-day web development.
+
+The executive summary:
+Well-written HTML is easier to read and debug, more accessible to all, ranked higher by search engines (not out of bias, but because they have an easier time scraping it).
+
+An important caveat:
+The mantra that HTML is "accesible by default" is misleading and shunning other technologies like JavaScript is misguided.
+Doing everything with "pure", "semantic" HTML is not a panacea, and testing is the ultimate indicator of quality over spec adherence.
 But writing good, spec-compliant HTML lets browsers do a bunch of work for you. Furthermore, even when they don't, it makes it easier to write scripts that do. Fewer issues will be found during testing and you can release faster. When issues do come up, you can often fix them more easily by refactoring HTML as opposed to heaping JavaScript and ARIA attributes over everything.
-
-// TODO: check last sentence here; pulled together from various paragraphs
-Effective HTML typically loads faster, is easier to read and debug, performs better both with search engine ranking and screen reader accessibility, and can be scraped programatically. 
 ****

book/CH01_HypermediaAReintroduction.adoc

@@ -695,20 +695,3 @@ We hope that, in addition, you will also become as passionate about it as we are
 This book is, in part, a plea that we "`let the web be the web`", that we take the original architecture of the web
 seriously, and that we consider the entire _hypermedia system_ it makes available to us when we build applications
 with it.
-
-
-[.design-note]
-.HTML Note: Stay Close to the Output
-****
-[quote, Manuel Matuzović, 'https://www.matuzo.at/blog/2023/single-page-applications-criticism[Why I\'m not the biggest fan of Single Page Applications]']
-The fact that the HTML document is something that you barely touch, because everything you need in there will be injected via JavaScript, puts the document and the page structure out of focus.
-
-In order to avoid `<div>` soup (or Markdown soup, or Component soup), you need to be aware of the markup you're producing and be able to change it.
-
-Some SPA frameworks, and some web components, make this more difficult by putting layers of abstraction between the code the developer writes and the generated markup.
-
-While these abstractions can allow developers to create richer UI or work faster,
-their pervasiveness means that developers can lose sight of the actual HTML (and JavaScript) being sent to clients.
-Without diligent testing, this leads to inaccessibility, poor SEO, and bloat.
-****
-

book/CH02_ComponentsOfAHypermediaSystem.adoc

@@ -796,10 +796,13 @@ working in web development, and building a hypermedia-oriented library to boot,
 special nature of HTML, hypermedia and the web!
 
 
-[.design-note]
-.HTML Note: <div> Soup
+[.html-note]
+.HTML Notes: <div> Soup
 ****
-The best-known kind of messy HTML is `<div>` soup. 
+The best-known kind of messy HTML is `<div>` soup.
+
+Advances in CSS and JavaScript technology have mostly obviated the need to add extraneous "wrapper" elements to out documents.
+However, while the number of elements can fall, the quality of usage does not necessatily improve.
 
 When developers fall back on the generic `<div>` and `<span>` elements instead of more meaningful tags,
 we either degrade the quality of our websites or create more work for ourselves -- probably both.
@@ -832,5 +835,15 @@ It's not obvious from the HTML source that this is a button,
 making the source harder to read and the absence of these attributes harder to spot.
 The source code of pages with div soup is difficult to edit and debug.
 
-To avoid div soup, learn the meaning of available tags and consider each another tool in your tool chest. (With the 113 elements currently defined in the spec, it's more of a tool shed).
+"`This is silly,`" you might be thinking.
+Who uses a div as a button?
+Ignoring the answer (more people than you'd think), not every UI pattern has a designated HTML element.
+We often need to compose elements and augment them with attributes.
+Do you know, off the top of your head, the best elements and attributes to use for...
+
+* A "command palette" menu?
+* A play-pause button?
+* A search field with a search button next to it? (Check the HTML spec -- there might be things on there you don't remember from before!)
+
+To avoid div soup, learn the meaning of available tags and consider each another tool in your tool chest. (With the 113 elements currently defined in the spec, it's more of a whole shed). 
 ****

book/CH03_BuildingASimpleWebApplication.adoc

@@ -864,12 +864,13 @@ that will let us improve our contact application _without_ abandoning the hyperm
 [.design-note]
 .HTML Note: Semantic HTML
 ****
+Telling people to "use semantic HTML" instead of "read the spec" has led to a lot of people guessing at the meaning of tags -- "`looks pretty semantic to me!" -- instead of engaging with the spec.
+
 [quote,https://t-ravis.com/post/doc/semantic_the_8_letter_s-word/]
 I think being asked to write _meaningful_ HTML better lights the path to realizing that it isn't about what the text means to humans--it's about using tags for the purpose outlined in the specs to meet the needs of software like browsers, assistive technologies, and search engines.
 
-Telling people to "use semantic HTML" instead of "read the spec" has led to a lot of people guessing at the meaning of tags -- "`looks pretty semantic to me!" -- instead of engaging with the spec.
-
 We recommend talking about, and writing, _conformant_ HTML.
+(We can always bikeshed further).
 Use the elements to the full extent provided by the HTML specification,
 and let the software take from it whatever meaning they can.
 ****

book/CH04_ExtendingHTMLAsHypermedia.adoc

@@ -894,11 +894,11 @@ them.
 
 
 [.design-note]
-.HTML Note: Caution with Improvised UI Elements
+.HTML Note: Don't Roll Your Own
 ****
 Accessibility problems can arise when we try to implement controls that aren't built into HTML.
 
-For example, what if you make something that looks like a set of tabs, but you use radio buttons and CSS hacks to build it? 
+For example, what if you make something that looks like a set of tabs, but you use radio buttons and CSS hacks to build it? It's a neat hack that makes the rounds in web development communities from time to time.
 
 The problem here is that tabs have requirements beyond clicking to change content.
 Your improvised tabs may be missing features that will lead to user confusion and frustration, as well as some undesirable behaviors.
@@ -927,8 +927,8 @@ but they are repetitive
 and others (like `aria-selected`) need to be set through JavaScript since they are dynamic.
 The keyboard interactions can be error-prone too.
 
-It's not impossible to make your own tab set implementation.
-However, it's difficult to trust that a new implementation will work in all environments, since most of us have limited access to testing devices.
+It's not impossible, not even that hard, to make your own tab set implementation.
+However, it's difficult to trust that a new implementation will work for all users in all environments, since most of us have limited resporces for testing.
 
-Stick with established libraries for UI interactions. If a use case requires an improvised solution, test carefully for keyboard interaction and accessibility.
+Stick with established libraries for UI interactions. If a use case requires a bespoke solution, test exhaustively for keyboard interaction and accessibility.
 ****

book/CH05_htmxPatterns.adoc

@@ -1033,9 +1033,9 @@ behavior, we are still exchanging hypermedia with the server, with no JSON API r
 
 As the web was designed.
 
-
+// TODO rewrite
 [.design-note]
-.Component Soup?
+.HTML Notes: Framework Soup
 ****
 Components encapsulate a section of a page along with its dynamic behavior.
 While encapsulating behavior is a good way to organize code,
@@ -1049,17 +1049,14 @@ Before you reach for components for reuse, consider your options.
 Lower-level mechanisms often (allow you to) produce better HTML.
 In some cases, components can actually _improve_ the clarity of your HTML.
 
-To decide if a component is appropriate for your use case, a good rule of thumb is to ask:
-"`Could this reasonably be a built-in HTML element?`"
-For example, a code editor is a good candidate,
-since HTML already has `<textarea>` and `contenteditable` elements.
-In addition, a fully-featured code editor will have many child elements that won't provide much information anyway.
-We can use features like
-link:https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM[Shadow DOM]
-to encapsulate these elementsfootnote:[
-Beware that Shadow DOM is a newer web platform feature that's still in development at the time of writing.
-In particular, there are some accessibility bugs that may occur when elements inside and outside the shadow root interact.].
-We can create a
-link:https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements[custom element],
-`<code-area>`, that we can drop into our page whenever we want.
-****
+[quote, Manuel Matuzović, 'https://www.matuzo.at/blog/2023/single-page-applications-criticism[Why I\'m not the biggest fan of Single Page Applications]']
+The fact that the HTML document is something that you barely touch, because everything you need in there will be injected via JavaScript, puts the document and the page structure out of focus.
+
+In order to avoid `<div>` soup (or Markdown soup, or Component soup), you need to be aware of the markup you're producing and be able to change it.
+
+Some SPA frameworks, and some web components, make this more difficult by putting layers of abstraction between the code the developer writes and the generated markup.
+
+While these abstractions can allow developers to create richer UI or work faster,
+their pervasiveness means that developers can lose sight of the actual HTML (and JavaScript) being sent to clients.
+Without diligent testing, this leads to inaccessibility, poor SEO, and bloat.
+****

book/CH06_MorehtmxPatterns.adoc

@@ -1171,7 +1171,7 @@ By using these elements, a page can make false promises, like `<article>` elemen
 The most authoritative resource for learning about HTML is the HTML specification.
 The current specification lives on link:https://html.spec.whatwg.org/multipage[].footnote:[
 The single-page version is too slow to load and render on most computers. 
-There's also a developers' edition at /dev, but I prefer the styling of the standard version.]
+There's also a developers' edition at /dev, but the standard version has nicer styling.]
 There's no need to rely on hearsay to keep up with developments in HTML.
 
 Section 4 features a list of all available elements,

book/CH07_ADynamicArchiveUIWithhtmx.adoc

@@ -663,4 +663,19 @@ you need to create a new tag,
 which means you can't have multiple behaviors on one element,
 and you isolate elements you add from elements already in the page,
 which is a problem if they need to have ARIA relationships.
+
+When should we use Web Components?
+A good rule of thumb is to ask yourself:
+"`Could this reasonably be a built-in HTML element?`"
+For example, a code editor is a good candidate,
+since HTML already has `<textarea>` and `contenteditable` elements.
+In addition, a fully-featured code editor will have many child elements that won't provide much information anyway.
+We can use features like
+link:https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM[Shadow DOM]
+to encapsulate these elementsfootnote:[
+Beware that Shadow DOM is a newer web platform feature that's still in development at the time of writing.
+In particular, there are some accessibility bugs that may occur when elements inside and outside the shadow root interact.].
+We can create a
+link:https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements[custom element],
+`<code-area>`, that we can drop into our page whenever we want.
 ****

book/CH08_TricksOfThehtmxMasters.adoc

@@ -732,7 +732,7 @@ Htmx is typically configured via a `meta` tag, found in the header of a page.  T
 an example:
 
 .An htmx configuration via `meta` tag
-[source, javascript]
+[source, html]
 ----
 <meta name="htmx-config" content='{"defaultSwapStyle":"outerHTML"}'>
 ----
@@ -741,10 +741,8 @@ In this case, we are overriding the default swap style from the usual `innerHTML
 if you find yourself using `outerHTML` more frequently than `innerHTML` and want to avoid having to explicitly set that
 swap value throughout your application.
 
-
-
 [.design-note]
-.HTML Notes: Know Your HTML Budget
+.HTML Notes: Budgeting For HTML
 ****
 The close relationship between content and markup means that
 good HTML is labor-intensive.

book/CH09_ScriptingInAHypermediaApplication.adoc

@@ -746,12 +746,15 @@ To get a flavor of AlpineJS, let's look at how to implement our counter example
 
 For the counter, the only state we need to keep track of is the current number, so let's declare a JavaScript object
 with one property, `count`, in an `x-data` attribute on the div for our counter:
+
 // TODO: check: removed class="counter" to avoid confusion
+
 .Counter with Alpine, line 1
 [source,html]
 ----
 <div x-data="{ count: 0 }">
----- 
+----
+
 This defines our state, that is, the data we are going to be using to drive dynamic updates to the DOM.  With the state
 declared like this, we can now use it _within_ the div element it is declared on.  Let's add an `output` element with
 an `x-text` attribute.