From 87245edbc1d7cd5b1731139e5ff0384f3557d81b Mon Sep 17 00:00:00 2001
From: clime <clime@fedoraproject.org>
Date: Apr 30 2021 16:07:02 +0000
Subject: extend macro reference with custom user macros and tips and tricks


---

diff --git a/doc/v3/macro_reference.rst b/doc/v3/macro_reference.rst
index 2247694..352f76c 100644
--- a/doc/v3/macro_reference.rst
+++ b/doc/v3/macro_reference.rst
@@ -733,3 +733,68 @@ Packs the git repository content by using ``git archive``.
 Outputs rpm's ``%setup`` macro with ``dir_name`` (``-n`` argument of ``%setup``) generated
 from basename of the repository remote URL. If you used ``git_repo_pack`` or ``git_repo_archive``
 for packing, use this macro in ``%prep`` spec file section for preparing the sources for rpm build.
+
+.. _user_defined_macros_v3:
+
+User-defined macros
+-------------------
+
+You can define your own rpkg macros that are basically just standard bash functions defined
+in a certain file in your project. Let's say you name the file ``rpkg.macros`` and you have it
+placed in top-level directory of your git project. To let rpkg know about this file and about
+the custom macros inside, you should set ``rpkg.user_macros`` option to ``"${git_props:root}/rpkg.macros"``.
+
+When used in spec file, standard output of your custom macro will be captured and the
+``{{{ <macro_name> }}}`` invocation will be replaced with it.
+
+Example of a custom macro placed in ``rpkg.macros`` file:
+
+.. code-block:: sh
+
+    function my_git_commits_no {
+        total_commits=$(git rev-list --all --count)
+        echo -n "$total_commits"
+    }
+
+You can then use this macro in your spec file to e.g. specify ``Release`` tag value:
+
+.. code-block:: spec
+
+    Release: {{{ my_git_commits_no }}}
+
+Calling ``rpkg spec`` will then produce a spec file with the following line in the content:
+
+.. code-block:: spec
+
+    Release: 267
+
+supposing the total number of commits in your project is 267.
+
+Instead of ``echo -n <output>``, you can also use ``output <output>`` command
+which comes directly from rpkg's standard bash library. This command
+will first cache the output value under ``<macro_name>`` key and only
+afterwards, it will echo the value to stdout.
+
+You can later access this value by ``${OUTPUT[my_git_commits_no]}``, which might
+become handy, for example, if computing your output is computionally demanding
+and you need to compute that same value more than once.
+
+Example usage:
+
+.. code-block:: sh
+
+    function my_git_commits_no {
+        total_commits=${OUTPUT[my_git_commits_no]}
+
+        if [ -z "$total_commits" ]; then
+            total_commits=$(git rev-list --all --count)
+        fi
+
+        output "$total_commits"
+    }
+
+**Tips and tricks:**
+
+To get proper bash highlighting in ``rpkg.macros`` in your favourite editor of choice,
+you can put ``#!/bin/bash`` shebang at the beginning. Alternatively for vim, you can
+use ``#<white>vim:syntax=sh`` directive where ``<white>`` can be a space or tab.