HEAD: document old macro names and undeprecate some

[Ralf Wildenhues]

This patch fixes a documentation regression: It adds documentation for
the branch-1-5 macro naming scheme to HEAD's manual, listing most of the
old macro names as deprecated.  Since however some of the old macro
names provide functionality not possible with LT_INIT, it also
resurrects some macros as non-deprecated.  For example, invoking
AC_DISABLE_STATIC in a shell conditional works at least partly[1] (and
is used quite a bit in real-world packages).  AFAICS this is not
possible with LT_INIT([disable-static]).

Do you think that
  AC_ENABLE_FAST_INSTALL
  AM_ENABLE_FAST_INSTALL
  AC_LIBTOOL_PICMODE

should also be documented?  They are undocumented in branch-1-5; I left
them undocumented for now.

Do you think that undeprecating AC_{DISABLE,ENABLE}_{SHARED,STATIC} is a
bad idea and that they should be named LT_* instead?  FWIW, I am very
reluctant to go this route as this would introduce yet another name for
the same thing (already 4 names then: AM_<X>, AC_<X>, LT_INIT(<x>) and
LT_<X> then).

Several people have reported these issues; I have forgotten who it was,
sorry.  Speak up and you will be mentioned in the ChangeLog entry.

OK to apply?  Patch not tested very much yet.

Cheers,
Ralf

[1] There are at least two glitches with putting AC_DISABLE_SHARED et al
in a shell conditional: first, I think if you put it in one execution
branch, you have to ensure all other branches see one of the *_SHARED
macros as well.  Second, the output of the default value with --help may
be wrong then.  I may be looking into a fix eventually...


2007-02-11  Ralf Wildenhues  <address@hidden>

        * doc/libtool.texi (LT_INIT): Fix wording of intro a bit.
        <shared, static>: Also describe these default LT_INIT options.
        <AC_LIBTOOL_DLOPEN, AC_LIBTOOL_WIN32_DLL>
        <AC_DISABLE_FAST_INSTALL>: Mention deprecated macro names,
        including the respective LT_INIT replacement.
        <AC_DISABLE_SHARED, AC_DISABLE_STATIC, AC_ENABLE_SHARED>
        <AC_ENABLE_STATIC>: Document, un-deprecate.  Suggest the
        respective LT_INIT replacement.
        <AM_DISABLE_SHARED, AM_DISABLE_STATIC, AM_ENABLE_SHARED>
        <AM_ENABLE_STATIC>: Document deprecated aliases.
        (Distributing libltdl) <AC_WITH_LTDL, AC_LIBLTDL_INSTALLABLE>
        <AC_LIBLTDL_CONVENIENCE>: Document deprecated aliases.
        * libltdl/m4/ltoptions.m4 (AM_ENABLE_SHARED, AM_DISABLE_SHARED)
        (AM_ENABLE_STATIC, AM_DISABLE_STATIC): Make these AU_ALIASes of
        the respective AC_* macros, so we do not recommend LT_INIT(*) in
        this case.
        (AC_ENABLE_SHARED, AC_DISABLE_SHARED, AC_ENABLE_STATIC)
        (AC_DISABLE_STATIC): Un-deprecate these.  Remove now-superfluous
        aclocal-1.4 backwards compatibility comments.

Index: doc/libtool.texi
===================================================================
RCS file: /cvsroot/libtool/libtool/doc/libtool.texi,v
retrieving revision 1.219
diff -u -r1.219 libtool.texi
--- doc/libtool.texi    11 Feb 2007 11:11:05 -0000      1.219
+++ doc/libtool.texi    11 Feb 2007 13:44:05 -0000
@@ -1862,7 +1862,8 @@
 If you are using @sc{gnu} Autoconf (or Automake), you should add a call to
 @code{LT_INIT} to your @file{configure.ac} file.  This macro
 adds many new tests to the @code{configure} script so that the generated
-libtool script will understand the characteristics of the host:
+libtool script will understand the characteristics of the host.  It's the
+most important of a number of macros defined by Libtool:
 
 @defmac LT_PREREQ (@var{VERSION})
 Ensure that a recent enough version of Libtool is being used.  If the
@@ -1891,10 +1892,7 @@
 and also enables static libraries if they don't conflict with the shared
 libraries.  You can modify these defaults by passing either
 @code{disable-shared} or @code{disable-static} in the option list to
address@hidden:@footnote{This used to be done with additional macro
-calls, @code{AC_DISABLE_SHARED} and @code{AC_DISABLE_STATIC}.  If you
-are upgrading from such an old version, again @code{autoupdate} is your
-friend.}
address@hidden, or using @code{AC_DISABLE_SHARED} or @code{AC_DISABLE_STATIC}.
 
 @example
 # Turn off shared libraries during beta-testing, since they
