Macro Archive Relaunch

[Peter Simons]

Hi everybody,

in a staggering example of over-engineering, I rewrote the
infrastructure that maintains and builds the GNU Autoconf Macro
Archive, which is available at:

    http://www.gnu.org/software/ac-archive/

There are numerous changes that allow for a much better archive than
we have today. To list the highlights:

 - The new "genarchive" tool can read macros in both the old format
   and in a new XML-based format, for which a DTD is available.

 - Macros in the XML format are validated using an SGML/XML parser
   before they're processed, thus greatly reducing the amount of
   manual effort involved in verifying the submissions.

 - The generated web pages of the archive are again being validated by
   a full SGML parser in order to assure that the HTML pages have a
   maximum of standard conformance and maximum availability on all
   kinds of HTML-capable devices.

 - Through the use of "style sheets", the visual appearance of the
   archive can be improved.

 - The "genarchive" tool allows for easy and painless additions such
   as new categories, etc.

 - The XML format allows for easy addition of meta information, which
   the old format cannot easily express. I could imagine, for
   instance, information about related macros (packages),
   dependencies, appliance to certain Autoconf versions, etc.

Everything is merry and well ... But I do need help in order to make
the whole thing take off. Before I go into the gory details, let me
show you what a macro submission in the NEW format looks like:

 | <?xml version="1.0" encoding="ISO-8859-1"?>
 | <!DOCTYPE acmacro PUBLIC "-//Peter Simons//DTD Autoconf Macro XML 1.0//EN"
 |     "http://gnu.org/software/ac-archive/dtd/acmacro1-xml.dtd";>
 |
 | <acmacro category="misc">
 |   <name>PETI_ENABLE_DYNAMIC_LINK</name>
 |
 |   <synopsis>PETI_ENABLE_DYNAMIC_LINK</synopsis>
 |
 |   <version>$Id: peti_enable_dynamic_link.xml,v 1.2 2003/01/15 23:48:53 
simons Exp $</version>
 |
 |   <author>
 |     <name>Peter Simons</name>
 |     <email>address@hidden</email>
 |   </author>
 |
 |   <summary>Add a command-line flag to enable/disable dynamic 
linking.</summary>
 |
 |   <description>
 |     <p>Calling this macro adds the flag
 | <code>--enable-dynamic-link</code> to the command-line options
 | supported by the configure script. This option effectively
 | controls whether the compiler/linker flag <code>-static</code> is
 | added to <code>$LDFLAGS</code> or not. The default is to link
 | dynamically.</p>
 |   </description>
 |
 |   <m4source>
 | AC_DEFUN([PETI_ENABLE_DYNAMIC_LINK], [
 | AC_MSG_CHECKING(what kind of binaries we shall create)
 | AC_ARG_ENABLE(dynamic-link,
 | [  --enable-dynamic-link   Create dynamically-linked binaries (default)],
 | if test "$enableval" = "yes"; then
 |     AC_MSG_RESULT(dynamically linked)
 | else
 |     LDFLAGS="$LDFLAGS -static"
 |     AC_MSG_RESULT(statically linked)
 | fi,
 | AC_MSG_RESULT(dynamically linked))
 | ]]></m4source>
 | </acmacro>

The formatted web page generated from this can be seen at:

    http://www.gnu.org/software/ac-archive/peti_enable_dynamic_link.html

Compared to the old mark-up format, this has the following significant
advantages:

 - A short description of the macro (summary) is visible on the index
   page.

 - Authors can be formatted into a real <a href="mailto:...";>name</a>
   element on the web page.

 - The description may include (a reduced set of) HTML 4.01 tags to
   create fancier layout.

 - The synopsis may include <br/> tags to allow for multi-line
   formatting.

 - The submitter can decide into which category the macro is going to
   be included (note the attribute "category") rather than me deciding
   that.

The <name> tag, which appears to be pointless, is used to determine
how the macro's file is to be called. It can be used to generate macro
packages -- something many people have missed badly in the past.
Effectively, you include multiple macros in the <m4source>, you
describe them in the <synopsis>, <summary>, and <description> tags,
and you set the <name> to something like "my_java_package" and there
you are.

Of course, I can automatically convert macros from the old format into
the new one. At the moment, though, I chose to retain all macros in
the format in which they were submitted.

Having outlined this, let me come to the part where I beg for
assistance. :-) I need help with the following tasks:

 (1) Work out some cool layout, formatting, style sheet, etc.

 (2) Major clean-up of the macro submissions included so far!

     Some macros have been obsoleted by newer Autoconf versions, some
     macros contain bugs or very poor formatting of the documentation,
     and some macros are outright stupid. (Like a few of my own
     submissions, which I removed with a slightly red head because of
     the shame.)

 (3) Clearly, the current set of categories is inadequate. We need to
     work out a new categorization ... And then we need to
     re-categorize the macros contained in the archive so far.

 (4) General ideas what to do and how to improve the archive.

 (5) Set-up a mechanism how submitters can easily validate their XML
     files. I would love to have a web-page where you just upload your
     submission and get all errors produced by the XML validator back
     right away. When the macro does not produce any errors, it should
     be submitted into a queue right away for addition to the archive.

 (6) Lot's of additional documentation must be written.

 (7) Work out a good way to show a list of most recent changes. (We DO
     have this information thanks to CVS, I am just not sure how to
     visualize it in a good way.)

 (8) Think of a good way to distribute the macros in a meaningful way
     so that Linux distributions can include them. (I do have a
     volunteer for creating RPM packages already, but I am just not
     sure how to organize things in the release archive.)

This is certainly getting over my head by now (as some submitters have
noticed by my poor response times) and I could really use some HELP!
:-)

Anyone interested? Any comments? Any suggestions?

Peter


P. S.: The whole thing is publicly available through Savannah. Take a
look at <https://savannah.gnu.org/projects/ac-archive/> if you're
interested.