Distributing libltdl documentation

[Anton Ertl]

I just added libltdl as a convenience subproject to our project
(gforth), and want to give some feedback on the documentation, in
particular on the Section "How to distribute libltdl with your
package":

- You might want to mention early that one can use libtoolize to
  perform the copying (however, it's unclear to me why
  
  libtoolize -v -c --ltdl libltdl --subproject
  
  copies ltmain.sh).

- The documantation gave me two conflicting impressions on how
  switching between the included and the installed libltdl could be
  performed:

  * Early I got the impression that there is no provision for this
    (but looking at that part again, I see that I just misinterpreted
    the documentation about symbol conflict problems from multiple
    libltdls; still, maybe there's a way to avoid such confusion).

  * Later I got the impression that the user has to specify
    --with-included-ltdl in order to get the included libltdl.  That
    impression comes from the following part of the documentation:

     If the `--with-included-ltdl' is not passed at configure time, and
     an installed `libltdl' is not found(2), then `configure' will exit
     immediately with an error that asks the user to either specify the
     location of an installed `libltdl' using the `--with-ltdl-include'
     and `--with-ltdl-lib' options, or to build with the `libltdl'
     sources shipped with the package by passing `--with-included-ltdl'.

  However, I found that LTDL_INIT automatically sets
  with_included_ltdl=yes if it does not like the installed libltdl.
  That's consistent with the usual autoconf behaviour, but given the
  documentation at first I though that it would always use the
  included libltdl, so I spent some time in trying to find a way to
  disable this behaviour (which turned out to be unnecessary).

  I would also find it nicer if the check done by LTDL_INIT used a
  function I care about, or a libtool version rather than the
  undocumented lt_dlinterface_register().

- Gforth does not use automake, and it was not obvious how to link the
  included libltdl.  I eventually settled on the following approach:
  
  In configure.in:
  
  #how to link with libltdl
  if test "x$with_included_ltdl" = "xyes"; then
    #hard-code it (hopefully portable); the official way is to use automake :-(
    LTDL_LDLIBS='-L $(top_builddir)/libltdl/.libs -lltdlc'
  else
    LTDL_LDLIBS='$(LIBLTDL)'
  fi
  AC_SUBST(LTDL_LDLIBS)
  
  In Makefile.in:
  
  LIBLTDL  = @LIBLTDL@
  LDLIBS  = @LIBS@ @LTDL_LDLIBS@

- The documentation gave me the impression that the line

  AC_CONFIG_MACRO_DIR([libltdl/m4])
  
  is enough to get aclocal and autoconf to see the libltdl macros, but I
  found that I had to change the call to aclocal in Makefile.in into
  
  aclocal -I libltdl/m4
  
  or the macros would no be expanded.  Versions:
  
  aclocal (GNU automake) 1.9.6
  autoconf (GNU Autoconf) 2.61


If you want to see the changes that I made to add libltdl, you can look
at our CVS repository
<http://www.complang.tuwien.ac.at/forth/gforth/cvs-public/> (changes
from April 20th), or I can extract a patch that you can look at.

- anton