document the update target annomaly

diff --git a/doc/libsolv-bindings.3 b/doc/libsolv-bindings.3
index 5ed7ae9a059bc731cc4560fcf6ad8874f289f21d..4758e46ac67583173fbab0c2ae1e909d1f14d836 100644 (file)
--- a/doc/libsolv-bindings.3
+++ b/doc/libsolv-bindings.3
@@ -2846,7 +2846,11 @@ An untargeted update of "B" will do nothing, as "B" is not installed\&.
 .sp
 An targeted update of "B" will update "A\-1\&.1" to "B"\&.
 .sp
-Note that the default is to do "auto\-targeting", thus if the specified set of packages does not include an installed package, the solver will assume targeted operation even if SOLVER_TARGETED is not used\&. You can turn off auto\-targeting with the SOLVER_FLAG_NO_AUTOTARGET solver option, see the Solver class for details\&.
+Note that the default is to do "auto\-targeting", thus if the specified set of packages does not include an installed package, the solver will assume targeted operation even if SOLVER_TARGETED is not used\&.
+.sp
+This mostly matches the intent of the user, with one exception: In the example above, an update of "A\-1\&.2" will update "A\-1\&.1" to "A\-1\&.2" (targeted mode), but a second update of "A\-1\&.2" will suddenly update to "B", as untargeted mode is chosen because "A\-1\&.2" is now installed\&.
+.sp
+If you want to have full control over when targeting mode is chosen, turn off auto\-targeting with the SOLVER_FLAG_NO_AUTOTARGET solver option\&. In that case, all updates are considered to be untargeted unless they include the SOLVER_TARGETED flag\&.
 .SS "SET BITS"
 .sp
 Set bits specify which parts of the specified packages where specified by the user\&. It is used by the solver when checking if an operation is allowed or not\&. For example, the solver will normally not allow the downgrade of an installed package\&. But it will not report a problem if the SOLVER_SETEVR flag is used, as it then assumes that the user specified the exact version and thus knows what he is doing\&.

diff --git a/doc/libsolv-bindings.txt b/doc/libsolv-bindings.txt
index 7a8068a85ff261483638ae73f71fdab4de802448..e43545bdc9eaf157e026d9bfcbf9a98cadc55818 100644 (file)
--- a/doc/libsolv-bindings.txt
+++ b/doc/libsolv-bindings.txt
@@ -1700,8 +1700,17 @@ An targeted update of "B" will update "A-1.1" to "B".
 Note that the default is to do "auto-targeting", thus if the specified
 set of packages does not include an installed package, the solver
 will assume targeted operation even if SOLVER_TARGETED is not used.
-You can turn off auto-targeting with the SOLVER_FLAG_NO_AUTOTARGET
-solver option, see the Solver class for details.
+
+This mostly matches the intent of the user, with one exception: In
+the example above, an update of "A-1.2" will update "A-1.1" to
+"A-1.2" (targeted mode), but a second update of "A-1.2" will suddenly
+update to "B", as untargeted mode is chosen because "A-1.2" is now
+installed.
+
+If you want to have full control over when targeting mode is chosen,
+turn off auto-targeting with the SOLVER_FLAG_NO_AUTOTARGET solver option.
+In that case, all updates are considered to be untargeted unless they
+include the SOLVER_TARGETED flag.
 
 === SET BITS ===
 Set bits specify which parts of the specified packages where specified