Do not directly reference figures in prose ("Here is...")

ch01-hypermedia-a-reintroduction.typ

@@ -244,14 +244,12 @@ In a typical web browser, this anchor tag would be interpreted to mean:
 
 Anchors provide the main mechanism we use to navigate around the web today, by
 selecting links to navigate from document to document, or from resource to
-resource.
-
-Here is what a user interaction with an anchor tag/hyperlink looks like in
-visual form:
+resource. @fig:get-in-action Here is what a user interaction with an anchor tag/hyperlink looks like in
+visual form.
 
 #asciiart(
   read("images/diagram/http-get-in-action.txt"), caption: [An HTTP GET In Action],
-)
+)<fig:get-in-action>
 
 #index[GET request]
 When the link is clicked the browser (or, as we sometimes refer to it, the _hypermedia client_)
@@ -322,13 +320,11 @@ form submission often _redirects_ the client to a different URL.
 
 This is true, and we will get down into the muck with forms in more detail in
 later chapters but, for now, this simple example suffices to demonstrate the
-core mechanism for updating system state purely within hypermedia.
-
-Here is a diagram of the interaction:
+core mechanism for updating system state purely within hypermedia. @fig:post-in-action is a diagram of the interaction.
 
 #asciiart(
   read("images/diagram/http-post-in-action.txt"), caption: [An HTTP POST In Action],
-)
+)<fig:post-in-action>
 
 ===== Web 1.0 applications <_web_1_0_applications>
 As someone interested in web development, the above diagrams and discussion are

ch03-a-web-1-0-application.typ

@@ -155,12 +155,12 @@ the root, and this will become the handler for the root URL in our web
 application.
 
 The handler in this case is dead simple, it just returns a string,
-"Hello World!", to the client. This isn’t hypermedia yet, but a browser will
-render it just fine:
+"Hello World!", to the client. This isn’t hypermedia yet, but as we can see in @fig:helloworld, a browser will
+render it just fine.
 
 #figure([#image("images/figure_2-1_hello_world.png")], caption: [
   Hello World!
-])
+])<fig:helloworld>
 
 Great, there’s our first step into Flask, showing the core technique we are
 going to use to respond to HTTP requests: routes mapped to handlers.
@@ -432,10 +432,10 @@ And that’s our complete template. Using this simple server-side template, in
 combination with our handler method, we can respond with an HTML _representation_ of
 all the contacts requested. So far, so hypermedia.
 
-Here is what the template looks like, rendered with a bit of contact
-information:
+@fig:contactapp is what the template looks like, rendered with a bit of contact
+information.
 
-#figure(image("images/figure_2-2_table_etc.png"), caption: [Contact.app])
+#figure(image("images/figure_2-2_table_etc.png"), caption: [Contact.app])<fig:contactapp>
 
 Now, our application won’t win any design awards at this point, but notice that
 our template, when rendered, provides all the functionality necessary to see all

ch05-htmx-patterns.typ

@@ -666,11 +666,11 @@ they will be displayed in this span, which will be highlighted red.
   1.0 server-side frameworks.]
 
 The error message shown when a user attempts to save a contact with a duplicate
-email is "Email Must Be Unique":
+email is "Email Must Be Unique", as seen in @fig:emailerror.
 
 #figure([#image("images/screenshot_validation_error.png")], caption: [
   Email validation error
-])
+])<fig:emailerror>
 
 All of this is done using plain HTML and using Web 1.0 techniques, and it works
 well.
@@ -1099,9 +1099,9 @@ applications.
 
 #figure(
   caption: [A Click To Load UI], image("images/screenshot_click_to_load.png"),
-)
+)<fig:clicktoload>
 
-Here, you have a button that you can click, and it will load the next set of
+In @fig:clicktoload, you have a button that you can click, and it will load the next set of
 contacts directly into the page, rather than "paging" to the next page. This
 allows you to keep the current contacts "in context" visually on the page, but
 still progress through them as you would in a normal, paged user interface.

ch06-more-htmx-patterns.typ

@@ -657,12 +657,10 @@ contacts next to the link to add new contacts, to give them a sense of how large
 the contact database is. This sort of rapid development is one of the joys of
 developing web applications the old way.
 
-Here is what the feature looks like in our application:
+@fig-totalcontacts is what the feature looks like in our application. Beautiful.
 
 #figure(image("images/screenshot_total_contacts.png"),
-  caption: [Total contact count display])
-
-Beautiful.
+  caption: [Total contact count display])<fig-totalcontacts>
 
 Of course, as you probably suspected, all is not perfect. Unfortunately, upon
 shipping this feature to production, we start getting complaints from users that