@@ -1976,11 +1974,27 @@
 default, depending on platform support, by specifying
 @option{--enable-fast-install} to @command{configure}.
 
address@hidden shared
+Change the default behaviour for @code{LT_INIT} to enable
+shared libraries.  This is the default on all systems where
+Libtool knows how to create shared libraries.
+The user may still override this default by specifying
address@hidden to @command{configure}.
+
 @item disable-shared
 Change the default behaviour for @code{LT_INIT} to disable
 shared libraries.  The user may still override this default by
 specifying @option{--enable-shared} to @command{configure}.
 
address@hidden static
+Change the default behaviour for @code{LT_INIT} to enable
+static libraries.  This is the default on all systems where
+shared libraries have been disabled for some reason, and on
+most systems where shared libraries have been enabled.
+If shared libraries are enabled, the user may still override
+this default by specifying @option{--disable-static} to
address@hidden
+
 @item disable-static
 Change the default behaviour for @code{LT_INIT} to disable
 static libraries.  The user may still override this default by
@@ -2027,6 +2041,58 @@
 
 @end defmac
 
address@hidden AC_LIBTOOL_DLOPEN
+This macro is deprecated, the @samp{dlopen} option to @code{LT_INIT} should be
+used instead.
address@hidden defmac
+
address@hidden AC_LIBTOOL_WIN32_DLL
+This macro is deprecated, the @samp{win32-dll} option to @code{LT_INIT} should
+be used instead.
address@hidden defmac
+
address@hidden AC_DISABLE_FAST_INSTALL
+This macro is deprecated, the @samp{disable-fast-install} option to 
@code{LT_INIT}
+should be used instead.
address@hidden defmac
+
address@hidden AC_DISABLE_SHARED
address@hidden AM_DISABLE_SHARED
+Change the default behaviour for @code{LT_INIT} to disable shared libraries.
+The user may still override this default by specifying @samp{--enable-shared}.
+The option @samp{disable-shared} to @code{LT_INIT} is a shorthand for this.
address@hidden is a deprecated alias for @code{AC_DISABLE_SHARED}.
address@hidden defmac
+
address@hidden AC_ENABLE_SHARED
address@hidden AM_ENABLE_SHARED
+Change the default behaviour for @code{LT_INIT} to enable shared libraries.
+This is the default on all systems where Libtool knows how to create
+shared libraries.  The user may still override this default by specifying
address@hidden  The option @samp{shared} to @code{LT_INIT} is a
+shorthand for this.
address@hidden is a deprecated alias for @code{AC_ENABLE_SHARED}.
address@hidden defmac
+
address@hidden AC_DISABLE_STATIC
address@hidden AM_DISABLE_STATIC
+Change the default behaviour for @code{LT_INIT} to disable static libraries.
+The user may still override this default by specifying @samp{--enable-static}.
+The option @samp{disable-static} to @code{LT_INIT} is a shorthand for this.
address@hidden is a deprecated alias for @code{AC_DISABLE_STATIC}.
address@hidden defmac
+
address@hidden AC_ENABLE_STATIC
address@hidden AM_ENABLE_STATIC
+Change the default behaviour for @code{LT_INIT} to enable static libraries.
+This is the default on all systems where shared libraries have been disabled
+for some reason, and on most systems where shared libraries have been enabled.
+If shared libraries are enabled, the user may still override this default by
+specifying @samp{--disable-static}.  The option @samp{static} to @code{LT_INIT}
+is a shorthand for this.
address@hidden is a deprecated alias for @code{AC_ENABLE_STATIC}.
address@hidden defmac
+
 The tests in @code{LT_INIT} also recognize the following
 environment variables:
 
@@ -4333,15 +4399,19 @@
 @end defmac
 
 @defmac LT_WITH_LTDL
address@hidden AC_WITH_LTDL
 Add the @option{--with-included-ltdl} option to the @file{configure}
 script.  This option will then allow the person who builds your
 package to choose between linking against an already installed
 @code{libltdl} (@option{--without-included-ltdl}), or the sources
 shipped with the package in the subdirectory named by
 @code{LT_CONFIG_LTDL_DIR} (@option{--with-included-ltdl}).
+
address@hidden is a deprecated alias for @code{LT_WITH_LTDL}.
 @end defmac
 
 @defmac LTDL_INSTALLABLE
address@hidden AC_LIBLTDL_INSTALLABLE
 If there is an installed @code{libltdl}, then set @code{LIBLTDL} to the
 link flags needed to use it, and @code{LTDLINCL} to the preprocessor
 flags needed to find the installed headers.  Otherwise, set them to
