Documentation patch

[tom fogal]

Alright, I'm very new at this so feel free to berate me && mention if I
did something wrong here.

Attached is a short doc patch that (I think) provides better
information on how convenience libraries work, and mentions that the
ordering is important to --preserve-dup-deps.  For the latter, I've
mentioned that the limitation will eventually be removed, although I've
given no timescale for this.
Maybe it would be appropriate to patch TODO as well... ?

-tom

? doc.patch
Index: doc/libtool.texi
===================================================================
RCS file: /cvsroot/libtool/libtool/doc/libtool.texi,v
retrieving revision 1.193
diff -r1.193 libtool.texi
1052a1053,1075
> When another libtool-created archive is linked to a convenience library, all
> objects from the convenience library are linked into the newly created
> archive.  This is different from a traditional static library, which only
> includes the objects required to resolve the current set of undefined
> references.  Due to this behavior, we can create one convenience library that
> is the union of a set of convenience libraries. 
> 
> @example
> host$ @kbd{libtool --mode=link $CC $CFLAGS $LDFLAGS -o lib123.la \
>               subdirA/lib1.la subdirB/lib2.la subdirC/lib3.la}
> @end example
> 
> This provides a logical and portable way of linking a project that includes
> several different modules, stored in different subdirectories.  Each
> subdirectory can create a libtool convenience archive, and then one archive
> can be created that has all the symbols from each of the different modules,
> by a command similar to the above.  Finally the application can be linked
> against the new all-encompassing convenience archive.
> 
> For those familiar with @sc{gnu} @command{ld}, convenience archives can be
> thought of as an abstracted, portable implementation of
> @option{--whole-archive}.
> 
1194c1217,1219
< that libtool knows it can safely.
---
> that libtool knows it can safely.  Please be aware that in current versions
> of libtool, this option must appear before @option{$CC} to be effective.
> This limitation will be removed in future versions of libtool.