GNU `libit' is a collection of common files and `lib/' type modules which,
for most of them, already exist and were collected from other GNU packages.
The goal of `libit' is merely to help uniformising distributions between a
few collaborating maintainers.  If it provides a library which is perceived
as useful in itself, this is only a side-effect, but not the primary goal.
Waiting for a real manual, see usage notes after the separation line.

   WARNING: `libit' is primarily a convenience for Gnits maintainers,
   nothing more.  It is not meant for official release nor distribution.
   A real distribution has no trace whether it has been libitized or not.

This collection exists as a convenience for those not having a direct
account on the FSF machines.  There is some far hope, too, for bringing
some order into the maze of symbolic links reaching such modules, and
providing a more encompassing picture of such modules when global edition
is needed.  The existence of `libit' might also alleviate the burden on
the translation teams associated with the internationalization of GNU.

`libit' is not meant to be released, or at least, not meant to be released
the usual way.  It is just a tool between maintainers, so their `lib/'
directories are more uniform.  In the long run, it should also allow the
translators to work on messages in `lib/' files only once, instead of once
per package.  So, it might be made available to Gnits members first, maybe
other GNU maintainers if we find a way, and also translators, more easily.
It might be published later, maybe, if Richard does not object to such
publication.  But since he objected once to the mere idea of `libit',
a few years ago, he will most probably object forever.

Why is it called `libit'?  Because it is a tiny name, not as heavy
as some other suggestions I received for naming the collection (like
`gnusubst', or so).  It goes well with sentences such as "Why don't you
`lib/' that package?  Why don't you lib it?".  Also, it suggests in itself
that `-lit' may be used to link against `libit' as a stand-alone library.

See file `ABOUT-NLS' for how to customize this package to your language.
See file `BACKLOG' for a summary of pending mail and articles.
See file `COPYING' for copying conditions.
See file `INSTALL' for compilation and installation instructions.
See file `NEWS' for a list of major changes in the current release.
See file `THANKS' for a list of contributors.

For installing `libit', you need GNU `touch' and any `test' understanding
`-L'.  There are probably many other GNU dependencies as well.  You may
report these, for me to document them, yet I'm not especially trying to
get rid of them.  We all have the required tools, I guess.

Once the installation is complete, you may `libitize' the `libit'
distribution itself to save some space (this is what I do), or just remove
it all.  For using `libitize', you need Perl, either 4 or 5, and GNU
`diff'.  I think Perl 4 does not work anymore, only because I use the
`hostname' Perl package.

Besides those configure options documented in files `INSTALL' and
`ABOUT-NLS', a few extra options may be accepted after `./configure':

* `--with-dmalloc' is a debugging option for looking memory management
problems, it prerequires Gray Watson's package, which is available as
`ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz'.

* `--without-regex' tells the installation to use Tom Lord's GNU `rx'
regular expression package instead of the gawk/libc `regex' package.
These packages are not very well supported, yet `regex' is less bad.

This collection is not more *official* than the true sources for all
modules it contains, and the maintainers of the original modules are still
the people to whom problems should be reported, and who are responsible
for these.  In fact, for this collection to reach its goal, we do need
a tight collaboration with maintainers of all such `lib/' type modules.

Send bug reports to `libit-bugs@gnu.ai.mit.edu'.  A bug report is an
adequate description of the problem: your input, what you expected,
what you got, and why this is wrong.  Diffs are welcome, but they only
describe a solution, from which the problem might be uneasy to infer.

======================================================================
What's next?

Once libit contents a bit more stable, the next logical undertaking
would be to address matters Tom explored already: producing system.h and
adjusting configure.in more automatically, according to lib/ contents.
And exploring all the accumulated mail, back-logged into folders, one per
module.  But only one step at a time, at least for the slow me...  If for
now, libit becomes usable enough for Jim, that would be a very good start!
======================================================================
Short usage notes for `libit'.

Merely unpack the distribution somewhere you may leave it afterwards,
then configure, make and install the usual way.  This will install the
`libitize' script and all data files.  This will also prepare and install
libit.a, not really needed, but still a check about how all modules would
configure and compile on your system.  It may also be useful in its own,
who knows.

Usage is simple.  You `cd' at the top-level of the directory in which
you want to establish symbolic links for to files, and call `libitize'.
Or else, you call `libitize' with, as arguments, the top-level directories
of a series of packages you want to libitize at once.  The time savings
from a common initialisation are noticeable, but not very important.

Operation would be as follow:

	libitize [PACKAGE]...

will study all given package directories (or the current directory if
none is given).  All files for which a substitute exists in `libit'
will be replaced by a symbolic link into the `libit' distribution,
after interactive permission has been given for each.  However, for
files being already symbolic links, the links are silently replaced.
There are no requirements about files being in a particular subdirectory.
They are replaced where found.  For example, you may `touch' a file where
you want it, and then, just call `libitize' again to get the symbolic
link created in its place.  For example, to add getopt1.c, I just do:

	touch lib/getopt1.c
	libitize

and the zero-length file is replaced by a symbolic link.  Any remaining
symbolic link not in `/intl/', neither being `/po/Makefile.in.in',
gets diagnosed.

A single `-v' or `--verbose' option will get `libitize' to tell you more
about what it does.  Also, for a while, until you have confidence, you
might want to ensure you have a safe copy of your distribution, just in
case `libitize' does something you do not like at all.

In your package, any file which has the same name as a `libit' file will be
automatically removed and replaced by a symbolic link to the `libit' file,
given your file is empty, has an identical contents as the `libit' file,
or is already a symbolic link (regardless of where or what it points to).
Any regular file which is different will be diff'ed with the `libit' file,
and the results shown to you, you will then be asked whether you want or
not the replacement of your file by a symbolic link to the `libit' file.

If you refuse the `libit' file, you are considering your copy as better.
In this case, please send it to the real maintainer, and ask *him* to send
the updated file to me, unless, of course, *you* are the real maintainer
of the said file :-).  Please don't wholly drop on me the responsibility
of convincing the real maintainers that your changes are good!

