Re: Documentation patch

[Ralf Wildenhues]

Hi Tom,

* tom fogal wrote on Sat, Aug 20, 2005 at 12:29:51AM CEST:
> Alright, I'm very new at this so feel free to berate me && mention if I
> did something wrong here.

No problem.

First, please always send patches in unified diff format (option `-d'
for diff, or just put the line `diff -u' in ~/.cvsrc).  That way, they
can be applied also to slightly changed sources.  Second, please
consider sending patches to the libtool-patches list so people only
wanting to read general discussion aren't bothered.  (I guess I forgot
that a few times, too).  You'll get moderated if you don't subscribe,
but only the first time.

> 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.

Notes below.

> Maybe it would be appropriate to patch TODO as well... ?

Yep.  A short note would suffice.

> 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. 

better: ..we can create a library that is the union..
because: you may create both a regular (either static or shared)
library out of it, or yet another convenience library.
You could highlight this fact by another sentence.

> > @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}.

Now while this last sentence is true, there is a slight difference in
semantics:  With --whole-archive, the decision to link-in-as-whole is
done at link time of the output, whereas with libtool it is done at link
time of the convenience archive.  (I have found the latter to be a very
good idea in practice, BTW.)

I'm not sure how/whether this fact is best put in above description.

> 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.

I would not write this last sentence here, but put it in TODO as you
suggested.

Just one more note for texi documentation: I usually use `make all dvi'
and read the info and dvi output for long lines, alignment and general
looks.  I'll do that with a unified diff of yours.  :)

Cheers, and thanks for working on this!
Ralf