From 24655052d12cba9802ad140679fe3332015bb3ce Mon Sep 17 00:00:00 2001
From: Vhyrro <vhyrro@gmail.com>
Date: Sun, 2 Oct 2022 15:37:03 +0200
Subject: [PATCH] feat: expand macro tag section

---
 1.0-specification.norg | 29 +++++++++++++++++++++++------
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/1.0-specification.norg b/1.0-specification.norg
index 371b696..cc540a5 100644
--- a/1.0-specification.norg
+++ b/1.0-specification.norg
@@ -797,19 +797,36 @@ version: 1.0
     The content of the macro tag is /any/ norg markup - this includes {** structural detached
     modifiers} and nested {* tags}. The macro tag is closed with the `=end` statement.
 
-    %TODO: explain that generally speaking, all tags are implemented as macros%
-    %TODO: show example macro%
+    Under the hood, all other {* tags}[tag] types are implemented as macros with special parameters
+    and contents.
 
-    The `next` and `...` arguments are automatically supplied. See the {:1.0-semantics:}[semantics
-    document] for more details.
-
-    Example:
+    The following is an example of a macro:
     |example
     =see url
     (see {&url&})
     =end
     |end
 
+    It can then be invoked using any of the other tag types, for example the {** infirm tag}:
+    |example
+    This is a recipe for a cake
+    .see https://wikipedia.com/some-cool-cake-recipe
+    \- let's begin cooking!
+    |end
+
+    After macro expansion, this is what the document would look like:
+    |example
+    This is a recipe for a cake
+    (see {https://wikipedia.com/some-cool-cake-recipe})
+    \- let's begin cooking!
+    |end
+
+    Which, when reformatted, would look (and render) like so:
+    |example
+    This is a recipe for a cake (see {https://wikipedia.com/some-cool-cake-recipe}) - let's begin
+    cooking!
+    |end
+
 *** Standard Ranged Tags
     There are times where you may want to create an isolated block of Norg markup.
     To do this you may use the standard ranged tag, which uses the `|` character.