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 <[EMAIL PROTECTED]> | 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>[EMAIL PROTECTED]</email></author> | <author>Peter Simons2 <email>[EMAIL PROTECTED]</email></author> | <version>1.4</version> | | <p>This € ¢ 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
