diff --git a/doc/manual.txt b/doc/manual.txt
index b63a4237202..a8af37c0fd7 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -418,6 +418,38 @@ package is downloaded, compiled and installed.
 NOTE: A function defined in a template has preference over the same function
 defined by a `build_style` script.
 
+Run-time dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+Dependencies for ELF executables or shared libraries are detected
+automatically by `xbps-src`, hence run-time dependencies must not be specified
+in the *package sections* with the following exceptions:
+
+- ELF binaries using dlopen(3).
+- non ELF objects, i.e perl/python/ruby/etc modules.
+- Overriding the minimal version specified in the `shlibs` file.
+
+The run-time dependencies for ELF binaries are detected by checking which SONAMEs
+use and then the SONAMEs are mapped to a binary package name with a minimal
+required version. The `shlibs` file in the `xbps-packages/common` directory
+sets up the `SONAME pkgname>=version` mappings.
+
+For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and
+software requiring this library will link to `libfoo`; the resulting binary
+package will have a run-time dependency to `foo>=1.0_1` package as specified in
+`common/shlibs`:
+
+-----------------------
+# common/shlibs
+...
+libfoo.so.1 foo-1.0_1
+...
+-----------------------
+
+- The first field specifies the SONAME.
+- The second field specified the package name and minimal version required.
+- A third optional field specifies the architecture (rarely used).
+
 Build options
 ~~~~~~~~~~~~~