From d54f5bc6d078f22d2b54ac1461c1309485fa0573 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Thu, 6 Apr 2023 16:41:05 -0400
Subject: [PATCH 01/18] Edits, aim to emphasize key points, ital vs bold

---
 book/CH03_EffectiveHtml.adoc | 72 ++++++++++++++++++------------------
 1 file changed, 37 insertions(+), 35 deletions(-)

diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index 927fe62..c3d907f 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/book/CH03_EffectiveHtml.adoc
@@ -9,8 +9,7 @@ WARNING: This chapter is a work in progress.
 The medium is the message.
 
 If you're here, you can probably write some HTML.
-The web is the #1 hypermedia system after all, the one this book will spend the most time with,
-and HTML is its format.
+The web is the #1 hypermedia system after all, and HTML is its format.
 
 As with every aspect of the web, it has been exapted and reinterpreted by web developers in myriad ways.
 Is it a document format?
@@ -33,31 +32,31 @@ An HTML file is not a program that produces a human-readable document.
 It _is_ the document.
 
 Unfortunately, HTML's development in terms of hypermedia controls has stagnated
-and what little there is often not put to full use.
+and, what little there is, is often not put to full use.
 
-This chapter looks at HTML as something worth studying in its own right, even in this day and age.
+This chapter looks at HTML as something worth studying in its own right.
 It covers our best practices for writing/generating HTML,
 and why HTML is something far cooler than a programming language.
-It won't be an HTML tutorial, as that would take a whole other book, but it can accompany you in your HTML re-learning journey.
+It won't be an HTML tutorial, but it can accompany you in your HTML re-learning journey.
 
 
-== Why relearn HTML?
+== Why Relearn HTML?
 
 Have you noticed that a lot of websites are bad?
 
- - Pages are bloated with `<div>` soup, and stylesheets are big as a result of trying to select elements in that mess. The result is slow loading times.footnote:[https://almanac.httparchive.org/en/2020/markup] Other than `<div>` being the most common element, the HTTP Archive Web Almanac found that 0.06% of pages surveyed in 2020 contained the nonexistent `<h7>` element. 0.0015% used `<h8>`.
+ - Pages are bloated with `<div>` soup, and stylesheets are big as a result of trying to select elements in that mess. The result is slow loading times.footnote:[https://almanac.httparchive.org/en/2020/markup] 
  - So-called MVPs (minimum viable product) are released in open beta while being completely unusable by vast swathes of people -- UX not just buggy, but nonexistent.footnote:[https://adrianroselli.com/2022/11/accessibility-gaps-in-mvps.html] Is an inaccessible product "`viable`"?
  - Websites, including websites containing public data or results of publicly-funded research, are impossible to scrape programmatically.
  - Search engines have a hard time extracting useful information from a page, and rank that page lower as a result. 
 
-In the rest of the chapter, we'll look at these issues in more detail and see how effective HTML can help us develop better websites.
-However, we should first note that HTML is not a panacea.
-If you care about machine readability, or human readability, or page weight, the most important thing to do is **testing**.
+We'll look at these issues in more detail and see how effective HTML can help us develop better websites.
+However, we should first note that even good HTML is not a panacea.
+If you care about machine readability, or human readability, or page weight, the most important thing to do is _testing_.
 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).
 
-So where does HTML and the s-word come in?
+So why concern ourselves with effective html?
 
 Easy. 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.
 
@@ -71,7 +70,7 @@ and many websites settle with _seeming to_ work.
 But better websites are possible, and anyone can learn HTML to the level of making websites that _actually_ work.
 
 
-== `<div>` soup
+== <div> Soup
 
 While programming code is described as spaghetti when it's not well organized,
 the food of choice for messy markup is soupfootnote:[hence BeautifulSoup, the web scraping library.].
@@ -97,7 +96,7 @@ There could be a few reasons:
 
  * *Styling.* The `<button>` element might have been harder to style.
  * *Confusion.* The button might have some other interactive features, which could lead to the developer not realizing it was a button.
- * *Apathy.* The developer doesn't care, and uses `<div>` except when he has to.
+ * *Apathy.* The developer doesn't care, and uses `<div>` except when they have to.
 
 It's absolutely possible to implement this button, and indeed most kinds of UI, using nothing but `<div>`.
 However, it makes the job harder.
@@ -127,6 +126,7 @@ Furthermore, even if you always remember to add the correct attributes and JavaS
 you've made your HTML less readable for little reason.
 The source code of pages with div soup is difficult to edit and debug.
 
+// maybe: point to an example from contact.app code. e.g., progress bar
 We often _don't_ remember to look out for these types of UX and accessibility bugs.
 [.dfn]_F5-Driven Development_ is the way most of us write HTML:
 write something, _Alt-Tab_ to the browser to see if it works, and go back to edit.
@@ -136,12 +136,12 @@ developers are biased towards their own UI needs,
 and users (who might use websites differently) become an afterthought.
 However, if we use HTML effectively, we can catch many of these issues before they ever occur, even before testing.
 
-Given all this, why are so many developers writing div soup?
-There is a tendency to understate the sophistication of HTML.
+So why are so many developers writing div soup?
+There is a tendency to overlook the sophistication of HTML. 
 
-Instead, learn the meaning of every tag 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).
+Instead, learn the meaning of every tag 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).
 
+// check: add Markdown Soup heading?
 [.dfn]_Markdown soup_ is the lesser known sibling of `<div>` soup.
 This is the result of web developers limiting themselves to the set of elements that the Markdown language provides shorthand for,
 even when these elements are incorrect.
@@ -202,7 +202,7 @@ 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.
 
 
-=== Remedy: Stay close to the output
+=== Remedy: 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.
@@ -216,7 +216,7 @@ While these abstractions can allow developers to create richer UI or work faster
 their pervasiveness means that they can lose sight of the actual HTML (and JavaScript) being sent to clients.
 Without diligent testing, this leads to inaccessibility, poor SEO, and bloat.
 
-For example, a popular concept found in many frameworks is *components*.
+For example, a popular concept found in many frameworks is _components_.
 Components encapsulate a section of a page along with its dynamic behavior.
 While encapsulating behavior is a good way to organize code,
 they also separate elements from their surrounding context,
@@ -278,7 +278,7 @@ 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
+== HTML5 Soup
 
 "`Yeah! Down with `<div>`! It's time to use the full power of *HTML5!*`"
 
@@ -326,7 +326,7 @@ To avoid this:
   Sometimes, `<div>` is fine.
 
 
-=== Keep the spec on hand
+=== Keep the Spec on Hand
 
 [quote,Confucius]
 The beginning of wisdom is to call things by their right names.
@@ -358,7 +358,7 @@ Reading it through (skipping over the implementation details, like the several p
 will give you a sense of how HTML is intended to be written.
 
 
-=== Remedy: Know your budget
+=== Remedy: Know Your Budget
 
 The close relationship between the content and the markup means that
 good HTML is actually quite labor-intensive, often across a whole organization.
@@ -379,7 +379,8 @@ Much like style guides, well-written HTML gives an air of quality and prestige t
 When it comes to HTML, you get what you pay for.
 
 
-== The S word
+// check: more useful table of contents
+== "`Semantic`" HTML
 
 [quote, '_Mean Girls_ (2004)']
 Gretchen, stop trying to make fetch happen! It's not going to happen!
@@ -419,7 +420,7 @@ A flexible format -- not an infinity of namespaces with URLs pointing to nothing
 ***
 
 This is a necessarily reductive explanation of the Semantic Web, a field that we've described in past tense even though it continues to have some practical use.
-The reason it doesn't matter to us is because *the Semantic Web has nothing to do with semantic HTML.*
+The reason it doesn't matter to us is because _the Semantic Web has nothing to do with semantic HTML_.
 
 Semantic HTML has no ambitions of robotic agents navigating information and helping us make connections and discoveries.
 It's actually quite mundane: _don't break the web._
@@ -430,23 +431,22 @@ I think being asked to write _meaningful_ HTML better lights the path to realizi
 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.
 
 I think even "`meaningful`" is too lofty.
-Instead, I recommend talking about, and writing, **conformant** HTML.
+Instead, I recommend talking about, and writing, _conformant_ HTML.
 Use the elements to the full extent provided by the HTML specification,
 and let the software take from it whatever meaning they can.
 
 Speaking of assistive technologies, by the way...
 
 
-== The A word
+== The "`Accessible`" Web
 
-Throughout this chapter, we've gestured at potential accessibility benefits to be had from effective HTML.
+We've gestured at potential accessibility benefits to be had from effective HTML.
 
 [quote, Manuel Matuzović, 'https://alistapart.com/article/my-accessibility-journey-what-ive-learned-so-far/[My Accessibility Journey: What I’ve Learned So Far]']
 (Re)learning HTML and using it consciously prevents and fixes many accessibility issues.
 
 It's true that all else being equal, an app that makes full use of HTML will be more accessible than one that is made of soup.
-However, HTML is not a panacea.
-Even the adage that HTML is "`accessible by default`" is a bit misleading.
+However, even the adage that HTML is "`accessible by default`" is a bit misleading.
 
 If you use simple HTML strictly as recommended by the spec, you are unlikely to run into accessibility bugs (though it does happen, because this is web development).
 Problems often arise when we try to implement controls that aren't built into HTML.
@@ -525,7 +525,7 @@ From the link:https://www.w3.org/WAI/ARIA/apg/patterns/tabs/[ARIA Authoring Prac
 }
 ----
 
-`vh` is short for "`visually hidden.`"This class uses multiple methods and workarounds to make sure no browser removes the element's function.
+`vh` is short for "`visually hidden.`" This class uses multiple methods and workarounds to make sure no browser removes the element's function.
 ****
 
 It turns out that fulfilling all of these requirements takes a lot of code. 
@@ -559,7 +559,7 @@ It might be possible to achieve an equal (or better!) quality of UX while allowi
 But when it's not, we shouldn't try to stuff every problem into an HTML box.
 
 
-=== Screen reader rage
+=== Screen Reader Rage
 
 The purpose of writing good HTML is not to please the specification deities.
 It's to make good websites.
@@ -573,7 +573,7 @@ After all, browser implementers do a _lot_ of work to deal with developers' brok
 
 It is of course frustrating when browsers and other tools misbehave.
 Accessibility itself feels inaccessible sometimes.
-It helps with the frustration is to recognize that hypermedia exchanges are not machine-to-machine communication.
+To reduce the frustration it may help to recognize that hypermedia exchanges are not machine-to-machine communication.
 An HTML file is not a program that produces a human-readable document.
 It _is_ the document.
 So, instead of banging your head against a wall, focus on people, not the tools they use.
@@ -693,16 +693,18 @@ This can be parsed into a JSON-like structure, as follows:
 }
 ----
 
+//maybe: try to suggest a rule of thumb for when to use a microformat,
+// versus creating a json api.
+// Would this be helpful for contact.app?
 In this example, Microformats and the extensibility of HTML proved quite useful.
 However, embedding data in HTML is hardly appropriate for every use case.
 Your human-facing and machine-facing interfaces may end up being limited by each other.
 It's often the best option to define a JSON data API separate from your HTML, which will be discussed later in this book.
 
 
-== Where to next
+== Where To Next
 
-Unfortunately, a full HTML tutorial is way out of scope for one chapter of this book.
-Here are some resources you can check out if you'd like to invest in your HTML knowledge:
+We've touched on some of the main challenges of writing good HTML. To continue to invest in your HTML knowledge, here are some resources we recommend:
 
 * Foundations
 * HTML specification: https://html.spec.whatwg.org/multipage

From e8c1817f7aa43db741dee62fdaf2de6068cd3388 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Thu, 6 Apr 2023 16:47:18 -0400
Subject: [PATCH 02/18] update, ch13

---
 book/CH13_BuildingAContactsAppWithHyperview.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/book/CH13_BuildingAContactsAppWithHyperview.adoc b/book/CH13_BuildingAContactsAppWithHyperview.adoc
index 451adac..92dc400 100644
--- a/book/CH13_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH13_BuildingAContactsAppWithHyperview.adoc
@@ -283,7 +283,7 @@ As you can see, this helper function uses `render_template()` under the hood.
 `render_template()` returns a string.
 This helper function uses that string to create an explicit `Response` object.
 The response object has a `headers` attribute, allowing us to set and change the response headers.
-Specifically, `render_to_response()` sets `Content-Type` to `application/xml` so that the Hyperview client recognizes the content.
+Specifically, `render_to_response()` sets `Content-Type` to `application/vnd.hyperview+xml` so that the Hyperview client recognizes the content.
 This helper is a drop-in replacement for `render_template` in our views.
 So all we need to do is update the last line of the `contacts()` function.
 

From 17422f26f7201df2a80cf7ca236bb0988935e7ec Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Thu, 6 Apr 2023 16:54:23 -0400
Subject: [PATCH 03/18] add comment

---
 book/CH03_EffectiveHtml.adoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index c3d907f..ee85b21 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/book/CH03_EffectiveHtml.adoc
@@ -704,6 +704,7 @@ It's often the best option to define a JSON data API separate from your HTML, wh
 
 == Where To Next
 
+//maybe: summarize key points or best practices
 We've touched on some of the main challenges of writing good HTML. To continue to invest in your HTML knowledge, here are some resources we recommend:
 
 * Foundations

From 27f2eb61f22470450758feabbd38b05ba0ec1ff9 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Tue, 11 Apr 2023 12:52:38 -0400
Subject: [PATCH 04/18] caution: test of chapter convert to pullouts

---
 book/CH03_EffectiveHtml.adoc | 518 ++++++++++-------------------------
 1 file changed, 141 insertions(+), 377 deletions(-)

diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index ee85b21..c5f7ec0 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/book/CH03_EffectiveHtml.adoc
@@ -1,23 +1,23 @@
 
-= Effective HTML
-:chapter: 03
-:url: ./effective-html/
+= Effective HTML - Pullouts
 
-WARNING: This chapter is a work in progress.
+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.
+//// 
 
+// move to ch1, The Essence of HTML as a Hypermedia
+.What is HTML?
+****
 [quote, Marshall McLuhan]
 The medium is the message.
 
-If you're here, you can probably write some HTML.
-The web is the #1 hypermedia system after all, and HTML is its format.
-
-As with every aspect of the web, it has been exapted and reinterpreted by web developers in myriad ways.
 Is it a document format?
 Is it for applications?
 Is it a rendering system?
 Is it (gasp!) a programming language?
-These are the contenders in the Eternal Debate of the web development world,
-and none will ever win because none of them are right.
 
 [quote, Roy Fielding, https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-718]
 ____
@@ -30,56 +30,32 @@ HTML is a hypermedium.
 
 An HTML file is not a program that produces a human-readable document.
 It _is_ the document.
+****
 
-Unfortunately, HTML's development in terms of hypermedia controls has stagnated
-and, what little there is, is often not put to full use.
-
-This chapter looks at HTML as something worth studying in its own right.
-It covers our best practices for writing/generating HTML,
-and why HTML is something far cooler than a programming language.
-It won't be an HTML tutorial, but it can accompany you in your HTML re-learning journey.
-
-
-== Why Relearn HTML?
-
-Have you noticed that a lot of websites are bad?
-
- - Pages are bloated with `<div>` soup, and stylesheets are big as a result of trying to select elements in that mess. The result is slow loading times.footnote:[https://almanac.httparchive.org/en/2020/markup] 
- - So-called MVPs (minimum viable product) are released in open beta while being completely unusable by vast swathes of people -- UX not just buggy, but nonexistent.footnote:[https://adrianroselli.com/2022/11/accessibility-gaps-in-mvps.html] Is an inaccessible product "`viable`"?
- - Websites, including websites containing public data or results of publicly-funded research, are impossible to scrape programmatically.
- - Search engines have a hard time extracting useful information from a page, and rank that page lower as a result. 
-
-We'll look at these issues in more detail and see how effective HTML can help us develop better websites.
-However, we should first note that even good HTML is not a panacea.
+.Test, and Test Again
+****
+Even good HTML is not a cure-all.
 If you care about machine readability, or human readability, or page weight, the most important thing to do is _testing_.
 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).
+****
 
-So why concern ourselves with effective html?
-
-Easy. 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.
-
-Knowing HTML well might not absolve you from doing your job, but it makes it a lot easier.
-
-"`But I already know HTML well.`"
-Maybe you do.
-But many people underestimate how sophisticated HTML is.
-Indeed, it's very easy (and sometimes acceptable) to produce mediocre HTML that _seems to_ work,
+.Why Care About Effective HTML?
+****
+It's very easy (and sometimes acceptable) to produce mediocre HTML that _seems to_ work,
 and many websites settle with _seeming to_ work.
-But better websites are possible, and anyone can learn HTML to the level of making websites that _actually_ 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.
+****
 
 
-== <div> Soup
+.<div> Soup
+****
+The best-known kind of messy HTML is `<div>` soup. 
 
-While programming code is described as spaghetti when it's not well organized,
-the food of choice for messy markup is soupfootnote:[hence BeautifulSoup, the web scraping library.].
-
-HTML can turn into soup in a variety of ways,
-usually due to a disregard for or misunderstanding of best practice
-or due to an excess of layers between the developer and the HTML.
-
-The best-known kind of messy HTML is `<div>` soup.
 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.
 
@@ -91,57 +67,31 @@ a `<div>` element might have a `click` event listener added to it.
 <div class="bg-accent padding-4 rounded-2" onclick="doStuff()">Do stuff</div>
 ----
 
-Why might a developer do this, when the `<button>` element is right there?
-There could be a few reasons:
-
- * *Styling.* The `<button>` element might have been harder to style.
- * *Confusion.* The button might have some other interactive features, which could lead to the developer not realizing it was a button.
- * *Apathy.* The developer doesn't care, and uses `<div>` except when they have to.
-
-It's absolutely possible to implement this button, and indeed most kinds of UI, using nothing but `<div>`.
-However, it makes the job harder.
-
 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.
 
-Let's fix that:
+We can fix that by adding `role="button"`` and `tabindex="0"`:
 
 [source,html]
 ----
 <div class="bg-accent padding-4 rounded-2"
-  role="button" <1>
-  tabindex="0" <2>
+  role="button" 
+  tabindex="0" 
   onclick="doStuff()">Do stuff</div>
 ----
-<1> Expose this element as a button.
-<2> Make this element focusable.
 
-Of course, these are both easy fixes but they're things you have to _remember_.
+These are easy fixes, but they're things you have to _remember_.
 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.
-Furthermore, even if you always remember to add the correct attributes and JavaScript
--- and yes, if you're making almost anything more complex than a button, you will need a lot of JavaScript --
-you've made your HTML less readable for little reason.
 The source code of pages with div soup is difficult to edit and debug.
 
-// maybe: point to an example from contact.app code. e.g., progress bar
-We often _don't_ remember to look out for these types of UX and accessibility bugs.
-[.dfn]_F5-Driven Development_ is the way most of us write HTML:
-write something, _Alt-Tab_ to the browser to see if it works, and go back to edit.
-It's a fast and enjoyable way to build things,
-but it means that during most of development,
-developers are biased towards their own UI needs,
-and users (who might use websites differently) become an afterthought.
-However, if we use HTML effectively, we can catch many of these issues before they ever occur, even before testing.
+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 why are so many developers writing div soup?
-There is a tendency to overlook the sophistication of HTML. 
-
-Instead, learn the meaning of every tag 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).
-
-// check: add Markdown Soup heading?
+.Markdown soup
+****
 [.dfn]_Markdown soup_ is the lesser known sibling of `<div>` soup.
 This is the result of web developers limiting themselves to the set of elements that the Markdown language provides shorthand for,
 even when these elements are incorrect.
@@ -166,12 +116,15 @@ Why could this be?
 The IEEE citation style requires that these numbers are presented in square brackets.
 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.
-
-[.info]
-****
-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 we were using a style like APA in our reference list, where citations are not referenced by number, we would use an `<ul>`.
 ****
 
+.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>`.
+****
+
+.Embedding HTML in Markdown
+****
 Don't shy away from using embedded HTML in Markdown.
 For larger sites, also consider Markdown extensions.
 
@@ -200,40 +153,38 @@ Available: <https://hypermedia.systems/>
 ----
 <1> `reference_list` is a macro that will transform the plain text to highly-detailed HTML.
 <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.
+****
 
-
-=== Remedy: Stay Close to the Output
-
+.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 similar), you need to constantly be aware what kind of markup you're producing and be able to change it.
+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.
 
-Web frameworks, particularly SPA frameworksfootnote:[
-This also applies to frameworks like Next and Remix that use SPA technologies like React to render static HTML.],
-can have a tall tower 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 they can lose sight of the actual HTML (and JavaScript) being sent to clients.
+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.
 
-For example, a popular concept found in many frameworks is _components_.
+****
+
+
+.Component Soup?
+****
 Components encapsulate a section of a page along with its dynamic behavior.
 While encapsulating behavior is a good way to organize code,
-they also separate elements from their surrounding context,
+it can also separate elements from their surrounding context,
 which can lead to wrong or inadequate relationships between elements.
 The result is what one might call [.dfn]_component soup_,
 where information is hidden in component state,
 rather than being present in the HTML, which is now incomprehensible due to missing context.
-In our Client Side Scripting chapter, we'll look at alternatives to component-based frameworks that can be used to avoid these shortcomings.
 
-To be abundantly clear, components aren't the cause of all div soup.
-Not even most of it.
-The root cause is the fact that HTML is falsely believed to be very simple,
-and as a result, developers and organizations don't invest in learning and applying HTML skills.
-However, don't reach for components for reuse without considering other options.
-Lower-level mechanisms usually (allow you to) produce better HTML.
+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.
 
-Components, when used well, 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,
@@ -247,9 +198,11 @@ In particular, there are some accessibility bugs that may occur when elements in
 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.
-See how we're _extending_ HTML, rather than abstracting it away.
 
-.Web Components
+Notice how these choices are _extending_ HTML, rather than abstracting it away.
+****
+
+.On Web Components
 ****
 Web Components is the collective name of a few standards;
 Custom Elements and Shadow DOM, and `<template>` and `<slot>`.
@@ -259,9 +212,9 @@ All of these standards bring useful capabilities to the table.
 Custom Elements let us initialize and tear down behaviors when elements are added or removed, which would previously require manual work or MutationObservers.
 Shadow DOM lets us encapsulate elements, leaving the "light" (non-shadow) DOM clean.
 
-However, trying to actually reap these benefits is often frustrating.
-Some of these are simply growing pains of new standards
-(like the many accessibility problems of Shadow DOM)
+However, trying to reap these benefits is often frustrating.
+Some difficulties are simply growing pains of new standards
+(like the accessibility problems of Shadow DOM)
 that are actively being worked on.
 Others are the result of Web Components trying to be too many things at the same time:
 
@@ -278,60 +231,23 @@ 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
-
-"`Yeah! Down with `<div>`! It's time to use the full power of *HTML5!*`"
-
-Be careful.
-
+.HTML5 Soup
+****
 Elements like `<section>`, `<article>`, `<nav>`, `<header>`, `<footer>`, `<figure>` have become a sort of shorthand for HTML.
-Developers may sprinkle them generously and haphazardly over `<div>` soup.
-This is not an improvement, and can in fact make a website worse.
-By using these elements, a page makes false promises, like `<article>` elements being self-contained, reusable entities, to clients like browsers, search engines and scrapers that can't know better.
 
