Repository: rpm-software-management/rpm
Pull request #3702: Add man pages to explain rpm runtime macro configuration
Author: login: pmatilai
Created: 2025-04-03T09:03:57Z | Merged: 2025-04-04T12:48:08Z

Turns out we need to add both rpm-rpmrc(5) and rpm-config(5) at once to explain the configuration adequately. Note that this differs from rpm-macrofile(5) which is a generic format usable for other purposes as well, but rpmrc is strictly tied to the path processing etc so there's no separating the format and how it gets processed.

Fixes: #3620
Fixes: #3614


Diff:
diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index 9c05d51b64..d180870683 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -2,7 +2,7 @@ set(core
 	gendiff.1 rpm2cpio.1 rpm2archive.1
 	rpm.8 rpmbuild.1 rpmdb.8 rpmkeys.8 rpmsign.1 rpmspec.1
 	rpmdeps.1 rpmgraph.1 rpmlua.1 rpm-common.8 rpmsort.1
-	rpm-macrofile.5 rpm-setup-autosign.1
+	rpm-macrofile.5 rpm-config.5 rpm-rpmrc.5 rpm-setup-autosign.1
 )
 set(extra
 	rpm-plugins.8 rpm-plugin-prioreset.8 rpm-plugin-syslog.8
diff --git a/docs/man/rpm-common.8.scd b/docs/man/rpm-common.8.scd
index d122098f03..fb1140779d 100644
--- a/docs/man/rpm-common.8.scd
+++ b/docs/man/rpm-common.8.scd
@@ -157,53 +157,6 @@ On success, 0 is returned, a non-zero failure code otherwise.
 
 # FILES
 
-## rpmrc Configuration
-
-Each file in the colon separated rpmrc path is read sequentially by
-*rpm* for configuration information. Only the first file in the
-list must exist, and tildes will be expanded to the value of
-*$HOME*. The default rpmrc path is as follows:
-
-```
-/usr/lib/rpm/rpmrc:
-/usr/lib/rpm/<vendor>/rpmrc:
-/etc/rpmrc:
-~/.config/rpm/rpmrc
-```
-
-If *XDG_CONFIG_HOME* environment variable is set, it replaces _~/.config_
-in the path.
-
-In older rpm versions the path of per-user rpmrc was _~/.rpmrc_.
-This is still processed if it exists and the new configuration directory
-does not exist.
-
-## Macro Configuration
-
-Each file or *glob*(7) pattern in the colon-separated macro path is
-read sequentially by *rpm* for macro definitions. Tildes will be expanded
-to the value of the environment variable *HOME*. The default macro path
-is as follows:
-
-```
-/usr/lib/rpm/macros:
-/usr/lib/rpm/macros.d/macros.*:
-/usr/lib/rpm/platform/%{\_target}/macros:
-/usr/lib/rpm/fileattrs/*.attr:
-/usr/lib/rpm/<vendor>/macros:
-/etc/rpm/macros.*:
-/etc/rpm/macros:
-/etc/rpm/%{\_target}/macros:
-~/.config/rpm/macros
-```
-
-If *XDG_CONFIG_HOME* environment variable is set, it replaces _~/.config_
-in the path.
-
-In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
-This is still processed if it exists and the new configuration directory
-does not exist.
-
 ## Database
 
 ```
@@ -217,4 +170,4 @@ does not exist.
 ```
 
 # SEE ALSO
-*popt*(3), *rpm*(8)
+*popt*(3), *rpm*(8) *rpm-config*(5), *rpm-rpmrc*(5)
diff --git a/docs/man/rpm-config.5.scd b/docs/man/rpm-config.5.scd
new file mode 100644
index 0000000000..4772bd031c
--- /dev/null
+++ b/docs/man/rpm-config.5.scd
@@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# FILES
+_/usr/lib/rpm/macros_++
+_/usr/lib/rpm/macros.d/macros.\*_++
+_/usr/lib/rpm/platform/%{\_target}/macros_++
+_/usr/lib/rpm/fileattrs/\*.attr_++
+_/usr/lib/rpm/<vendor>/macros_++
+_/etc/rpm/macros.\*_++
+_/etc/rpm/macros_++
+_/etc/rpm/%{\_target}/macros_++
+_~/.config/rpm/macros_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the _macro path_.
+
+Each file or *glob*(7) pattern in the colon-separated _macro path_ is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+_macro path_ uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default _macro path_ can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy*: Dummy backend (no actual functionality)
+	- *bdb_ro*: Berkeley DB (read-only)
+	- *ndb*: Native database (no external dependencies)
+	- *sqlite*: Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs*: Plain ASCII files in a directory
+	- *openpgp*: Shared OpenPGP certificate directory
+	- *rpmdb*: Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0*: disable
+	- *1*: enable
+	- *-1*: (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
+	Location of passwd(5) files as : separated list
+
+*%\_pkgverify_flags* _VSFLAGS_
+	Transaction package verification flags, used for fine-grained
+	control of *%\_pkgverify_level* operation.
+	Set to 0x0 for full compatibility with v4 packages.
+
+*%\_pkgverify_level* _MODE_
+	Enforced package verification mode in transactions,
+	where _MODE_ is one of:
+	- *all*: require valid digest(s) and signature(s)
+	- *signature*: require valid signature(s)
+	- *digest*: require valid digest(s)
+	- *none*: legacy rpm behavior, nothing required
+
+*%\_prefer_color* _VALUE_
+	Package conflict resolution in bi-arch transactions.
+	See also *%\_transaction_color*. Possible values are:
+	- *0*: disabled
+	- *1*: prefer 32-bit packages
+	- *2*: prefer 64-bit packages
+
+*%\_\_plugindir* _DIRECTORY_
+	Transaction plugin directory.
+
+*%\_query_all_fmt* _FORMAT_
+	Default output format string for rpm -qa.
+	*%* signs need to be escaped, eg. *%%{nevra}*.
+
+*%\_rpmlock_path* _FILE_
+	The path of the file used for transaction fcntl lock.
+
+*%\_tmppath* _PATH_
+	The directory where temporary files are created.
+
+*%\_\_urlhelpercmd* _EXECUTABLE_
+	The executable to use for retrieving remote files.
+
+*%\_\_urlhelperopts* _OPTIONS_
+	Generic options to pass to the *%\_\_urlhelpercmd* command.
+
+*%\_\_urlhelper_localopts* _OPTIONS_
+	User/host specific options to pass to the *%\_\_urlhelpercmd* command.
+
+*%\_\_urlhelper_proxyopts* _OPTIONS_
+	Proxy options to pass to the *%\_\_urlhelpercmd* command.
+
+*%\_urlhelper* _COMMAND_
+	Full command (with options) to use when retrieving remote files.
+	Normally pieced together from the double-underscore *%\_\_urlhelper\**
+	macros.
+
+*%\_transaction_color* _VALUE_
+	Package and file conflict behavior in bi-arch transactions.
+	See also *%\_prefer_color*. Possible values are:
+	- *0*: do not consider "colors", only use arch compatibility map
+	- *1*: only allow 32-bit packages
+	- *2*: only allow 64-bit packages
+	- *3*: allow 32- and 64-bit packages to share files
+
+*%\_vsflags_erase* _VSFLAGS_
+	Transaction verification flags used when erasing or updating packages.
+
+*%\_vsflags_install* _VSFLAGS_
+	Transaction verification flags used when installing packages.
+
+*%\_vsflags_query* _VSFLAGS_
+	Transaction verification flags used when querying packages.
+
+*%\_vsflags_rebuilddb* _VSFLAGS_
+	Transaction verification flags used when rebuilding the database.
+
+*%\_vsflags_verify* _VSFLAGS_
+	Transaction verification flags used when verifying packages.
+
+## Verification flags
+Digest/signature verification flags for various rpm operations are controlled
+by a bitmask known as _VSFLAGS_. These flags control various aspects
+of digital checksum and signature verification when reading rpm package
+files and their headers.
+
+_VSFLAGS_ is formed by bitwise or'ing the individual flags:
+- *0x00001* (RPMVSF_NOHDRCHK): don't verify headers from rpmdb
+- *0x00100* (RPMVSF_NOSHA1HEADER): don't verify header SHA1 digest
+- *0x00200* (RPMVSF_NOSHA256HEADER): don't verify header SHA255 digest
+- *0x00400* (RPMVSF_NODSAHEADER): don't verify header DSA signature(s)
+- *0x00800* (RPMVSF_NORSAHEADER): don't verify header RSA signature(s)
+- *0x01000* (RPMVSF_NOOPENPGP): don't verify header OpenPGP signature(s)
+- *0x10000* (RPMVSF_NOPAYLOAD): don't verify package payload digest
+- *0x20000* (RPMVSF_NOMD5): don't verify legacy header+payload MD5 digest
+- *0x40000* (RPMVSF_NODSA): don't verify legacy header+payload DSA signature
+- *0x80000* (RPMVSF_NORSA): don't verify legacy header+payload RSA signature
+
+RPM's Python bindings can be helpful for working with these values,
+for example:
+```
+>>> import rpm
+>>> hex(rpm.RPMVSF_NOSHA1HEADER)
+'0x100'
+>>> hex(rpm.RPMVSF_NOSHA1HEADER|rpm.RPMVSF_NOMD5)
+'0x20100'
+>>>
+```
+
+# ENVIRONMENT
+If *XDG_CONFIG_HOME* environment variable is set, it replaces _~/.config_
+in the _macro path_.
+
+# SEE ALSO
+*rpm*(8), *rpm-common*(8), *rpm-macrofile*(5), *rpm-rpmrc*(5)
diff --git a/docs/man/rpm-man-template.scd b/docs/man/rpm-man-template.scd
index a270c2fe9e..aca571e345 100644
--- a/docs/man/rpm-man-template.scd
+++ b/docs/man/rpm-man-template.scd
@@ -76,7 +76,7 @@ Typographic conventions:
 - Put option aliases on separate lines
 - Put option arguments with pre-determined values into <> (see below)
 
-See *rpm.common*(8) for the options common to all *rpm* executables.
+See *rpm-common*(8) for the options common to all *rpm* executables.
 
 *-d*,
 *--do-this*
@@ -124,7 +124,7 @@ if necessary.
 List main configurables affecting this program here, but don't describe.
 If the command has no relevant configuration, delete this section.
 
-See *rpm.config*(5) for details:
+See *rpm-config*(5) for details:
 - *%\_bar_mode*
 - *%\_foo_mode*
 
@@ -155,6 +155,6 @@ Describe files specific to this command.
 Delete this section if there are none.
 
 # SEE ALSO
-*rpm*(8) *rpm.common*(8) *popt*(3)
+*rpm*(8) *rpm-common*(8) *rpm-config*(5) *popt*(3)
 
 *http://www.rpm.org/*
diff --git a/docs/man/rpm-rpmrc.5.scd b/docs/man/rpm-rpmrc.5.scd
new file mode 100644
index 0000000000..6595717ba2
--- /dev/null
+++ b/docs/man/rpm-rpmrc.5.scd
@@ -0,0 +1,100 @@
+RPM-RPMRC(5)
+
+# NAME
+*rpm-rpmrc* - rpm platform compatibility configuration
+
+# SYNOPSIS
+_VARIABLE_: {_ARCH_|_OS_}: _VALUE_ ...
+
+_VARIABLE_: _ARCH_ _VALUE_
+
+# FILES
+_/usr/lib/rpm/rpmrc_++
+_/usr/lib/rpm/<vendor>/rpmrc_++
+_/etc/rpmrc_++
+_~/.config/rpm/rpmrc_
+
+# DESCRIPTION
+The low-level machine architecture and OS configuration in *rpm* is
+managed via a set of rpmrc files as defined by the _rpmrc path_.
+Most users never need to look at, much less touch these files.
+
+Each file in the colon separated _rpmrc path_ is read sequentially by
+*rpm* for configuration information. Tildes will be expanded to the
+value of the environment variable *HOME*.
+The first file in the path must exist, others are considered optional.
+
+If a value is defined multiple times, the last entry wins. The default
+_rpmrc path_ uses this to achieve the following hierarchy of platform
+configuration:
+. Generic *rpm* factory defaults
+. Vendor (distribution) specific configuration
+. Host specific configuration
+. User specific configuration
+
+In older rpm versions the path of per-user rpmrc was _~/.rpmrc_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+_ARCH_ and _OS_ relate to *uname*(2) machine and operating system
+information, but are not 1:1 equivalent.
+The following directives are supported in the rpmrc files:
+
+*arch_canon* _ARCH_: _CANON_ARCH_ _ARCH_NUM_
+	Names and numbers of known architectures to
+	alias different spellings to a canonical one.
+	_CANON_ARCH_ is what the _ARCH_ entries in other rpmrc
+	directives refer to.
+
+	The number is not used for any calculations by *rpm* but
+	must be present for historical reasons.
+
+*arch_compat*: _ARCH_: _COMPAT_ARCH_ ...
+	Declare compatibility between machine architectures,
+	ie. _ARCH_ machines can install packages for _COMPAT_ARCH_
+	architecture.
+
+*archcolor*: _ARCH_ _COLOR_
+	Declare the "color" of _ARCH_. The color relates to the word length
+	aka bitness of the architecture:
+	- *0* means none (noarch packages and similar)
+	- *1* means 32-bit
+	- *2* means 64-bit
+
+*buildarch_compat*: _ARCH_: _COMPAT_ARCH_ ...
+	Declare compatibility between build architectures targets,
+	ie. _ARCH_ machines can produce _COMPAT_ARCH_ binaries.
+
+*buildarchtranslate*: _ARCH_: _TRANSLATE_ARCH_
+	Automatically translate detected host architecture _ARCH_ to
+	_TRANSLATE_ARCH_ when building packages. This is used to map
+	sub-architectures to a main one, for example when building on a
+	*x86_64_v2* host we typically want the generated package to be
+	of the main *x86_64* architecture.
+
+*optflags*: _ARCH_ _OPTFLAGS_
+	Compiler flags to use when building packages for _ARCH_ architecture.
+	The _OPTFLAGS_ value is available as *%{optflags}* macro in
+	spec files.
+
+*os_canon*: _OS_: _CANON_OS_ _OS_NUM_
+	Names and numbers of known operating systems to
+	alias different spellings to a canonical one.
+	_CANON_OS_ is what the _OS_ entries in other rpmrc directives
+	refer to.
+
+	The number is not used for any calculations by *rpm* but
+	must be present for historical reasons.
+
+*os_compat*: _OS_: _COMPAT_OS_ ...
+	Declare compatibility between operating systems, ie.
+	_OS_ machine can install packages for _COMPAT_OS_ operating
+	system.
+
+# ENVIRONMENT
+If *XDG_CONFIG_HOME* environment variable is set, it replaces _~/.config_
+in the _rpmrc path_.
+
+# SEE ALSO
+*rpm*(8), *rpm-common*(8), *rpm-config*(5)
diff --git a/docs/man/rpm.8.scd b/docs/man/rpm.8.scd
index b5cd551910..0e2d328589 100644
--- a/docs/man/rpm.8.scd
+++ b/docs/man/rpm.8.scd
@@ -654,7 +654,7 @@ unique to verify mode are:
 On success, 0 is returned, a non-zero failure code otherwise.
 
 # FILES
-See *rpm-common*(8).
+See *rpm-common*(8), *rpm-config*(5) and *rpm-rpmrc*(5).
 
 # SEE ALSO
 *rpm-common*(8), *popt*(3), *rpm2cpio*(1), *rpmbuild*(1), *rpmdb*(8),
diff --git a/docs/man/rpmkeys.8.scd b/docs/man/rpmkeys.8.scd
index b950b0ed68..45b38d9f30 100644
--- a/docs/man/rpmkeys.8.scd
+++ b/docs/man/rpmkeys.8.scd
@@ -99,7 +99,7 @@ See *rpm-common*(8) for the options common to all *rpm* executables.
 # CONFIGURATION
 
 There are several configurables affecting the behavior of this
-verification, see *rpm.config*(5) for details:
+verification, see *rpm-config*(5) for details:
 - *%\_keyring*
 - *%\_keyringpath*
 - *%\_pkgverify_flags*
@@ -121,7 +121,7 @@ On success, 0 is returned, a non-zero failure code otherwise.
 	Verify hello-2.0-1.x86_64.rpm package file.
 
 # SEE ALSO
-*popt*(3), *rpm*(8), *rpm-common*(8), *rpmsign*(1)
+*popt*(3), *rpm*(8), *rpm-common*(8), *rpm-config*(5), *rpmsign*(1)
 
 *rpmkeys --help* - as rpm supports customizing the options via popt
 aliases it's impossible to guarantee that what's described in the
diff --git a/macros.in b/macros.in
index 3ee59f80e3..c161ae7615 100644
--- a/macros.in
+++ b/macros.in
@@ -1,11 +1,7 @@
-#/*! \page config_macros Default configuration: @RPM_CONFIGDIR@/macros
-# \verbatim
-#
 # This is a global RPM configuration file. All changes made here will
-# be lost when the rpm package is upgraded. Any per-system configuration
-# should be added to /etc/rpm/macros, while per-user configuration should
-# be added to ~/.rpmmacros.
+# be lost when the rpm package is upgraded.
 #
+# See rpm-macrofile(5) and rpm-config(5) for more information.
 
 #==============================================================================
 # ---- A macro that expands to nothing.


Reviews:
user: login: Conan-Kudo
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-03T13:10:09Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T08:52:08Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T08:53:52Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T08:57:53Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T09:10:54Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T09:17:54Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T09:29:27Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T09:30:36Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T09:43:44Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T09:44:21Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T09:44:59Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T09:54:14Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T09:58:09Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T10:15:56Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T10:24:15Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T10:31:13Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T10:37:16Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T10:57:59Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T10:58:25Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T11:00:39Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T11:02:53Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T11:16:08Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T11:35:22Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T11:36:11Z
user: login: dmnks
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T11:37:57Z
user: login: pmatilai
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-04T11:49:55Z

Review comments:
diff_hunk: @@ -0,0 +1,100 @@
+RPM-RPMRC(5)
+
+# NAME
+*rpm-rpmrc* - rpm platform compatibility configuration
+
+# SYNOPSIS
+_VARIABLE_: {_ARCH_|_OS_}: _VALUE_ ...
+
+_VARIABLE_: _ARCH_ _VALUE_
+
+# DESCRIPTION
+The low-level machine architecture and OS configuration in *rpm* is
+managed via a set of rpmrc files as defined by the rpmrc path.
+Most users never need to look at, much less touch these files.
+
+Each file in the colon separated rpmrc path is read sequentially by
+*rpm* for configuration information. Tildes will be expanded to the
+value of the environment variable *HOME*.
+The first file in the path must exist, others are considered optional.
+
+If a value is defined multiple times, the last entry wins. The default
+rpmrc path uses this to achieve the following hierarchy of platform
+configuration:
+. Generic *rpm* factory defaults
+. Vendor (distribution) specific configuration
+. Host specific configuration
+. User specific configuration
+
+In older rpm versions the path of per-user rpmrc was _~/.rpmrc_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+_ARCH_ and _OS_ relate to *uname*(2) machine and operating system
+information, but are not 1:1 equivalent.
+The following directives are supported in the rpmrc files:
+
+*arch_canon* _ARCH_: _CANON_ARCH_ _ARCH_NUM_
path: docs/man/rpm-rpmrc.5.scd
user: login: dmnks
body: I'm still confused by this directive (so the description perhaps doesn't do justice) :sweat_smile: As in, what is actually being aliased to what. Is it `_ARCH_` being declared as an alias to `_CANON_ARCH_`?
created_at: 2025-04-04T08:52:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,100 @@
+RPM-RPMRC(5)
+
+# NAME
+*rpm-rpmrc* - rpm platform compatibility configuration
+
+# SYNOPSIS
+_VARIABLE_: {_ARCH_|_OS_}: _VALUE_ ...
+
+_VARIABLE_: _ARCH_ _VALUE_
+
+# DESCRIPTION
+The low-level machine architecture and OS configuration in *rpm* is
+managed via a set of rpmrc files as defined by the rpmrc path.
+Most users never need to look at, much less touch these files.
+
+Each file in the colon separated rpmrc path is read sequentially by
+*rpm* for configuration information. Tildes will be expanded to the
+value of the environment variable *HOME*.
+The first file in the path must exist, others are considered optional.
+
+If a value is defined multiple times, the last entry wins. The default
+rpmrc path uses this to achieve the following hierarchy of platform
+configuration:
+. Generic *rpm* factory defaults
+. Vendor (distribution) specific configuration
+. Host specific configuration
+. User specific configuration
+
+In older rpm versions the path of per-user rpmrc was _~/.rpmrc_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+_ARCH_ and _OS_ relate to *uname*(2) machine and operating system
+information, but are not 1:1 equivalent.
+The following directives are supported in the rpmrc files:
+
+*arch_canon* _ARCH_: _CANON_ARCH_ _ARCH_NUM_
path: docs/man/rpm-rpmrc.5.scd
user: login: dmnks
body: Eh, after reading the line that follows once again ("CANON_ARCH is what the ARCH entries in other rpmrc directives refer to."), I think I'm getting it now :smile: ARCH is indeed an alias to CANON_ARCH.
created_at: 2025-04-04T08:53:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,100 @@
+RPM-RPMRC(5)
+
+# NAME
+*rpm-rpmrc* - rpm platform compatibility configuration
+
+# SYNOPSIS
+_VARIABLE_: {_ARCH_|_OS_}: _VALUE_ ...
+
+_VARIABLE_: _ARCH_ _VALUE_
+
+# DESCRIPTION
+The low-level machine architecture and OS configuration in *rpm* is
+managed via a set of rpmrc files as defined by the rpmrc path.
+Most users never need to look at, much less touch these files.
+
+Each file in the colon separated rpmrc path is read sequentially by
+*rpm* for configuration information. Tildes will be expanded to the
+value of the environment variable *HOME*.
+The first file in the path must exist, others are considered optional.
+
+If a value is defined multiple times, the last entry wins. The default
+rpmrc path uses this to achieve the following hierarchy of platform
+configuration:
+. Generic *rpm* factory defaults
+. Vendor (distribution) specific configuration
+. Host specific configuration
+. User specific configuration
+
+In older rpm versions the path of per-user rpmrc was _~/.rpmrc_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+_ARCH_ and _OS_ relate to *uname*(2) machine and operating system
+information, but are not 1:1 equivalent.
+The following directives are supported in the rpmrc files:
+
+*arch_canon* _ARCH_: _CANON_ARCH_ _ARCH_NUM_
+	Names and numbers of known architectures to
+	alias different spellings to a canonical one.
+	_CANON_ARCH_ is what the _ARCH_ entries in other rpmrc
+	directives refer to.
+
+	The number is not used for any calculations by *rpm* but
+	must be present for historical reasons.
+
+*arch_compat*: _ARCH_: _COMPAT_ARCH_ ...
+	Declare compatibility between machine architectures,
+	ie. _ARCH_ machines can install packages for _COMPAT_ARCH_
+	architecture.
+
+*archcolor*: _ARCH_ _COLOR_
+	Declare the "color" of _ARCH_. The color relates to the word length
+	aka bitness of the architecture:
+	- *0* means none (noarch packages and similar)
+	- *1* means 32-bit
+	- *2* means 64-bit
+
+*buildarch_compat*: _ARCH_: _COMPAT_ARCH_ ...
+	Declare compatibility between build architectures targets,
+	ie. _ARCH_ machines can produce _COMPAT_ARCH_ binaries.
+
+*buildarchtranslate*: _ARCH_: _TRANSLATE_ARCH_
+	Automatically translate detected host architecture _ARCH_ to
+	_TRANSLATE_ARCH_ when building packages. This is used to map
+	sub-architectures to a main one, for example when building on a
+	*x86_64_v2* host we typically want the generated package to be
+	of the main *x86_64* architecture.
+
+*optflags*: _ARCH_ _OPTFLAGS_
+	Compiler flags to use when building packages for _ARCH_ architecture.
+	The _OPTFLAGS_ value is available as *%{optflags}* macro in
+	spec files.
+
+*os_canon*: _OS_: _CANON_OS_ _OSNUM_
path: docs/man/rpm-rpmrc.5.scd
user: login: dmnks
body: Very much cosmetic: Use `OS_NUM` for consistency with `ARCH_NUM`
created_at: 2025-04-04T08:57:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: I feel like "macro path" should be emphasized (underlined) here as it's basically a term that's later referred to in the text.
created_at: 2025-04-04T09:10:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Proof-reading @dmnks goes "yay!"
created_at: 2025-04-04T09:17:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Cosmetic: These bullets should probably have a colon, e.g. "dummy: Dummy backend", based on the template scd file. That said, I don't mind really, it's readable this way, too (and minimal too) since the separation is there based on bold typeface.
created_at: 2025-04-04T09:29:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: Oh, I forgot the template has a case for this :facepalm: I didn't like the style here and wondered what to do about it, so I'll update to the : convention, there are more of these IIRC.
created_at: 2025-04-04T09:30:36Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
+	- *bdb_ro* Berkeley DB (read-only)
+	- *ndb* Native database (no external dependencies)
+	- *sqlite* Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs* Plain ASCII files in a directory
+	- *openpgp* Shared OpenPGP certificate directory
+	- *rpmdb* Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0* disable
+	- *1* enable
+	- *-1* (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Maybe move this next to _group_path?
created_at: 2025-04-04T09:43:44Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
+	- *bdb_ro* Berkeley DB (read-only)
+	- *ndb* Native database (no external dependencies)
+	- *sqlite* Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs* Plain ASCII files in a directory
+	- *openpgp* Shared OpenPGP certificate directory
+	- *rpmdb* Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0* disable
+	- *1* enable
+	- *-1* (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Argh, it's sorted alphabetically, just noticed :smile: Nevermind then.
created_at: 2025-04-04T09:44:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
+	- *bdb_ro* Berkeley DB (read-only)
+	- *ndb* Native database (no external dependencies)
+	- *sqlite* Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs* Plain ASCII files in a directory
+	- *openpgp* Shared OpenPGP certificate directory
+	- *rpmdb* Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0* disable
+	- *1* enable
+	- *-1* (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: Logically they belong together of course, but the list is now in alphabetical order.
created_at: 2025-04-04T09:44:59Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
+	- *bdb_ro* Berkeley DB (read-only)
+	- *ndb* Native database (no external dependencies)
+	- *sqlite* Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs* Plain ASCII files in a directory
+	- *openpgp* Shared OpenPGP certificate directory
+	- *rpmdb* Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0* disable
+	- *1* enable
+	- *-1* (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
+	Location of passwd(5) files as : separated list
+
+*%\_pkgverify_flags* _VSFLAGS_
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: I'd add something like "See Verification flags for details" here... but then, we'd have to add the same to each of the `%_vsflags_*` macros below, at which point it becomes quite hysterical...
created_at: 2025-04-04T09:54:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
+	- *bdb_ro* Berkeley DB (read-only)
+	- *ndb* Native database (no external dependencies)
+	- *sqlite* Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs* Plain ASCII files in a directory
+	- *openpgp* Shared OpenPGP certificate directory
+	- *rpmdb* Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0* disable
+	- *1* enable
+	- *-1* (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
+	Location of passwd(5) files as : separated list
+
+*%\_pkgverify_flags* _VSFLAGS_
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: Yep, that's a tricky thing. One possibility would be covering all these in the "Verification flags" subsection, but then it seems somehow inconsistent too.
created_at: 2025-04-04T09:58:09Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy* Dummy backend (no actual functionality)
+	- *bdb_ro* Berkeley DB (read-only)
+	- *ndb* Native database (no external dependencies)
+	- *sqlite* Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs* Plain ASCII files in a directory
+	- *openpgp* Shared OpenPGP certificate directory
+	- *rpmdb* Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0* disable
+	- *1* enable
+	- *-1* (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
+	Location of passwd(5) files as : separated list
+
+*%\_pkgverify_flags* _VSFLAGS_
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Yeah, I'd say just leave it as-is for now. The format is documented, that's important.
created_at: 2025-04-04T10:15:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: It's a bit annoying that when reading this paragraph, you have no clue what those files are and where they reside. So maybe add a "see FILES for the paths" or similar here? (Same for the other man page)
created_at: 2025-04-04T10:24:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: That, or put the files (back to) SYNOPSIS maybe. There is a certain point to having the paths up-front there in SYNOPSIS, even if it seems wrong otherwise.
created_at: 2025-04-04T10:31:13Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Indeed. In my experience, I tend to look for the *filenames* first when opening up a man page about configuration :smile: So +1 on putting them back to SYNOPSIS.
created_at: 2025-04-04T10:37:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: Another idea could be putting FILES before DESCRIPTION in section 5 manuals :thinking:
created_at: 2025-04-04T10:57:59Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
+macro path uses this to achieve the following hierarchy of settings:
+. Generic *rpm* factory defaults
+. Platform-specific *rpm* factory defaults
+. Vendor (distribution) specific settings
+. Host specific settings
+. User specific settings
+. Command-line override settings
+
+The default macro path can be inspected with *rpm --showrc|grep ^Macro*.
+
+In older versions of rpm, the path of per-user macros was _~/.rpmmacros_.
+This is still processed if it exists and the new configuration directory
+does not exist.
+
+# CONFIGURATION
+The following configurables are supported for the *rpm* runtime (as
+opposed opposed to just package building) parts:
+
+*%\_color_output* _MODE_
+	Output coloring mode. Valid values are *never* and *auto*.
+
+*%\_db_backend* _BACKEND_
+	The database backend to use. Possible values for _BACKEND_ are:
+	- *dummy*: Dummy backend (no actual functionality)
+	- *bdb_ro*: Berkeley DB (read-only)
+	- *ndb*: Native database (no external dependencies)
+	- *sqlite*: Sqlite database
+
+*%\_dbpath* _DIRECTORY_
+	The location of the rpm database file(s).
+
+*%\_excludedocs* _VALUE_
+	Boolean (i.e. 1 == "yes", 0 == "no") that controls whether files
+	marked as %doc should be installed.
+
+*%\_flush_io* _VALUE_
+	Flush file IO during transactions (at a severe cost in performance
+	for rotational disks). Possible values are 1 to enable, 0 to disable.
+
+*%\_group_path* _PATH_
+	Location of group(5) files as : separated list
+
+*%\_httpport* _PORT_
+	The port of HTTP proxy (used for FTP/HTTP).
+
+*%\_httpproxy* _HOSTNAME_
+	The hostname of HTTP proxy (used for FTP/HTTP).
+
+*%\_install_langs* _LOCALES_
+	A colon separated list of desired locales to be installed;
+	*all* means install all locale specific files.
+
+*%\_install_script_path* _PATH_
+	The PATH put into the environment before running %pre/%post et al.
+
+*%\_keyring* _BACKEND_
+	The keyring type to use. Possible values for _BACKEND_ are:
+	- *fs*: Plain ASCII files in a directory
+	- *openpgp*: Shared OpenPGP certificate directory
+	- *rpmdb*: Pseudo-packages in the rpmdb
+
+*%\_keyringpath* _DIRECTORY_
+	The location of the keyring path for non-rpmdb variants.
+
+*%\_minimize_writes* _VALUE_
+	Minimize writes during transactions (at the cost of more reads) to
+	conserve eg SSD disks (EXPERIMENTAL). Possible values are:
+	- *0*: disable
+	- *1*: enable
+	- *-1*: (or undefined) autodetect on platforms where supported,
+	  otherwise default to disabled
+
+*%\_netsharedpath* _PATH_
+	A colon separated list of paths where files should *not* be installed.
+	Usually, these are network file system mount points.
+
+*%\_passwd_path* _PATH_
+	Location of passwd(5) files as : separated list
+
+*%\_pkgverify_flags* _VSFLAGS_
+	Transaction package verification flags, used for fine-grained
+	control of *%\_pkgverify_level* operation.
+	Set to 0x0 for full compatibility with v4 packages.
+
+*%\_pkgverify_level* _MODE_
+	Enforced package verification mode in transactions,
+	where _MODE_ is one of:
+	- *all*: require valid digest(s) and signature(s)
+	- *signature*: require valid signature(s)
+	- *digest*: require valid digest(s)
+	- *none*: legacy rpm behavior, nothing required
+
+*%\_prefer_color* _VALUE_
+	Package conflict resolution in bi-arch transactions.
+	See also *%\_transaction_color*. Possible values are:
+	- *0*: disabled
+	- *1*: prefer 32-bit packages
+	- *2*: prefer 64-bit packages
+
+*%\_\_plugindir* _DIRECTORY_
+	Transaction plugin directory.
+
+*%\_query_all_fmt* _FORMAT_
+	Default output format string for rpm -qa.
+	*%* signs need to be escaped, eg. *%%{nevra}*.
+
+*%\_rpmlock_path* _FILE_
+	The path of the file used for transaction fcntl lock.
+
+*%\_tmppath* _PATH_
+	The directory where temporary files are created.
+
+*%\_\_urlhelpercmd* _EXECUTABLE_
+	The executable to use for retrieving remote files.
+
+*%\_\_urlhelperopts* _OPTIONS_
+	Generic options to pass to the *%\_\_urlhelpercmd* command.
+
+*%\_\_urlhelper_localopts* _OPTIONS_
+	User/host specific options to pass to the *%\_\_urlhelpercmd* command.
+
+*%\_\_urlhelper_proxyopts* _OPTIONS_
+	Proxy options to pass to the *%\_\_urlhelpercmd* command.
+
+*%\_urlhelper* _COMMAND_
+	Full command (with options) to use when retrieving remote files.
+	Normally pieced together from the double-underscore *%\_\_urlhelper\**
+	macros.
+
+*%\_transaction_color* _VALUE_
+	Package and file conflict behavior in bi-arch transactions.
+	See also *%\_prefer_color*. Possible values are:
+	- *0*: do not consider "colors", only use arch compatibility map
+	- *1*: only allow 32-bit packages
+	- *2*: only allow 64-bit packages
+	- *3*: allow 32- and 64-bit packages to share files
+
+*%\_vsflags_erase* _VSFLAGS_
+	Transaction verification flags used when erasing or updating packages.
+
+*%\_vsflags_install* _VSFLAGS_
+	Transaction verification flags used when installing packages.
+
+*%\_vsflags_query* _VSFLAGS_
+	Transaction verification flags used when querying packages.
+
+*%\_vsflags_rebuilddb* _VSFLAGS_
+	Transaction verification flags used when rebuilding the database.
+
+*%\_vsflags_verify* _VSFLAGS_
+	Transaction verification flags used when verifying packages.
+
+## Verfication flags
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Oh, typo here: VerIfication flags
created_at: 2025-04-04T10:58:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: Pushed this (FILES at top) as a fixup for easy reversal. It looks strange but so does files in SYNOPSIS. But, I think everybody agrees having the file information right there is very handy :smile: 
created_at: 2025-04-04T11:00:39Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
+
+Each file or *glob*(7) pattern in the colon-separated macro path is
+read sequentially by *rpm* for macro definitions. *%{\_target}* is
+expanded to the detected <arch>-<os> platform. Tildes are expanded
+to the value of the environment variable *HOME*.
+
+If a macro is defined multiple times, the last entry wins. The default
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Oh, yep, that sounds like a good idea, let's try.
created_at: 2025-04-04T11:02:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: I agree it probably should be emphasized somehow, just wondering about the form. Is there a guidance in man-pages(7) on that or...? (not finding anything immediately obvious here)
created_at: 2025-04-04T11:16:08Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Perhaps the closest one (after skimming through the page):
```
Expressions,  if  not written on a separate indented line, should be specified in italics.  Again,
the use of nonbreaking spaces may be appropriate if the expression is inlined with normal text.
```
created_at: 2025-04-04T11:35:22Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: But that's "expressions", perhaps in the programming sense of the word (?)
created_at: 2025-04-04T11:36:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
path: docs/man/rpm-config.5.scd
user: login: dmnks
body: Hmm, there's a more accurate example perhaps, see the `NULL, NUL, null pointer, and null byte` section in man-pages(7). It defines the term "null pointer" and its italicized (underlined) there.


created_at: 2025-04-04T11:37:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,217 @@
+RPM-CONFIG(5)
+
+# NAME
+*rpm-config* - rpm runtime macro configuration
+
+# SYNOPSIS
+_NAME_ _VALUE_
+
+# DESCRIPTION
+The primary configuration mechanism in *rpm* is via macros. On startup,
+*rpm* reads a set of macro files (*rpm-macrofile*(5)) as defined
+in the macro path.
path: docs/man/rpm-config.5.scd
user: login: pmatilai
body: Added underlining now, both for macro path and rpmrc path (which is very similar)
created_at: 2025-04-04T11:49:55Z
author_association: MEMBER

PR comments:
user: login: pmatilai
created_at: 2025-04-03T09:05:12Z
body: FWIW, I realized we kinda need this for the alpha release because we were referring to an non-existent rpm-config(5) in places.
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-03T09:10:30Z
body: Other remarks, subject to debate etc :sweat_smile: 
- There are lines to be drawn as to which macros we want to document - eg %{_urlhelper} is the only part *rpm* actually looks at, but the helper consists of multiple related macros which by now are actually more intended for user fiddling than %_urlhelper itself. Although, replacing %_urlhelper by another program is a totally legit thing to do.
- rpmrc covers both run- and build-time aspects, but the rpm-config(5) page only covers runtime configuration, intentionally. We'll need a separate rpmbuild-config(5) or such page to cover the build side tunables, but that's a much much bigger job.
- There's no predecent in the man template for some of the items in here, eg what to call the section where the various configurables are covered. systemd seems to use OPTIONS and that'd be an *option*  :smile: for sure, just kinda torn on it. Not that I'm too enthusiastic about the CONFIGURATION title either. 
author_association: MEMBER
user: login: Conan-Kudo
created_at: 2025-04-03T13:10:49Z
body: I don't love `SYNOPSIS` for listing file locations, but apparently that's what others do, so... 🤷🏾‍♂️ 
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-03T14:02:19Z
body: Oh indeed, that was one thing missing from my "random remarks" comment: what to do with SYNOPSIS.

I basically copied this practise from systemd and thought "don't these belong to FILES instead" but went ahead anyway because then I didn't know what to put into SYNOPSIS. Another common practise is omitting SYNOPSIS entirely and putting the files into FILES. 
author_association: MEMBER
user: login: Conan-Kudo
created_at: 2025-04-03T14:03:51Z
body: I would prefer `FILES` and maybe just leave out `SYNOPSIS`.
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-03T14:21:13Z
body: I think I concur :smile: It's also not exactly hard to come up with a short synopsis to summarize what the page is about.
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-04T07:23:09Z
body: Uff, I added a rpm-platform(5) man too, but when double checking the behavior quickly discarded the idea - that stuff is sooooooo buggy, murky and incomplete, there's a reason its not documented at all. Better keep that cellar door closed for now.
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-04T07:24:44Z
body: Anyway, the main point here was moving the file lists to FILES and using synopsis to outline the main config syntax. Not sure it makes sense that way but I'd already done it in rpm-macrofile(5) so...
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T09:01:18Z
body: Note that the old "rpm.config(5)" name is still referred to in rpm-man-template.scd and rpmkeys.8.scd. 
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T09:25:45Z
body: I also wonder if it makes sense to document the underscore convention in macro names (e.g. `_foo` and `__foo`) in the rpm-config page. That said, the macros don't follow the convention very well so perhaps that's why we shouldn't document that (yet) :sweat_smile: 
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T09:31:28Z
body: It's a good point about the underscores though, we should mention it here. It wont be 100% because historical reasons, but we can always just state as much.
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T09:36:19Z
body: I'm thinking what we should do with the existing "documentation" (comments) in the `macros`/`platform` files we ship. Removing them sounds too bothersome but then, we don't want to maintain *those* now that we have proper man pages.
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T09:37:28Z
body: I'd say, let's leave those comments in place and add a note to the top of the file(s) that they're no longer kept up-to-date and that one should consult the man pages instead (?)
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T09:56:25Z
body: > I'm thinking what we should do with the existing "documentation" (comments) in the macros/platform files we ship. Removing them sounds too bothersome but then, we don't want to maintain those now that we have proper man pages.
> I'd say, let's leave those comments in place and add a note to the top of the file(s) that they're no longer kept up-to-date and that one should consult the man pages instead (?)

There are all manner of lines to be drawn on that front - we clearly need to document the actual configuration knobs in here, but does it make sense to document something like %__rm and its buddies? Not something we need to decide here, thankfully :smile: 

Anyway, I'll add a note pointing to the manual to the top of the file. 
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T09:58:21Z
body: > Anyway, the main point here was moving the file lists to FILES and using synopsis to outline the main config syntax. Not sure it makes sense that way but I'd already done it in rpm-macrofile(5) so...

Works for me.
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T09:59:17Z
body: > There are all manner of lines to be drawn on that front - we clearly need to document the actual configuration knobs in here, but does it make sense to document something like %__rm and its buddies? Not something we need to decide here, thankfully 😄

Yep, that's for another summer-y rainy day.

> Anyway, I'll add a note pointing to the manual to the top of the file.

Ack
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T10:05:26Z
body: > Other remarks, subject to debate etc 😅
> 
> * There are lines to be drawn as to which macros we want to document - eg %{_urlhelper} is the only part _rpm_ actually looks at, but the helper consists of multiple related macros which by now are actually more intended for user fiddling than %_urlhelper itself. Although, replacing %_urlhelper by another program is a totally legit thing to do.

Yeah, I'd say let's just focus on kick-starting the man page in this PR. We can add/remove items in future iterations.

> * rpmrc covers both run- and build-time aspects, but the rpm-config(5) page only covers runtime configuration, intentionally. We'll need a separate rpmbuild-config(5) or such page to cover the build side tunables, but that's a much much bigger job.

Oh right, I think we should mention in the rpmrc page that it's about the runtime only, not about build time. Something similar is already mentioned in a passing in rpm-config (but maybe it could be made more obvious there, too).

>  * There's no predecent in the man template for some of the items in here, eg what to call the section where the various configurables are covered. systemd seems to use OPTIONS and that'd be an _option_  😄 for sure, just kinda torn on it. Not that I'm too enthusiastic about the CONFIGURATION title either.

How about MACROS in rpm-config and ENTRIES in rpmrc?
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T10:08:29Z
body: > How about MACROS in rpm-config and ENTRIES in rpmrc?

Meh, maybe just keep CONFIGURATION after all. Using MACROS could give the impression that there are also other ways to configure rpm.
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T10:17:46Z
body: Other ideas:
* TUNABLES
* SETTINGS

One other solution that comes to mind: Split the man page into sections based on the type of configurables. For example: DATABASE, ARCHITECTURE, etc. Because after all, the whole page is about configuration already.
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T10:33:56Z
body: FWIW, I had a long internal debate between MACROS and SETTINGS and all that, before landing on CONFIGURATION and disliking that too :laughing: 

I think my main reason for using CONFIGURATION as the name was that it's the same name we use in the template: these are the configurables, look into rpm-config(5) for details.
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T10:38:59Z
body: > FWIW, I had a long internal debate between MACROS and SETTINGS and all that, before landing on CONFIGURATION and disliking that too 😆

Oh, ack :smile: 

> I think my main reason for using CONFIGURATION as the name was that it's the same name we use in the template: these are the configurables, look into rpm-config(5) for details.

Indeed. More than fine with me :smile: 
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T10:43:44Z
body: It's rather annoying how man-pages(7) has practically zero guidance on section 5. It says CONFIGURATION normally only applies to section 4, and then OPTIONS which would be another reasonably standard section for listing the tunables is "should only appear in section 1 and 8 manuals"

...

...while having guidance on preferring the term "negative infinity" over "minus infinity" :flushed: :joy: 
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T10:52:13Z
body: > It's rather annoying how man-pages(7) has practically zero guidance on section 5. It says CONFIGURATION normally only applies to section 4, and then OPTIONS which would be another reasonably standard section for listing the tunables is "should only appear in section 1 and 8 manuals"

Oh indeed, there's no mention of "Section 5" at all :thinking: Also:

```
CONFIGURATION
              Configuration details for a device.

              This section normally appears only in Section 4 pages.
```

I guess they just meant that Section 5 manuals are more free-form. And indeed, there's more style variability when you look at various project's section 5 manuals than there is for 1 and 8.

That doesn't mean we can't come up with our own project specific style (much like we're just doing here) :sweat_smile: 

> ...while having guidance on preferring the term "negative infinity" over "minus infinity" 😳 😂

Uff right :laughing: 
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T10:53:50Z
body: Pushed fixups for the more obvious things in one batch + marked resolved, will do more in another batch...
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T10:59:46Z
body: Hmm, couldn't we name `rpm-rpmrc(5)` just as `rpmrc(5)`?

Edit: Oh right, we wanted to distinguish commands from the other pages, so in that sense, it's better this way.
Edit2: But... that above doesn't apply here because it's a different section. Hmm.
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T11:03:56Z
body: > Hmm, couldn't we name rpm-rpmrc(5) just as rpmrc(5)?

There's another internal debate I had :laughing: I figured it's just most consistent to have everything rpm- prefixed. It looks a bit silly with rpm-rpmrc of course. Another possibility could be rpm-rc but then it no longer matches the actual filename, so its probably worse.
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T11:04:57Z
body: > > Hmm, couldn't we name rpm-rpmrc(5) just as rpmrc(5)?
> 
> There's another internal debate I had 😆 I figured it's just most consistent to have everything rpm- prefixed. It looks a bit silly with rpm-rpmrc of course. Another possibility could be rpm-rc but then it no longer matches the actual filename, so its probably worse.

Yup, "rpm-rc", don't :sweat_smile:

Ack then, it's more consistent this way (with the other section 5 pages at least).
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T11:07:35Z
body: It all gets inconsistent anyhow because there's no meaningful macros counterpart no matter what: the per-user macros file used to be ~/.rpmmacros, but the main global file was "macros". And now with the new XDG layout, the user macro file is ~/.config/rpm/macros ... but the rc is still ~/.config/rpm/rpmrc :zany_face: 
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T11:10:18Z
body: > It all gets inconsistent anyhow because there's no meaningful macros counterpart no matter what: the per-user macros file used to be ~/.rpmmacros, but the main global file was "macros". And now with the new XDG layout, the user macro file is ~/.config/rpm/macros ... but the rc is still ~/.config/rpm/rpmrc 🤪

Yep, and there's now `rpm-config(5)` which actually refers to the `macros` file(s). Argh :rofl: 
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T11:13:48Z
body: We're basically trying to abstract away the filenames for rpm configuration (`rpm-config(5)`) while still keeping the filenames in the name `rpm-rpmrc(5)`. I wonder if the latter couldn't also be renamed to something more descriptive then :smile: 
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T11:15:48Z
body: Random idea (perhaps silly):

* `rpm-runtime(5)`: runtime config
* `rpm-machine(5)`: low-level machine/arch config (current `rpm-rpmrc(5)`)
* `rpm-build(5)`: build config

Basically, we could even just have `rpm(5)` for the runtime bits and `rpmbuild(5)` for the build time bits.
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T11:18:58Z
body: Yep, but note that rpm-config(5) is just half the story, there's going to be rpmbuild-config(5) too to cover the build-side tunables. And rpm-macrofile(5) covers the file format strictly. Then we'd have something like rpm-macros(7) to explain the whole macro engine :zany_face: 
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-04T11:20:47Z
body: Replied before seeing your latest comment, argh :smile: 
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-04T11:24:03Z
body: > Basically, we could even just have rpm(5) for the runtime bits and rpmbuild(5) for the build time bits.

The matter is further complicated by the fact that most of rpm-config also applies to any librpm users, and somehow calling it just rpm(5) to me is a stronger indication that its just about the rpm(8) executable. But, its not like we make the executable/library difference clear anywhere just now.
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T11:25:43Z
body: > The matter is further complicated by the fact that most of rpm-config also applies to any librpm users, and somehow calling it just rpm(5) to me is a stronger indication that its just about the rpm(8) executable. But, its not like we make the executable/library difference clear anywhere just now.

Yep, I've come to realize that foo(5) where foo is a program name doesn't seem that common. What's more common is to use the filename (e.g. foo.conf(5) or foorc(5)). So scratch that idea, indeed.
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T11:27:29Z
body: It's an annoying thing in all. rpmrc is the only "straightforward" case here because there's only one meaning for it. The macro stuff is used in so many different ways...
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T11:28:03Z
body: Also scratch the -runtime idea of mine above. That'd just look weird and more confusing.

I think the -config style is a good one, and clear at that. Those pages cover configuration files after all (section 5 is not just for configuration but also for file formats).

The rpmrc thing is a bit more annoying but something we can live with I guess :smile: 
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T11:30:33Z
body: Yes! The FILES section on top looks much more natural (to my eye at least).
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T11:31:18Z
body: rpmrc is annoying in its own ways - the name suggests its a central way of configuration, which it WAS, and of course kinda still is, not just something that an end-user would be touching. So one could call it eg rpm-platform(5) but then nobody is going to find it because the filename is always rpmrc :sweat_smile: 
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-04T11:32:44Z
body: > nobody is going to find 

...which might not be an entirely bad thing :smile: 
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T11:41:18Z
body: It does make me think that maybe just having a single `rpmrc(5)` page for *configuration* would be also an option. There, we could document the differences...

Edit: But that would also inflate the page quite a bit, with all those low-level macros... uff.
author_association: CONTRIBUTOR
user: login: Conan-Kudo
created_at: 2025-04-04T11:42:23Z
body: `rpm-configuration(5)` is also fine, and if we need aliases for `rpmrc(5)` to point to it, that's also possible.
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-04T11:55:21Z
body: The split feels wrong now, which probably means it is. rpmrc side is probably fine, its this isolated lowlevel island. But for the macros there are:
- the macro engine with its syntax (no man page yet)
- the macro file format (rpm-macrofile(5))
- the way macros are initialized on librpm startup (munged into rpm-config), closely related to rpm-macrofile(5) too
- the main runtime configuration (in rpm-config)
- the buildtime config (no man page yet)
- the signing config (covered in rpmsign(1))

:zany_face: 
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T12:24:44Z
body: Joining some man pages is also an option. It's not like *long* man pages are a problem, IMO, they're *manuals* after all. That would save us the head ache of coming up with clever naming, at least to some extent.

Looking at our role model git here, `git-config(1)` is a command but it also includes a whole section called CONFIGURATION FILE. That's perhaps not a shining example of how this can be done and a bit more on the "too much on one page" side of things :sweat_smile: 
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T12:27:56Z
body: I'd say, for the purposes of this PR, we're now good. As you said (in chat), we can always shuffle content around, including adding/removing whole man pages, until perhaps the first final release (6.0.0).
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T12:28:24Z
body: Yeah the issue here is really just that rpm's configuration is complicated. There are two entirely different mechnisms, glued together by an init function, and used criss-cross for a whole multitude of different purposes. And describing this tangle isn't too easy :smile: 
author_association: MEMBER
user: login: dmnks
created_at: 2025-04-04T12:31:18Z
body: Yep, TIL (for real, in my case at least) :sweat_smile: 
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T12:32:08Z
body: I see no other unresolved threads (checked your latest fixups, looks good), so feel free to undraft now.
author_association: CONTRIBUTOR
user: login: dmnks
created_at: 2025-04-04T12:33:23Z
body: And of course, there's a bunch of stuff in the actual configurables descriptions that I've noticed while skimming through, but it's just not in scope here, as you've just copy&pasted the descriptions (mostly) from the macro files. We can (and will) clean up the content later.
author_association: CONTRIBUTOR
user: login: pmatilai
created_at: 2025-04-04T12:33:40Z
body: One idea could be lumping all librpm* configuration into the rpm-config file. This is mostly the one underscore-items.
We could then split the CONFIGURATION section into run, build and sign-time sections. This would be a long manual, but not insanely so.

There are a thousand different macros for *packaging* but that's yet another entirely world.

And of course, once you start drawing such lines, you'll be drawing a whole lot of them :smile: 
And, I don't know if that's a good idea but it's one possibility.
author_association: MEMBER
user: login: pmatilai
created_at: 2025-04-04T12:44:22Z
body: Fixups squashed and undrafted.

There's one unresolved remark on the macro naming, but conjuring a good description of that is beyond me at this point in the day/week. So lets try to add that on some other round...
author_association: MEMBER