docs(hiccup): update readme

thi-ng · Jan 22, 2025 · c863a15 · c863a15
1 parent 42e7717
commit c863a15
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 15 deletions.
diff --git a/packages/hiccup/README.md b/packages/hiccup/README.md
@@ -37,6 +37,7 @@
   - [Component objects](#component-objects)
   - [Behavior control attributes](#behavior-control-attributes)
   - [Comments](#comments)
+  - [Inlined/embedded markup](#inlinedembedded-markup)
   - [XML / DTD processing instructions](#xml--dtd-processing-instructions)
 - [API](#api)
   - [serialize()](#serialize)
@@ -183,7 +184,7 @@ For Node.js REPL:
 const h = await import("@thi.ng/hiccup");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.20 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.24 KB
 
 ## Dependencies
 
@@ -391,7 +392,9 @@ serialize([div, {id: "foo"}, "bar"]);
 
 Also see
 [@thi.ng/hiccup-svg](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup-svg)
-for related functionality.
+and
+[@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom)
+for related (and more advanced) functionality.
 
 ```ts tangle:export/readme-circles.js
 import { serialize } from "@thi.ng/hiccup";
@@ -554,11 +557,10 @@ Re-formatted HTML output:
 
 The sibling library
 [@thi.ng/hdom](https://github.com/thi-ng/umbrella/tree/develop/packages/hdom)
-supports components with basic life cycle methods (init, render,
-release). In order to support serialization of hdom component trees,
-hiccup too supports such components since version 2.0.0. However, for
-static serialization only the `render` method is of interest and others
-are ignored.
+supports components with basic life cycle methods (init, render, release). To
+support serialization of hdom component trees, hiccup too supports such
+components since version 2.0.0. For static serialization only the `render`
+method is of interest and others are ignored.
 
 ```js
 const component = {
@@ -573,6 +575,7 @@ serialize([component, "Hello world", "Body"]);
 The following attributes can be used to control the serialization
 behavior of individual elements / tree branches:
 
+- **`__escape`** - boolean flag to enable/disable entity escaping
 - **`__skip`** - if true, skips serialization (also used by
   [@thi.ng/hdom](https://github.com/thi-ng/umbrella/tree/develop/packages/hdom))
 - **`__serialize`** - if false, skips serialization (hiccup only)
@@ -585,7 +588,7 @@ serialize(["div.container", ["div", { __skip: true }, "ignore me"]]);
 ### Comments
 
 Single or multiline comments can be included using the special `COMMENT`
-tag (`__COMMENT__`) (always WITHOUT attributes!).
+tag (or `__COMMENT__`, always WITHOUT attributes!).
 
 ```ts
 import { COMMENT } from "@thi.ng/hiccup";
@@ -601,6 +604,22 @@ import { COMMENT } from "@thi.ng/hiccup";
 // -->
 ```
 
+### Inlined/embedded markup
+
+Pre-serialized markup can be inlined without any further processing using the
+special `INLINE` tag (or `__INLINE__`, always WITHOUT attributes!):
+
+```js
+import { INLINE, serialize } from "@thi.ng/hiccup";
+
+serialize(
+    ["div", {}
+        [INLINE, "<h3>Inlined &amp; Embedded</h3><p>Lorem ipsum...</p>"]
+    ]
+);
+// <div><h3>Inlined &amp; Embedded</h3><p>Lorem ipsum...</p></div>
+```
+
 ### XML / DTD processing instructions
 
 Currently, the only processing / DTD instructions supported are:

diff --git a/packages/hiccup/tpl.readme.md b/packages/hiccup/tpl.readme.md
@@ -278,7 +278,9 @@ serialize([div, {id: "foo"}, "bar"]);
 
 Also see
 [@thi.ng/hiccup-svg](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup-svg)
-for related functionality.
+and
+[@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom)
+for related (and more advanced) functionality.
 
 ```ts tangle:export/readme-circles.js
 import { serialize } from "@thi.ng/hiccup";
@@ -441,11 +443,10 @@ Re-formatted HTML output:
 
 The sibling library
 [@thi.ng/hdom](https://github.com/thi-ng/umbrella/tree/develop/packages/hdom)
-supports components with basic life cycle methods (init, render,
-release). In order to support serialization of hdom component trees,
-hiccup too supports such components since version 2.0.0. However, for
-static serialization only the `render` method is of interest and others
-are ignored.
+supports components with basic life cycle methods (init, render, release). To
+support serialization of hdom component trees, hiccup too supports such
+components since version 2.0.0. For static serialization only the `render`
+method is of interest and others are ignored.
 
 ```js
 const component = {
@@ -460,6 +461,7 @@ serialize([component, "Hello world", "Body"]);
 The following attributes can be used to control the serialization
 behavior of individual elements / tree branches:
 
+- **`__escape`** - boolean flag to enable/disable entity escaping
 - **`__skip`** - if true, skips serialization (also used by
   [@thi.ng/hdom](https://github.com/thi-ng/umbrella/tree/develop/packages/hdom))
 - **`__serialize`** - if false, skips serialization (hiccup only)
@@ -472,7 +474,7 @@ serialize(["div.container", ["div", { __skip: true }, "ignore me"]]);
 ### Comments
 
 Single or multiline comments can be included using the special `COMMENT`
-tag (`__COMMENT__`) (always WITHOUT attributes!).
+tag (or `__COMMENT__`, always WITHOUT attributes!).
 
 ```ts
 import { COMMENT } from "@thi.ng/hiccup";
@@ -488,6 +490,22 @@ import { COMMENT } from "@thi.ng/hiccup";
 // -->
 ```
 
+### Inlined/embedded markup
+
+Pre-serialized markup can be inlined without any further processing using the
+special `INLINE` tag (or `__INLINE__`, always WITHOUT attributes!):
+
+```js
+import { INLINE, serialize } from "@thi.ng/hiccup";
+
+serialize(
+	["div", {}
+		[INLINE, "<h3>Inlined &amp; Embedded</h3><p>Lorem ipsum...</p>"]
+	]
+);
+// <div><h3>Inlined &amp; Embedded</h3><p>Lorem ipsum...</p></div>
+```
+
 ### XML / DTD processing instructions
 
 Currently, the only processing / DTD instructions supported are: