obsoleted vs acinclude tool / Re: Masterplan

[Guido Draheim]

>     *  Reassess the contents of the archive
>
>         Several macros contained in the archive are 
>         obsolete because they have been incorporated
>         (in one way or another) in the current Autoconf
>         release.

obsoleted macros have been the most problematic part for
me in the last months - they might even be responsible for
trying to get into more control over the handling of
submissions.

The acinclude tool is a result of my long usage of
trying to automate the handling of autoconf extensions
when they are shared
(a) between different users
(b) for multiple projects
(c) on multiple workareas

It basically allows to maintain a local (!!) repository of
autoconf extensions - some part of that local repository
is a copy from the gnu ac-archive, some other are out
of work from sfnet users, some other from local users,
some other just reference macros from current projects.

* how it works

After some iterations, the subdir handling showed best,
and it is performing very well these days. The normal
/usr/share/aclocal directory contains a bunch of
subdirectories that are search for autoconf extensions
by the acinlude tool. The gnu folders are named
according to the legacy format - very easy to sync up.

The user directories might actually be symlinks (!!)
to the actual directory in the users home. That allows
each user to have a local autoconf extension repository
and the system binds it into the global processing.

Furthermore, it might even have symlinks to the "m4"
subdirectories of some local projects - that makes it
a lot easier to keep the macros in sync when there
are local projects that depend on each other, and
which need a certain macro to configure correctly
with the other side.

* the update problem

Now, sometimes a user wishes to rename a macro, or
perhaps that is just a result of the wish to modify
the call-synopsis or behaviour slightly. The old
macro is not invalid by that, but it shall be moved
out of being used in the current projects.

Simply removing the obsoleted macro will mean that
the entire build process stops working when it did
incorporate `acinclude` to handle to distribute the
autoconf extensions into the various projects around.

Apart from that, looking just as the website, some
other documentation might href a certain macro, but
clicking on it will not show up with anything. No
sign that the functionality is continued under a
slightly different name with some slightly different
behaviour.

* obsolete marker

Therefore, obsoleted macros should not just be
removed from the repository - but they should be
marked as "obsolete". The `acinclude` tool
recognizes a line in the doc-part of an autoconf
extension macro and shows it to the user screen
(actually, a kind of `grep "obsoleted" macro.m4`).

The current sfnet'  macro2html.pl recognizes it
as well and puts it into <b>old marker. The
macro text itself contains a hint to the new
(and recommended) macro to pick instead. That
showed enough for now.

The next level would have been, to let the
gen-index program detect obsoleted versions as
well, and _not_ list them in the index page
anymore, even that the macro itself and its
html page are still there to be the endpoint
of href's.

* status level and staging area

When deleting it from the main index page,
it might be better however to make up yet
another index page - one that will list
obsoleted macros. That is also needed for
google bots, so that a google search for
a specific macro will still resolve but
get into the "obsoleted" staging area on
the webserver.

The obsoleted macros should be around for
quite a while - I would say about a year
atleast - so that projects have time to
pick up the new variant (when moving into
the next release cycle), and have
documentations and search spiders update
their link databases.

The same scheme of this "autoconf extension
lifecycle" can be picked up for being
used for very new submissions - they are
not listed in the main index page for a
while but they are there in a staging
area for "proposed" inclusion.

I do not know whether it is good to extend
the lifecycle to more that these three
phases, but a status labelling of macros
surely allows to do so.

wdyt, cheers, guido