documentation comments

[Ross Boylan]

It would be good if the documentation (I'm looking at 1.5.6.) were
clearer on the setup of libtool and its requirements.  In previous
discussion on this list, I've learned that autoconf is required.  I've
just discovered a little more is necessary too (at least install-sh,
which can be produced by automake).

Also, it could be clearer that you don't actually distribute a libtool
with your package, but have it generated on the build machine by
configure.  In particular, I found this confusing:
----------------------------------------------------
5.3 Configuring libtool
=======================

Libtool requires intimate knowledge of your compiler suite and operating
system in order to be able to create shared libraries and link against
them properly.  When you install the libtool distribution, a
system-specific libtool script is installed into your binary directory.

   However, when you distribute libtool with your own packages (*note
Distributing::), you do not always know which compiler suite and
operating system are used to compile your package.

   For this reason, libtool must be "configured" before it can be used.
This idea should be familiar to anybody who has used a GNU `configure'
script.  `configure' runs a number of tests for system features, then
generates the `Makefiles' (and possibly a `config.h' header file),
after which you can run `make' and build the package.

   Libtool adds its own tests to your `configure' script in order to
generate a libtool script for the installer's host machine.
-------------------------------------------------------------
"when you distribute libtool with your own packages" meant, to me, that
the file libtool would be part of my package.  The line 'libtool must be
"configured" before it can be used' also suggested there was some file
that configure acted upon, rather than one that it created.  The
statement that "Libtool adds its own tests to your 'configure' script"
similarly suggests that libtool exists before configure (I realize this
is sort of true, though it applies to the maintainer machine).  


Now, back to the issue of required programs and packages.....

Documentation section 5.4, Including libtool in your package,
lists a bunch of required files, and recommends running libtoolize.  (It
also does say not to include libtool itself).  Having done all this, I
put the project on a new system and ran configure.  It failed because
install-sh was absent.

So at least that file is necessary.  I did 
   automake --foreign --add-missing
which added 3 files (though I did get some complaints from it).  Things
then worked.

Finally, section 5.1, Writing `Makefile' rules for libtool, does say "If
you want to use libtool in a regular `Makefile' (or `Makefile.in'), you
are on your own."  Since I am trying to use libtool without automake,
this could be taken as a general warning and disclaimer.  Even if that
was the intent, it would be nice to add the information mentioned above
for those who aren't using automake.

-- 
Ross Boylan                                      wk:  (415) 502-4031
530 Parnassus Avenue (Library) rm 115-4          address@hidden
Dept of Epidemiology and Biostatistics           fax: (415) 476-9856
University of California, San Francisco
San Francisco, CA 94143-0840                     hm:  (415) 550-1062