From 3f4188b4aa25c9e0a6ca68425531c4200e669a6e Mon Sep 17 00:00:00 2001
From: clime <clime@fedoraproject.org>
Date: Jun 10 2021 15:34:38 +0000
Subject: [doc] clarify more, the diff between rpkg and rpm macros


---

diff --git a/doc/v3/macro_reference.rst b/doc/v3/macro_reference.rst
index 28562e8..3506935 100644
--- a/doc/v3/macro_reference.rst
+++ b/doc/v3/macro_reference.rst
@@ -15,6 +15,13 @@ Rpkg macro reference
     triple braces (e.g. ``{{{ <macro_name> }}}``) which are the ``preproc`` specific tags used
     to differentiate macro invocations from the normal text.
 
+    **The difference** between rpkg macro and standard rpm macro (``%macro`` or ``%(shell cmd)``)
+    is that rpm macros are re-evaluated when an srpm is built into rpm whereas rpkg macros are
+    evaluated only once at the beginning in the ``code -> srpm -> rpm`` build-chain. Therefore,
+    if a macro should use information being stripped off during srpm buld (e.g. git metadata),
+    then it should be an rpkg macro for created srpms (if any) to be valid. Otherwise, you may
+    also use rpkg macros any time you find them more convenient than rpm macros.
+
 Examples
 --------
 
diff --git a/macros/man/rpkg-macros.1 b/macros/man/rpkg-macros.1
index 36d8c16..33eb06b 100644
--- a/macros/man/rpkg-macros.1
+++ b/macros/man/rpkg-macros.1
@@ -41,6 +41,13 @@ Don\(aqt confuse it with \fIrpm macro\fP which is part of the rpm spec file synt
 "executed") by \fBpreproc\fP utility and you will therefore see them in a spec file enclosed
 triple braces (e.g. \fB{{{ <macro_name> }}}\fP) which are the \fBpreproc\fP specific tags used
 to differentiate macro invocations from the normal text.
+.sp
+\fBThe difference\fP between rpkg macro and standard rpm macro (\fB%macro\fP or \fB%(shell cmd)\fP)
+is that rpm macros are re\-evaluated when an srpm is built into rpm whereas rpkg macros are
+evaluated only once at the beginning in the \fBcode \-> srpm \-> rpm\fP build\-chain. Therefore,
+if a macro should use information being stripped off during srpm buld (e.g. git metadata),
+then it should be an rpkg macro for created srpms (if any) to be valid. Otherwise, you may
+also use rpkg macros any time you find them more convenient than rpm macros.
 .UNINDENT
 .UNINDENT
 .SH EXAMPLES