From b6f226cd6cf8c0bc27681aa39fdba17b89aa0977 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Mon, 20 Feb 2023 22:10:29 +0000
Subject: [PATCH] Explain how "macros" work in djot

---
 Makefile              |  3 +--
 doc/code-examples.lua |  8 ++++++++
 doc/syntax.css        | 14 ++++++++++++++
 doc/syntax.md         | 45 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index ee41d0c..0a8c141 100644
--- a/Makefile
+++ b/Makefile
@@ -2,6 +2,5 @@ VIMDIR?=~/.vim
 
 all: doc/syntax.html
 
-doc/syntax.html: doc/syntax.md
+doc/syntax.html: doc/syntax.md doc/syntax.css doc/code-examples.lua
 	pandoc --lua-filter doc/code-examples.lua $< -t html -o $@ -s --css doc/syntax.css --self-contained --wrap=preserve --toc --section-divs -Vpagetitle="Djot syntax reference"
-
diff --git a/doc/code-examples.lua b/doc/code-examples.lua
index 73814ff..8df6cdc 100644
--- a/doc/code-examples.lua
+++ b/doc/code-examples.lua
@@ -5,6 +5,14 @@ function renderdjot(txt)
 end
 
 function CodeBlock(el)
+  local lang = el.attr.classes[1]
+  if lang then
+    return {
+      pandoc.Div(
+      { pandoc.Div({pandoc.CodeBlock(el.text)}, {class=lang})
+      }, {class="example"})
+    }
+  end
   local rendered = renderdjot(el.text)
   return {
     pandoc.Div(
diff --git a/doc/syntax.css b/doc/syntax.css
index 7c75385..8ad91ce 100644
--- a/doc/syntax.css
+++ b/doc/syntax.css
@@ -212,3 +212,17 @@ ul.task-list{list-style: none;}
 .example code {
   font-size: 78%;
 }
+
+kbd {
+  background-color: #eee;
+  border-radius: 3px;
+  border: 1px solid #b4b4b4;
+  box-shadow: 0 1px 1px rgba(0, 0, 0, 0.2), 0 2px 0 0 rgba(255, 255, 255, 0.7) inset;
+  color: #333;
+  display: inline-block;
+  font-size: 0.85em;
+  font-weight: 700;
+  line-height: 1;
+  padding: 2px 4px;
+  white-space: nowrap;
+}
diff --git a/doc/syntax.md b/doc/syntax.md
index aeee124..c108976 100644
--- a/doc/syntax.md
+++ b/doc/syntax.md
@@ -781,6 +781,51 @@ See the [Epilogue][].
 # Epilogue
 ```
 
+## Syntax extensions
+
+Djot doesn't have macros or other built-in facilities to extend the syntax of
+the language. However, [divs](#div), [spans](#span), and
+[attributes](#block-attributes) allow achieving equivalent results by extending
+the way a djot document is converted to a target format.
+
+For example, djot doesn't have syntax for keyboard shortcuts like
+<kbd>ctrl</kbd> + <kbd>v</kbd>. Nevertheless, the appropriate semantics can be
+ascribed to spans with a `.kbd` class.
+
+By default, they will be rendered with `<span>` tags in HTML:
+
+```
+[ctrl + f]{.kbd}
+```
+
+By customizing the rendering, it's possible to change the output to the desired
+`<kbd>`:
+
+```html
+<kbd>ctrl</kbd> + <kbd>f</kbd>
+```
+
+For example, JavaScript implementation of djot allows overriding rendering of
+arbitrary elements:
+
+```ts
+{
+  span: (node: Span, r: HTMLRenderer) => {
+    if (hasClass(node, "kbd")) {
+      return getStringContent(node)
+        .split("+")
+        .map((key) => `<kbd>${key}</kbd>`)
+        .join("+");
+    }
+    return r.renderAstNodeDefault(node);
+  }
+}
+```
+
+Specific mechanisms for customizing rendering are implementation defined.
+However, all implementations are expected to provide facilities for customizing
+the output based on the Djot abstract syntax tree.
+
 ## Nesting limits
 
 Conforming implementations can impose reasonable limits on