-.HTMHell, [.cite]##10 <section> is no replacement for <div>#, https://www.htmhell.dev/10-section-is-no-replacement-for-div/
-[source,html]
-----
-<section id="page-top">
-  <section data-section-id="page-top" style="display: none;"></section>
-</section>
-<main>
-  <section id="main-content">
-    <header id="main-header">
-      <h1>...</h1>
-      <section class="container-fluid">
-        <section class="row">
-          <article class="content col-sm-12">
-            <section class="content-inner">
-              <div class="content__body">
-                <article class="slider">
-                  <section class="slide"> … </section>
-                </article>
-              </div>
-            </section>
-          </article>
-        </section>
-      </section>
-    </header>
-  </section>
-</main>
-----
+By using these elements, a page can make false promises, like `<article>` elements being self-contained, reusable entities, to clients like browsers, search engines and scrapers that can't know better. To avoid this:
 
-Most HTML isn't this much of a mess,
-but it's far too common for `<section>` and `<article>` to be used as a drop-in replacement `<div>` instead of adding useful information.
-To avoid this:
-
-* Check the HTML spec. Make sure that the element you're using fits your use case.
+* 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.
+****
 
-
-=== Keep the Spec on Hand
-
+.Keep the Spec on Hand
+****
 [quote,Confucius]
 The beginning of wisdom is to call things by their right names.
 
-The most authoritative (though not necessarily best) resource for learning about HTML is the HTML specification.
+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.]
@@ -340,55 +256,32 @@ 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!
-
-[source,html]
-----
-<!doctype html>
-<html lang=en>
-This is a valid HTML document.
-----
-
-[.info]
-****
-The `<html>` tag can also be omitted (since it's obvious that an HTML document with an HTML doctype is HTML) but it's bad practice to leave out the opening tag since it holds the `lang` attribute which specifies the natural language of the document.
 ****
 
-Section 4 in particular is a great piece of reference material and an useful read in general.
-Reading it through (skipping over the implementation details, like the several pages of algorithms)
-will give you a sense of how HTML is intended to be written.
-
-
-=== Remedy: Know Your Budget
-
-The close relationship between the content and the markup means that
-good HTML is actually quite labor-intensive, often across a whole organization.
+.Know Your HTML Budget
+****
+The close relationship between content and markup means that
+good HTML is labor-intensive.
 Most sites have a separation between the authors,
-who are rarely familiar with HTML and _very_ rarely want to think about it,
+who are rarely familiar with HTML,
 and the developers, who need to develop a generic system able to handle any content that's thrown at it --
 this separation usually taking the form of a CMS.
 As a result, having markup tailored to content, which is often necessary for advanced HTML, is rarely feasible.
-Furthermore, for internationalized sites, content in different languages being injected into the same elements can degrade markup quality as stylistic conventions differ between languages.
-Dishearteningly, but understandably, it's an expense few organizations can spare.
 
-Thus, we don't demand that every site contains the most conformant HTML it can.
+Furthermore, for internationalized sites, content in different languages being injected into the same elements can degrade markup quality as stylistic conventions differ between languages.
+It's an expense few organizations can spare.
+
+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.
-The kinds of defects caused by _inadequate_ HTML can usually be caught through testing.
 
 If you have the resources, however, putting more care in your HTML will produce a more polished site.
-Much like style guides, well-written HTML gives an air of quality and prestige to a document, even if few notice it.
-When it comes to HTML, you get what you pay for.
-
-
-// check: more useful table of contents
-== "`Semantic`" HTML
+****
 
+.The "`Semantic Web`"
+****
 [quote, '_Mean Girls_ (2004)']
 Gretchen, stop trying to make fetch happen! It's not going to happen!
 
-You might have noticed how we've avoided the use of the word "`semantic`" so far, partly because many people associate it with annoying pedantic colleagues (couldn't be us!), and partly because it has multiple meanings, only one of which we care about.
-
-We're not really about the "`Semantic Web`".
-
 The "Semantic Web" was a vision of a system that could both express any kind of human knowledge, and be useful for computing.
 It planned to achieve this using _ontologies_, repositories of schemas like "person", "movie" and "species" and relations like "named", "part of" and "created by".
 
@@ -405,111 +298,62 @@ and clients are hardcoded to support a fixed set of schemas.
 The requirement for prior agreement between server and client means this technology does not have the generality of the Web,
 and for most use cases, you might as well define a JSON API.
 
-Instead of extensibility through custom namespaces,
-HTML is extensible through its flexibility --
-both its tolerance for errors and its well-defined extension points like classes and `data-` attributes.
-These affordances let us embed metadata in it without native support.
-They all have the possibility of name collisions,
-but fragility and messiness is ultimately unavoidable for a generalized human information exchange language.
-Tag and attribute names in such a language are not _identifiers_ for behavior -- like function names in a programing language -- but _words_ with well-understood meanings.
-No amount of namespacing can make fetch happen,
-and developers should be able to deal with that.
-Embrace the mess and let go of your schemas.
-A flexible format -- not an infinity of namespaces with URLs pointing to nothing -- is "`software design on the scale of decades`".
-
-***
-
-This is a necessarily reductive explanation of the Semantic Web, a field that we've described in past tense even though it continues to have some practical use.
-The reason it doesn't matter to us is because _the Semantic Web has nothing to do with semantic HTML_.
-
-Semantic HTML has no ambitions of robotic agents navigating information and helping us make connections and discoveries.
-It's actually quite mundane: _don't break the web._
+_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/]
 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.
 
-I think even "`meaningful`" is too lofty.
-Instead, I recommend talking about, and writing, _conformant_ HTML.
+We recommend talking about, and writing, _conformant_ HTML.
 Use the elements to the full extent provided by the HTML specification,
 and let the software take from it whatever meaning they can.
+****
 
-Speaking of assistive technologies, by the way...
+.Caution: Improvised UI Elements
+****
+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? 
 
-== The "`Accessible`" Web
-
-We've gestured at potential accessibility benefits to be had from effective HTML.
-
-[quote, Manuel Matuzović, 'https://alistapart.com/article/my-accessibility-journey-what-ive-learned-so-far/[My Accessibility Journey: What I’ve Learned So Far]']
-(Re)learning HTML and using it consciously prevents and fixes many accessibility issues.
-
-It's true that all else being equal, an app that makes full use of HTML will be more accessible than one that is made of soup.
-However, even the adage that HTML is "`accessible by default`" is a bit misleading.
-
-If you use simple HTML strictly as recommended by the spec, you are unlikely to run into accessibility bugs (though it does happen, because this is web development).
-Problems often arise when we try to implement controls that aren't built into HTML.
-Sometimes, JavaScript is necessary to implement a UI control in an accessible manner
-(that is, in a way that supports all required keyboard interaction and presenting state to assistive tools).
-Clever "tricks" to implement controls in only HTML/CSS are fun, but often not practical.
-Take the following code, which uses radio buttons and CSS hacks to create something that resembles tabs:
-
-[source,html]
-----
-<input type="radio" name="tabs" id="tab1" checked>
-<label for="tab1">Tab 1</label> <1>
-<input type="radio" name="tabs" id="tab2">
-<label for="tab2">Tab 2</label>
-
-<div class="tabpanel" id="tabpanel1">Tab 1 contents</div>
-<div class="tabpanel" id="tabpanel2">Tab 2 contents</div>
-
-<style>
-  input[name="tabs"] { display: none; } <2>
-  .tabpanel { display: none; }
-  #tab1:checked ~ #tabpanel1 { display: block; } <3>
-  #tab2:checked ~ #tabpanel2 { display: block; } <3>
-</style>
-----
-<1> Each tab is an `<input>` and a `<label>`.
-<2> Hide the radio buttons. We can actuate them by clicking the associated labels.
-<3> A tabpanel will be visible when the associated tab is selected.
-
-This code will "`work.`"
-Clicking on the tabs will change the content displayed, and without a single line of JavaScript.
-Unfortunately, tabs have requirements beyond clicking to change content.
-This implementation has many missing features that will lead to user confusion and frustration, as well as some undesirable behaviors.
+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.
 From the link:https://www.w3.org/WAI/ARIA/apg/patterns/tabs/[ARIA Authoring Practices Guide on tabs]:
 
 * Keyboard interaction
 
-** The tabs can't be focused with the Tab key. Because the radio buttons are hidden with `display: none`, they are removed from the focus order, and label elements are not focusable.
-
-** "`[...] does not listen for Down Arrow or Up Arrow so those keys can provide their normal browser scrolling functions [...]`" 
-   Radio buttons listen to these events (since they're usually presented vertically). Thankfully, right and left arrow keys also work.
+** Can the tabs be focused with the Tab key?
 
 * ARIA roles, states, and properties
 
 ** "`[The element that contains the tabs] has role `tablist`.`" 
-   There is no such element in this implementation, as that would break the CSS.
 
 ** "`Each [tab] has role `tab` [...]`"
-   The tab elements have role `label`. Furthermore, the elements they are labeling are hidden.
 
 ** "`Each element that contains the content panel for a `tab` has role `tabpanel`.`"
-   No, though that could be added.
 
 ** "`Each [tab] has the property `aria-controls` referring to its associated tabpanel element.`"
-   Nope.
 
 ** "`The active `tab` element has the state `aria-selected` set to `true` and all other `tab` elements have it set to `false`.`"
-   Nope.
 
 ** "`Each element with role `tabpanel` has the property `aria-labelledby` referring to its associated `tab` element.`"
-   No. The element that _is_ labelled by the tab element is a hidden radio button.
 
-[.info]
+You would need to write a lot of code to make your improvised tabs fulfill all of these requirements. Some of the ARIA attributes can be added directly in HTML,
+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.
+
+// meaning, we recommend?
+Use established libraries for UI interactions unless a unique use case compels you to roll your own.
+****
+
+.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:
 
@@ -528,20 +372,10 @@ From the link:https://www.w3.org/WAI/ARIA/apg/patterns/tabs/[ARIA Authoring Prac
 `vh` is short for "`visually hidden.`" This class uses multiple methods and workarounds to make sure no browser removes the element's function.
 ****
 
-It turns out that fulfilling all of these requirements takes a lot of code. 
-Some of the ARIA attributes can be added directly in HTML,
-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 a good 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.
-This is why it's often recommended to use established libraries for UI interactions instead of rolling your own.
-
-Before adding a dependency, however, let's reconsider our design.
-Does the information really need to be presented as tabs?
-Sometimes the answer is yes
--- we used dummy text in our code example, so we can't tell --
-but if not, a sequence of details disclosures fulfills a very similar purpose.
+.Remember <details>
+****
+Does the information need to be presented as tabs?
+Sometimes the answer is yes, but if not, a sequence of details and disclosures fulfills a very similar purpose.
 
 [source,html]
 ----
@@ -554,24 +388,18 @@ but if not, a sequence of details disclosures fulfills a very similar purpose.
 ----
 
 Compromising UX just to avoid JavaScript is bad development.
-At the same time, the possibilities and constraints of the platform should be considered while designing interfaces.
-It might be possible to achieve an equal (or better!) quality of UX while allowing for a simpler and more robust implementation.
-But when it's not, we shouldn't try to stuff every problem into an HTML box.
+But sometimes it's possible to achieve an equal (or better!) quality of UX while allowing for a simpler and more robust implementation.
+****
 
-
-=== Screen Reader Rage
-
-The purpose of writing good HTML is not to please the specification deities.
-It's to make good websites.
+.Screen Reader Rage
+****
 The spec is a good starting point when deciding how to mark something up,
 but when browser implementations don't conform,
 we shouldn't throw up our hands because we did what was specified.
 
-****
 After all, browser implementers do a _lot_ of work to deal with developers' broken HTML -- is it such a burden to return the favor?
-****
 
-It is of course frustrating when browsers and other tools misbehave.
+It is frustrating when browsers and other tools misbehave.
 Accessibility itself feels inaccessible sometimes.
 To reduce the frustration it may help to recognize that hypermedia exchanges are not machine-to-machine communication.
 An HTML file is not a program that produces a human-readable document.
@@ -581,27 +409,16 @@ So, instead of banging your head against a wall, focus on people, not the tools
 Don't write HTML for browsers. or assistive tools, or validators.
 HTML is not _for_ them.
 HTML is for humans.
+****
 
 
-== The Scrapeable Web
-
-Hypermedia systems perform best with human-operated clients.
-However, machine-readable information can be embedded into HTML pages through a variety of extension mechanisms:
-
-* Classes
-
-* `data-` attributes
-
-* `<meta>` tags
-
-* Link relations (`rel`)
-
-* Microdata (`itemscope`, `itemtype`, `itemprop`)
-
-These mechanisms are fairly unstructured (as per earlier discussion on Semantic Web schematamania),
-but structure can be imposed upon them if needed.
-One standard for including structured data in HTML is https://microformats.org/[microformats].
-Microformats use classes to mark certain elements as containing information to be extracted.
+// maybe: discuss data options at top of Data API chapter
+// or, cut if you don't recommend using
+.Microformats
+****
+In some cases you may want to include machine-readable structured data in HTML. 
+https://microformats.org/[Microformats] is one standard for doing so.
+It uses classes to mark certain elements as containing information to be extracted.
 The microformats2 standard uses five kinds of classes:
 
 * `h-` classes denote that an element represents a machine-readable entity, e.g., `h-entry`, `h-resume`
@@ -623,6 +440,8 @@ By adding these classes into the HTML representation of an object, we allow the
 ----
 
 can be parsed into this JSON-like structure:
+// maybe: briefly describe how
+
 
 [source,json]
 ----
@@ -631,81 +450,25 @@ can be parsed into this JSON-like structure:
   "properties": {
     "name": ["John Doe"],
     "photo": ["john.jpg"],
+    ""
     "url": ["https://john.example"]
   }
 }
 ----
 
-We can see microformats in action by looking back at how we can mark up the reference list we mentioned earlier in this example.
-Using a variety of properties and nested objects, we can mark up every bit of information about the work being cited in a machine-readable way:
+Using a variety of properties and nested objects, we could mark up every bit of information about a contact, for example, in a machine-readable way.
 
-[source,html]
-----
-<ol class="reference-list">
-  <li class="h-cite" id="cite-hypers2023">
-    <span class="p-author">C.&#8202;H. Gross</span>,
-    <span class="p-author">A. Stepinski</span>,
-    and <span class="p-author">D. Akşimşek</span>,
-    <cite class="p-name">Hypermedia Systems</cite>,
-    <span class="p-publisher h-card">
-      <span class="p-adr h-adr">
-        <span class="p-locality">Bozeman</span>,
-        <span class="p-region">MT</span>,
-        <span class="p-country-name">USA</span>
-      </span>:
-      <span class="p-name">Big Sky Software</span>
-    </span>,
-    <time class="dt-published">2023</time>.
-    Available:
-    <a class="u-url" href="https://hypermedia.systems/">
-      https://hypermedia.systems/
-    </a>
-  </li>
-</ol>
-----
-
-This can be parsed into a JSON-like structure, as follows:
-
-[source,json]
-----
-{
-  "type": ["h-cite"],
-  "properties": {
-    "author": ["C.\u200aH. Gross", "A. Stepinski", "D. Akşimşek"],
-    "name": ["Hypermedia Systems"],
-    "url": ["https://hypermedia.systems/"],
-    "published": ["2023"],
-    "publisher": [{
-      "type": ["h-card"],
-      "properties": {
-        "name": ["Big Sky Software"],
-        "adr": [{
-          "type": ["h-adr"],
-          "properties": {
-            "locality": ["Bozeman"],
-            "region": ["MT"],
-            "country-name": ["USA"]
-          }
-        }]
-      }
-    }]
-  }
-}
-----
-
-//maybe: try to suggest a rule of thumb for when to use a microformat,
-// versus creating a json api.
-// Would this be helpful for contact.app?
-In this example, Microformats and the extensibility of HTML proved quite useful.
-However, embedding data in HTML is hardly appropriate for every use case.
+// maybe: rule of thumb for when to use a microformat
+// Would this be worthwhile for contact.app?
+Microformats and the extensibility of HTML can prove useful, but embedding data in HTML is not appropriate for every use case.
 Your human-facing and machine-facing interfaces may end up being limited by each other.
-It's often the best option to define a JSON data API separate from your HTML, which will be discussed later in this book.
+It's often the best option to define a JSON data API separate from your HTML.
+****
 
-
-== Where To Next
-
-//maybe: summarize key points or best practices
-We've touched on some of the main challenges of writing good HTML. To continue to invest in your HTML knowledge, here are some resources we recommend:
+// move to end, ch1 or 2
+.HTML Resources
+****
+Some resources we recommend:
 
 * Foundations
 * HTML specification: https://html.spec.whatwg.org/multipage
@@ -721,3 +484,4 @@ We've touched on some of the main challenges of writing good HTML. To continue t
 ** 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/
+****
\ No newline at end of file

From 80e591d3a5c20ae583d96588d6f6fd4dc3b65ba2 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Fri, 14 Apr 2023 16:33:55 -0400
Subject: [PATCH 05/18] Edit, work toward sprinkle concept

---
 book/CH03_EffectiveHtml.adoc | 188 +++++++++++++++++++++++------------
 1 file changed, 127 insertions(+), 61 deletions(-)

diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index c5f7ec0..5de6703 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/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
-.What is HTML?
+[.design-note]
+.Why Effective HTML?
 ****
-[quote, Marshall McLuhan]
-The medium is the message.
+Sprinkled throughout this book you will find tips and best practices for writing effective HTML.
 
-Is it a document format?
-Is it for applications?
-Is it a rendering system?
-Is it (gasp!) a programming language?
+It's very easy (and sometimes acceptable) to produce mediocre HTML that _seems to_ work,
+and many websites settle with _seeming to_ work.
 
