macro archive re-launch

[Peter Simons]

Dear autoconf users,

for a while, I have been unsatisfied with the way the autoconf archive
<http://www.gnu.org/software/ac-archive/> works internally, because
the macro mark-up I used is somewhat cumbersome and doesn't really
produce the kind of high-quality output you'd expect from a site
dealing with such a staggeringly fine tool like autoconf. :-)

So I finally found the time to re-do the internals and am quite
pleased with the results. In this mail, I'll outline the way the
archive will hopefully work in the future and hope that some of you
have feedback and useful suggestions for me. If you have any thoughts,
fire away! Please Cc a copy of your mail directly to me, though,
because I am not subscribed to this list.

When I came up with the archive, my goal was to find a way how the web
site and all related files could be generated from the featured macros
automatically, and my result was a simple way to include meta
information into commens at the top of the macro, such as in:

 | dnl @synopsis PETI_PATH_SENDMAIL
 | dnl
 | dnl This macro will find a sendmail binary in many obscure places and
 | dnl replace @SENDMAIL@ with the path in all output files.
 | dnl
 | dnl @version $Id: peti_path_sendmail.m4,v 1.4 2000/12/31 10:18:09 simons Exp 
$
 | dnl @author Peter Simons <address@hidden>
 | dnl
 | AC_DEFUN([PETI_PATH_SENDMAIL], [
 | peti_path_backup=$PATH
 | PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/lib:/usr/libexec:/usr/local/bin
 | PATH=$PATH:/usr/local/sbin:/usr/local/lib:/usr/local/libexec:/usr/etc
 | AC_PATH_PROG(SENDMAIL, sendmail, sendmail)
 | PATH=$peti_path_backup
 | ])
 |   </m4source>
 | </acmacro>

A small tool would then turn this into the HTML page you can see at
<http://www.gnu.org/software/ac-archive/Installed_Packages/peti_path_sendmail.html>.
Unfortunately, this mark-up has some serious limitations: It can't
deal with packages of macros, there's no way to format the
documentation nicely, and it is difficult to parse reliably.

In the new system, the macros are formatted in a simple format
described by an SGML DTD. The same macro then looks like this:

 | <!DOCTYPE acmacro PUBLIC "-//Peter Simons//DTD Autoconf Macro V1.0//EN">
 | 
 | <acmacro name="peti_path_sendmail" category="installedpackages">
 |   <documentation>
 |     <synopsis>PETI_PATH_SENDMAIL</synopsis>
 |     <synopsis>PETI_PATH_SENDMAIL</synopsis>
 |     <shortdescription>Find the local sendmail binary</shortdescription>
 |     <author>Peter Simons <email>address@hidden</email></author>
 |     <author>Peter Simons2 <email>address@hidden</email></author>
 |     <version>1.4</version>
 | 
 |     <p>This &euro; &cent; is a <a href="http://cryp.to/";>test</a>.</p>
 |   </documentation>
 | 
 |   <m4source>
 | AC_DEFUN([PETI_PATH_SENDMAIL], [
 | peti_path_backup=$PATH
 | PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/lib:/usr/libexec:/usr/local/bin
 | PATH=$PATH:/usr/local/sbin:/usr/local/lib:/usr/local/libexec:/usr/etc
 | AC_PATH_PROG(SENDMAIL, sendmail, sendmail)
 | PATH=$peti_path_backup
 | ])
 |   </m4source>
 | </acmacro>

If anyone is interested in the DTD file describing this format, just
mail me for a copy.

You can include any number of macros into a single file, as long as
they're delimited by an ACMACRO tag. Furthermore, each macro has some
special documentation fields, which correspond to the fields we have
on the web site today already. What is nicer, though, is that you can
legally speficy multiple synopsis- and author lines here. As you can
see, the actual macro follows at the end included in an M4SOURCE tag.
This tag is declared to contain un-parsed CDATA, so you don't have to
worry about escaping any SGML/HTML specials in that section.

The ACMACRO tag has some required attributes, namely the name the
macro is is to be stored under in the archive and the name of the
category it will be listen in. At the moment, I support the categories

 | <!ELEMENT acmacro - - (documentation,m4source)>
 | <!ATTLIST acmacro name CDATA #REQUIRED
 |        category (cxxsupport|csupport|crosscompilation|
 |                  javasupport|misc|installedpackages) #REQUIRED>

but I can easily add more.

What is really nice is that the DOCUMENTATION tag refers to the HTML
4.01 DTD for valid tokens, hence you can use the complete HTML tag set
in that section. In the example, I included a hyper text link and some
fancy currency symbols -- God bless Europe.

Furthermore, I wrote a formatting engine that will parse the SGML file
to (a) extract the macro as raw m4 file and (b) create an HTML page
with the documentation and everything. The formatter fetches all
items and makes them available as variables to be inserted into a text
template that resides on the hard disk. The template I use at the
moment looks like this:

 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 | <html>
 |   <head>
 |     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 |     <title>Macro: ${name}</title>
 |   </head>
 |   <body>
 | 
 |     <!-- Each page starts with a short navigation segment. -->
 | 
 |     <table summary="Navigation bar to go back to the main page or to 
download the macro." width="100%">
 |         <tr>
 |           <td width="50%" align="center"><a href="../">Back to the Main 
Page.</a></td>
 |           <td width="50%" align="center"><a href="${name}.m4">Download the 
M4 Source.</a></td>
 |         </tr>
 |     </table>
 |     <hr>
 | 
 |     <!-- Here comes the macro's author- and version information. -->
 | 
 |     <h1 align="center">${name}</h1>
 | 
 |     <h2>Synopsis</h2>
 |     <p style="margin-left:2cm"><code>${name:u}</code></p>
 | 
 |     <h2>Version</h2>
 |     <p style="margin-left:2cm">${version}</p>
 | 
 |     <h2>Author</h2>
 |     <div style="margin-left:2cm">
 |       ${author}
 |     </div>
 | 
 |     <!-- Here comes the macro's documentation. -->
 | 
 |     <h2>Description</h2>
 |     <div style="margin-left:2cm">
 |       ${documentation}
 |     </div>
 | 
 |     <!-- The macro's m4 source code. -->
 | 
 |     <h2>M4 Source Code</h2>
 |     <pre style="margin-left:2cm">
 | ${m4source}
 |     </pre>
 | 
 |   </body>
 | </html>

The variables to be inserted here are ${name}, ${version}, ${autor},
${documentation}, and ${m4source}. Furthermore, you can modify the
contens of the variables with the usual shell operations. Note the
${name:u}, for example, which will turn the text to upper-case. Using
this template mechanism, we have detached the presentation completely
from the contents; my tool could, for all it is worth, also generate
that page with DHTML, JavaScript and Flash at no extra cost!

Of course all tools involved into generating this page have full
unicode support, so if anybody feels like it, he or she can write the
documentation in Japanese. :-)

Apparently, the possibilities are limitless; one could add an LANG
attribute to the documentation, for example, and have the formatter
generate multiple versions of the page, each with a different language
included. Furthermore, one could add an ID attribute to each macro use
that to generate cross-references on the fly. That would be extremely
useful if anybody REQUIRE()s other macros, included in the archive.

So that's about it. What do you think? Is there anything I might want
to add to the format? Any tags I should support?

        -peter