Improve versioning algorithm documentation.

* doc/libtool.texi (Updating version info): Repeat the
algorithms in different, hopefully simpler terms.
* THANKS: Update.
Prompted by Richard B. Kreckel.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

diff --git a/ChangeLog b/ChangeLog
index 496911b9dafe123d7dc3a8309c1873e560686fae..61bc746bdbae0fe643fdca26d0f0f27d7775cd6a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2009-11-01  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
+
+       Improve versioning algorithm documentation.
+       * doc/libtool.texi (Updating version info): Repeat the
+       algorithms in different, hopefully simpler terms.
+       * THANKS: Update.
+       Prompted by Richard B. Kreckel.
+
 2009-11-01  Ingo Weinhold  <ingo_weinhold@gmx.de>  (tiny change)
 
        Support for the Haiku operating system.

diff --git a/THANKS b/THANKS
index 03cd59275c2132f48983ab962c764e68bec784cf..691017d1edb50deea4307eed3832625947bd0596 100644 (file)
--- a/THANKS
+++ b/THANKS
@@ -145,6 +145,7 @@
   Rainer Orth                  ro@TechFak.Uni-Bielefeld.DE
   Rainer Tammer                        tammer@tammer.net
   Ralf Menzel                  menzel@ls6.cs.uni-dortmund.de
+  Richard B. Kreckel           kreckel@ginac.de
   Richard Purdie               rpurdie@rpsys.net
   Richard Sandiford            richards@transitive.com
   Robert Garron                        Robert.Garron@Access3000.net

diff --git a/doc/libtool.texi b/doc/libtool.texi
index 27bf221b5096db095a92dbf01901c3359ce8c7d4..482e635cacc964b7731df3b1ab08cd19ae0bd2b1 100644 (file)
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -2870,6 +2870,37 @@ Instead, use the @option{-release} flag (@pxref{Release numbers}), but be
 warned that every release of your package will not be binary compatible
 with any other release.
 
+The following explanation may help to understand the above rules a bit
+better: consider that there are three possible kinds of reactions from
+users of your library to changes in a shared library:
+
+@enumerate 1
+@item
+Programs using the previous version may use the new version as
+drop-in replacement, and programs using the new version can also work
+with the previous one.  In other words, no recompiling nor relinking
+is needed.  In this case, bump @var{revision} only, don't touch
+@var{current} nor @var{age}.
+
+@item
+Programs using the previous version may use the new version as
+drop-in replacement, but programs using the new version may use APIs not
+present in the previous one.  In other words, a program linking against
+the new version may fail with ``unresolved symbols'' if linking against
+the old version at runtime: set @var{revision} to 0, bump @var{current}
+and @var{age}.
+
+@item
+Programs may need to be changed, recompiled, relinked in order to use
+the new version.  Bump @var{current}, set @var{revision} and @var{age}
+to 0.
+@end enumerate
+
+@noindent
+In the above description, @emph{programs} using the library in question
+may also be replaced by other libraries using it.
+
+
 @node Release numbers
 @section Managing release information