--- a/docs/man/man5/package-mapping.conf.rst	Tue Feb 28 09:22:26 2023 +0100
+++ b/docs/man/man5/package-mapping.conf.rst	Wed Mar 01 09:28:18 2023 +0100
@@ -8,8 +8,36 @@
 
 Used by :manpage:`check-ports(8)`.
 
+This is a textfile where every line contains two words -- each being
+a package names::
+
+    package-name  mapped-package-name
+
+When :command:`check-ports` determines the package status for
+`mapped-package-name` then the repositories are checked with regard to
+`package-name` also.
+
+This is useful when the update status of renamed (private) forks should be
+checked against the original parent package also.
+
+
+Examples
+--------
+
+Assume that package ``pack-orig`` is forked into a local package with
+a different name ``my-forked-pack``. To let the :command:`check-ports` tool
+to take this into account use::
+
+    pack-orig my-forket-pack
+
 
 See Also
 --------
 
 :manpage:`check-ports(8)`
+
+
+Bugs
+----
+
+Comments in the file are currently not allowed.