There is also another operation mode, meant for the `libit' maintainer:

	libitize --maintenance [PACKAGE]...

In this case, this is the other way around.  Each file in the package
which is also in the libit distribution is `diff'ed and, if not identical,
interactively replaced in libit from the package.  Files in `/lib/' not
being in `libit' are interactively saved in `libit'.  `Makefile.in' files,
`ChangeLog' files and such are ignored, of course.

There is also a `-m' or `--maintenance' option which I use to update the
`libit' collection itself.  You need it if you want to update the libit
distribution yourself.  Here is how it works.  In maintenance mode, in case
of a file difference, `libitize' will give you the choice of preferring
either your own copy from your package, the copy from libit, or none
at all.  If you make no choice, nothing changes.  If you choose `libit',
it works as before.  If you choose your package, `libit' files will be
updated from your package, and only then, a link be established as usual.
All files in your package `lib/' directory which are unknown to `libit'
will be added to the installed `libit' files, after confirmation for each.
After all packages have been processed, the installed `misc/References'
file is automatically updated to reflect which files your packages use
or do not use anymore.  `misc/Changes' is also appended to, and it helps
me updating ChangeLogs before packaging a new libit.  You should ensure
you have write permission to these two files.

For adding other files to `libit', I simply move them in it by hand in some
subdirectory of `/usr/local/share/libit/', they are immediately effective
for any subsequent `libitize' call.  Doing `make maintainer-check' warns
me about installed files which are missing in the distribution, and which
distributed files are not installed.  The first list tells which files
need to be copied from the installed directory into the libit distribution.
Both lists help me adjusting various `Makefile.am' files.

======================================================================
Miscellaneous notes.

All `libit' files should use the GPL instead of the LGPL.  Normalisation
is not complete yet.  At the FSF, a special `make' is launched nightly,
under the control of `cron', to rewrite the copyright notice for many
files.  The `Makefile' lies in `/gd/gnu/lib/libc-copy', it updates
`/gd/gnu/lib/libc-copy/copies' from the `libc' source.  The copyright
text comes from a file `/gd/gnu/lib/libc-copy/lgpl2gpl.sed'.  It may be
that there are also files copied the other direction, into `libc' from
master sources living in `/gd/gnu/lib'.

About our COPYING files, Richard writes:

   Date: 1996-11-23 12:59:47-06:00
   Message-Id: <199611231859.MAA16557@xochitl.nuclecu.unam.mx>
   From: Richard Stallman <rms@nuclecu.unam.mx>
   To: pinard@IRO.UMontreal.CA
   cc: djm@gnu.ai.mit.edu
   Subject: Re: Autoconf 2.10.2: file COPYING
   Reply-to: rms@gnu.ai.mit.edu

   The lawyer said it was ok for us to change the FSF's address in COPYING
   to the new (Temple Place) address.

Here is how I proceed with credits, in THANKS and ChangeLog.  For almost
all user contributions to the program I maintain, textually significant or
not, requiring legalese or not, I get the name of the contributor under
the ChangeLog entry describing the change, introduced by a `Reported by'
clause.  Only the name, not the email address.  I also decided to not
qualify the importance of the contribution, so contributors would not
compare between them about how well I received them...  I also add the
name of the contributor *and* his/her email address in the THANKS file,
so if the user later asks to update the email address (this happens at
times), I have less places to revise.  Also, and only if the name was *not*
already in the THANKS file, I use a canned message to explain where are
prereleases and invite the contributor to become a pretester.

					  Have fun,
					  Franois