@@ -4358,9 +4428,13 @@
 appear @strong{before} the call to @code{LT_WITH_LTDL}.  If you are
 not using @code{LT_WITH_LTDL}, then you must add a call to
 @code{AC_CONFIG_SUBDIRS(@var{DIRECTORY})} to your @file{configure.ac}.
+
address@hidden is a deprecated alias for
address@hidden
 @end defmac
 
 @defmac LTDL_CONVENIENCE
address@hidden AC_LIBLTDL_CONVENIENCE
 Unless you call @code{LTDL_INSTALLABLE} before hand,
 @code{LT_WITH_LTDL} calls this macro automatically, so you should only
 ever need to use it yourself if @code{LT_WITH_LTDL} doesn't do what
@@ -4372,6 +4446,9 @@
 using automake, you will need to define @code{top_builddir} and
 @code{top_srcdir} in your makefile so that @code{LIBLTDL} and
 @code{LTDLINCL} are expanded properly.
+
address@hidden is a deprecated alias for
address@hidden
 @end defmac
 
 One advantage of the convenience library is that it is not installed,
Index: libltdl/m4/ltoptions.m4
===================================================================
RCS file: /cvsroot/libtool/libtool/libltdl/m4/ltoptions.m4,v
retrieving revision 1.7
diff -u -r1.7 ltoptions.m4
--- libltdl/m4/ltoptions.m4     12 Nov 2005 12:08:14 -0000      1.7
+++ libltdl/m4/ltoptions.m4     11 Feb 2007 14:07:07 -0000
@@ -183,38 +183,19 @@
 LT_OPTION_DEFINE([disable-shared], [_LT_ENABLE_SHARED([no])])
 
 # Old names:
-AU_DEFUN([AC_ENABLE_SHARED],
+AC_DEFUN([AC_ENABLE_SHARED],
 [_LT_SET_OPTION([shared])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you
-put the `shared' option into LT_INIT's first parameter.])
-])
-
-AU_DEFUN([AM_ENABLE_SHARED],
-[_LT_SET_OPTION([shared])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you
-put the `shared' option into LT_INIT's first parameter.])
 ])
 
-AU_DEFUN([AC_DISABLE_SHARED],
+AC_DEFUN([AC_DISABLE_SHARED],
 [_LT_SET_OPTION([disable-shared])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you put
-the `disable-shared' option into LT_INIT's first parameter.])
 ])
 
-AU_DEFUN([AM_DISABLE_SHARED],
-[_LT_SET_OPTION([disable-shared])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you put
-the `disable-shared' option into LT_INIT's first parameter.])
-])
+AU_DEFUN([AM_ENABLE_SHARED], [AC_ENABLE_SHARED($@)])
+AU_DEFUN([AM_DISABLE_SHARED], [AC_DISABLE_SHARED($@)])
 
 dnl aclocal-1.4 backwards compatibility:
-dnl AC_DEFUN([AC_ENABLE_SHARED], [])
 dnl AC_DEFUN([AM_ENABLE_SHARED], [])
-dnl AC_DEFUN([AC_DISABLE_SHARED], [])
 dnl AC_DEFUN([AM_DISABLE_SHARED], [])
 
 
@@ -256,38 +237,19 @@
 LT_OPTION_DEFINE([disable-static], [_LT_ENABLE_STATIC([no])])
 
 # Old names:
-AU_DEFUN([AC_ENABLE_STATIC],
+AC_DEFUN([AC_ENABLE_STATIC],
 [_LT_SET_OPTION([static])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you
-put the `static' option into LT_INIT's first parameter.])
-])
-
-AU_DEFUN([AM_ENABLE_STATIC],
-[_LT_SET_OPTION([static])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you
-put the `static' option into LT_INIT's first parameter.])
 ])
 
-AU_DEFUN([AC_DISABLE_STATIC],
+AC_DEFUN([AC_DISABLE_STATIC],
 [_LT_SET_OPTION([disable-static])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you put
-the `disable-static' option into LT_INIT's first parameter.])
 ])
 
-AU_DEFUN([AM_DISABLE_STATIC],
-[_LT_SET_OPTION([disable-static])
-AC_DIAGNOSE([obsolete],
-[$0: Remove this warning and the call to _LT_SET_OPTION when you put
-the `disable-static' option into LT_INIT's first parameter.])
-])
+AU_DEFUN([AM_ENABLE_STATIC], [AC_ENABLE_STATIC($@)])
+AU_DEFUN([AM_DISABLE_STATIC], [AC_DISABLE_STATIC($@)])
 
 dnl aclocal-1.4 backwards compatibility:
-dnl AC_DEFUN([AC_ENABLE_STATIC], [])
 dnl AC_DEFUN([AM_ENABLE_STATIC], [])
-dnl AC_DEFUN([AC_DISABLE_STATIC], [])
 dnl AC_DEFUN([AM_DISABLE_STATIC], [])