-[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.
-____
+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.
 
-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.
-
-HTML is a hypermedium.
-
-An HTML file is not a program that produces a human-readable document.
-It _is_ the document.
+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
 ****
 
+
+[.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?
-****
-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.
+So, let’s make that hypermedia best practice no. 1. Test.
 ****
 
 
+[.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?
-Use established libraries for UI interactions unless a unique use case compels you to roll your own.
+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.
 ****
 
+
+// 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
-* HTML specification: https://html.spec.whatwg.org/multipage
+Is it a document format?
+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.
-
-** 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/
+An HTML file is not a program that produces a human-readable document.
+It _is_ the document.
 ****
\ No newline at end of file

From b6d6694e1f338aceffc3fa932f8b81ba8fb9b286 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sat, 15 Apr 2023 00:08:02 -0400
Subject: [PATCH 06/18] Move bits from ch3, design-note style

---
 book/CH01_HypermediaAReintroduction.adoc     |  17 +
 book/CH02_ComponentsOfAHypermediaSystem.adoc |  40 +++
 book/CH03_EffectiveHtml.adoc                 | 352 +++----------------
 book/CH04_BuildingASimpleWebApplication.adoc |  14 +
 book/CH05_ExtendingHTMLAsHypermedia.adoc     |  41 +++
 book/CH06_htmxPatterns.adoc                  |  31 ++
 book/CH07_MorehtmxPatterns.adoc              |  26 ++
 book/CH08_ADynamicArchiveUIWithhtmx.adoc     |  32 ++
 book/CH11_JSONDataAPIs.adoc                  |  54 +++
 9 files changed, 306 insertions(+), 301 deletions(-)

diff --git a/book/CH01_HypermediaAReintroduction.adoc b/book/CH01_HypermediaAReintroduction.adoc
index a2062c6..679e8d4 100644
--- a/book/CH01_HypermediaAReintroduction.adoc
+++ b/book/CH01_HypermediaAReintroduction.adoc
@@ -695,3 +695,20 @@ 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.
+****
+
diff --git a/book/CH02_ComponentsOfAHypermediaSystem.adoc b/book/CH02_ComponentsOfAHypermediaSystem.adoc
index 7b6feb5..a84cfa7 100644
--- a/book/CH02_ComponentsOfAHypermediaSystem.adoc
+++ b/book/CH02_ComponentsOfAHypermediaSystem.adoc
@@ -794,3 +794,43 @@ systems so flexible.
 If you were not aware of the full significance of REST and HATEOAS before now, don't feel bad: it took some of us over a decade of
 working in web development, and building a hypermedia-oriented library to boot, to understand the
 special nature of HTML, hypermedia and the web!
+
+
+[.design-note]
+.HTML Note: <div> Soup
+****
+The best-known kind of messy HTML is `<div>` soup. 
+
+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.
+
+For example, instead of adding a button using the dedicated `<button>` element,
+a `<div>` element might have a `click` event listener added to it.
+
+[source,html]
+----
+<div class="bg-accent padding-4 rounded-2" onclick="doStuff()">Do stuff</div>
+----
+
+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.
+
+Yes, we can fix that by adding `role="button"`` and `tabindex="0"`:
+
+[source,html]
+----
+<div class="bg-accent padding-4 rounded-2"
+  role="button" 
+  tabindex="0" 
+  onclick="doStuff()">Do stuff</div>
+----
+
+These are easy fixes, but they're things you have to _remember_.
+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).
+****
\ No newline at end of file
diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index 5de6703..39ac71c 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/book/CH03_EffectiveHtml.adoc
@@ -10,7 +10,7 @@ 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
+which... may not be useful
 //// 
 
 [.design-note]
@@ -28,22 +28,7 @@ Effective HTML typically loads faster, is easier to read and debug, performs bet
 ****
 
 
-[.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]
@@ -53,54 +38,12 @@ Even good HTML is not a cure-all.
 If you care about machine readability, or human readability, or page weight, the most important thing to do is _testing_.
 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).
 
-So, let’s make that hypermedia best practice no. 1. Test.
+Test with screenreaders, test with a keyboard, test on different browsers and hardware, and run linters (while coding and/or in CI).
 ****
 
 
-[.design-note]
-.<div> Soup
-****
-The best-known kind of messy HTML is `<div>` soup. 
 
-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.
-
-For example, instead of adding a button using the dedicated `<button>` element,
-a `<div>` element might have a `click` event listener added to it.
-
-[source,html]
-----
-<div class="bg-accent padding-4 rounded-2" onclick="doStuff()">Do stuff</div>
-----
-
-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.
-
-Yes, we can fix that by adding `role="button"`` and `tabindex="0"`:
-
-[source,html]
-----
-<div class="bg-accent padding-4 rounded-2"
-  role="button" 
-  tabindex="0" 
-  onclick="doStuff()">Do stuff</div>
-----
-
-These are easy fixes, but they're things you have to _remember_.
-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).
-
-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]
@@ -133,11 +76,11 @@ but Markdown doesn't have a way to add a class to elements meaning the square br
 ****
 
 
-// maybe an info gem?
+// TODO: 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>`.
+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>`.
 ****
 
 
@@ -175,103 +118,15 @@ Available: <https://hypermedia.systems/>
 ****
 
 
+
+
+
+
+
+
+
+
 [.design-note]
-.Component Soup?
-****
-Components encapsulate a section of a page along with its dynamic behavior.
-While encapsulating behavior is a good way to organize code,
-it can also separate elements from their surrounding context,
-which can lead to wrong or inadequate relationships between elements.
-The result is what one might call [.dfn]_component soup_,
-where information is hidden in component state,
-rather than being present in the HTML, which is now incomprehensible due to missing context.
-
-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.
-
-// 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;
-Custom Elements and Shadow DOM, and `<template>` and `<slot>`.
-
-All of these standards bring useful capabilities to the table.
-`<template>` elements remove their contents from the document, while still parsing them as HTML (unlike comments) and making them accessible to JavaScript.
-Custom Elements let us initialize and tear down behaviors when elements are added or removed, which would previously require manual work or MutationObservers.
-Shadow DOM lets us encapsulate elements, leaving the "light" (non-shadow) DOM clean.
-
-However, trying to reap these benefits is often frustrating.
-Some difficulties are simply growing pains of new standards
-(like the accessibility problems of Shadow DOM)
-that are actively being worked on.
-Others are the result of Web Components trying to be too many things at the same time:
-
- * An extension mechanism for HTML. To this end, each custom element is a tag we add to the language.
- * A lifecycle mechanism for behaviors. Methods like `createdCallback`, `connectedCallback`, etc. allow behavior to be added to elements without needing to be manually invoked when those elements are added.
- * A unit of encapsulation. Shadow DOM insulates elements from their surroundings.
-
-The result is that if you want any one of these things,
-the others come along for the ride.
-If you want to attach some behaviors to some elements using lifecycle callbacks,
-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.
-****
-
-
-
-.HTML5 Soup
-****
-Elements like `<section>`, `<article>`, `<nav>`, `<header>`, `<footer>`, `<figure>` have become a sort of shorthand for HTML.
-
-By using these elements, a page can make false promises, like `<article>` elements being self-contained, reusable entities, to clients like browsers, search engines and scrapers that can't know better. To avoid this:
-
-* 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
-****
-[quote,Confucius]
-The beginning of wisdom is to call things by their right names.
-
-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 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
 ****
 The close relationship between content and markup means that
@@ -289,102 +144,25 @@ 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)']
-Gretchen, stop trying to make fetch happen! It's not going to happen!
-
-The "Semantic Web" was a vision of a system that could both express any kind of human knowledge, and be useful for computing.
-It planned to achieve this using _ontologies_, repositories of schemas like "person", "movie" and "species" and relations like "named", "part of" and "created by".
-
-The problem with this vision is that information on the Web rarely fits into neat categories.
-Because no single ontology can be defined that encapsulates all kinds of information one might wish to publish on the Web,
-Semantic Web systems need to be pluggable with different schemas.
-In turn, a Semantic Web client, in order to do something useful with an arbitrary piece of HTML, needs to be able to parse these schemas, which means we need to define a standard machine-readable format for ontologies.
-But a single format couldn't express every kind of object and relation...
-It's turtles all the way down.
-
-In practice, most implementations stop at the topmost turtle.
-Ontologies are defined in natural language,
-and clients are hardcoded to support a fixed set of schemas.
-The requirement for prior agreement between server and client means this technology does not have the generality of the Web,
-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/]
-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.
-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.
-
-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? 
-
-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.
-From the link:https://www.w3.org/WAI/ARIA/apg/patterns/tabs/[ARIA Authoring Practices Guide on tabs]:
-
-* Keyboard interaction
-
-** Can the tabs be focused with the Tab key?
-
-* ARIA roles, states, and properties
-
-** "`[The element that contains the tabs] has role `tablist`.`" 
-
-** "`Each [tab] has role `tab` [...]`"
-
-** "`Each element that contains the content panel for a `tab` has role `tabpanel`.`"
-
-** "`Each [tab] has the property `aria-controls` referring to its associated tabpanel element.`"
-
-** "`The active `tab` element has the state `aria-selected` set to `true` and all other `tab` elements have it set to `false`.`"
-
-** "`Each element with role `tabpanel` has the property `aria-labelledby` referring to its associated `tab` element.`"
-
-You would need to write a lot of code to make your improvised tabs fulfill all of these requirements. Some of the ARIA attributes can be added directly in HTML,
-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.
-
-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.
-****
 
 
 // TODO: check. Does this list accurately condense the work of ch.3?
 [.design-note]
-.Best Practices for Effective HTML
+.Toward 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.
+Throughout the book we discuss a number of best practices for writing effective HTML. Here's a nutshell version: 
+
+* Stay close to the HTML markup you’re producing and be able to change it. Prefer frameworks and components that help you do this. 
+// TODO: maybe add. Aim for 'locality of behavior' in your markup, so that you or another developer can understand what each part of the page is doing just by looking at that part of the page.  
+* Make the full range of available tags part of your toolkit. 
+* Aim for good fit between tag specs and your use case; check the HTML specs when in doubt. 
+* When more specific tags don’t fit, it is okay -- and usually better -- to step back to <div> than to use a tag incorrectly. 
+* Stick with established libraries for UI interactions. If a use case requires an improvised solution, test carefully for keyboard interaction and accessibility.
+* Prefer components that extend HTML, rather than abstracting it away.
+* Test your HTML with screenreaders, with a keyboard, with different browsers and hardware, and run linters (while coding and/or in CI).
 ****
 
 
@@ -409,6 +187,7 @@ Some resources we recommend:
 ** [.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
 ****
@@ -451,7 +230,7 @@ But sometimes it's possible to achieve an equal (or better!) quality of UX while
 ****
 
 
-// TODO: Nice writing here. Some readers may want more specific advice: what does it mean to write HTML for humans? 
+// TODO: 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,
@@ -473,61 +252,6 @@ HTML is for humans.
 ****
 
 
-// maybe: discuss data options as part of Data API chapter
-// or, cut if you don't recommend using
-.Microformats
-****
-In some cases you may want to include machine-readable structured data in HTML. 
-https://microformats.org/[Microformats] is one standard for doing so.
-It uses classes to mark certain elements as containing information to be extracted.
-The microformats2 standard uses five kinds of classes:
-
-* `h-` classes denote that an element represents a machine-readable entity, e.g., `h-entry`, `h-resume`
-* The other prefixes denote that an element represents properties of an enclosing entity:
-** `p-` classes are plain text properties, from an element's inner text or `alt` attribute, e.g., `p-name`, `p-category`
-** `u-` classes are URL properties, from an element's `href` or `src`, e.g., `u-url`, `u-email`, `u-photo`
-** `dt-` classes are date/time properties, from `<time>` elements, e.g., `dt-published`, `dt-updated`
-** `e-` classes are embedded markup properties, from an element's inner HTML, e.g., `e-content`, `e-description`
-
-There are also conventions for extracting common properties like name, URL and photo without needing classes for each property.
-
-By adding these classes into the HTML representation of an object, we allow the properties of the object to be recovered from the HTML. For example, this simple HTML:
-
-[source,html]
-----
-<a class="h-card" href="https://john.example">
-  <img src="john.jpg" alt=""> John Doe
-</a>
-----
-
-can be parsed into this JSON-like structure:
-// maybe: briefly describe how
-
-
-[source,json]
-----
-{
-  "type": ["h-card"],
-  "properties": {
-    "name": ["John Doe"],
-    "photo": ["john.jpg"],
-    ""
-    "url": ["https://john.example"]
-  }
-}
-----
-
-Using a variety of properties and nested objects, we could mark up every bit of information about a contact, for example, in a machine-readable way.
-
-// maybe: rule of thumb for when to use a microformat
-// Would this be worthwhile for contact.app?
-Microformats and the extensibility of HTML can prove useful, but embedding data in HTML is not appropriate for every use case.
-Your human-facing and machine-facing interfaces may end up being limited by each other.
-It's often the best option to define a JSON data API separate from your HTML.
-****
-
-
-
 // maybe move to ch1, The Essence of HTML as a Hypermedia
 .What is HTML?
 ****
@@ -550,4 +274,30 @@ HTML is a hypermedium.
 
 An HTML file is not a program that produces a human-readable document.
 It _is_ the document.
+****
+
+
+// TODO: keep? format as pullout, like Web Components, ARIA
+.The "`Semantic Web`"
+****
+[quote, '_Mean Girls_ (2004)']
+Gretchen, stop trying to make fetch happen! It's not going to happen!
+
+The "Semantic Web" was a vision of a system that could both express any kind of human knowledge, and be useful for computing.
+It planned to achieve this using _ontologies_, repositories of schemas like "person", "movie" and "species" and relations like "named", "part of" and "created by".
+
+The problem with this vision is that information on the Web rarely fits into neat categories.
+Because no single ontology can be defined that encapsulates all kinds of information one might wish to publish on the Web,
+Semantic Web systems need to be pluggable with different schemas.
+In turn, a Semantic Web client, in order to do something useful with an arbitrary piece of HTML, needs to be able to parse these schemas, which means we need to define a standard machine-readable format for ontologies.
+But a single format couldn't express every kind of object and relation...
+It's turtles all the way down.
+
+In practice, most implementations stop at the topmost turtle.
+Ontologies are defined in natural language,
+and clients are hardcoded to support a fixed set of schemas.
+The requirement for prior agreement between server and client means this technology does not have the generality of the Web,
+and for most use cases, you might as well define a JSON API.
+
+_The Semantic Web has nothing to do with semantic HTML_.
 ****
\ No newline at end of file
diff --git a/book/CH04_BuildingASimpleWebApplication.adoc b/book/CH04_BuildingASimpleWebApplication.adoc
index d2533d2..a1d8c30 100644
--- a/book/CH04_BuildingASimpleWebApplication.adoc
+++ b/book/CH04_BuildingASimpleWebApplication.adoc
@@ -859,3 +859,17 @@ No.  No it isn't.
 It turns out that we can improve the user experience of this application within the
 hypermedia architecture. In the next few chapters we will look at https://htmx.org[htmx], a hypermedia-oriented library
 that will let us improve our contact application _without_ abandoning the hypermedia approach we have used so far.
+
+
+[.design-note]
+.HTML Note: Semantic HTML
+****
+[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.
+Use the elements to the full extent provided by the HTML specification,
+and let the software take from it whatever meaning they can.
+****
diff --git a/book/CH05_ExtendingHTMLAsHypermedia.adoc b/book/CH05_ExtendingHTMLAsHypermedia.adoc
index dad04f7..adc244c 100644
--- a/book/CH05_ExtendingHTMLAsHypermedia.adoc
+++ b/book/CH05_ExtendingHTMLAsHypermedia.adoc
@@ -891,3 +891,44 @@ By staying closer to the original model of the web, htmx aims to strike a balanc
 deferring to other libraries for more elaborate frontend extensions on top of the existing web platform.  The good news
 is that htmx plays well with others, so when these needs arise it is often easy enough to bring in another library to handle
 them.
+
+
+[.design-note]
+.HTML Note: Caution with Improvised UI Elements
+****
+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? 
+
+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.
+From the link:https://www.w3.org/WAI/ARIA/apg/patterns/tabs/[ARIA Authoring Practices Guide on tabs]:
+
+* Keyboard interaction
+
+** Can the tabs be focused with the Tab key?
+
+* ARIA roles, states, and properties
+
+** "`[The element that contains the tabs] has role `tablist`.`" 
+
+** "`Each [tab] has role `tab` [...]`"
+
+** "`Each element that contains the content panel for a `tab` has role `tabpanel`.`"
+
+** "`Each [tab] has the property `aria-controls` referring to its associated tabpanel element.`"
+
+** "`The active `tab` element has the state `aria-selected` set to `true` and all other `tab` elements have it set to `false`.`"
+
+** "`Each element with role `tabpanel` has the property `aria-labelledby` referring to its associated `tab` element.`"
+
+You would need to write a lot of code to make your improvised tabs fulfill all of these requirements. Some of the ARIA attributes can be added directly in HTML,
+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.
+
+Stick with established libraries for UI interactions. If a use case requires an improvised solution, test carefully for keyboard interaction and accessibility.
+****
\ No newline at end of file
diff --git a/book/CH06_htmxPatterns.adoc b/book/CH06_htmxPatterns.adoc
index fda3ad5..ee3a480 100644
--- a/book/CH06_htmxPatterns.adoc
+++ b/book/CH06_htmxPatterns.adoc
@@ -1032,3 +1032,34 @@ And, again, we are doing all this within the original, RESTful model of the web.
 behavior, we are still exchanging hypermedia with the server, with no JSON API response to be seen.
 
 As the web was designed.
+
+
+[.design-note]
+.Component Soup?
+****
+Components encapsulate a section of a page along with its dynamic behavior.
+While encapsulating behavior is a good way to organize code,
+it can also separate elements from their surrounding context,
+which can lead to wrong or inadequate relationships between elements.
+The result is what one might call [.dfn]_component soup_,
+where information is hidden in component state,
+rather than being present in the HTML, which is now incomprehensible due to missing context.
+
+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.
+****
\ No newline at end of file
diff --git a/book/CH07_MorehtmxPatterns.adoc b/book/CH07_MorehtmxPatterns.adoc
index 1414c31..d380c3b 100644
--- a/book/CH07_MorehtmxPatterns.adoc
+++ b/book/CH07_MorehtmxPatterns.adoc
@@ -1152,3 +1152,29 @@ contacts that were deleted) will be re-rendered.
 And there we go, we now have a bulk delete feature for our application.  Once again, not a huge amount of code, and we
 are implementing these features entirely by exchanging hypermedia with a server in the traditional, RESTful manner of
 the web.
+
+
+[.design-note]
+.HTML Note: HTML5 Soup
+****
+[quote,Confucius]
+The beginning of wisdom is to call things by their right names.
+
+Elements like `<section>`, `<article>`, `<nav>`, `<header>`, `<footer>`, `<figure>` have become a sort of shorthand for HTML.
+
+By using these elements, a page can make false promises, like `<article>` elements being self-contained, reusable entities, to clients like browsers, search engines and scrapers that can't know better. To avoid this:
+
+* 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.
+
+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 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!
+****
\ No newline at end of file
diff --git a/book/CH08_ADynamicArchiveUIWithhtmx.adoc b/book/CH08_ADynamicArchiveUIWithhtmx.adoc
index 9c61fe6..aaa7549 100644
--- a/book/CH08_ADynamicArchiveUIWithhtmx.adoc
+++ b/book/CH08_ADynamicArchiveUIWithhtmx.adoc
@@ -632,3 +632,35 @@ auto-downloading, and we've done nearly all of it -- with the exception of a sma
 pure hypermedia. It took about 16 lines of front end code and 16 lines of backend code to build the whole thing.
 
 HTML, with a bit of help from a hypermedia-oriented JavaScript library such as htmx, can in fact be extremely powerful and expressive.
+
+
+// TODO: this might work best as a vanilla pullout
+[.design-note]
+.HTML Notes: On Web Components
+****
+Web Components is the collective name of a few standards;
+Custom Elements and Shadow DOM, and `<template>` and `<slot>`.
+
+All of these standards bring useful capabilities to the table.
+`<template>` elements remove their contents from the document, while still parsing them as HTML (unlike comments) and making them accessible to JavaScript.
+Custom Elements let us initialize and tear down behaviors when elements are added or removed, which would previously require manual work or MutationObservers.
+Shadow DOM lets us encapsulate elements, leaving the "light" (non-shadow) DOM clean.
+
+However, trying to reap these benefits is often frustrating.
+Some difficulties are simply growing pains of new standards
+(like the accessibility problems of Shadow DOM)
+that are actively being worked on.
+Others are the result of Web Components trying to be too many things at the same time:
+
+ * An extension mechanism for HTML. To this end, each custom element is a tag we add to the language.
+ * A lifecycle mechanism for behaviors. Methods like `createdCallback`, `connectedCallback`, etc. allow behavior to be added to elements without needing to be manually invoked when those elements are added.
+ * A unit of encapsulation. Shadow DOM insulates elements from their surroundings.
+
+The result is that if you want any one of these things,
+the others come along for the ride.
+If you want to attach some behaviors to some elements using lifecycle callbacks,
+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.
+****
\ No newline at end of file
diff --git a/book/CH11_JSONDataAPIs.adoc b/book/CH11_JSONDataAPIs.adoc
index 4e93243..52405ac 100644
--- a/book/CH11_JSONDataAPIs.adoc
+++ b/book/CH11_JSONDataAPIs.adoc
@@ -503,3 +503,57 @@ another.
 
 With properly built "`thin`" controllers and "`fat`" models, keeping two separate APIs both in sync and yet
 still evolving separately is not as difficult or as crazy as it might sound.
+
+
+// TODO: does some version of this fit here?
+// or, cut if you don't recommend using
+.Microformats
+****
+In some cases you may want to include machine-readable structured data in HTML. 
+https://microformats.org/[Microformats] is one standard for doing so.
+It uses classes to mark certain elements as containing information to be extracted.
+The microformats2 standard uses five kinds of classes:
+
+* `h-` classes denote that an element represents a machine-readable entity, e.g., `h-entry`, `h-resume`
+* The other prefixes denote that an element represents properties of an enclosing entity:
+** `p-` classes are plain text properties, from an element's inner text or `alt` attribute, e.g., `p-name`, `p-category`
+** `u-` classes are URL properties, from an element's `href` or `src`, e.g., `u-url`, `u-email`, `u-photo`
+** `dt-` classes are date/time properties, from `<time>` elements, e.g., `dt-published`, `dt-updated`
+** `e-` classes are embedded markup properties, from an element's inner HTML, e.g., `e-content`, `e-description`
+
+There are also conventions for extracting common properties like name, URL and photo without needing classes for each property.
+
+By adding these classes into the HTML representation of an object, we allow the properties of the object to be recovered from the HTML. For example, this simple HTML:
+
+[source,html]
+----
+<a class="h-card" href="https://john.example">
+  <img src="john.jpg" alt=""> John Doe
+</a>
+----
+
+can be parsed into this JSON-like structure:
+// maybe: briefly describe how
+
+
+[source,json]
+----
+{
+  "type": ["h-card"],
+  "properties": {
+    "name": ["John Doe"],
+    "photo": ["john.jpg"],
+    ""
+    "url": ["https://john.example"]
+  }
+}
+----
+
+Using a variety of properties and nested objects, we could mark up every bit of information about a contact, for example, in a machine-readable way.
+
+// maybe: rule of thumb for when to use a microformat
+// Would this be worthwhile for contact.app?
+Microformats and the extensibility of HTML can prove useful, but embedding data in HTML is not appropriate for every use case.
+Your human-facing and machine-facing interfaces may end up being limited by each other.
+It's often the best option to define a JSON data API separate from your HTML.
+****
\ No newline at end of file

From 79905e65a9aa64e316daca1cc5fc2e2b0504c85b Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sat, 15 Apr 2023 13:06:17 -0400
Subject: [PATCH 07/18] Pullout test - into chapter

---
 book/CH00_Introduction.adoc  | 16 ++++++++++++++++
 book/CH03_EffectiveHtml.adoc | 17 -----------------
 2 files changed, 16 insertions(+), 17 deletions(-)

diff --git a/book/CH00_Introduction.adoc b/book/CH00_Introduction.adoc
index a79d582..0e28ba7 100644
--- a/book/CH00_Introduction.adoc
+++ b/book/CH00_Introduction.adoc
@@ -144,3 +144,19 @@ about it.
 ____
 Remember the message? “The future is not set. There is no fate but what we make for ourselves.”
 ____
+
+
+
+[.design-note]
+.HTML Notes: Why Effective HTML?
+****
+At the end of each chapter you will find tips and best practices for writing effective HTML.
+
+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.
+
+// 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. 
+****
\ No newline at end of file
diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index 39ac71c..f5ac3fa 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/book/CH03_EffectiveHtml.adoc
@@ -13,23 +13,6 @@ Note: I used [.design-note] to flag for formatting.
 which... may not be useful
 //// 
 
-[.design-note]
-.Why Effective HTML?
-****
-Sprinkled throughout this book you will find tips and best practices for writing effective HTML.
-
-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. 
-// TODO: check last sentence here; pulled together from various paragraphs
-****
-
-
-
-
 
 [.design-note]
 .Test, and Test Again

From 2090ee73fc34c0e98eb30e01c1dbb48d9d18847a Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sat, 15 Apr 2023 16:32:45 -0400
Subject: [PATCH 08/18] more design-notes additions

---
 book/CH03_EffectiveHtml.adoc                  | 184 +-----------------
 book/CH09_TricksOfThehtmxMasters.adoc         |  22 +++
 ...H10_ScriptingInAHypermediaApplication.adoc |  30 +++
 book/CH12_HyperviewAMobileHypermedia.adoc     |  35 ++++
 ...H13_BuildingAContactsAppWithHyperview.adoc |  22 +++
 book/CH14_ExtendingTheHyperviewClient.adoc    |  12 ++
 book/CH15_Conclusion.adoc                     |  38 +++-
 7 files changed, 166 insertions(+), 177 deletions(-)

diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index f5ac3fa..7f53eb1 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/book/CH03_EffectiveHtml.adoc
@@ -4,61 +4,16 @@
 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.
+Pieces have been moved to end of chapter "'html notes'" (or similar).
 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'
+I we go this route, it would be useful to index or add a ToC entry for 'HTML Topics'
 
 Note: I used [.design-note] to flag for formatting. 
 which... may not be useful
 //// 
 
 
-[.design-note]
-.Test, and Test Again
-****
-Even good HTML is not a cure-all.
-If you care about machine readability, or human readability, or page weight, the most important thing to do is _testing_.
-Test manually.
-Test automatically.
-
-Test with screenreaders, test with a keyboard, test on different browsers and hardware, and run linters (while coding and/or in CI).
-****
-
-
-
-
-
-[.design-note]
-.Markdown soup
-****
-[.dfn]_Markdown soup_ is the lesser known sibling of `<div>` soup.
-This is the result of web developers limiting themselves to the set of elements that the Markdown language provides shorthand for,
-even when these elements are incorrect.
-Consider the following example of an IEEE-style citation:
-
-[source,markdown]
-----
-[1] C.H. Gross, A. Stepinski, and D. Akşimşek, <1>
-_Hypermedia Systems_, <2>
-Bozeman, MT, USA: Big Sky Software.
-Available: <https://hypermedia.systems/>
-----
-<1> The reference number is written in brackets.
-<2> Underscores around the book title creates an <em> element.
-
-Here, <em> is used because it's the only Markdown element that is presented in italics by default.
-This indicates that the book title is being stressed, but the purpose is to mark it as the title of a work.
-HTML has the `<cite>` element that's intended for this exact purpose.
-
-Furthermore, even though this is a numbered list perfect for the `<ol>` element, which Markdown supports, plain text is used for the reference numbers instead.
-Why could this be?
-The IEEE citation style requires that these numbers are presented in square brackets.
-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.
-****
-
-
 // TODO: maybe an info gem?
 [.design-note]
 .On Lists 
@@ -67,114 +22,10 @@ We call `<ol>` and `<ul>` "ordered" and "unordered" lists. Both are actually ord
 ****
 
 
-[.design-note]
-.Embedding HTML in Markdown
-****
-Don't shy away from using embedded HTML in Markdown.
-For larger sites, also consider Markdown extensions.
-
-[source,markdown]
-----
-{.ieee-reference-list} <1>
-1. C.H. Gross, A. Stepinski, and D. Akşimşek, <2>
-   <cite>Hypermedia Systems</cite>, <3>
-   Bozeman, MT, USA: Big Sky Software.
-   Available: <https://hypermedia.systems/>
-----
-<1> Many Markdown dialects let us add ids, classes and attributes using curly braces.
-<2> We can now use the <ol> element, and create the brackets in CSS.
-<3> We use `<cite>` to mark the title of the work being cited (not the whole citation!)
-
-You can also use custom processors to produce extra-detailed HTML instead of writing it by hand:
-
-[source,markdown]
-----
-{% reference_list %} <1>
-[hypers2023]: <2>
-C.H. Gross, A. Stepinski, and D. Akşimşek, _Hypermedia Systems_,
-Bozeman, MT, USA: Big Sky Software, 2023.
-Available: <https://hypermedia.systems/>
-{% end %}
-----
-<1> `reference_list` is a macro that will transform the plain text to highly-detailed HTML.
-<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.
-****
-
-
-
-
-
-
-
-
-
-
-[.design-note]
-.Know Your HTML Budget
-****
-The close relationship between content and markup means that
-good HTML is labor-intensive.
-Most sites have a separation between the authors,
-who are rarely familiar with HTML,
-and the developers, who need to develop a generic system able to handle any content that's thrown at it --
-this separation usually taking the form of a CMS.
-As a result, having markup tailored to content, which is often necessary for advanced HTML, is rarely feasible.
-
-Furthermore, for internationalized sites, content in different languages being injected into the same elements can degrade markup quality as stylistic conventions differ between languages.
-It's an expense few organizations can spare.
-
-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.
-****
-
-
-
-
-// TODO: check. Does this list accurately condense the work of ch.3?
-[.design-note]
-.Toward Effective HTML
-****
-Throughout the book we discuss a number of best practices for writing effective HTML. Here's a nutshell version: 
-
-* Stay close to the HTML markup you’re producing and be able to change it. Prefer frameworks and components that help you do this. 
-// TODO: maybe add. Aim for 'locality of behavior' in your markup, so that you or another developer can understand what each part of the page is doing just by looking at that part of the page.  
-* Make the full range of available tags part of your toolkit. 
-* Aim for good fit between tag specs and your use case; check the HTML specs when in doubt. 
-* When more specific tags don’t fit, it is okay -- and usually better -- to step back to <div> than to use a tag incorrectly. 
-* Stick with established libraries for UI interactions. If a use case requires an improvised solution, test carefully for keyboard interaction and accessibility.
-* Prefer components that extend HTML, rather than abstracting it away.
-* Test your HTML with screenreaders, with a keyboard, with different browsers and hardware, and run linters (while coding and/or in CI).
-****
-
-
-[.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
+.HTML Notes: "'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:
+One problem with `display: none;` in CSS is that it 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:
 
 [source,css]
 ----
@@ -192,28 +43,8 @@ Some resources we recommend:
 ****
 
 
-// TODO: format as info gem
-.Remember <details>
-****
-Does the information need to be presented as tabs?
-Sometimes the answer is yes, but if not, a sequence of details and disclosures fulfills a very similar purpose.
 
-[source,html]
-----
-<details><summary>Disclosure 1</summary>
-  Disclosure 1 contents
-</details>
-<details><summary>Disclosure 2</summary>
-  Disclosure 2 contents
-</details>
-----
-
-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: Some readers may want more specific advice: what does it mean to write HTML for humans? 
+// TODO: Some readers may want more specific advice. Are there rules of thumb for writing HTML for humans? 
 .Screen Reader Rage
 ****
 The spec is a good starting point when deciding how to mark something up,
@@ -235,7 +66,7 @@ HTML is for humans.
 ****
 
 
-// maybe move to ch1, The Essence of HTML as a Hypermedia
+// maybe move to ch1? The Essence of HTML as a Hypermedia
 .What is HTML?
 ****
 [quote, Marshall McLuhan]
@@ -260,7 +91,8 @@ It _is_ the document.
 ****
 
 
-// TODO: keep? format as pullout, like Web Components, ARIA
+// TODO: keep? some readers will love it, others may wonder how it fits
+format as pullout, like Web Components, ARIA
 .The "`Semantic Web`"
 ****
 [quote, '_Mean Girls_ (2004)']
diff --git a/book/CH09_TricksOfThehtmxMasters.adoc b/book/CH09_TricksOfThehtmxMasters.adoc
index 52eeda8..f211362 100644
--- a/book/CH09_TricksOfThehtmxMasters.adoc
+++ b/book/CH09_TricksOfThehtmxMasters.adoc
@@ -740,3 +740,25 @@ an example:
 In this case, we are overriding the default swap style from the usual `innerHTML` to `outerHTML`.  This might be useful
 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
+****
+The close relationship between content and markup means that
+good HTML is labor-intensive.
+Most sites have a separation between the authors,
+who are rarely familiar with HTML,
+and the developers, who need to develop a generic system able to handle any content that's thrown at it --
+this separation usually taking the form of a CMS.
+As a result, having markup tailored to content, which is often necessary for advanced HTML, is rarely feasible.
+
+Furthermore, for internationalized sites, content in different languages being injected into the same elements can degrade markup quality as stylistic conventions differ between languages.
+It's an expense few organizations can spare.
+
+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.
+****
diff --git a/book/CH10_ScriptingInAHypermediaApplication.adoc b/book/CH10_ScriptingInAHypermediaApplication.adoc
index dfd3c8b..5dcb514 100644
--- a/book/CH10_ScriptingInAHypermediaApplication.adoc
+++ b/book/CH10_ScriptingInAHypermediaApplication.adoc
@@ -1302,3 +1302,33 @@ we would focus on these more general concerns:
 And even on these topics, sometimes a web developer has to do what a web developer has to do.  If the perfect widget for your application exists but uses a JSON data API?  That's OK.
 
 Just don't make it a habit.
+
+
+[.design-note]
+.HTML Notes: Markdown soup
+****
+[.dfn]_Markdown soup_ is the lesser known sibling of `<div>` soup.
+This is the result of web developers limiting themselves to the set of elements that the Markdown language provides shorthand for,
+even when these elements are incorrect.
+Consider the following example of an IEEE-style citation:
+
+[source,markdown]
+----
+[1] C.H. Gross, A. Stepinski, and D. Akşimşek, <1>
+_Hypermedia Systems_, <2>
+Bozeman, MT, USA: Big Sky Software.
+Available: <https://hypermedia.systems/>
+----
+<1> The reference number is written in brackets.
+<2> Underscores around the book title creates an <em> element.
+
+Here, <em> is used because it's the only Markdown element that is presented in italics by default.
+This indicates that the book title is being stressed, but the purpose is to mark it as the title of a work.
+HTML has the `<cite>` element that's intended for this exact purpose.
+
+Furthermore, even though this is a numbered list perfect for the `<ol>` element, which Markdown supports, plain text is used for the reference numbers instead.
+Why could this be?
+The IEEE citation style requires that these numbers are presented in square brackets.
+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.
+****
\ No newline at end of file
diff --git a/book/CH12_HyperviewAMobileHypermedia.adoc b/book/CH12_HyperviewAMobileHypermedia.adoc
index bf1453a..ad7f6f8 100644
--- a/book/CH12_HyperviewAMobileHypermedia.adoc
+++ b/book/CH12_HyperviewAMobileHypermedia.adoc
@@ -1264,3 +1264,38 @@ One way to implement the hypermedia architecture for mobile apps is with HTML we
 Hyperview offers an alternative approach using the hypermedia architecture, based on a new format called HXML. It also provides an open-source mobile thin-client to render HXML. Again, HXML looks similar to HTML, but it uses elements and patterns that correspond to mobile UIs.
 
 The extensibility of HXML and the Hyperview client make it easy to define custom elements and behaviors. Developers can evolve Hyperview to suit their apps' requirements, while fully embracing the hypermedia architecture.
+
+
+
+[.design-note]
+.HTML Notes: Embedding HTML in Markdown
+****
+Don't shy away from using embedded HTML in Markdown.
+For larger sites, also consider Markdown extensions.
+
+[source,markdown]
+----
+{.ieee-reference-list} <1>
+1. C.H. Gross, A. Stepinski, and D. Akşimşek, <2>
+   <cite>Hypermedia Systems</cite>, <3>
+   Bozeman, MT, USA: Big Sky Software.
+   Available: <https://hypermedia.systems/>
+----
+<1> Many Markdown dialects let us add ids, classes and attributes using curly braces.
+<2> We can now use the <ol> element, and create the brackets in CSS.
+<3> We use `<cite>` to mark the title of the work being cited (not the whole citation!)
+
+You can also use custom processors to produce extra-detailed HTML instead of writing it by hand:
+
+[source,markdown]
+----
+{% reference_list %} <1>
+[hypers2023]: <2>
+C.H. Gross, A. Stepinski, and D. Akşimşek, _Hypermedia Systems_,
+Bozeman, MT, USA: Big Sky Software, 2023.
+Available: <https://hypermedia.systems/>
+{% end %}
+----
+<1> `reference_list` is a macro that will transform the plain text to highly-detailed HTML.
+<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.
+****
\ No newline at end of file
diff --git a/book/CH13_BuildingAContactsAppWithHyperview.adoc b/book/CH13_BuildingAContactsAppWithHyperview.adoc
index 92dc400..f4c8499 100644
--- a/book/CH13_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH13_BuildingAContactsAppWithHyperview.adoc
@@ -1316,3 +1316,25 @@ Since our HXML templates don't expose any entrypoints to the Archive functionali
 - Events are a client-side feature of Hyperview that allows triggering behaviors across screens. They are useful to keep state in sync throughout the app, such as after editing or deleting a contact.
 - A Hyperview-powered mobile app can be bundled and released through the iOS and Android app stores. New screens and features can be added to the app just by updating the backend!
 - The same Flask backend can support both web and mobile apps. Using HTTP content negotiation, a server can render either HTML or HXML responses from the same view. More complex apps may require the use of redirects and platform-specific views.
+
+
+
+// TODO: better as info gem?
+.HTML Notes: Remember <details>
+****
+Does the information need to be presented as tabs?
+Sometimes the answer is yes, but if not, a sequence of details and disclosures fulfills a very similar purpose.
+
+[source,html]
+----
+<details><summary>Disclosure 1</summary>
+  Disclosure 1 contents
+</details>
+<details><summary>Disclosure 2</summary>
+  Disclosure 2 contents
+</details>
+----
+
+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.
+****
\ No newline at end of file
diff --git a/book/CH14_ExtendingTheHyperviewClient.adoc b/book/CH14_ExtendingTheHyperviewClient.adoc
index 0b260f7..571db06 100644
--- a/book/CH14_ExtendingTheHyperviewClient.adoc
+++ b/book/CH14_ExtendingTheHyperviewClient.adoc
@@ -722,3 +722,15 @@ And importantly, this evolution preserves the Hypermedia, server-driven architec
 - Support for customized screen elements (like swipeable items in lists) can be added with Hyperview custom components.
 - The standard behaviors and components that come with the Hyperview client are implemented the same way as custom behavior actions and components.
 - By customizing the Hyperview client, developers can build a mobile app that suits their specific needs while retaining the benefits of a thin-client, hypermedia architecture.
+
+
+
+[.design-note]
+.HTML Note: Test, and Test Again
+****
+Sadly, not even good HTML-- or HXML -- can cure all ills.
+If you care about machine readability, or human readability, or page weight, the most important thing to do is _testing_.
+Test manually.
+Test automatically.
+Test with screenreaders, test with a keyboard, test on different browsers and hardware, and run linters (while coding and/or in CI).
+****
diff --git a/book/CH15_Conclusion.adoc b/book/CH15_Conclusion.adoc
index b327dd1..cc67e40 100644
--- a/book/CH15_Conclusion.adoc
+++ b/book/CH15_Conclusion.adoc
@@ -13,7 +13,7 @@ or a technology only appropriate for "`documents`" of links, text and pictures,
 building _applications_.  In this book you have seen how to build sophisticated user interfaces -- for both the web, with htmx,
 and for mobile applications, using Hyperview -- using hypermedia as a core underlying application technology.
 
-// check edits
+// check: edits
 Many web developers view the links and forms of "`plain`" HTML as bygone tools
 from a less sophisticated age.  And, in some ways, they are right: there were definite usability issues with the
 original web. However, there are now JavaScript libraries that extend HTML by addressing its core limitations. Htmx, for example, allowed us to:
@@ -66,3 +66,39 @@ put the endless swirl of the "`new new`" aside, look back on where the web came
 
 // check: suggest this as the stronger concluding line
 Perhaps it's time to give hypermedia a chance.
+
+
+
+// TODO: check. Does this list accurately condense the work?
+[.design-note]
+.HTML Notes: Toward Effective HTML
+****
+Throughout the book we discuss a number of best practices for writing effective HTML. They are, in a nutshell: 
+
+* Stay close to the HTML markup you’re producing and be able to change it. Prefer frameworks and components that help you do this. 
+// TODO: maybe add. Aim for 'locality of behavior' in your markup, so that you or another developer can understand what each part of the page is doing just by looking at that part of the page.  
+* Make the full range of available tags part of your toolkit. 
+* Aim for good fit between tag specs and your use case; check the HTML specs when in doubt. 
+* When more specific tags don’t fit, it is usually better to step back to <div> than to use a tag incorrectly. 
+* Stick with established libraries for UI interactions. If a use case requires an improvised solution, test carefully for keyboard interaction and accessibility.
+* Prefer components that extend HTML, rather than abstracting it away.
+* Test your HTML with screenreaders, with a keyboard, with different browsers and hardware, and run linters (while coding and/or in CI).
+
+// TODO: Placement?
+.Helpful Resources
+
+* 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/
+****
\ No newline at end of file

From 36f5f7c39a1e1f4e6e3c3c83388000707f4051fc Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sat, 15 Apr 2023 17:23:49 -0400
Subject: [PATCH 09/18] post-chapter html notes added to all chapters

---
 book/CH03_EffectiveHtml.adoc                  | 23 +------------------
 book/CH08_ADynamicArchiveUIWithhtmx.adoc      |  2 +-
 book/CH11_JSONDataAPIs.adoc                   |  3 ++-
 ...H13_BuildingAContactsAppWithHyperview.adoc |  2 +-
 book/CH14_ExtendingTheHyperviewClient.adoc    | 19 ++++++++++++++-
 book/CH15_Conclusion.adoc                     |  2 +-
 6 files changed, 24 insertions(+), 27 deletions(-)

diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
index 7f53eb1..db95086 100644
--- a/book/CH03_EffectiveHtml.adoc
+++ b/book/CH03_EffectiveHtml.adoc
@@ -22,29 +22,8 @@ We call `<ol>` and `<ul>` "ordered" and "unordered" lists. Both are actually ord
 ****
 
 
-// TODO: format as info gem
-.HTML Notes: "'Display: none'"
-****
-One problem with `display: none;` in CSS is that it 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:
 
-[source,css]
-----
-.vh {
-	clip: rect(0 0 0 0);
-	clip-path: inset(50%);
-	block-size: 1px;
-	inline-size: 1px;
-	overflow: hidden;
-	white-space: nowrap;
-}
-----
-
-`vh` is short for "`visually hidden.`" This class uses multiple methods and workarounds to make sure no browser removes the element's function.
-****
-
-
-
-// TODO: Some readers may want more specific advice. Are there rules of thumb for writing HTML for humans? 
+// TODO: Some readers may want more specific advice on how to write HTML for humans. 
 .Screen Reader Rage
 ****
 The spec is a good starting point when deciding how to mark something up,
diff --git a/book/CH08_ADynamicArchiveUIWithhtmx.adoc b/book/CH08_ADynamicArchiveUIWithhtmx.adoc
index aaa7549..b20bd9a 100644
--- a/book/CH08_ADynamicArchiveUIWithhtmx.adoc
+++ b/book/CH08_ADynamicArchiveUIWithhtmx.adoc
@@ -634,7 +634,7 @@ pure hypermedia. It took about 16 lines of front end code and 16 lines of backen
 HTML, with a bit of help from a hypermedia-oriented JavaScript library such as htmx, can in fact be extremely powerful and expressive.
 
 
-// TODO: this might work best as a vanilla pullout
+// TODO: work here? better as a vanilla pullout? 
 [.design-note]
 .HTML Notes: On Web Components
 ****
diff --git a/book/CH11_JSONDataAPIs.adoc b/book/CH11_JSONDataAPIs.adoc
index 52405ac..0e7524e 100644
--- a/book/CH11_JSONDataAPIs.adoc
+++ b/book/CH11_JSONDataAPIs.adoc
@@ -507,7 +507,8 @@ still evolving separately is not as difficult or as crazy as it might sound.
 
 // TODO: does some version of this fit here?
 // or, cut if you don't recommend using
-.Microformats
+[.design-note]
+.HTML Notes: Microformats
 ****
 In some cases you may want to include machine-readable structured data in HTML. 
 https://microformats.org/[Microformats] is one standard for doing so.
diff --git a/book/CH13_BuildingAContactsAppWithHyperview.adoc b/book/CH13_BuildingAContactsAppWithHyperview.adoc
index f4c8499..570fc27 100644
--- a/book/CH13_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH13_BuildingAContactsAppWithHyperview.adoc
@@ -1319,7 +1319,7 @@ Since our HXML templates don't expose any entrypoints to the Archive functionali
 
 
 
-// TODO: better as info gem?
+// TODO: okay, or better as integrated info gem?
 .HTML Notes: Remember <details>
 ****
 Does the information need to be presented as tabs?
diff --git a/book/CH14_ExtendingTheHyperviewClient.adoc b/book/CH14_ExtendingTheHyperviewClient.adoc
index 571db06..b3e4d4e 100644
--- a/book/CH14_ExtendingTheHyperviewClient.adoc
+++ b/book/CH14_ExtendingTheHyperviewClient.adoc
@@ -726,11 +726,28 @@ And importantly, this evolution preserves the Hypermedia, server-driven architec
 
 
 [.design-note]
-.HTML Note: Test, and Test Again
+.HTML Note: "'Display: none'"
 ****
 Sadly, not even good HTML-- or HXML -- can cure all ills.
 If you care about machine readability, or human readability, or page weight, the most important thing to do is _testing_.
 Test manually.
 Test automatically.
 Test with screenreaders, test with a keyboard, test on different browsers and hardware, and run linters (while coding and/or in CI).
+
+// TODO: okay here? not sure where to put this
+One common problem is with the use of `display: none;` in CSS. The issue is that it is not purely cosmetic -- it also 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:
+
+[source,css]
+----
+.vh {
+	clip: rect(0 0 0 0);
+	clip-path: inset(50%);
+	block-size: 1px;
+	inline-size: 1px;
+	overflow: hidden;
+	white-space: nowrap;
+}
+----
+
+`vh` is short for "`visually hidden.`" This class uses multiple methods and workarounds to make sure no browser removes the element's function.
 ****
diff --git a/book/CH15_Conclusion.adoc b/book/CH15_Conclusion.adoc
index cc67e40..8f9d55c 100644
--- a/book/CH15_Conclusion.adoc
+++ b/book/CH15_Conclusion.adoc
@@ -84,7 +84,7 @@ Throughout the book we discuss a number of best practices for writing effective
 * Prefer components that extend HTML, rather than abstracting it away.
 * Test your HTML with screenreaders, with a keyboard, with different browsers and hardware, and run linters (while coding and/or in CI).
 
-// TODO: Placement?
+// TODO: Finish or cut. Placement okay?
 .Helpful Resources
 
 * Foundations

From 0abfd47b4e112a3f3b5d15c0099a8a31a9b3c949 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sat, 15 Apr 2023 19:22:17 -0400
Subject: [PATCH 10/18] remove ch3, change chapter references

---
 book/CH01_HypermediaAReintroduction.adoc      |  4 +-
 book/CH02_ComponentsOfAHypermediaSystem.adoc  |  4 +-
 ...> CH03_BuildingASimpleWebApplication.adoc} |  2 +-
 book/CH03_EffectiveHtml.adoc                  | 97 -------------------
 ...oc => CH04_ExtendingHTMLAsHypermedia.adoc} |  0
 ...mxPatterns.adoc => CH05_htmxPatterns.adoc} |  2 +-
 ...tterns.adoc => CH06_MorehtmxPatterns.adoc} |  0
 ...oc => CH07_ADynamicArchiveUIWithhtmx.adoc} |  8 +-
 ....adoc => CH08_TricksOfThehtmxMasters.adoc} |  8 +-
 ...09_ScriptingInAHypermediaApplication.adoc} |  0
 ...ONDataAPIs.adoc => CH10_JSONDataAPIs.adoc} |  0
 ...c => CH11_HyperviewAMobileHypermedia.adoc} |  0
 ...12_BuildingAContactsAppWithHyperview.adoc} |  3 +-
 ... => CH13_ExtendingTheHyperviewClient.adoc} |  0
 ...5_Conclusion.adoc => CH14_Conclusion.adoc} |  0
 15 files changed, 16 insertions(+), 112 deletions(-)
 rename book/{CH04_BuildingASimpleWebApplication.adoc => CH03_BuildingASimpleWebApplication.adoc} (99%)
 delete mode 100644 book/CH03_EffectiveHtml.adoc
 rename book/{CH05_ExtendingHTMLAsHypermedia.adoc => CH04_ExtendingHTMLAsHypermedia.adoc} (100%)
 rename book/{CH06_htmxPatterns.adoc => CH05_htmxPatterns.adoc} (99%)
 rename book/{CH07_MorehtmxPatterns.adoc => CH06_MorehtmxPatterns.adoc} (100%)
 rename book/{CH08_ADynamicArchiveUIWithhtmx.adoc => CH07_ADynamicArchiveUIWithhtmx.adoc} (99%)
 rename book/{CH09_TricksOfThehtmxMasters.adoc => CH08_TricksOfThehtmxMasters.adoc} (99%)
 rename book/{CH10_ScriptingInAHypermediaApplication.adoc => CH09_ScriptingInAHypermediaApplication.adoc} (100%)
 rename book/{CH11_JSONDataAPIs.adoc => CH10_JSONDataAPIs.adoc} (100%)
 rename book/{CH12_HyperviewAMobileHypermedia.adoc => CH11_HyperviewAMobileHypermedia.adoc} (100%)
 rename book/{CH13_BuildingAContactsAppWithHyperview.adoc => CH12_BuildingAContactsAppWithHyperview.adoc} (99%)
 rename book/{CH14_ExtendingTheHyperviewClient.adoc => CH13_ExtendingTheHyperviewClient.adoc} (100%)
 rename book/{CH15_Conclusion.adoc => CH14_Conclusion.adoc} (100%)

diff --git a/book/CH01_HypermediaAReintroduction.adoc b/book/CH01_HypermediaAReintroduction.adoc
index 679e8d4..fb5a8ab 100644
--- a/book/CH01_HypermediaAReintroduction.adoc
+++ b/book/CH01_HypermediaAReintroduction.adoc
@@ -130,7 +130,7 @@ network model using the term _REpresentational State Transfer (REST)_.
 Fielding's work became a major touchstone for early web developers, giving them a language to discuss the new technical
 medium they were building applications in.
 
-We will discuss Fielding's key ideas in depth in Chapter 3, and try to correct the record with respect to REST,
+We will discuss Fielding's key ideas in depth in Chapter 2, and try to correct the record with respect to REST,
 HATEOAS and hypermedia.
 
 == The World's Most Successful Hypertext: HTML
@@ -198,7 +198,7 @@ When the link is clicked the browser (or, as we sometimes refer to it, the _hype
 `GET` request to the URL encoded in the link's `href` attribute.
 
 Note that the HTTP request includes additional data (i.e., _metadata_) on what, exactly, the browser wants from the server,
-in the form of headers.  We will discuss these headers, and HTTP in more depth in Chapter 3.
+in the form of headers.  We will discuss these headers, and HTTP in more depth in Chapter 2.
 
 The _hypermedia server_ then responds to this request with a _hypermedia response_ -- the HTML -- for the new page.
 This may seem like a small and obvious point, but it is an absolutely crucial aspect of a truly RESTful _hypermedia
diff --git a/book/CH02_ComponentsOfAHypermediaSystem.adoc b/book/CH02_ComponentsOfAHypermediaSystem.adoc
index a84cfa7..c9180a1 100644
--- a/book/CH02_ComponentsOfAHypermediaSystem.adoc
+++ b/book/CH02_ComponentsOfAHypermediaSystem.adoc
@@ -205,7 +205,7 @@ HTTP (which is the Hypertext Transfer Protocol, after all!): if you wish to issu
 applications.
 
 This is an obvious shortcoming of HTML as a hypermedia; it would be wonderful to see this fixed in the
-HTML specification. For now, we'll discuss ways to get around this in Chapter 5.
+HTML specification. For now, we'll discuss ways to get around this in Chapter 4.
 
 ==== HTTP response codes
 
@@ -779,7 +779,7 @@ should of course be allowed in a Hypermedia-Driven Application.
 
 However, in a Hypermedia-Driven Application the presence of scripting should _not_ change the fundamental networking
 model: hypermedia should still be the engine of application state, server communication should still consist of
-hypermedia exchanges rather than, for example, JSON data exchanges, and so on. (JSON Data API's certainly have their place; in Chapter 11 we'll discuss when and how to use them).
+hypermedia exchanges rather than, for example, JSON data exchanges, and so on. (JSON Data API's certainly have their place; in Chapter 10 we'll discuss when and how to use them).
 
 Today, unfortunately, the scripting layer of the web, JavaScript, is quite often used to _replace_, rather than augment
 the hypermedia model.  We will elaborate in a later chapter what scripting that does not replace the underlying hypermedia
diff --git a/book/CH04_BuildingASimpleWebApplication.adoc b/book/CH03_BuildingASimpleWebApplication.adoc
similarity index 99%
rename from book/CH04_BuildingASimpleWebApplication.adoc
rename to book/CH03_BuildingASimpleWebApplication.adoc
index a1d8c30..7a54a66 100644
--- a/book/CH04_BuildingASimpleWebApplication.adoc
+++ b/book/CH03_BuildingASimpleWebApplication.adoc
@@ -438,7 +438,7 @@ In the first line of code we create a form that will submit back _to the same pa
 Rather than issuing an HTTP `GET` to this path, however, we will issue an HTTP `POST` to it.  Using a `POST` in this manner
 will signal to the server that we want to create a new Contact, rather than get a form.
 
-We then have a label (always a good practice, as mentioned in the last chapter!) and an input that captures the email of
+We then have a label (always a good practice!) and an input that captures the email of
 the contact being created.  The name of the input is `email` and, when this form is submitted, the value of this input
 will be submitted in the `POST` request, associated with the `email` key.
 
diff --git a/book/CH03_EffectiveHtml.adoc b/book/CH03_EffectiveHtml.adoc
deleted file mode 100644
index db95086..0000000
--- a/book/CH03_EffectiveHtml.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-
-= Effective HTML - Pullouts
-
-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.
-Pieces have been moved to end of chapter "'html notes'" (or similar).
-This is just an option to consider.
-
-I we go this route, it would be useful to index or add a ToC entry for 'HTML Topics'
-
-Note: I used [.design-note] to flag for formatting. 
-which... may not be useful
-//// 
-
-
-// TODO: 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>`.
-****
-
-
-
-// TODO: Some readers may want more specific advice on how to write HTML for humans. 
-.Screen Reader Rage
-****
-The spec is a good starting point when deciding how to mark something up,
-but when browser implementations don't conform,
-we shouldn't throw up our hands because we did what was specified.
-
-After all, browser implementers do a _lot_ of work to deal with developers' broken HTML -- is it such a burden to return the favor?
-
-It is frustrating when browsers and other tools misbehave.
-Accessibility itself feels inaccessible sometimes.
-To reduce the frustration it may help to recognize that hypermedia exchanges are not machine-to-machine communication.
-An HTML file is not a program that produces a human-readable document.
-It _is_ the document.
-So, instead of banging your head against a wall, focus on people, not the tools they use.
-
-Don't write HTML for browsers. or assistive tools, or validators.
-HTML is not _for_ them.
-HTML is for humans.
-****
-
-
-// maybe move to ch1? The Essence of HTML as a Hypermedia
-.What is HTML?
-****
-[quote, Marshall McLuhan]
-The medium is the message.
-
-Is it a document format?
-Is it for applications?
-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]
-____
-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.
-
-HTML is a hypermedium.
-
-An HTML file is not a program that produces a human-readable document.
-It _is_ the document.
-****
-
-
-// TODO: keep? some readers will love it, others may wonder how it fits
-format as pullout, like Web Components, ARIA
-.The "`Semantic Web`"
-****
-[quote, '_Mean Girls_ (2004)']
-Gretchen, stop trying to make fetch happen! It's not going to happen!
-
-The "Semantic Web" was a vision of a system that could both express any kind of human knowledge, and be useful for computing.
-It planned to achieve this using _ontologies_, repositories of schemas like "person", "movie" and "species" and relations like "named", "part of" and "created by".
-
-The problem with this vision is that information on the Web rarely fits into neat categories.
-Because no single ontology can be defined that encapsulates all kinds of information one might wish to publish on the Web,
-Semantic Web systems need to be pluggable with different schemas.
-In turn, a Semantic Web client, in order to do something useful with an arbitrary piece of HTML, needs to be able to parse these schemas, which means we need to define a standard machine-readable format for ontologies.
-But a single format couldn't express every kind of object and relation...
-It's turtles all the way down.
-
-In practice, most implementations stop at the topmost turtle.
-Ontologies are defined in natural language,
-and clients are hardcoded to support a fixed set of schemas.
-The requirement for prior agreement between server and client means this technology does not have the generality of the Web,
-and for most use cases, you might as well define a JSON API.
-
-_The Semantic Web has nothing to do with semantic HTML_.
-****
\ No newline at end of file
diff --git a/book/CH05_ExtendingHTMLAsHypermedia.adoc b/book/CH04_ExtendingHTMLAsHypermedia.adoc
similarity index 100%
rename from book/CH05_ExtendingHTMLAsHypermedia.adoc
rename to book/CH04_ExtendingHTMLAsHypermedia.adoc
diff --git a/book/CH06_htmxPatterns.adoc b/book/CH05_htmxPatterns.adoc
similarity index 99%
rename from book/CH06_htmxPatterns.adoc
rename to book/CH05_htmxPatterns.adoc
index ee3a480..5dcbfe8 100644
--- a/book/CH06_htmxPatterns.adoc
+++ b/book/CH05_htmxPatterns.adoc
@@ -509,7 +509,7 @@ Currently, our application has a small amount of validation that is done entirel
 message when an error is detected.
 
 We are not going to go into the details of how validation works in the model objects, but recall what
-the code for updating a contact looks like from Chapter 4:
+the code for updating a contact looks like from Chapter 3:
 
 [source, python]
 .Server-side validation on contact update
diff --git a/book/CH07_MorehtmxPatterns.adoc b/book/CH06_MorehtmxPatterns.adoc
similarity index 100%
rename from book/CH07_MorehtmxPatterns.adoc
rename to book/CH06_MorehtmxPatterns.adoc
diff --git a/book/CH08_ADynamicArchiveUIWithhtmx.adoc b/book/CH07_ADynamicArchiveUIWithhtmx.adoc
similarity index 99%
rename from book/CH08_ADynamicArchiveUIWithhtmx.adoc
rename to book/CH07_ADynamicArchiveUIWithhtmx.adoc
index b20bd9a..5a106e0 100644
--- a/book/CH08_ADynamicArchiveUIWithhtmx.adoc
+++ b/book/CH07_ADynamicArchiveUIWithhtmx.adoc
@@ -506,7 +506,7 @@ As nice as this UI is, there is one minor annoyance: as the progress bar updates
 
 Let's think through the cause of the problem. If you're in a hurry to get to an answer, feel free to jump ahead to "`our solution.`" 
 
-It turns out that there is a native HTML technology for smoothing out changes on an element from one state to another: the CSS Transitions API, the same that we discussed in Chapter 5. Using CSS Transitions, you can smoothly animate an element between different styling by using the `transition` property.
+It turns out that there is a native HTML technology for smoothing out changes on an element from one state to another: the CSS Transitions API, the same that we discussed in Chapter 4. Using CSS Transitions, you can smoothly animate an element between different styling by using the `transition` property.
 
 If you look back at our CSS definition of the `.progress-bar` class, you will see the following transition definition: `transition: width .6s ease;`. This means that when the width of the progress bar is changed from, say 20% to
 30%, the browser will animate over a period of .6 seconds using the "`ease`" function (which has a nice accelerate/decelerate
@@ -522,7 +522,7 @@ The good news: htmx has a way to rectify this situation.
 
 === The "`Settling`" Step in Htmx
 
-When we discussed the htmx swap model in Chapter 5, we focused on the classes that htmx adds and removes, but we skipped
+When we discussed the htmx swap model in Chapter 4, we focused on the classes that htmx adds and removes, but we skipped
 over the process of "`settling.`" In htmx, settling involves several steps:  when htmx is
 about to replace a chunk of content, it looks through the new content and finds all elements with an `id` on it.  It then
 looks in the _existing_ content for elements with the same `id`.  If there is one, it does the following shuffle:
@@ -603,10 +603,10 @@ alternatives. Currently, a progress bar shows the progress of
 the process and, when it completes, the user is presented with a link to actually download the file. Another pattern that we see on the web is "auto-downloading", where the file downloads immediately without the user needing to click a link.
 
 We can add this functionality quite easily to our application with just a bit of scripting.  We will discuss scripting
-in a Hypermedia-Driven Application in more depth in chapter 10, but, put briefly: scripting is perfectly
+in a Hypermedia-Driven Application in more depth in chapter 9, but, put briefly: scripting is perfectly
 acceptable in a HDA, as long as it doesn't replace the core hypermedia mechanics of the application.
 
-For our auto-download feature we will use https://hyperscript.org[+_hyperscript+], our preferred scripting option. JavaScript would also work here, and would be nearly as simple; again, we'll discuss scripting options in Chapter 10.
+For our auto-download feature we will use https://hyperscript.org[+_hyperscript+], our preferred scripting option. JavaScript would also work here, and would be nearly as simple; again, we'll discuss scripting options in Chapter 9.
 
 All we need to do to implement the auto-download feature is the following: when the download link renders, automatically click on the link for the user.
 
diff --git a/book/CH09_TricksOfThehtmxMasters.adoc b/book/CH08_TricksOfThehtmxMasters.adoc
similarity index 99%
rename from book/CH09_TricksOfThehtmxMasters.adoc
rename to book/CH08_TricksOfThehtmxMasters.adoc
index f211362..22d6a26 100644
--- a/book/CH09_TricksOfThehtmxMasters.adoc
+++ b/book/CH08_TricksOfThehtmxMasters.adoc
@@ -45,10 +45,10 @@ options for creating more advanced Hypermedia-Driven Applications.
 
 We'll start with the hx-swap attribute. This is often not included on elements that issue htmx-driven requests because its default behavior -- `innerHTML`, which swaps the inner HTML of the element -- tends to cover most use cases.  
 
-We earlier saw situations where we wanted to override the default behavior and use `outerHTML`, for example.  And, in chapter 3, we discussed some
+We earlier saw situations where we wanted to override the default behavior and use `outerHTML`, for example.  And, in chapter 2, we discussed some
 other swap options beyond these two, `beforebegin`, `afterend`, etc.
 
-In chapter 6, we also looked at the `swap` delay modifier for `hx-swap`, which allowed us to fade some content out before it was removed from the DOM.
+In chapter 5, we also looked at the `swap` delay modifier for `hx-swap`, which allowed us to fade some content out before it was removed from the DOM.
 
 In addition to these, `hx-swap` offers further control with the following modifiers:
 
@@ -433,7 +433,7 @@ an idea of how the `HX-Trigger` response header can be used to coordinate sophis
 == HTTP Requests & Responses
 
 We have just seen an advanced feature of HTTP responses supported by htmx, the `HX-Trigger` response header,
-but htmx supports quite a few more headers for both requests and responses.  In chapter 5 we discussed the
+but htmx supports quite a few more headers for both requests and responses.  In chapter 4 we discussed the
 headers present in HTTP Requests.  Here are some of the more important headers you can use to change htmx behavior with
 HTTP responses:
 
@@ -454,7 +454,7 @@ You can find a reference for all requests and response headers in the https://ht
 === HTTP Response Codes
 
 Even more important than response headers, in terms of information conveyed to the client, is the _HTTP Response Code_.
-We discussed HTTP Response Codes in Chapter 4.  By and large htmx handles various response codes in the manner that
+We discussed HTTP Response Codes in Chapter 3.  By and large htmx handles various response codes in the manner that
 you would expect: it swaps content for all 200-level response codes and does nothing for others.  There are, however,
 two "`special`" 200-level response codes:
 
diff --git a/book/CH10_ScriptingInAHypermediaApplication.adoc b/book/CH09_ScriptingInAHypermediaApplication.adoc
similarity index 100%
rename from book/CH10_ScriptingInAHypermediaApplication.adoc
rename to book/CH09_ScriptingInAHypermediaApplication.adoc
diff --git a/book/CH11_JSONDataAPIs.adoc b/book/CH10_JSONDataAPIs.adoc
similarity index 100%
rename from book/CH11_JSONDataAPIs.adoc
rename to book/CH10_JSONDataAPIs.adoc
diff --git a/book/CH12_HyperviewAMobileHypermedia.adoc b/book/CH11_HyperviewAMobileHypermedia.adoc
similarity index 100%
rename from book/CH12_HyperviewAMobileHypermedia.adoc
rename to book/CH11_HyperviewAMobileHypermedia.adoc
diff --git a/book/CH13_BuildingAContactsAppWithHyperview.adoc b/book/CH12_BuildingAContactsAppWithHyperview.adoc
similarity index 99%
rename from book/CH13_BuildingAContactsAppWithHyperview.adoc
rename to book/CH12_BuildingAContactsAppWithHyperview.adoc
index 570fc27..de4d9dd 100644
--- a/book/CH13_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH12_BuildingAContactsAppWithHyperview.adoc
@@ -12,7 +12,7 @@ This chapter covers:
 
 Earlier chapters in this book explained the benefits of building apps using the hypermedia architecture.
 These benefits were demonstrated by building a robust Contacts web application.
-Then, Chapter 6 argued that hypermedia concepts can and should be applied to platforms other than the Web.
+Then, Chapter 11 argued that hypermedia concepts can and should be applied to platforms other than the Web.
 We introduced Hyperview as an example of a hypermedia format and client specifically designed for building mobile apps.
 But you may still be wondering: what is it like to create a fully-featured, production-ready mobile app using Hyperview?
 Do we have to learn a whole new language and framework?
@@ -1320,6 +1320,7 @@ Since our HXML templates don't expose any entrypoints to the Archive functionali
 
 
 // TODO: okay, or better as integrated info gem?
+[.design-note]
 .HTML Notes: Remember <details>
 ****
 Does the information need to be presented as tabs?
diff --git a/book/CH14_ExtendingTheHyperviewClient.adoc b/book/CH13_ExtendingTheHyperviewClient.adoc
similarity index 100%
rename from book/CH14_ExtendingTheHyperviewClient.adoc
rename to book/CH13_ExtendingTheHyperviewClient.adoc
diff --git a/book/CH15_Conclusion.adoc b/book/CH14_Conclusion.adoc
similarity index 100%
rename from book/CH15_Conclusion.adoc
rename to book/CH14_Conclusion.adoc

From 593004780cef95895e8e450620508242870c6cc0 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sun, 16 Apr 2023 10:23:35 -0400
Subject: [PATCH 11/18] chapter numbers updated

---
 book/CH03_BuildingASimpleWebApplication.adoc     | 2 +-
 book/CH04_ExtendingHTMLAsHypermedia.adoc         | 2 +-
 book/CH05_htmxPatterns.adoc                      | 2 +-
 book/CH06_MorehtmxPatterns.adoc                  | 2 +-
 book/CH07_ADynamicArchiveUIWithhtmx.adoc         | 2 +-
 book/CH08_TricksOfThehtmxMasters.adoc            | 2 +-
 book/CH09_ScriptingInAHypermediaApplication.adoc | 2 +-
 book/CH10_JSONDataAPIs.adoc                      | 2 +-
 book/CH11_HyperviewAMobileHypermedia.adoc        | 2 +-
 book/CH12_BuildingAContactsAppWithHyperview.adoc | 2 +-
 book/CH13_ExtendingTheHyperviewClient.adoc       | 2 +-
 book/CH14_Conclusion.adoc                        | 2 +-
 12 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/book/CH03_BuildingASimpleWebApplication.adoc b/book/CH03_BuildingASimpleWebApplication.adoc
index 7a54a66..8563f3c 100644
--- a/book/CH03_BuildingASimpleWebApplication.adoc
+++ b/book/CH03_BuildingASimpleWebApplication.adoc
@@ -1,6 +1,6 @@
 
 = A Web 1.0 Application
-:chapter: 04
+:chapter: 03
 :url: ./a-web-1-0-application/
 
 To start our journey into Hypermedia-Driven Applications, we are going to create a simple contact management web
diff --git a/book/CH04_ExtendingHTMLAsHypermedia.adoc b/book/CH04_ExtendingHTMLAsHypermedia.adoc
index adc244c..f46b70c 100644
--- a/book/CH04_ExtendingHTMLAsHypermedia.adoc
+++ b/book/CH04_ExtendingHTMLAsHypermedia.adoc
@@ -1,6 +1,6 @@
 
 = Extending HTML As Hypermedia
-:chapter: 05
+:chapter: 04
 :part: Hypermedia-Driven Web Applications with Htmx
 :part_url: ./part/htmx/
 :url: ./extending-html-as-hypermedia/
diff --git a/book/CH05_htmxPatterns.adoc b/book/CH05_htmxPatterns.adoc
index 5dcbfe8..cbf329c 100644
--- a/book/CH05_htmxPatterns.adoc
+++ b/book/CH05_htmxPatterns.adoc
@@ -1,6 +1,6 @@
 
 = Htmx Patterns
-:chapter: 06
+:chapter: 05
 :url: ./htmx-in-action/
 
 Now that we've seen how htmx extends HTML as a hypermedia, it's time to put it into action.  As we use htmx, we will still
diff --git a/book/CH06_MorehtmxPatterns.adoc b/book/CH06_MorehtmxPatterns.adoc
index d380c3b..5a95013 100644
--- a/book/CH06_MorehtmxPatterns.adoc
+++ b/book/CH06_MorehtmxPatterns.adoc
@@ -1,6 +1,6 @@
 
 = More Htmx Patterns
-:chapter: 07
+:chapter: 06
 :url: ./more-htmx-patterns/
 
 == Active Search
diff --git a/book/CH07_ADynamicArchiveUIWithhtmx.adoc b/book/CH07_ADynamicArchiveUIWithhtmx.adoc
index 5a106e0..5d8895b 100644
--- a/book/CH07_ADynamicArchiveUIWithhtmx.adoc
+++ b/book/CH07_ADynamicArchiveUIWithhtmx.adoc
@@ -1,6 +1,6 @@
 
 = A Dynamic Archive UI
-:chapter: 08
+:chapter: 07
 :url: ./a-dynamic-archive-ui/
 
 == A Dynamic Archive UI
diff --git a/book/CH08_TricksOfThehtmxMasters.adoc b/book/CH08_TricksOfThehtmxMasters.adoc
index 22d6a26..9c00fb3 100644
--- a/book/CH08_TricksOfThehtmxMasters.adoc
+++ b/book/CH08_TricksOfThehtmxMasters.adoc
@@ -1,6 +1,6 @@
 
 = Tricks Of The Htmx Masters
-:chapter: 09
+:chapter: 08
 :url: ./deep-htmx/
 
 
diff --git a/book/CH09_ScriptingInAHypermediaApplication.adoc b/book/CH09_ScriptingInAHypermediaApplication.adoc
index 5dcb514..47fe6ae 100644
--- a/book/CH09_ScriptingInAHypermediaApplication.adoc
+++ b/book/CH09_ScriptingInAHypermediaApplication.adoc
@@ -1,6 +1,6 @@
 
 = Client-Side Scripting
-:chapter: 10
+:chapter: 09
 :url: ./client-side-scripting/
 
 [quote, Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures]
diff --git a/book/CH10_JSONDataAPIs.adoc b/book/CH10_JSONDataAPIs.adoc
index 0e7524e..40ba284 100644
--- a/book/CH10_JSONDataAPIs.adoc
+++ b/book/CH10_JSONDataAPIs.adoc
@@ -1,6 +1,6 @@
 
 = JSON Data APIs & Hypermedia-Driven Applications
-:chapter: 11
+:chapter: 10
 :url: ./json-data-apis/
 
 [partintro]
diff --git a/book/CH11_HyperviewAMobileHypermedia.adoc b/book/CH11_HyperviewAMobileHypermedia.adoc
index ad7f6f8..578477f 100644
--- a/book/CH11_HyperviewAMobileHypermedia.adoc
+++ b/book/CH11_HyperviewAMobileHypermedia.adoc
@@ -1,6 +1,6 @@
 
 = Hyperview: A Mobile Hypermedia
-:chapter: 12
+:chapter: 11
 :part: Bringing Hypermedia To Mobile
 :part_url: ./part/hyperview/
 :url: ./hyperview-a-mobile-hypermedia/
diff --git a/book/CH12_BuildingAContactsAppWithHyperview.adoc b/book/CH12_BuildingAContactsAppWithHyperview.adoc
index de4d9dd..8a3b12d 100644
--- a/book/CH12_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH12_BuildingAContactsAppWithHyperview.adoc
@@ -1,6 +1,6 @@
 
 = Building a Contacts App With Hyperview
-:chapter: 13
+:chapter: 12
 :url: ./building-a-contacts-app-with-hyperview/
 
 This chapter covers:
diff --git a/book/CH13_ExtendingTheHyperviewClient.adoc b/book/CH13_ExtendingTheHyperviewClient.adoc
index b3e4d4e..5689c8a 100644
--- a/book/CH13_ExtendingTheHyperviewClient.adoc
+++ b/book/CH13_ExtendingTheHyperviewClient.adoc
@@ -1,6 +1,6 @@
 
 = Extending the Hyperview Client
-:chapter: 14
+:chapter: 13
 :url: ./extending-the-hypermedia-client/
 
 This chapter covers:
diff --git a/book/CH14_Conclusion.adoc b/book/CH14_Conclusion.adoc
index 8f9d55c..df1ad9d 100644
--- a/book/CH14_Conclusion.adoc
+++ b/book/CH14_Conclusion.adoc
@@ -1,6 +1,6 @@
 
 = Conclusion
-:chapter: 15
+:chapter: 14
 :part: Conclusion
 :part_url: ./part/conclusion/
 :url: ./conclusion/

From fca95c604db337c447401271364669a92b0be015 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sun, 16 Apr 2023 17:50:46 -0400
Subject: [PATCH 12/18] ch12 intro

---
 book/CH12_BuildingAContactsAppWithHyperview.adoc | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/book/CH12_BuildingAContactsAppWithHyperview.adoc b/book/CH12_BuildingAContactsAppWithHyperview.adoc
index 8a3b12d..b26876f 100644
--- a/book/CH12_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH12_BuildingAContactsAppWithHyperview.adoc
@@ -3,12 +3,6 @@
 :chapter: 12
 :url: ./building-a-contacts-app-with-hyperview/
 
-This chapter covers:
-
-* Transforming the existing Contacts web app into a native mobile app using Hyperview
-* Using Hyperview behaviors to navigate between screens using stacks and modals
-* Communicating between screens using the Events system
-* Using the same backend to power both the web app and mobile app
 
 Earlier chapters in this book explained the benefits of building apps using the hypermedia architecture.
 These benefits were demonstrated by building a robust Contacts web application.

From 6579c246d1beb2714737a21808542dcfdab600a2 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Sun, 16 Apr 2023 17:53:05 -0400
Subject: [PATCH 13/18] ch13 intro

---
 book/CH13_ExtendingTheHyperviewClient.adoc | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/book/CH13_ExtendingTheHyperviewClient.adoc b/book/CH13_ExtendingTheHyperviewClient.adoc
index 5689c8a..2f93c3a 100644
--- a/book/CH13_ExtendingTheHyperviewClient.adoc
+++ b/book/CH13_ExtendingTheHyperviewClient.adoc
@@ -3,11 +3,6 @@
 :chapter: 13
 :url: ./extending-the-hypermedia-client/
 
-This chapter covers:
-
-* Adding phone call and email integration with a custom behavior action
-* Showing confirmation toast messages with a custom behavior action
-* Supporting a "`swipeable row`" UI with a custom Hyperview component
 
 In the previous chapter, we created a fully-featured native mobile version of our Contacts app.
 Aside from customizing the entrypoint URL, we didn't need to touch any code that runs on the mobile device.

From 56d8ae513d82ca83bcbf49815c599ed584674883 Mon Sep 17 00:00:00 2001
From: codetalcott <32972881+codetalcott@users.noreply.github.com>
Date: Tue, 18 Apr 2023 12:55:04 -0400
Subject: [PATCH 14/18] Update CH12_BuildingAContactsAppWithHyperview.adoc

minor edits
---
 book/CH12_BuildingAContactsAppWithHyperview.adoc | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/book/CH12_BuildingAContactsAppWithHyperview.adoc b/book/CH12_BuildingAContactsAppWithHyperview.adoc
index b26876f..af2ae52 100644
--- a/book/CH12_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH12_BuildingAContactsAppWithHyperview.adoc
@@ -30,11 +30,11 @@ We can directly port web app features implemented with htmx (search, infinite lo
 
 Essentially, we can re-use almost everything from the web app backend, but we will need to replace the HTML templates with HXML templates.
 Most of the sections in this chapter will assume we have the web contacts app running locally and listening on port 5000.
-The focus will be on creating new HXML templates for our mobile app's UI.
+Ready? Let's create new HXML templates for our mobile app's UI.
 
 == Creating a mobile app
 
-But before we dive into HXML, there's one pesky requirement: the Hyperview client.
+To get started with HXML, there's one pesky requirement: the Hyperview client.
 When developing web applications, you only need to worry about the server because the client (web browser) is universally available.
 There's no equivalent Hyperview client installed on every mobile device.
 Instead, we will create our own Hyperview client, customized to only talk to our server.
@@ -75,7 +75,7 @@ With our Hyperview client now pointing to the right endpoint, we see a different
 That's because the backend is responding to requests with HTML content, but the Hyperview client expects an XML response (specifically, HXML).
 So it's time to turn our attention to our Flask backend.
 We will go through the Flask views, and replace the HTML templates with HXML templates.
-Specifically, let's support the following features to our mobile app:
+Specifically, let's support the following features in our mobile app:
 
 - A searchable list of contacts
 - Viewing the details of a contact
@@ -1332,4 +1332,4 @@ Sometimes the answer is yes, but if not, a sequence of details and disclosures f
 
 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.
-****
\ No newline at end of file
+****

From 34fd7f635a51ac59302776270750b0c30cbbf1ce Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Tue, 18 Apr 2023 20:48:00 -0400
Subject: [PATCH 15/18] edits, Hyperview chapters

---
 book/CH11_HyperviewAMobileHypermedia.adoc     |  21 +-
 ...H12_BuildingAContactsAppWithHyperview.adoc | 198 ++++++++++--------
 book/CH13_ExtendingTheHyperviewClient.adoc    |  16 +-
 3 files changed, 127 insertions(+), 108 deletions(-)

diff --git a/book/CH11_HyperviewAMobileHypermedia.adoc b/book/CH11_HyperviewAMobileHypermedia.adoc
index 578477f..03b95be 100644
--- a/book/CH11_HyperviewAMobileHypermedia.adoc
+++ b/book/CH11_HyperviewAMobileHypermedia.adoc
@@ -1242,28 +1242,27 @@ These concepts can be mixed together too.
 It's not unusual for a production Hyperview app to contain several behaviors, some triggering together and others triggering on different interactions.
 Using multiple behaviors with custom actions keeps HXML declarative, without sacrificing functionality.
 
-=== Quick Sketch: Elements of Hyperview
-We've covered a lot of new material, so here is a quick summary of the key aspects of Hyperview:
-
+// TODO: keep? reformat?
+.HXML and Hyperview in Brief
+****
 - HXML looks similar to HTML, but it uses elements that correspond to mobile UIs, like `<screen>`, `<header>`, `<list>` and more.
-- HXML also includes input elements that implement common patterns in mobile apps, such as `<switch>`, `<select-single>`, and `<select-multiple>`.
+- HXML includes input elements that implement common patterns in mobile apps, such as `<switch>`, `<select-single>`, and `<select-multiple>`.
 - New UI components can be added to HXML using namespaced elements. The Hyperview client can be easily extended to render these new elements.
 - Interactions in HXML are defined using `<behavior>` elements. Inspired by htmx, `<behavior>` elements decouple user interactions (triggers) from the resulting actions.
 - Navigation between screens in Hyperview is done using behaviors with navigation actions, like `push`, `back`, `new`, and `close`.
 - Updates to screens in Hyperview are defined using behaviors with update actions, such as `replace` and `append`.
 - System interactions in Hyperview are defined using behaviors with system actions, such as `alert` and `share`.
 - New actions can be added to HXML using namespaced attributes. The Hyperview client can be easily extended to interpret the new actions.
+****
 
+// TODO: suggested conclusion, transition
+== Hypermedia, for Mobile
 
-== Summary
+There is a story for Hypermedia-Driven Applications on mobile. Mobile app platforms push developers towards a thick-client architecture. But apps that use a thick client suffer from the same problems as SPAs on the web. Using the hypermedia architecture for mobile apps can solve these problems.
 
-Mobile app platforms push developers towards a thick-client architecture. But apps that use a thick client suffer from the same problems as SPAs on the web. Using the hypermedia architecture for mobile apps can solve these problems.
+Hyperview, based on a new format called HXML, offers a path here. It provides an open-source mobile thin-client to render HXML. And HXML opens a took-kit of elements and patterns that correspond to mobile UIs. Developers can evolve Hyperview to suit their apps' requirements, while fully embracing the hypermedia architecture. That's a win.
 
-One way to implement the hypermedia architecture for mobile apps is with HTML web views. But HTML is not designed for mobile UIs, so this approach does not deliver a great user experience. 
- 
-Hyperview offers an alternative approach using the hypermedia architecture, based on a new format called HXML. It also provides an open-source mobile thin-client to render HXML. Again, HXML looks similar to HTML, but it uses elements and patterns that correspond to mobile UIs.
-
-The extensibility of HXML and the Hyperview client make it easy to define custom elements and behaviors. Developers can evolve Hyperview to suit their apps' requirements, while fully embracing the hypermedia architecture.
+Yes, hypermedia works for mobile, too. In the next two chapters we'll show how by moving Contact.app to mobile. 
 
 
 
diff --git a/book/CH12_BuildingAContactsAppWithHyperview.adoc b/book/CH12_BuildingAContactsAppWithHyperview.adoc
index af2ae52..6176632 100644
--- a/book/CH12_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH12_BuildingAContactsAppWithHyperview.adoc
@@ -91,7 +91,7 @@ Think of the entrypoint URL as the address you type into a web browser to open a
 Except in Hyperview, there is no address bar, and the browser is hard-coded to only open one URL.
 This URL will load the first screen when a user launches the app.
 Every other action the user can take will be declared in the HXML of that first screen.
-This minimal configuration is one elegant aspect of the Hypermedia-driven architecture!
+This minimal configuration is one of the benefits of the Hypermedia-driven architecture.
 
 Of course, you may want to write more on-device code to support more features in your mobile app.
 We will demonstrate how to do that later in this chapter, in the section called "`Extending the Client.`"
@@ -110,7 +110,7 @@ Additionally, we will add a "`pull-to-refresh`" interaction on the list, since u
 
 If you recall, all of the pages in the Contacts web app extended a common base template, `layout.html`.
 We need a similar base template for the screens of the mobile app.
-This base template will contain the style rules or our UI, and a basic structure common to all screens.
+This base template will contain the style rules of our UI, and a basic structure common to all screens.
 Let's call it `layout.xml`.
 
 .Base template `hv/layout.xml`
@@ -133,10 +133,10 @@ Let's call it `layout.xml`.
   </screen>
 </doc>
 ----
-<1> The header section of the template, with a default title
+<1> The header section of the template, with a default title.
 <2> The content section of the template, to be provided by other templates.
 
-We covered the HXML tags and attributes in the previous chapter.
+We're using the HXML tags and attributes covered in the previous chapter.
 This template sets up a basic screen layout using `<doc>`, `<screen>`, `<body>`, `<header>`, and `<view>` tags.
 Note that the HXML syntax plays well with the Jinja templating library.
 Here, we're using Jinja's blocks to define two sections (`header` and `content`) that will hold the unique content of a screen.
@@ -188,8 +188,8 @@ It also allows the server to respond with just the `rows.xml` template for inter
   {% endfor %}
 </items>
 ----
-<1> An HXML element that groups a set of `<item>` elements in a common parent
-<2> Iterate over the contacts that were passed in to the template
+<1> An HXML element that groups a set of `<item>` elements in a common parent.
+<2> Iterate over the contacts that were passed in to the template.
 <3> Render an `<item>` for each contact, showing the name, phone number, or email.
 
 In the web app, each row in the list showed the contact's name, phone number, and email address.
@@ -249,8 +249,8 @@ def contacts():
     template_name = "hv/rows.xml" if rows_only else "hv/index.xml" <2>
     return render_template(template_name, contacts=contacts_set, page=page)
 ----
-<1> Check for a new `rows_only` query param
-<2> Render the appropriate HXML template based on `rows_only`
+<1> Check for a new `rows_only` query param.
+<2> Render the appropriate HXML template based on `rows_only`.
 
 There's one more change we have to make.
 Flask assumes that most views will respond with HTML.
@@ -270,7 +270,7 @@ def render_to_response(template_name, *args, **kwargs):
     return response
 ----
 <1> Renders the given template with the supplied arguments and keyword arguments.
-<2> Create an explicit response object with the rendered template
+<2> Create an explicit response object with the rendered template.
 <3> Sets the response `Content-Type` header to XML.
 
 As you can see, this helper function uses `render_template()` under the hood.
@@ -316,7 +316,7 @@ This requires expanding `<text-field>` to add a `<behavior>` element.
   />
 </text-field>
 ----
-<1> This behavior will trigger when the value of the text field changes
+<1> This behavior will trigger when the value of the text field changes.
 <2> When the behavior triggers, the action will replace the content inside the target element.
 <3> The target of the action is the element with ID `contacts-list`.
 <4> The replacement content will be fetched from this URL path.
@@ -324,16 +324,17 @@ This requires expanding `<text-field>` to add a `<behavior>` element.
 
 The first thing you'll notice is that we changed the text field from using a self-closing tag (`<text-field />`) to using opening and closing tags (`<text-field>...</text-field>`).
 This allows us to add a child `<behavior>` element to define an interaction.
+
 The `trigger="change"` attribute tells Hyperview that a change to the value of the text field will trigger an action.
 Any time the user edits the content of the text field by adding or deleting characters, an action will trigger.
+
 The remaining attributes on the `<behavior>` element define the action.
 `action="replace-inner"` means the action will update content on the screen, by replacing the HXML content of an element with new content.
 For `replace-inner` to do its thing, we need to know two things: the current element on the screen that will be targeted by the action, and the content that will used for the replacement.
 `target="contacts-list"` tells us the ID of the current element.
 Note that we set `id="contacts-list"` on the `<list>` element in `index.xml`.
 So when the user enters a search query into the text field, Hyperview will replace the content of `<list>` (a bunch of `<item>` elements)
-with new content (`<item>` elements that match the search query) received in the relative href response
-(the domain is inferred from the domain used to fetch the screen).
+with new content (`<item>` elements that match the search query) received in the relative href response. The domain here is inferred from the domain used to fetch the screen.
 Note that `href` includes our `rows_only` query param; we want the response to only include the rows and not the entire screen.
 
 .Searching for Contacts
@@ -350,11 +351,11 @@ So the value of the `<text-field>` will be included in our HTTP request for the
 Since we are making a `GET` request, the name and value of the text field will be serialized as a query param.
 Any existing query params on the `href` will be preserved.
 This means the actual HTTP request to our backend looks like `GET /contacts?rows_only=true&q=Car`.
-Our backend already supports the `q` param for searching, so the response will include rows that match the string "`Car`".
+Our backend already supports the `q` param for searching, so the response will include rows that match the string "`Car.`"
 
 === Infinite scroll
 If the user has hundreds or thousands of contacts, loading them all at once may result in poor app performance.
-That's why most mobile apps with long lists implement an interaction known as "`infinite scroll`".
+That's why most mobile apps with long lists implement an interaction known as "`infinite scroll.`"
 The app loads a fixed number of initial items in the list, let's say 100 items.
 If the user scrolls to the bottom of the list, they see a spinner indicating more content is loading.
 Once the content is available, the spinner is replaced with the next page of 100 items.
@@ -394,23 +395,25 @@ To do this, let's edit `rows.xml` to add a new `<item>` below the Jinja for-loop
   {% endif %}
 </items>
 ----
-<1> Include an extra `<item>` in the list to show the spinner
-<2> The item behavior triggers when visible in the viewport
-<3> When triggered, the behavior will replace an element on the screen
-<4> The element to be replaced is the item itself (ID `load-more`)
-<5> Replace the item with the next page of content
-<6> The spinner element
+<1> Include an extra `<item>` in the list to show the spinner.
+<2> The item behavior triggers when visible in the viewport.
+<3> When triggered, the behavior will replace an element on the screen.
+<4> The element to be replaced is the item itself (ID `load-more`).
+<5> Replace the item with the next page of content.
+<6> The spinner element.
 
 If the current list of contacts passed to the template is empty, we can assume there's no more contacts to fetch from the backend.
 So we use a Jinja conditional to only include this new `<item>` if the list of contacts is non-empty.
 This new `<item>` element gets an ID and a behavior.
 The behavior defines the infinite scroll interaction.
+
 Up until now, we've seen `trigger` values of `change` and `refresh`.
 But to implement infinite scroll, we need a way to trigger the action when the user scrolls to the bottom of the list.
 The `visible` trigger can be used for this exact purpose.
 It will trigger the action when the element with the behavior is visible in the device viewport.
 In this case, the new `<item>` element is the last item in the list, so the action will trigger when the user scrolls down far enough for the item to enter the viewport.
 As soon as the item is visible, the action will make an HTTP GET request, and replace the loading `<item>` element with the response content.
+
 Note that our href must include the `rows_only=true` query param, so that our response will only include HXML for the contact items, and not the entire screen.
 Also, we're passing the `page` query param, incrementing the current page number to ensure we load the next page.
 
@@ -460,6 +463,7 @@ Let's add pull-to-refresh to our list of contacts to see it in action.
 You'll notice something unusual in the snippet above: rather than adding a `<behavior>` element to the `<list>`, we added the behavior attributes directly to the `<list>` element.
 This is a shorthand notation that's sometimes useful for specifying single behaviors on an element.
 It is equivalent to adding a `<behavior>` element to the `<list>` with the same attributes.
+
 So why did we use the shorthand syntax here?
 It has to do with the action, `replace-inner`.
 Remember, this action replaces all child elements of the target with the new content.
@@ -468,7 +472,7 @@ Let's say our `<list>` did contain a `<behavior>`.
 If the user did a search or pull-to-refresh, we would replace the content of `<list>` with the content from `rows.xml`.
 The `<behavior>` would no longer be defined on the `<list>`, and subsequent attempts to pull-to-refresh would not work.
 By defining the behavior as attributes of `<list>`, the behavior will persist even when replacing the items in the list.
-Generally, we prefer to use explicit `<behavior>` elements in my HXML.
+Generally, we prefer to use explicit `<behavior>` elements in HXML.
 It makes it easier to define multiple behaviors, and to move the behavior around while refactoring.
 But the shorthand syntax is good to apply in situations like this.
 
@@ -511,7 +515,7 @@ def contacts_view(contact_id=0):
 ----
 <1> Generate an XML response from a new template file.
 
-Just like with the `contacts()` view, `contacts_view()` uses `render_to_response()` to set the `Content-Type` header on the response.
+Just like the `contacts()` view, `contacts_view()` uses `render_to_response()` to set the `Content-Type` header on the response.
 We're also generating the response from a new HXML template, which we can create now:
 
 .`hv/show.xml`
@@ -542,20 +546,21 @@ We're also generating the response from a new HXML template, which we can create
 </view>
 {% endblock %}
 ----
-<1> Extend the base layout template
-<2> Override the `header` block of the layout template to include a "Back" button
-<3> Behavior to navigate to the previous screen when pressed
+<1> Extend the base layout template.
+<2> Override the `header` block of the layout template to include a "Back" button.
+<3> Behavior to navigate to the previous screen when pressed.
 <4> Override the `content` block to show the full details of the selected contact.
 
 The contacts detail screen extends the base `layout.xml` template, just like we did in `index.xml`.
 This time, we're overriding content in both the `header` block and `content` block.
 Overriding the header block lets us add a "Back" button with a behavior.
 When pressed, the Hyperview client will unwind the navigation stack and return the user to the contacts list.
+
 Note that triggering this behavior is not the only way to navigate back.
 The Hyperview client respects navigation conventions on different platforms.
 On iOS, users can also navigate to the previous screen by swiping right from the left edge of the device.
 On Android, users can also navigate to the previous screen by pressing the hardware back button.
-We don't need to specify anything extra in the HXML to get these interactions!
+We don't need to specify anything extra in the HXML to get these interactions.
 
 .Contact Details Screen
 image::screenshot_hyperview_detail_cropped.png[Contact detail shows phone number and email as well as back and edit buttons in navbar]
@@ -596,12 +601,12 @@ This button can be added to the header of the contact details screen.
   </text>
 {% endblock %}
 ----
-<1> The new "`Edit`" button
-<2> Behavior to reload the current screen with the edit screen when pressed
+<1> The new "`Edit`" button.
+<2> Behavior to reload the current screen with the edit screen when pressed.
 
 Once again, we're reusing an existing Flask route (`/contacts/<contact_id>/edit`) for the edit UI, and filling in the contact ID using data passed to the Jinja template.
 We also need to update the `contacts_edit_get()` view to return an XML response based on an HXML template (`hv/edit.xml`).
-I'll skip the code sample because the needed changes are identical to what we applied to `contacts_view()` in the previous section.
+We'll skip the code sample because the needed changes are identical to what we applied to `contacts_view()` in the previous section.
 Instead, let's focus on the template for the edit screen.
 
 .`hv/edit.xml`
@@ -635,10 +640,10 @@ Instead, let's focus on the template for the edit screen.
 </form>
 {% endblock %}
 ----
-<1> Form wrapping the input fields and buttons
-<2> Container with ID, containing the input fields
-<3> Template include to render the input fields
-<4> Button to submit the form data and update the input fields container
+<1> Form wrapping the input fields and buttons.
+<2> Container with ID, containing the input fields.
+<3> Template include to render the input fields.
+<4> Button to submit the form data and update the input fields container.
 
 Since the edit screen needs to send data to the backend, we wrap the entire content section in a `<form>` element.
 This ensures the form field data will be included in the HTTP requests to our backend.
@@ -662,11 +667,11 @@ The actual form fields are defined in a separate template (`form_fields.xml`) an
   <!-- same markup for contact.email and contact.phone -->
 </view>
 ----
-<1> Text input holding the current value for the contact's first name
-<2> Text element that could display errors from the contact model
-<3> Another text field, this time for the contact's last name
+<1> Text input holding the current value for the contact's first name.
+<2> Text element that could display errors from the contact model.
+<3> Another text field, this time for the contact's last name.
 
-I omitted the code for the contact's phone number and email address, because they follow the same pattern as the first and last name.
+We omitted the code for the contact's phone number and email address, because they follow the same pattern as the first and last name.
 Each contact field has its own `<text-field>`, and a `<text>` element below it to display possible errors.
 The `<text-field>` has two important attributes:
 
@@ -683,7 +688,7 @@ The HXML response will replace the contents of form field container (ID `form-fi
 But what should that response be?
 That depends on the validity of the form data:
 
-1. If the data is invalid (eg duplicate email address), our UI will remain in the editing mode and show error messages on the invalid fields.
+1. If the data is invalid (e.g., duplicate email address), our UI will remain in the editing mode and show error messages on the invalid fields.
 This allows the user to correct the errors and try saving again.
 2. If the data is valid, our backend will persist the edits, and our UI will switch back to a display mode (the contact details UI).
 
@@ -736,19 +741,20 @@ We will update the template to use this flag to implement our desired UI: switch
 </view>
 ----
 <1> Only include this behavior after successfully saving a contact.
-<2> Trigger the behavior immediately
-<3> The behavior will reload the entire screen
+<2> Trigger the behavior immediately.
+<3> The behavior will reload the entire screen.
 <4> The screen will be reloaded with the contact details screen.
 
 The Jinja template conditional ensures that our behavior only renders on successful saves, and not when the screen first opens (or the user submits invalid data).
 On success, the template includes a behavior that triggers immediately thanks to `trigger="load"`.
 The action reloads the current screen with the Contact Details screen (from the `/contacts/<contact_id>` route).
+
 The result?
 When the user hits "`Save`", our backend persists the new contact data, and the screen switches back to the Details screen.
 Since the app will make a new HTTP request to get the contact details, it's guaranteed to show the freshly saved edits.
 
 
-.Why not use a redirect?
+.Why Not Redirect?
 ****
 You may remember the web app version of this code behaved a little differently.
 On a successful save, the view returned `redirect("/contacts/" + str(contact_id))`.
@@ -762,6 +768,7 @@ Mobile apps use a nested hierarchy of navigation stacks, modals, and tabs.
 All screens in this hierarchy are active, and may be displayed instantly in response to user actions.
 In this world, how would the Hyperview client interpret an HTTP redirect?
 Should it reload the current screen, push a new one, or navigate to a screen in the stack with the same URL?
+
 Instead of making a choice that would be suboptimal for many scenarios, Hyperview takes a different approach.
 Server-controlled redirects are not possible, but the backend can render navigation behaviors into the HXML.
 This is what we do to switch from the Edit UI to the Details UI in the code above.
@@ -796,12 +803,12 @@ We can add this as a new button below the "`Save`" button.
   <text style="button-label">Cancel</text>
 </view>
 ----
-<1> New Cancel button on the edit screen
-<2> When pressed, reload the entire screen
+<1> A new Cancel button on the edit screen.
+<2> When pressed, reload the entire screen.
 <3> The screen will be reloaded with the contact details screen.
 
 This is the same technique we used to switch from the edit UI to the details UI upon successfully editing the contact.
-But pressing "`Cancel`" will update the UI faster than pressing "`Save`".
+But pressing "`Cancel`" will update the UI faster than pressing "`Save.`"
 On save, the app will first make a `POST` request to save the data, and then a `GET` request for the details screen.
 Cancelling skips the `POST`, and immediately makes the `GET` request.
 
@@ -819,16 +826,17 @@ Let's walk through this series of interactions:
 
 1. Launch the app to the Contacts List.
 2. Press on the contact "`Joe Blow`" to load his Contact Details.
-3. Press Edit to switch to the edit mode, and change the contact's first name to "`Joseph`".
-4. Press Save to switch back to viewing mode. The contact's name is now "`Joseph Blow`".
+3. Press Edit to switch to the edit mode, and change the contact's first name to "`Joseph.`"
+4. Press Save to switch back to viewing mode. The contact's name is now "`Joseph Blow.`"
 5. Hit the back button to return to the Contacts List.
 
 Did you catch the issue?
 Our Contacts list is still showing the same list of names as when we launched the app.
-The contact we just renamed to "`Joseph`" is still showing up in the list as "`Joe`".
-This is a general problem in Hypermedia applications.
+The contact we just renamed to "`Joseph`" is still showing up in the list as "`Joe.`"
+This is a general problem in hypermedia applications.
 The client does not have a notion of shared data across different parts of the UI.
 Updates in one part of the app will not automatically update other parts of the app.
+
 Luckily, there's a solution to this problem in Hyperview: events.
 Events are built into the behavior system, and allow lightweight communication between different parts of the UI.
 
@@ -836,9 +844,12 @@ Events are built into the behavior system, and allow lightweight communication b
 .Event Behaviors
 ****
 Events are a client-side feature of Hyperview.
-You are probably familiar with events from working with HTML and the DOM.
+Earlier chapter discussed events while working with HTML, htmx and the DOM.
 DOM Elements will dispatch events as a result of user interactions.
 Scripts can listen for these events, and respond to them by running arbitrary JavaScript code.
+We saw some examples in chapter 9.  
+// TODO: optional, add link to an example
+
 Events in Hyperview are a good deal simpler, but they don't require any scripting and can be defined declaratively in the HXML.
 This is done through the behavior system.
 Events require adding a new behavior attribute, action type, and trigger type:
@@ -870,7 +881,7 @@ The second behavior (on Screen B) will trigger on an event with this name, and t
 Events have plenty of uses, but the most common is to inform different screens about backend state changes that require the UI to be re-fetched.
 ****
 
-We know enough about Hyperview's event system to solve the bug in our app.
+We now know enough about Hyperview's event system to solve the bug in our app.
 When the user saves a change to a contact, we need to dispatch an event from the Details screen.
 And the Contacts screen needs to listen to that event, and reload itself to reflect the edits.
 Since the `form_fields.xml` template already gets the `saved` flag when the backend successfully saves a contact, it's a good place to dispatch the event:
@@ -891,9 +902,9 @@ Since the `form_fields.xml` template already gets the `saved` flag when the back
   />
 {% endif %}
 ----
-<1> Trigger the behavior immediately
-<2> The behavior will dispatch an event
-<3> The event name is "contact-updated"
+<1> Trigger the behavior immediately.
+<2> The behavior will dispatch an event.
+<3> The event name is "contact-updated".
 <4> The existing behavior to show the Details UI.
 
 Now, we just need the contacts list to listen for the `contact-updated` event, and reload itself:
@@ -916,16 +927,16 @@ Now, we just need the contacts list to listen for the `contact-updated` event, a
   </list>
 </form>
 ----
-<1> Trigger the behavior on event dispatch
-<2> Trigger the behavior for dispatched events with the name "`contact-updated`"
-<3> When triggered, replace the contents of the `<list>` element with rows from the backend
+<1> Trigger the behavior on event dispatch.
+<2> Trigger the behavior for dispatched events with the name "`contact-updated`".
+<3> When triggered, replace the contents of the `<list>` element with rows from the backend.
 
 Any time the user edits a contact, the Contacts List screen will update to reflect the edits.
-The addition of these two `<behavior>` elements fixes the bug: the Contacts List screen will correctly show "`Joseph Blow`" in the list.
-Note that we intentionally added the new behavior inside the `<form>` element.
+The addition of these two `<behavior>` elements fixes the bug: the Contacts List screen will correctly show "`Joseph Blow`" in the list. Note that we intentionally added the new behavior inside the `<form>` element.
 The ensures the triggered request will preserve any search query.
+
 To show what we mean, let's revisit the set of steps that demonstrated the buggy behavior.
-Assume that before pressing on "`Joe Blow`", the user had searched the contacts by typing "`Joe`" in the search field.
+Assume that before pressing on "`Joe Blow,`" the user had searched the contacts by typing "`Joe`" in the search field.
 When the user later updates the contact to "`Joseph Blow`", our template dispatches the "`contact-updated`" event, which triggers the `replace-inner` behavior on the contact list screen.
 Due to the parent `<form>` element, the search query "`Joe`" will be serialized with the request: `GET /contacts?rows_only=true&q=Joe`.
 Since the name "`Joseph`" doesn't match the query "`Joe`", the contact we edited will not appear in the list (until the user clears out the query).
@@ -935,6 +946,7 @@ Events introduce a level of abstraction to behaviors.
 So far, we've seen that editing a contact will cause the list of contacts to refresh.
 But the list of contacts should also refresh after other actions, such as deleting a contact or adding a new contact.
 As long as our HXML responses for deletion or creation include a behavior to dispatch a `contact-updated` event, then we will get the desired refresh behavior on the contacts list screen.
+
 The screen doesn't care what causes the `contact-updated` event to be dispatched.
 It just knows what it needs to do when it happens.
 
@@ -966,9 +978,9 @@ So let's add a new button to `edit.xml`.
   <text style="button-label button-label-delete">Delete Contact</text>
 </view>
 ----
-<1> New Delete Contact button on the edit screen
-<2> When pressed, append HXML to a container on the screen
-<3> The HXML will be fetched by making a `POST /contacts/<contact_id>/delete` request
+<1> New Delete Contact button on the edit screen.
+<2> When pressed, append HXML to a container on the screen.
+<3> The HXML will be fetched by making a `POST /contacts/<contact_id>/delete` request.
 
 The HXML for the Delete button is pretty similar to the Save button, but there are a few subtle differences.
 Remember, pressing the Save button results in one of two expected outcomes: failing and showing validation errors on the form, or succeeding and switching to the contact details screen.
@@ -990,20 +1002,21 @@ Therefore, using the `append` action will preserve the current UI while Hypervie
   <behavior trigger="load" action="back" /> <2>
 </view>
 ----
-<1> On load, dispatch the `contact-updated` event to update the contact lists screen
+<1> On load, dispatch the `contact-updated` event to update the contact lists screen.
 <2> Navigate back to the contacts list screen.
 
 Note that in addition to behavior to navigate back, this template also includes a behavior to dispatch the `contact-updated` event.
 In the previous chapter section, we added a behavior to `index.xml` to refresh the list when that event is dispatched.
 By dispatching the event after a deletion, we will make sure the deleted contact gets removed from the list.
 
-Once again, I'm going to skip over the changes to the Flask backend.
+Once again, we'll skip over the changes to the Flask backend.
 Suffice it to say, we will need to update the `contacts_delete()` view to respond with the `hv/deleted.xml` template.
 And we need to update the route to support `POST` in addition to `DELETE`, since the Hyperview client only understands `GET` and `POST`.
 
 We now have a fully functioning deletion feature!
 But it's not the most user-friendly: it takes one accidental tap to permanently delete a contact.
 For destructive actions like deleting a contact, it's always a good idea to ask the user for confirmation.
+
 We can add a confirmation to the delete behavior by using the `alert` system action described in the previous chapter.
 As you recall, the `alert` action will show a system dialog box with buttons that can trigger other behaviors.
 All we have to do is wrap the delete `<behavior>` in a behavior that uses `action="alert"`.
@@ -1034,8 +1047,8 @@ All we have to do is wrap the delete `<behavior>` in a behavior that uses `actio
 </view>
 ----
 <1> Pressing "Delete" triggers an action to show the system dialog with the given title and message.
-<2> The first pressable option in the system dialog
-<3> Pressing the first option will trigger contact deletion
+<2> The first pressable option in the system dialog.
+<3> Pressing the first option will trigger contact deletion.
 <4> The second pressable option has no behavior, so it only closes the dialog.
 
 Unlike before, pressing the delete button will not have an immediate effect.
@@ -1053,13 +1066,12 @@ We can reuse the concepts (and even some templates) from features we've already
 In particular, adding a new contact is very similar to editing an existing contact.
 Both features need to:
 
-- Show a form to collect information about the contact
-- Have a way to save the entered information
-- Show validation errors on the form
-- Persist the contact when there are no validation errors
+- Show a form to collect information about the contact.
+- Have a way to save the entered information.
+- Show validation errors on the form.
+- Persist the contact when there are no validation errors.
 
-Since the functionality is so similar, I'm going to summarize the changes here without showing the code.
-Hopefully, you can follow along:
+Since the functionality is so similar, we'll summarize the changes here without showing the code.
 
 1. Update `index.xml`.
   - Override the `header` block to add a new "`Add`" button.
@@ -1082,7 +1094,7 @@ The screen will reload itself to show the Contact Details.
 image::screenshot_hyperview_add.png[Form to enter contact details pops up from bottom of screen]
 
 == Deploying the App
-With the completion of the contact creation UI, we have a fully implemented mobile app!
+With the completion of the contact creation UI, we have a fully implemented mobile app.
 It supports searching a list of contacts, viewing the details of a contact, editing and deleting a contact, and adding a new contact.
 But so far, we've been developing the app using a simulator on our desktop computer.
 How can we see it running on a mobile device?
@@ -1096,7 +1108,7 @@ This might look something like `flask run --host 192.168.7.229`, where the host
 3. Update the Hyperview client code so that `ENTRY_POINT_URL` (in `demo/src/constants.js`) points to the IP and port that the Flask server is bound to.
 4. After running `yarn start` in the Hyperview demo app, you will see a QR code printed in the console, with instructions on how to scan it on Android and iOS.
 
-Once you scan the QR code, the full app will run on the device!
+Once you scan the QR code, the full app will run on the device.
 As you interact with the app, you will see HTTP requests made to the Flask server.
 You can even use the physical device during development.
 Any time you make a change in the HXML, just reload the screen to see the UI updates.
@@ -1104,6 +1116,7 @@ Any time you make a change in the HXML, just reload the screen to see the UI upd
 So we have the app running on a physical device, but it's still not production ready.
 To get the app into the hands of our users, there's a few things we need to do:
 
+// TODO: mention presentation here?
 1. Deploy our backend in production.
 We need to use a production-grade web server like Gunicorn instead of the Flask development server.
 And we should run our app on a machine reachable on the Internet, most likely using a cloud provider like AWS or Heroku.
@@ -1145,11 +1158,11 @@ They will see the Google home page localized in German and Japanese, respectivel
 How does Google know to return a different version of the homepage based on the user's preferred language?
 The answer lies in the REST architecture, and how it separates the concepts of resources and representations.
 
-In the REST architecture, the Google homepage is considered to be a single "`resource`", represented by a unique URL.
-However, that single resource can have multiple "`representations`".
+In the REST architecture, the Google homepage is considered to be a single "`resource,`" represented by a unique URL.
+However, that single resource can have multiple "`representations.`"
 Representations are variations on how the content of the resource is presented to the client.
 The German and Japanese versions of the Google homepage are two representations of the same resource.
-To determine the best representation of a resource to return, HTTP clients and servers engage in a process called "`content negotiation`".
+To determine the best representation of a resource to return, HTTP clients and servers engage in a process called "`content negotiation.`"
 It works like this:
 
 - Clients specify the preferred representation through `Accept-*` request headers.
@@ -1166,7 +1179,8 @@ Content negotiation over content type is done using the `Accept` request header
 Web browsers set `text/html` as the preferred content type in the `Accept` header.
 The Hyperview client sets `application/vnd.hyperview+xml` as the preferred content type.
 This gives our backend a way to distinguish requests coming from a web browser or Hyperview client, and serve the appropriate content to each.
-There are two main approaches: fine-grained and global.
+
+There are two main approaches to content negotiation: fine-grained and global.
 
 === Approach 1: Template Switching
 When we ported the Contacts app from the web to mobile, we kept all of the Flask views but made some minor changes.
@@ -1201,10 +1215,10 @@ def render_to_response(html_template_name, hxml_template_name, *args, **kwargs):
     response.headers['Content-Type'] = response_type <4>
     return response
 ----
-<1> Function signature takes two templates, one for HTML and one for HXML
-<2> Determine whether the client wants HTML or HXML
-<3> Select the template based on the best match for the client
-<4> Set the `Content-Type` header based on the best match for the client
+<1> Function signature takes two templates, one for HTML and one for HXML.
+<2> Determine whether the client wants HTML or HXML.
+<3> Select the template based on the best match for the client.
+<4> Set the `Content-Type` header based on the best match for the client.
 
 Flask's request object exposes an `accept_mimetypes` property to help with content negotiation.
 We pass our two content MIME types to `request.accept_mimetypes.best_match()` and get back the MIME type that works for our client.
@@ -1225,7 +1239,8 @@ def contacts_view(contact_id=0):
 After updating all of the Flask views to support both templates, our backend will support both web browsers and our mobile app!
 This technique works well for the Contacts app because the screens in the mobile app map directly to pages of the web application.
 Each app has a dedicated page (or screen) for listing contacts, showing and editing details, and creating a new contact.
-This meant the Flask views could be as-is without major changes.
+This meant the Flask views could be kept as-is without major changes.
+
 But what if we wanted to re-imagine the Contacts app UI for our mobile app?
 Perhaps we want the mobile app to use a single screen, with rows that expanded in-line to support viewing and editing the information?
 In situations where the UI diverges between platforms, Template Switching becomes cumbersome or impossible.
@@ -1263,9 +1278,9 @@ def index():
     else:
       return redirect("/web/contacts") <3>
 ----
-<1> Determine whether the client wants HTML or HXML
-<2> If the client wants HXML, redirect them to `/mobile/contacts`
-<3> If the client wants HTML, redirect them to `/web/contacts`
+<1> Determine whether the client wants HTML or HXML.
+<2> If the client wants HXML, redirect them to `/mobile/contacts`.
+<3> If the client wants HTML, redirect them to `/web/contacts`.
 
 The entrypoint is a fork in the road: if the client wants HTML, we redirect them to one path.
 If the client wants HXML, we redirect them to a different path.
@@ -1294,6 +1309,7 @@ After all, we need to write double the number of views: one set for the web appl
 That is true, which is why the Redirect Fork is only preferred if the two platforms require a disjointed set of view logic.
 If the apps are similar on both platforms, Template Switching will save a lot of time and keep the apps consistent.
 Even if we need to use the Redirect Fork, the bulk of the logic in our models can be shared by both sets of views.
+
 In practice, you may start out using Template Switching, but then realize you need to implement a fork for platform-specific features.
 In fact, we're already doing that in the Contacts app.
 When porting the app from web to mobile, we didn't bring over certain features like archiving functionality.
@@ -1301,16 +1317,20 @@ The dynamic archive UI is a power feature that wouldn't make sense on a mobile d
 Since our HXML templates don't expose any entrypoints to the Archive functionality, we can treat it as "`web-only`" and not worry about supporting it in Hyperview.
 
 
-== Summary
-
-- Creating a Hyperview-powered mobile app is as simple as cloning a Git repo and configuring a single entrypoint URL.
+.HXML and Hyperview in Brief, Part Two
+****
+- It is possible to create a Hyperview-powered mobile app by simply as cloning a Git repo and configuring a single entrypoint URL.
 - Flask is perfectly suited for serving a Hyperview mobile app. The Jinja templating system can generate dynamic HXML based on the context from a view.
 - Using elements like `<view>`, `<text>`, `<list>`, and `<item>`, we can create native-feeling screens in HXML.
 - Using behaviors, we can implement interactions on the contacts list such as infinite scroll, search-as-you-type, and pull-to-refresh.
 - Events are a client-side feature of Hyperview that allows triggering behaviors across screens. They are useful to keep state in sync throughout the app, such as after editing or deleting a contact.
 - A Hyperview-powered mobile app can be bundled and released through the iOS and Android app stores. New screens and features can be added to the app just by updating the backend!
 - The same Flask backend can support both web and mobile apps. Using HTTP content negotiation, a server can render either HTML or HXML responses from the same view. More complex apps may require the use of redirects and platform-specific views.
+****
 
+We've covered a lot of ground in this chapter. Take a breath and take stock of how far we've come: we ported the core functionality of the Contact.app web application to mobile. And we did it by re-using much of our Flask backend and while sticking with Jinja templating. We again saw the utility of events for connecting different aspects of an application. 
+
+We're not done yet. In the next chapter we'll finish our mobile Contact.app and see how to implement custom behaviors and UI elements.
 
 
 // TODO: okay, or better as integrated info gem?
diff --git a/book/CH13_ExtendingTheHyperviewClient.adoc b/book/CH13_ExtendingTheHyperviewClient.adoc
index 2f93c3a..a1f89e7 100644
--- a/book/CH13_ExtendingTheHyperviewClient.adoc
+++ b/book/CH13_ExtendingTheHyperviewClient.adoc
@@ -8,14 +8,14 @@ In the previous chapter, we created a fully-featured native mobile version of ou
 Aside from customizing the entrypoint URL, we didn't need to touch any code that runs on the mobile device.
 We defined our mobile app's UI and logic completely in the backend code, using Flask and HXML templates.
 This is possible because the standard Hyperview client supports all of the basic features by mobile apps.
+
 But the standard Hyperview client can't do everything out of the box.
-App developers want their apps to have unique touches like custom UIs or deep integration with platform capabilities.
+As app developers, we want apps to have unique touches like custom UIs or deep integration with platform capabilities.
 To support these needs, the Hyperview client was designed to be extended with custom behavior actions and UI elements.
 In this section, we will enhance our mobile app with examples of both.
 
-Before diving in, a quick introduction on the tech stack we'll be using.
-The Hyperview client is written in React Native.
-If you're not familiar with React Native, it is a popular cross-platform framework for creating mobile apps.
+Before diving in, let's take a quick look at the tech stack we'll be using.
+The Hyperview client is written in React Native, a popular cross-platform framework for creating mobile apps.
 It uses the same component-based API as React.
 This means developers familiar with JavaScript and React can quickly pick up React Native.
 React Native has a healthy ecosystem of open-source libraries.
@@ -60,20 +60,20 @@ So let's define two new actions, "`open-phone`" and "`open-email`".
   </text>
 </view>
 ----
-<1> Define an alias for an XML namespace used by our new attributes
-<2> When pressed, prompt the user to call the given phone number
+<1> Define an alias for an XML namespace used by our new attributes.
+<2> When pressed, prompt the user to call the given phone number.
 <3> When pressed, open an e-mail client with the given address populated in the `to:` field.
 
 Notice we defined the actual phone number and email address using separate attributes.
 In HTML, the scheme and data are crammed into the `href` attribute.
 HXML's `<behavior>` elements give more options for representing the data.
-I chose to use attributes, but we could've represented the phone number or email using child elements.
+I chose to use attributes, but we could have represented the phone number or email using child elements.
 I'm also using a namespace to avoid potential future conflicts with other client extensions.
 
 So far so good, but how does the Hyperview client know how to interpret `open-phone` and `open-email`, and how to reference the `phone-number` and `email-address` attributes?
 This is where we finally need to write some JavaScript.
 
-First, I'm going to add a 3rd-party library (`react-native-communications`) to our demo app.
+First, we're going to add a 3rd-party library (`react-native-communications`) to our demo app.
 This library provides a simple API that interacts with OS-level functionality for calls and emails.
 
 [source,bash]

From 742ef8953671be115d7f456bc149af34bfd9e3a5 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Tue, 18 Apr 2023 20:49:39 -0400
Subject: [PATCH 16/18] edit, ch12 conclusion

---
 book/CH12_BuildingAContactsAppWithHyperview.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/book/CH12_BuildingAContactsAppWithHyperview.adoc b/book/CH12_BuildingAContactsAppWithHyperview.adoc
index 6176632..30ba5ec 100644
--- a/book/CH12_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH12_BuildingAContactsAppWithHyperview.adoc
@@ -1330,7 +1330,7 @@ Since our HXML templates don't expose any entrypoints to the Archive functionali
 
 We've covered a lot of ground in this chapter. Take a breath and take stock of how far we've come: we ported the core functionality of the Contact.app web application to mobile. And we did it by re-using much of our Flask backend and while sticking with Jinja templating. We again saw the utility of events for connecting different aspects of an application. 
 
-We're not done yet. In the next chapter we'll finish our mobile Contact.app and see how to implement custom behaviors and UI elements.
+We're not done yet. In the next chapter we'll implement custom behaviors and UI elements to finish our mobile Contact.app.
 
 
 // TODO: okay, or better as integrated info gem?

From 17c1281ec29bb2bd85e5468f942cfc4fa7b8cf4e Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Tue, 18 Apr 2023 21:08:16 -0400
Subject: [PATCH 17/18] Edits, revise, add ch13 conclusion

---
 book/CH13_ExtendingTheHyperviewClient.adoc | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/book/CH13_ExtendingTheHyperviewClient.adoc b/book/CH13_ExtendingTheHyperviewClient.adoc
index a1f89e7..b5a4d7e 100644
--- a/book/CH13_ExtendingTheHyperviewClient.adoc
+++ b/book/CH13_ExtendingTheHyperviewClient.adoc
@@ -698,27 +698,37 @@ If we wanted to, we could have the action buttons trigger our custom actions, li
 Custom components and actions can be mixed freely with the standard components and actions that come standard with the Hyperview framework.
 This makes the extensions to the Hyperview client feel like first-class features.
 
-In fact, I'll let you in on a secret.
+In fact, we'll let you in on a secret.
 Within the Hyperview client, standard components and actions are implemented the same way as custom components and actions!
 The rendering code does not treat `<view>` differently from `<swipe:row>`.
 The behavior code does not treat `alert` differently from `open-phone`.
 They are both implemented using the same techniques described in this section.
 Standard components and actions are just the ones that are universally needed by all mobile apps.
 But they are just the starting point.
+
 Most mobile apps will require some extensions to the Hyperview client to deliver a great user experience.
-Extensions evolve the client from being a generic "`Hyperview client`", to being a purpose-built client for your app.
+Extensions evolve the client from being a generic "`Hyperview client,`" to being a purpose-built client for your app.
 And importantly, this evolution preserves the Hypermedia, server-driven architecture and all of its benefits.
 
 
-== Conclusion
+.HXML and Hyperview in Brief, Part Three
+****
 - With custom components and behaviors, Hyperview apps can do anything a native app can do.
 - Support for system actions (like SMS and email) can be added with a Hyperview behavior action.
 - Support for high-level UIs (like confirmation toasts) can also be added with a Hyperview behavior action.
 - Support for customized screen elements (like swipeable items in lists) can be added with Hyperview custom components.
 - The standard behaviors and components that come with the Hyperview client are implemented the same way as custom behavior actions and components.
 - By customizing the Hyperview client, developers can build a mobile app that suits their specific needs while retaining the benefits of a thin-client, hypermedia architecture.
+****
 
 
+//TODO: conclusion okay? add?
+=== Hypermedia-Driven Mobile Applications
+
+That concludes our build of mobile Contact.app. Step back from the code details and consider the broader pattern: the Hypermedia-Driven Application architecture allowed for signicant code reuse, and led to a manageable stack for ongoing app updates and maintenance for both web and mobile. 
+
+Yes, there is a story for hypermedia on mobile.
+
 
 [.design-note]
 .HTML Note: "'Display: none'"

From 507ffaf89d830f8199b4e90c9a5d7306266b5bd1 Mon Sep 17 00:00:00 2001
From: Bill Talcott <wtalcott@gmail.com>
Date: Wed, 19 Apr 2023 20:49:56 -0400
Subject: [PATCH 18/18] edits, ch11-13

---
 book/CH07_ADynamicArchiveUIWithhtmx.adoc      |   2 +-
 book/CH11_HyperviewAMobileHypermedia.adoc     |  18 ++-
 ...H12_BuildingAContactsAppWithHyperview.adoc |   2 +-
 book/CH13_ExtendingTheHyperviewClient.adoc    | 122 +++++++++---------
 4 files changed, 73 insertions(+), 71 deletions(-)

diff --git a/book/CH07_ADynamicArchiveUIWithhtmx.adoc b/book/CH07_ADynamicArchiveUIWithhtmx.adoc
index 5d8895b..1f5c90b 100644
--- a/book/CH07_ADynamicArchiveUIWithhtmx.adoc
+++ b/book/CH07_ADynamicArchiveUIWithhtmx.adoc
@@ -561,7 +561,7 @@ Now that, dear reader, does spark joy.
 
 == Dismissing The Download UI
 
-Some users may change their mind, and decide not to download the archive. They may never witness our progress bar, but that's okay. We're going to give these users a button to dismiss the download link and return to the original export UI state.
+Some users may change their mind, and decide not to download the archive. They may never witness our progress bar, but that's OK. We're going to give these users a button to dismiss the download link and return to the original export UI state.
 
 To do this, we'll add a button that issues a `DELETE` to the path `/contacts/archive`, indicating that the current archive can be removed or cleaned up.
 
diff --git a/book/CH11_HyperviewAMobileHypermedia.adoc b/book/CH11_HyperviewAMobileHypermedia.adoc
index 03b95be..601678d 100644
--- a/book/CH11_HyperviewAMobileHypermedia.adoc
+++ b/book/CH11_HyperviewAMobileHypermedia.adoc
@@ -5,21 +5,17 @@
 :part_url: ./part/hyperview/
 :url: ./hyperview-a-mobile-hypermedia/
 
-This chapter covers
-
-* Shortcomings with the current state of mobile app development
-* How a hypermedia architecture can address these problems
-* Hyperview as a mobile app framework that uses the hypermedia architecture
-* An overview of HXML, the hypermedia format used by Hyperview
-
 You may be forgiven for thinking the hypermedia architecture is synonymous with the Web, web browsers, and HTML.
 No doubt, the Web is the largest hypermedia system, and web browsers are the most popular hypermedia client.
 The dominance of the Web in discussions about hypermedia make it easy to forget that hypermedia is a general concept, and can be applied to all types of platforms and applications.
 In this chapter, we will see the hypermedia architecture applied to a non-web platform: native mobile applications.
+
 Mobile as a platform has different constraints than the Web.
 It requires different trade-offs and design decisions.
-Nonetheless, the concepts of hypermedia, HATEOAS, and REST can be directly applied to build delightful mobile applications!
+Nonetheless, the concepts of hypermedia, HATEOAS, and REST can be directly applied to build delightful mobile applications.
 
+// TODO: chapter overview changed to fit other chapters. okay?
+In this chapter we will cover shortcomings with the current state of mobile app development, and how a hypermedia architecture can address these problems. We will then look at a path toward hypermedia on mobile: Hyperview, a mobile app framework that uses the hypermedia architecture. We'll conclude with an overview of HXML, the hypermedia format used by Hyperview.
 
 == The State of Mobile App Development
 Before we can discuss how to apply hypermedia to mobile platforms, we need to understand how native mobile apps are commonly built.
@@ -1243,7 +1239,9 @@ It's not unusual for a production Hyperview app to contain several behaviors, so
 Using multiple behaviors with custom actions keeps HXML declarative, without sacrificing functionality.
 
 // TODO: keep? reformat?
-.HXML and Hyperview in Brief
+We're covering a lot of new material, so we'll add brief summaries to our sprint through Hyperview and HXML. 
+
+.Summary
 ****
 - HXML looks similar to HTML, but it uses elements that correspond to mobile UIs, like `<screen>`, `<header>`, `<list>` and more.
 - HXML includes input elements that implement common patterns in mobile apps, such as `<switch>`, `<select-single>`, and `<select-multiple>`.
@@ -1262,7 +1260,7 @@ There is a story for Hypermedia-Driven Applications on mobile. Mobile app platfo
 
 Hyperview, based on a new format called HXML, offers a path here. It provides an open-source mobile thin-client to render HXML. And HXML opens a took-kit of elements and patterns that correspond to mobile UIs. Developers can evolve Hyperview to suit their apps' requirements, while fully embracing the hypermedia architecture. That's a win.
 
-Yes, hypermedia works for mobile, too. In the next two chapters we'll show how by moving Contact.app to mobile. 
+Yes, hypermedia can work for mobile apps, too. In the next two chapters we'll show how by moving Contact.app to mobile. 
 
 
 
diff --git a/book/CH12_BuildingAContactsAppWithHyperview.adoc b/book/CH12_BuildingAContactsAppWithHyperview.adoc
index 30ba5ec..befed5f 100644
--- a/book/CH12_BuildingAContactsAppWithHyperview.adoc
+++ b/book/CH12_BuildingAContactsAppWithHyperview.adoc
@@ -1317,7 +1317,7 @@ The dynamic archive UI is a power feature that wouldn't make sense on a mobile d
 Since our HXML templates don't expose any entrypoints to the Archive functionality, we can treat it as "`web-only`" and not worry about supporting it in Hyperview.
 
 
-.HXML and Hyperview in Brief, Part Two
+.Summary
 ****
 - It is possible to create a Hyperview-powered mobile app by simply as cloning a Git repo and configuring a single entrypoint URL.
 - Flask is perfectly suited for serving a Hyperview mobile app. The Jinja templating system can generate dynamic HXML based on the context from a view.
diff --git a/book/CH13_ExtendingTheHyperviewClient.adoc b/book/CH13_ExtendingTheHyperviewClient.adoc
index b5a4d7e..712f6e9 100644
--- a/book/CH13_ExtendingTheHyperviewClient.adoc
+++ b/book/CH13_ExtendingTheHyperviewClient.adoc
@@ -67,8 +67,8 @@ So let's define two new actions, "`open-phone`" and "`open-email`".
 Notice we defined the actual phone number and email address using separate attributes.
 In HTML, the scheme and data are crammed into the `href` attribute.
 HXML's `<behavior>` elements give more options for representing the data.
-I chose to use attributes, but we could have represented the phone number or email using child elements.
-I'm also using a namespace to avoid potential future conflicts with other client extensions.
+We chose to use attributes, but we could have represented the phone number or email using child elements.
+We're also using a namespace to avoid potential future conflicts with other client extensions.
 
 So far so good, but how does the Hyperview client know how to interpret `open-phone` and `open-email`, and how to reference the `phone-number` and `email-address` attributes?
 This is where we finally need to write some JavaScript.
@@ -105,7 +105,7 @@ export default {
 };
 ----
 <1> Import the function we need from the 3rd party library.
-<2> The name of the action
+<2> The name of the action.
 <3> The callback that runs when the action triggers.
 <4> Get the phone number from the `<behavior>` element.
 <5> Pass the phone number to the function from the 3rd party library.
@@ -118,7 +118,7 @@ That means we can call methods on it like `getAttribute`, or access attributes l
 In this case, we use `getAttributeNS` to read the phone number from the `phone-number` attribute on the `<behavior>` element.
 If the phone number is defined on the element, we can call the `phonecall()` function provided by the `react-native-communications` library.
 
-There's one more thing we need to do before we can use our custom action: register the action with the Hyperview client.
+There's one more thing to do before we can use our custom action: register the action with the Hyperview client.
 The Hyperview client is represented as a React Native component called `Hyperview`.
 This component takes a prop called `behaviors`, which is an array of custom action objects like our "`open-phone`" action.
 Let's pass our "`open-phone`" implementation to the `Hyperview` component in our demo app.
@@ -146,12 +146,13 @@ export default class HyperviewScreen extends PureComponent {
   }
 }
 ----
-<1> Import the open-phone action
-<2> Create an array of custom actions
+<1> Import the open-phone action.
+<2> Create an array of custom actions.
 <3> Pass the custom actions to the `Hyperview` component, as a prop called `behaviors`.
 
 Under the hood, the `Hyperview` component is responsible for taking HXML and turning it into mobile UI elements.
 It also handles triggering behavior actions based on user interactions.
+
 By passing the "`open-phone`" action to Hyperview, we can now use it as a value for the `action` attribute on `<behavior>` elements.
 In fact, let's do that now by updating the `show.xml` template in our Flask app:
 
@@ -186,32 +187,32 @@ In fact, let's do that now by updating the `show.xml` template in our Flask app:
 </view>
 {% endblock %}
 ----
-<1> Add a behavior to the phone number section that triggers on "`press`".
+<1> Add a behavior to the phone number section that triggers on "`press.`"
 <2> Trigger the new "`open-phone`" action.
 <3> Set the attribute expected by the "`open-phone`" action.
-<4> Same idea, with a different action ("`open-email`")
+<4> Same idea, with a different action ("`open-email`").
 
-I skipped over the implementation of the second custom action, "`open-email`".
+We'll skip over the implementation of the second custom action, "`open-email.`"
 As you can guess, this action will open a system-level email composer to let the user send an email to their contact.
-The implementation of "`open-email`" is almost identical to "`open-phone`".
+The implementation of "`open-email`" is almost identical to "`open-phone.`"
 The `react-native-communications` library exposes a function called `email()`, so we just wrap it and pass arguments to it in the same way.
 
-There we have a complete example of extending the client with some custom behavior actions!
+We now have a complete example of extending the client with custom behavior actions.
 We chose a new name for our actions ("`open-phone`" and "`open-email`"), and mapped those names to functions.
 The functions take `<behavior>` elements and can run any arbitrary React Native code.
 We wrapped an existing 3rd party library, and read attributes set on the `<behavior>` element to pass data to the library.
 After re-starting our demo app, our client has new capabilities we can immediately utilize by referencing the actions from our HXML templates.
 
 == Adding Toast Messages
-The phone and email actions added in the previous section are examples of "`system actions`".
+The phone and email actions added in the previous section are examples of "`system actions.`"
 System actions trigger some UI or capability provided by the device's OS.
-But custom actions are not limited to only interacting with OS-level APIs.
+But custom actions are not limited to interacting with OS-level APIs.
 Remember, the callbacks that implement actions can run arbitrary code, including code that renders our own UI elements.
 This next custom action example will do just that: render a custom confirmation toast UI element.
 
 If you recall, our Contacts web app shows messages upon successful actions, such as deleting or creating a contact.
 These messages are generated in the Flask backend using the `flash()` function, called from the views.
-Then the base `layout.html` template rendered the messages into the final web page.
+Then the base `layout.html` template renders the messages into the final web page.
 
 .Snippet templates/layout.html
 ----
@@ -222,6 +223,7 @@ Then the base `layout.html` template rendered the messages into the final web pa
 
 Our Flask app still includes the calls to `flash()`, but the Hyperview app is not accessing the flashed message to display to the user.
 Let's add that support now.
+
 We could just show the messages using a similar technique to the web app: loop through the messages and render some `<text>` elements in `layout.xml`.
 This approach has a major downside: the rendered messages would be tied to a specific screen.
 If that screen was hidden by a navigation action, the message would be hidden too.
@@ -259,18 +261,18 @@ export default {
 };
 ----
 <1> Import the `Toast` API.
-<2> The name of the action
-<3> The callback that runs when the action triggers
-<4> Pass the message to the toast library
+<2> The name of the action.
+<3> The callback that runs when the action triggers.
+<4> Pass the message to the toast library.
 
 This code looks very similar to the implementation of `open-phone`.
 Both callbacks follow a similar pattern: read namespaced attributes from the `<behavior>` element, and pass those values to a 3rd party library.
-For simplicity, I'm hard-coding options to show the toast at the top of the screen, fading out after 2 seconds.
+For simplicity, we're hard-coding options to show the toast at the top of the screen, fading out after 2 seconds.
 But `react-native-root-toast` exposes many options for positioning, timing of animations, colors, and more.
 We could specify these options using extra attributes on `behaviorElement` to make the action more configurable.
 For our purposes, we will just stick to a bare-bones implementation.
 
-Now we just need to register our custom action with the `<Hyperview>` component, by passing it to the `behaviors` prop.
+Now we need to register our custom action with the `<Hyperview>` component, by passing it to the `behaviors` prop.
 
 .demo/src/HyperviewScreen.js
 [source,js]
@@ -317,8 +319,8 @@ Since the actual behaviors will be the same in both templates, let's create a sh
   />
 {% endfor %}
 ----
-<1> Define a behavior for each message to display
-<2> Trigger this behavior as soon as the screen loads
+<1> Define a behavior for each message to display.
+<2> Trigger this behavior as soon as the screen loads.
 <3> Trigger the new "`show-toast`" action.
 <4> The "`show-toast`" action will display the flashed message in its UI.
 
@@ -354,7 +356,7 @@ And we can do the same thing in `deleted.xml`:
 ----
 <1> Show the toasts as soon as the screen loads.
  
-In both `form_fields.xml` and `deleted.xml`, multiple behaviors get triggered on "`load`".
+In both `form_fields.xml` and `deleted.xml`, multiple behaviors get triggered on "`load.`"
 In `deleted.xml`, we immediately navigate back to the previous screen.
 In `form_fields.xml`, we immediately reload the current screen to show the Contact details.
 If we rendered our toast UI elements directly in the screen, the user would barely see them before the screen disappeared or reloaded.
@@ -391,16 +393,17 @@ Rather than implementing the swipe gesture from scratch, we will once again use
 > yarn add react-native-swipeable <1>
 > yarn start <2>
 ----
-<1> Add dependency on `react-native-swipeable`
-<2> Re-start the mobile app
+<1> Add dependency on `react-native-swipeable`.
+<2> Re-start the mobile app.
 
 This library provides a React Native component called `Swipeable`.
 It can render any React Native components as its main content (the part that can be swiped). 
 It also takes an array of React Native components as a prop to render as the action buttons.
+
 When designing a custom component, we like to define the HXML of the component before writing the code.
 This way, we can make sure the markup is expressive but succinct, and will work with the underlying library.
+
 For the swipeable row, we need a way to represent the entire component, the main content, and one of many buttons.
-I came up with something that looks like this:
 
 [source,xml]
 ----
@@ -418,18 +421,19 @@ I came up with something that looks like this:
   </swipe:button>
 </swipe:row>
 ----
-<1> Parent element encapsulating the entire swipeable row, with custom namespace
-<2> The main content of the swipeable row, can hold any HXML
-<3> The first button that appears when swiping, can hold any HXML
-<4> The second button that appears when swiping, can hold any HXML
+<1> Parent element encapsulating the entire swipeable row, with custom namespace.
+<2> The main content of the swipeable row, can hold any HXML.
+<3> The first button that appears when swiping, can hold any HXML.
+<4> The second button that appears when swiping, can hold any HXML.
 
 This structure clearly separates the main content from the buttons.
 It also supports one, two, or more buttons.
 Buttons appear in the order of definition, making it easy to swap the order.
+
 This design covers everything we need to implement a swipeable row for our contacts list.
 But it's also generic enough to be reusable.
-The markup above contains nothing specific to the contact name, editing the contact, or deleting the contact.
-If down the line, we add another list screen to our app, we can use this component to make the items in that list swipeable.
+The previous markup contains nothing specific to the contact name, editing the contact, or deleting the contact.
+If later we add another list screen to our app, we can use this component to make the items in that list swipeable.
 
 === Implementing The Component
 Now that we know the HXML structure of our custom component, we can write the code to implement it.
@@ -439,13 +443,13 @@ These React Native components are mapped to a unique XML namespace and tag name.
 When the Hyperview client encounters that namespace and tag name in the HXML, it delegates rendering of the HXML element to the matching React Native component.
 As part of delegation, the Hyperview Client passes several props to the React Native component:
 
-- `element`: The XML DOM element that maps to the React Native component
-- `stylesheets`: The styles defined in the `<screen>`
-- `onUpdate`: The function to call when the component triggers a behavior
+- `element`: The XML DOM element that maps to the React Native component.
+- `stylesheets`: The styles defined in the `<screen>`.
+- `onUpdate`: The function to call when the component triggers a behavior.
 - `option`: Miscellaneous settings used by the Hyperview client.
 
 Our swipeable row component is a container with slots to render arbitrary main content and buttons.
-That means it needs to delegate rendering back to the Hyperview client to render those parts of the UI.
+That means it needs to delegate back to the Hyperview client to render those parts of the UI.
 This is done with a public function exposed by the Hyperview client, `Hyperview.renderChildren()`.
 
 Now that we know how custom Hyperview components are implemented, let's write the code for our swipeable row.
@@ -487,13 +491,13 @@ export default class SwipeableRow extends PureComponent { <1>
   }
 }
 ----
-<1> Class-based React Native component
-<2> Map this component to the given HXML namespace
-<3> Map this component to the given HXML tag name
+<1> Class-based React Native component.
+<2> Map this component to the given HXML namespace.
+<3> Map this component to the given HXML tag name.
 <4> Function that returns an array of React Native components for each `<button>` element.
-<5> Delegate to the Hyperview client to render each button
-<6> Pass the buttons and main content to the third-party library
-<7> Delegate to the Hyperview client to render the main content
+<5> Delegate to the Hyperview client to render each button.
+<6> Pass the buttons and main content to the third-party library.
+<7> Delegate to the Hyperview client to render the main content.
 
 The `SwipeableRow` class implements a React Native component.
 At the top of the class, we set a static `namespaceURI` property and `localName` property.
@@ -501,23 +505,23 @@ These properties map the React Native component to a unique namespace and tag na
 This is how the Hyperview client knows to delegate to `SwipeableRow` when encountering custom elements in the HXML.
 At the bottom of the class, you'll see a `render()` method.
 `render()` gets called by React Native to return the rendered component.
-Since React Native is built on principle of composition, `render()` typically returns a composition of other React Native components.
+Since React Native is built on the principle of composition, `render()` typically returns a composition of other React Native components.
 In this case, we return the `Swipeable` component (provided by the `react-native-swipeable` library), composed with React Native components for the buttons and main content.
 The React Native components for the buttons and main content are created using a similar process:
 
-- Find the specific child elements (`<button>` or `<main>`)
-- Turn those elements into React Native components using `Hyperview.renderChildren()`
+- Find the specific child elements (`<button>` or `<main>`).
+- Turn those elements into React Native components using `Hyperview.renderChildren()`.
 - Set the components as children or props of `Swipeable`.
 
 .Component rendering delegation
 image::figure_hyperview_components.png["The HyperviewClient delegates to us to render XML swipe:row element. We delegate back to render text elements."]
 
-I realize this code may be hard to follow if you've never worked with React or React Native.
-That's ok.
-The important takeaway is: we can write code to translate arbitrary HXML into React Native components.
-The structure of the HXML (both attributes and elements) can be used to represent multiple facets of the UI (in this case, the buttons and main content).
+This code may be hard to follow if you've never worked with React or React Native.
+That's OK.
+The important takeaway is: we can write code to translate arbitrary HXML into React Native components. The structure of the HXML (both attributes and elements) can be used to represent multiple facets of the UI (in this case, the buttons and main content).
 Finally, the code can delegate rendering of child components back to the Hyperview client.
-That means this swipeable row component is completely generic.
+
+The result: this swipeable row component is completely generic.
 The actual structure and styling and interactions of the main content and buttons can be defined in the HXML.
 Creating a generic component means we can reuse it across multiple screens for different purposes.
 If we add more custom components or new behavior actions in the future, they will work with our swipeable row implementation.
@@ -554,11 +558,11 @@ export default class HyperviewScreen extends PureComponent {
   }
 }
 ----
