From: Patrice Dumas <pertusus@free.fr>
Date: Sun, 21 Sep 2025 21:06:00 +0000 (+0300)
Subject: libtool.texi: Update descriptions for command-line options
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fheads%2Fdevelopment;p=thirdparty%2Flibtool.git

libtool.texi: Update descriptions for command-line options

* doc/libtool.texi: Make descriptions for '--no-finish' and
  '--reorder-cache' clearer for users to understand.
---

diff --git a/doc/libtool.texi b/doc/libtool.texi
index 07aa1e7e0..8dffdd609 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -1275,32 +1275,31 @@ required, this option will preserve them, only stripping the libraries
 that libtool knows it can safely.
 
 @item --no-finish
-Do not execute finish_cmds (disabled by default). This option is for
-specifying that testing of local changes to shared libraries is being
-performed so that ldconfig will not alter the shared library cache, which
-is an issue observed on OpenBSD 7.5. This option should be combined with
-the usage of @option{--mode=install} and @option{--mode=finish} to have
-any effect. Prior to utilizing this option, the shared library cache must
-not contain links to the listed install directory for shared libraries
-undergoing testing; otherwise, it will have no useful effect. In OpenBSD,
-the shared library cache can be reordered to prefer directories for
-testing shared libraries over the directories already listed in the shared
-library cache with @option{--reorder-cache=@var{shared_lib_dirs}}.
+Do not execute finish_cmds (disabled by default). This option should
+be combined with the usage of @option{--mode=install} and
+@option{--mode=finish} to have any effect. This option is relevant
+for OpenBSD 7.5, where ldconfig adds the shared libraries install
+directory to the shared library cache directories list. Specifying this
+option is useful on that platform if you want to load local shared
+libraries but not shared libraries from the install directory. If the
+shared library cache already contains the install directory, the option
+should not have any useful effect. In OpenBSD, the shared library cache
+can be reordered to prefer directories for testing shared libraries over
+the directories already listed in the shared library cache with
+@option{--reorder-cache=@var{shared_lib_dirs}}.
 
 @item --reorder-cache=@var{shared_lib_dirs}
 Reorder the shared library cache by providing the preferred directories
-(@var{shared_lib_dirs}) to link shared libraries from. The previous
-shared library cache is unconfigured, and the preferred directories are
-configured with the previous directories appended to the end (if not in
-the preferred directory list)@footnote{Additionally, all directories
-that no longer exist will be removed from the shared library cache.}.
-This option is currently only available on OpenBSD where @code{make
-install} has been required before @code{make check} for the shared
-library cache to be updated.
+(@var{shared_lib_dirs}) first to link shared libraries from. The directories
+previously present in the shared library cache are appended to the end
+(if not in the preferred directory list). Additionally, all directories
+that no longer exist are removed from the shared library cache. This
+option is currently only available on OpenBSD.
 
 This option is essentially a wrapper for executing @command{ldconfig},
 and it should be used as an independent option before and after testing
-changes to shared libraries. Below are some usage examples:
+changes to shared libraries. Below are some examples of the effects of
+the option:
 
 @example
 $ @kbd{libtool --reorder-cache=/tmp/testing}
@@ -1325,7 +1324,7 @@ Reordered: /usr/lib /usr/X11R6/lib /usr/local/lib
 $ @kbd{libtool --reorder-cache=/tmp/testing:/usr/local/lib:/home/user/dir}
 Original: /usr/lib /usr/X11R6/lib /usr/local/lib
 Reordered: /tmp/testing /usr/local/lib /home/user/dir /usr/lib /usr/X11R6/lib
-$ @kbd{libtool --reorder-cache=/usr/lib /usr/X11R6/lib /usr/local/lib}
+$ @kbd{libtool --reorder-cache=/usr/lib:/usr/X11R6/lib:/usr/local/lib}
 Original: /tmp/testing /usr/local/lib /home/user/dir /usr/lib /usr/X11R6/lib
 Reordered: /usr/lib /usr/X11R6/lib /usr/local/lib /tmp/testing /home/user/dir
 @end example