@@ -937,9 +935,11 @@ page is re-rendered.
 #sidebar[A Style Sidebar][One side effect of adding this delete link is that we are starting to pile up
   the actions in a contact row:
 
-  #figure([#image("images/screenshot_stacked_actions.png")], caption: [
-    That’s a lot of actions
-  ])
+  #figure(
+    image("images/screenshot_stacked_actions.png"),
+    caption: [That’s a lot of actions],
+    placement: none,
+  )<fig:stacked-actions>
 
   It would be nice if we didn’t show the actions all in a row, and, additionally,
   it would be nice if we only showed the actions when the user indicated interest
@@ -1199,11 +1199,11 @@ Here is what the updated code for `rows.html` looks like:
 
 We’ll also need to add an empty column in the header for the table to
 accommodate the checkbox column. With that done we now get a series of check
-boxes, one for each row, a pattern no doubt familiar to you from the web:
+boxes, one for each row, a pattern no doubt familiar to you from the web (@fig:checkboxes).
 
 #figure(image("images/screenshot_checkboxes.png"), caption: [
   Checkboxes for our contact rows
-])
+])<fig:checkboxes>
 
 If you are not familiar with or have forgotten the way checkboxes work in HTML:
 a checkbox will submit its value associated with the name of the input if and

ch07-a-dynamic-archive-ui.typ

@@ -429,12 +429,10 @@ Finally, for completeness, here is the CSS we’ll use for this progress bar:
     box-shadow: inset 0 -1px 0 rgba(0,0,0,.15);
     transition: width .6s ease;
 }
-``` ]
-
-Which ends up rendering like this:
+```]<lst:progress-bar-css>
 
-#figure([#image("images/screenshot_progress_bar.png")], caption: [
-  Our CSS-Based Progress Bar
+#figure(image("images/screenshot_progress_bar.png"), caption: [
+  Our CSS-Based Progress Bar, as implemented in @lst:progress-bar-css
 ])
 
 ===== Adding The Progress Bar UI <_adding_the_progress_bar_ui>

ch09-client-side-scripting.typ

@@ -1467,17 +1467,15 @@ Given all that, our updated code will look like this:
 3. Handle the result of the user’s selection
 
 And now, when this button is clicked, we get a nice looking dialog in our web
-application:
-
-#figure([#image("images/screenshot_sweet_alert.png")], caption: [
-])
-
-Much nicer than the system confirmation dialog. Still, this feels a little
+application (@fig:swal-screenshot) --- much nicer than the system confirmation dialog. Still, this feels a little
 wrong. This is a lot of code to write just to trigger a slightly nicer `confirm()`,
 isn’t it? And the htmx JavaScript code we are using here feels awkward. It would
 be more natural to move the htmx out to attributes on the button, as we have
 been doing, and then trigger the request via events.
 
+#figure([#image("images/screenshot_sweet_alert.png")], caption: [
+])<fig:swal-screenshot>
+
 So let’s take a different approach and see how that looks.
 
 ===== Integrating using events <_integrating_using_events>

ch11-hyperview-a-mobile-hypermedia.typ

@@ -187,11 +187,11 @@ It may seem a little strange that developing a HDA using Hyperview requires a
 single-purpose client binary. After all, we don’t ask users to first download
 and install a binary to view a web app. No, users just enter a URL in the
 address bar of a general-purpose web browser. A single HTML client renders apps
-from any HTML server.
+from any HTML server (@fig:1clientmanyserver).
 
 #asciiart(
   read("images/diagram/one-client-many-servers.txt"), caption: [One HTML client, multiple HTML servers],
-)
+)<fig:1clientmanyserver>
 
 It is theoretically possible to build an equivalent general-purpose
 "Hyperview browser." This HXML client would render apps from any HXML server,
@@ -200,11 +200,11 @@ Android are built around the concept of single-purpose apps. Users expect to
 find and install apps from an app store, and launch them from the home screen of
 their device. Hyperview embraces this app-centric paradigm of today’s popular
 mobile platforms. That means that the HXML client (app binary) renders its UI
-from a single pre-configured HXML server:
+from a single pre-configured HXML server (@fig:1client1server).
 
 #asciiart(
   read("images/diagram/one-server-one-hxml-client.txt"), caption: [One HXML client, one HXML server],
-)
+)<fig:1client1server>
 
 Luckily, developers do not need to write a HXML client from scratch; the
 open-source client library does 99% of the work. And as we will see in the next