-<1> Import the `SwipeableRow` component
-<2> Create an array of custom components
+<1> Import the `SwipeableRow` component.
+<2> Create an array of custom components.
 <3> Pass the custom component to the `Hyperview` component, as a prop called `components`.
 
-We're now ready to update our HXML templates to make use of the new swipeable row component!
+We're now ready to update our HXML templates to make use of the new swipeable row component.
 
 ==== Using the component
 Currently, the HXML for a contact item in the list consists of a `<behavior>` and `<text>` element:
@@ -628,8 +632,8 @@ Let's add two buttons to the swipeable row.
   </swipe:row>
 </item>
 ----
-<1> Added `<swipe:button>` for edit action
-<2> Added `<swipe:button>` for delete action
+<1> Added `<swipe:button>` for edit action.
+<2> Added `<swipe:button>` for delete action.
 
 Now if we use our mobile app, we can see the swipeable row in action!
 As you swipe the contact item, the "`Edit`" and "`Delete`" buttons reveal themselves.
@@ -683,10 +687,10 @@ This interaction will work for our action button as well:
   </view>
 </swipe:button>
 ----
-<1> When pressed, open a system dialog box asking the user to confirm the action
+<1> When pressed, open a system dialog box asking the user to confirm the action.
 <2> If confirmed, make a POST request to the deletion endpoint, and append the response to the parent `<item>`.
 
