document the new behavior of collect_libs with symlinks

reference/tools.rst

@@ -1377,10 +1377,19 @@ inter-dependent libraries or with complex names like ``libmylib-x86-debug-en.lib
     from conans import tools
 
     def package_info(self):
-        self.cpp_info.libdirs = ["lib", "other_libdir"]  # Deafult value is 'lib'
+        self.cpp_info.libdirs = ["lib", "other_libdir"]  # Default value is 'lib'
         self.cpp_info.libs = tools.collect_libs(self)
 
-For UNIX libraries staring with **lib**, like *libmath.a*, this tool will collect the library name **math**.
+For UNIX libraries starting with **lib**, like *libmath.a*, this tool will collect the library name **math**.
+
+Regarding symlinks, this tool will keep only the "most generic" file among the resolved real file and all symlinks pointing to this real file.
+For example among files below, this tool will select *libmath.dylib* file and therefore only append *math* in the returned list:
+
+.. code-block:: shell
+
+    -rwxr-xr-x libmath.1.0.0.dylib
+    lrwxr-xr-x libmath.1.dylib -> libmath.1.0.0.dylib
+    lrwxr-xr-x libmath.dylib -> libmath.1.dylib
 
 **Parameters:**
     - **conanfile** (Required): A ``ConanFile`` object to get the ``package_folder`` and ``cpp_info``.