Edit, work toward sprinkle concept

book/CH03_EffectiveHtml.adoc

@@ -6,32 +6,47 @@ WARNING: test of key ideas as pullouts to be sprinkled throughout the book
 Many pieces of the chapter read like little gems; these might work well as pullouts.
 The following attempts to break the chapter into pieces for use throughout the book.
 This is just an option to consider.
+
+I we go this route, it would useful to index or add a ToC entry for 'HTML Topics'
+
+Note: I used [.design-note] to flag for formatting. 
+As far as I know, it means nothing to Asciidoc
 //// 
 
-// move to ch1, The Essence of HTML as a Hypermedia
+[.design-note]
-.What is HTML?
+.Why Effective HTML?
 ****
-[quote, Marshall McLuhan]
+Sprinkled throughout this book you will find tips and best practices for writing effective HTML.
-The medium is the message.
 
-Is it a document format?
+It's very easy (and sometimes acceptable) to produce mediocre HTML that _seems to_ work,
-Is it for applications?
+and many websites settle with _seeming to_ work.
-Is it a rendering system?
-Is it (gasp!) a programming language?
 
-[quote, Roy Fielding, https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-718]
+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.
-____
-When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions.
-____
 
-HTML, like all hypermedia, blurs the distinction between the information being accessed and the application used to access it. HTML is for documents, insofar as you're willing to adopt a broad definition of "`document`" -- and it is for applications, ones that are interwoven with the data they process.
+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. 
-
+// TODO: check last sentence here; pulled together from various paragraphs
-HTML is a hypermedium.
-
-An HTML file is not a program that produces a human-readable document.
-It _is_ the document.
 ****
 
+
+[.design-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.
+
+Hypermedia best practice no. 1: Stay aware of HTML markup you’re producing and be able to change it.
+****
+
+
+[.design-note]
 .Test, and Test Again
 ****
 Even good HTML is not a cure-all.
@@ -39,19 +54,12 @@ If you care about machine readability, or human readability, or page weight, the
 Test manually.
 Test automatically.
 Test with screenreaders, test with a keyboard, test on different browsers and hardware, run linters (while coding and/or in CI).
-****
 
-.Why Care About Effective HTML?
+So, let’s make that hypermedia best practice no. 1. Test.
-****
-It's very easy (and sometimes acceptable) to produce mediocre HTML that _seems to_ work,
-and many websites settle with _seeming to_ work.
-
-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.
-
-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.
 ****
 
 
+[.design-note]
 .<div> Soup
 ****
 The best-known kind of messy HTML is `<div>` soup. 
@@ -72,7 +80,7 @@ There are two main issues with this button:
 * It's not focusable -- the Tab key won't get you to it.
 * There's no way for assistive tools to tell that it's a button.
 
-We can fix that by adding `role="button"`` and `tabindex="0"`:
+Yes, we can fix that by adding `role="button"`` and `tabindex="0"`:
 
 [source,html]
 ----
@@ -88,8 +96,14 @@ making the source harder to read and the absence of these attributes harder to s
 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).
+
+So, let's call these hypermedia best practices no. 2 & 3: 
+2. Make the full tool shed of available tags your own. 
+3. Aim for good tag fit, where tag specs match your use case.
 ****
 
+
+[.design-note]
 .Markdown soup
 ****
 [.dfn]_Markdown soup_ is the lesser known sibling of `<div>` soup.
@@ -118,11 +132,16 @@ This could be achieved on an `<ol>` with CSS,
 but Markdown doesn't have a way to add a class to elements meaning the square brackets would apply to all ordered lists.
 ****
 
-.On Lists
+
+// maybe an info gem?
+[.design-note]
+.On Lists 
 ****
 We call `<ol>` and `<ul>` "ordered" and "unordered" lists. Both are actually ordered, however, and the difference is whether the place of a particular element is significant. For instance, instructions should usually be marked up with `<ol>` since it may contain references like "Repeat steps 3 to 5". If items in our  list are not referenced by number, we would use an `<ul>`.
 ****
 