-Now when we press "`Delete`", we get the confirmation dialog as expected.
+Now when we press "`Delete,`" we get the confirmation dialog as expected.
 After pressing confirm, the backend response triggers behaviors that show a confirmation toast and reload the list of contacts.
 The item for the deleted contact disappears from the list.
 
@@ -711,7 +715,7 @@ Extensions evolve the client from being a generic "`Hyperview client,`" to being
 And importantly, this evolution preserves the Hypermedia, server-driven architecture and all of its benefits.
 
 
-.HXML and Hyperview in Brief, Part Three
+.Summary
 ****
 - With custom components and behaviors, Hyperview apps can do anything a native app can do.
 - Support for system actions (like SMS and email) can be added with a Hyperview behavior action.
@@ -723,11 +727,11 @@ And importantly, this evolution preserves the Hypermedia, server-driven architec
 
 
 //TODO: conclusion okay? add?
-=== Hypermedia-Driven Mobile Applications
+=== Mobile Hypermedia-Driven Applications
 
 That concludes our build of mobile Contact.app. Step back from the code details and consider the broader pattern: the Hypermedia-Driven Application architecture allowed for signicant code reuse, and led to a manageable stack for ongoing app updates and maintenance for both web and mobile. 
 
-Yes, there is a story for hypermedia on mobile.
+Yes, there is a story for Hypermedia-Driven Applications on mobile.
 
 
 [.design-note]