From 5938ca8c3d6d9911b735e97ebd0d079405409c66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deniz=20Ak=C5=9Fim=C5=9Fek?= <deniz@denizaksimsek.com>
Date: Sat, 27 May 2023 17:42:06 +0300
Subject: [PATCH] make microformats note fit into preceding chapter

---
 book/CH10_JSONDataAPIs.adoc | 37 +++++++++++++------------------------
 1 file changed, 13 insertions(+), 24 deletions(-)

diff --git a/book/CH10_JSONDataAPIs.adoc b/book/CH10_JSONDataAPIs.adoc
index fdf7875..a87f48b 100644
--- a/book/CH10_JSONDataAPIs.adoc
+++ b/book/CH10_JSONDataAPIs.adoc
@@ -504,26 +504,12 @@ 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 dz4k: does this content fit here?
-// or, cut if you don't recommend using
 [.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.
-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.
-
+https://microformats.org/[Microformats] is a standard for embedding machine-readable structured data in HTML.
+It uses classes to mark certain elements as containing information to be extracted,
+with conventions for extracting common properties like name, URL and photo without classes.
 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]
@@ -533,8 +519,7 @@ By adding these classes into the HTML representation of an object, we allow the
 </a>
 ----
 
-can be parsed into this JSON-like structure:
-// maybe: briefly describe how
+can be parsed into this JSON-like structure by a microformats parser:
 
 
 [source,json]
@@ -544,7 +529,6 @@ can be parsed into this JSON-like structure:
   "properties": {
     "name": ["John Doe"],
     "photo": ["john.jpg"],
-    ""
     "url": ["https://john.example"]
   }
 }
@@ -552,9 +536,14 @@ can be parsed into this JSON-like structure:
 
 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.
+As explained in the above chapter, trying to use the same mechanism for human and machine interaction is not a good idea.
 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.
+If you want to expose domain-specific data and actions to users and developers, a JSON API is a great option.
+
+However, microformats are way easier to adopt.
+A protocol or standard that requires websites to implement a JSON API has a high technical barrier.
+In comparison, any website can be augmented with microformats simply by adding a few classes.
+Other HTML-embedded data formats like microdata, Open Graph are similarly easy to adopt.
+This makes microformats useful for cross-website (dare we say _web-scale_) systems like the https://indieweb.org[IndieWeb], which uses it pervasively.
+
 ****
\ No newline at end of file