+
+[.design-note]
 .Embedding HTML in Markdown
 ****
 Don't shy away from using embedded HTML in Markdown.
@@ -155,22 +174,8 @@ Available: <https://hypermedia.systems/>
 <2> A processor can also resolve identifiers, so we don't have to manually keep the reference list in order and the in-text citations in sync.
 ****
 
-.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.
-
-****
-
 
+[.design-note]
 .Component Soup?
 ****
 Components encapsulate a section of a page along with its dynamic behavior.
@@ -199,9 +204,12 @@ 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.
 
-Notice how these choices are _extending_ HTML, rather than abstracting it away.
+// TODO: maybe?
+There might be a hypermedia best practice here: Prefer components that extend HTML, rather than abstracting it away.
 ****
 
+
+// this might work best as a vanilla pullout
 .On Web Components
 ****
 Web Components is the collective name of a few standards;
@@ -231,6 +239,8 @@ and you isolate elements you add from elements already in the page,
 which is a problem if they need to have ARIA relationships.
 ****
 
+
+
 .HTML5 Soup
 ****
 Elements like `<section>`, `<article>`, `<nav>`, `<header>`, `<footer>`, `<figure>` have become a sort of shorthand for HTML.
@@ -240,6 +250,8 @@ By using these elements, a page can make false promises, like `<article>` elemen
 * Make sure that the element you're using fits your use case. Check the HTML spec.
 * Don't try to be specific when you can't or don't need to.
   Sometimes, `<div>` is fine.
+
+This might be best practice no. 5: If more specific tags don’t fit, <div> may suit.  
 ****
 
 .Keep the Spec on Hand
@@ -256,6 +268,8 @@ There's no need to rely on hearsay to keep up with developments in HTML.
 Section 4 features a list of all available elements,
 including what they represent, where they can occur, and what they are allowed to contain.
 It even tells you when you're allowed to leave out closing tags!
+
+Best practice: keep the HTML spec on hand.
 ****
 
 .Know Your HTML Budget
@@ -275,8 +289,12 @@ Thus, we don't expect every site to contain perfectly conformant HTML.
 What's most important is to avoid _wrong_ HTML -- it can be better to fall back on a more generic element than to be precisely incorrect.
 
 If you have the resources, however, putting more care in your HTML will produce a more polished site.
+
+Let’s call that best practice no. 6: A generic loose fit is better than a specific incorrect fit.
 ****
 
+
+// TODO: format as pullout, like Web Components, ARIA
 .The "`Semantic Web`"
 ****
 [quote, '_Mean Girls_ (2004)']
@@ -301,6 +319,7 @@ and for most use cases, you might as well define a JSON API.
 _The Semantic Web has nothing to do with semantic HTML_.
 ****
 
