Add proper documentation about our different macro types and scopes

Explaining aliases needs context that we were missing before.
rpm-software-management · Oct 26, 2023 · 3a404fe · 3a404fe
1 parent e25c0b0
commit 3a404fe
Showing 1 changed file with 48 additions and 9 deletions.
diff --git a/docs/manual/macros.md b/docs/manual/macros.md
@@ -16,22 +16,31 @@ expansion of the macro which contains nested macros.
 
 ## Defining a Macro
 
-To define a macro use:
+The usual macro definition syntax is as follows:
 
 ```
 	%define <name>[(opts)] <body>
 ```
 
 All whitespace surrounding `<body>` is removed.  Name may be composed
 of alphanumeric characters and the character `_`, and must be at least
-3 characters in length. A macro without an `(opts)` field is "simple"
-in that only recursive macro expansion is performed. A parameterized
-macro contains an `(opts)` field. Since rpm >= 4.17 `-` as opts disables all option
-processing, otherwise the opts (i.e. string between parentheses) are passed
-exactly as is to getopt(3) for argc/argv processing at the beginning of
-a macro invocation (only short options are supported). `--` can be used
-to separate options from arguments. While a parameterized macro is being
-expanded, the following shell-like macros are available:
+3 characters in length. The body is (re-)expanded on each macro invocation.
+
+### Parametric macros
+A macro which contains an `(opts)` field is called parametric.
+The opts (i.e. string between parentheses) are passed exactly as is
+to to getopt(3) for argc/argv processing at the beginning of
+a macro invocation. Only short options are supported.
+`--` can be used to separate options from arguments.
+Since rpm >= 4.17 `-` as opts disables all option processing.
+
+Macros `%define`d inside a parametric macro have a scope local to the
+macro, otherwise all macros are global.
+
+### Automatic macros
+
+While a parameterized macro is being expanded, the following shell-like
+automatic macros are available:
 
 | Macro  | Description
 | ------ | -----------
@@ -55,6 +64,36 @@ With rpm >= 4.17 and disabled option processing the mentioned macros are defined
 At the end of invocation of a parameterized macro, the above macros are
 automatically discarded.
 
+### Global macros
+
+A macro can be declared into the global scope as follows:
+
+```
+	%global <name>[(opts)] <body>
+```
+
+An important and useful feature of `%global` is that the body is expanded
+at the time of definition, as opposed to time of use with regular macros.
+This is important inside parametric macros because otherwise the body could
+be referring to macros that are out of scope at the time of use, but also
+useful to avoid re-expansion of expensive macros.
+
+### Aliases (rpm >= 4.20)
+
+A macro alias can be declared as follows:
+
+```
+    %alias <name> <target>
+```
+
+A macro alias is just that: an another name for a macro. Aliases can point
+to any other macro type and using it behaves exactly as if accessing the
+original macro, parameters and all, with one exception: `%undefine <name>`
+undefines the alias, rather than the target macro. An alias always exists
+in the same scope as the target macro, so an alias defined on automatic
+or locally scoped macros inside parametric macros become automatically
+undefined when leaving the parametric macro.
+
 ## Writing a Macro
 
 Within the body of a macro, there are several constructs that permit