+
 .Semantic HTML
 ****
 [quote,https://t-ravis.com/post/doc/semantic_the_8_letter_s-word/]
@@ -313,6 +332,8 @@ Use the elements to the full extent provided by the HTML specification,
 and let the software take from it whatever meaning they can.
 ****
 
+
+[.design-note]
 .Caution: Improvised UI Elements
 ****
 Accessibility problems can arise when we try to implement controls that aren't built into HTML.
@@ -349,10 +370,46 @@ 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.
 
-// meaning, we recommend?
+Hence, hypermedia best practice no. 7: Stick with established libraries for UI interactions. If a use case requires an improvised solution, test carefully for keyboard interaction and accessibility.
-Use established libraries for UI interactions unless a unique use case compels you to roll your own.
 ****
 
+
+// TODO: check. Does this list accurately condense the work of ch.3?
+[.design-note]
+.Best Practices for Effective HTML
+****
+1. Stay close to the HTML markup you’re producing and be able to change it.
+2. Make the full tool shed of available tags your own; keep the HTML spec on hand. 
+3. Aim for good tag fit, where tag specs match your use case.
+4. If more specific tags don’t fit, <div> may suit. A generic loose fit is better than a specific incorrect fit. 
+5. Stick with established libraries for UI interactions. If a use case requires an improvised solution, test carefully for keyboard interaction and accessibility.
+6. Prefer components that extend HTML, rather than abstracting it away.
+7. Test, and test with screenreaders, with a keyboard, with different browsers and hardware.
+****
+
+
+[.design-note]
+.Resources for Effective HTML
+****
+Some resources we recommend:
+
+* Foundations
+* HTML specification: https://html.spec.whatwg.org/multipage
+
+* TODO link resources on alt text.
+
+* https://htmhell.dev: Along with sinister abuses of HTML, this website shares development tips that will help ypu keep up-to-date with best practice.
+
+* Referenced
+
+** Manuel Matuzović, [.cite]_Lost in Translation_, https://www.youtube.com/watch?v=Wno1IhEBTxc.
+
+** Manuel Matuzović, [.cite]_Why I'm not the biggest fan of Single Page Applications_, https://www.matuzo.at/blog/2023/single-page-applications-criticism/
+
+** [.cite]_semantic: the 8 letter s-word_, https://t-ravis.com/post/doc/semantic_the_8_letter_s-word/
+****
+
+// TODO: format as info gem
 .About Display: none
 ****
 `display: none;` in CSS is not purely cosmetic -- it removes elements from the accessibility tree and keyboard focus. If you want to hide an element visually without hiding it from assistive technology, you can use this utility class:
@@ -372,6 +429,8 @@ Use established libraries for UI interactions unless a unique use case compels y
 `vh` is short for "`visually hidden.`" This class uses multiple methods and workarounds to make sure no browser removes the element's function.
 ****
 
+
+// TODO: format as info gem
 .Remember <details>
 ****
 Does the information need to be presented as tabs?
@@ -391,6 +450,8 @@ Compromising UX just to avoid JavaScript is bad development.
 But sometimes it's possible to achieve an equal (or better!) quality of UX while allowing for a simpler and more robust implementation.
 ****
 
+
+// TODO: Nice writing here. Some readers may want more specific advice: what does it mean to write HTML for humans? 
 .Screen Reader Rage
 ****
 The spec is a good starting point when deciding how to mark something up,
@@ -412,7 +473,7 @@ HTML is for humans.
 ****
 
 
-// maybe: discuss data options at top of Data API chapter
+// maybe: discuss data options as part of Data API chapter
 // or, cut if you don't recommend using
 .Microformats
 ****
@@ -465,23 +526,28 @@ Your human-facing and machine-facing interfaces may end up being limited by each
 It's often the best option to define a JSON data API separate from your HTML.
 ****
 
-// move to end, ch1 or 2
+
-.HTML Resources
+
+// maybe move to ch1, The Essence of HTML as a Hypermedia
+.What is HTML?
 ****
-Some resources we recommend:
+[quote, Marshall McLuhan]
+The medium is the message.
 
-* Foundations
+Is it a document format?
-* HTML specification: https://html.spec.whatwg.org/multipage
+Is it for applications?
+Is it a rendering system?
+Is it (gasp!) a programming language?
 
-* TODO link resources on alt text.
+[quote, Roy Fielding, https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-718]
+____
+When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions.
+____
 
-* https://htmhell.dev: Along with sinister abuses of HTML, this website shares development tips that will help ypu keep up-to-date with best practice.
+HTML, like all hypermedia, blurs the distinction between the information being accessed and the application used to access it. HTML is for documents, insofar as you're willing to adopt a broad definition of "`document`" -- and it is for applications, ones that are interwoven with the data they process.
 
-* Referenced
+HTML is a hypermedium.
 
-** Manuel Matuzović, [.cite]_Lost in Translation_, https://www.youtube.com/watch?v=Wno1IhEBTxc.
+An HTML file is not a program that produces a human-readable document.
-
+It _is_ the document.
-** Manuel Matuzović, [.cite]_Why I'm not the biggest fan of Single Page Applications_, https://www.matuzo.at/blog/2023/single-page-applications-criticism/
-
-** [.cite]_semantic: the 8 letter s-word_, https://t-ravis.com/post/doc/semantic_the_8_letter_s-word/
 ****