MHonArc: HTML archives per year

In my section on SmartList, I present an rc-file for maintaining a per-year HTML archive of a SmartList based mailing-list. (It essentially calls

mhonarc -add
      -quiet -outdir /path/to/html_archive/$year

, where $year is the four-digit year). However, that rc-file does not care about special settings for the archives; it simply assumes that you either create the configuration file(s) for MHonArc manually, or use its default settings.

Here, I am presenting my way of automating this process. It consists of a set of M4 files, plus a shell script for updating the per-year directories. (M4 is a macro processor, i.e., something like the C preprocessor, but with a different syntax, and more powerful.) The script assumes the GNU version of M4 because GNU M4 knows the options -I (directory for include instructions) and -D (define a symbol).

The files and directories

The main directory of the list archive contains

one sub-directory per year, named after the year (i.e., 1999, 2000, etc.). Further directories, e.g. for archiving administrative mails (like the subscription confirmation), may be added.
Optionally, a file the_years that gives the names of those sub-directories. If it is missing, all directories with 4-digit numbers as their names are used, so you only need it if you have additional directories.
RCFILE.m4, giving the title to use for the archive index files (a name or short description of the list). It also tells M4 to use curly brackets (i.e., { and }) as "quote characters".
Of course, an "index file" for the WWW-Server. This uses some server-side include mechanism to present an up-to-date list of per-year index files. This example is for the Apache WWW server; it should be named index.shtml, welcome.shtml, or whatever your server configuration looks for (ask your webmaster if you don't know).
My standard configuration file; it creates indexes by date and by thread. It includes (for historical reasons as well as for better readability) M4 files defining the header and the footer of these two indexes. File compact_en.m4 is also included.
If you want other indexes, e.g., by author or by subject, list them in a file called otherindexes. Each line of this file contains three fields, separated by whitespace (the third field may contain whitespace, the first two may not). These fields are:
- the name of the MHonArc resource file for this index. A file with this name will be created in each subdirectory (see file the_years above), and a file with this name and additional suffix .m4 must be in the main directory.
- The name of the first index file for this index. This must be the same as given in the <IDXFNAME> resource of the resource file given in the first field. It is used to create a link to this index in the year overview included by the webserver index file.
- An addition describing the index, also for the year overview included by the webserver index file.
For example, given the line
```
subject.mrc	subject.html	by subject
```
there must be a file subject.mrc.m4 in the main directory of the archive. From this, files 2000/subject.mrc, 2001/subject.mrc, etc. will be created. The year overview will contain the text "2000 by subject", linking to 2000/subject.mrc. See years.html for the result.

If you maintain the archives for several mailing lists in "neighbour" directories (like I do for several lists to which I am subscribed--I store them in $HOME/public_html/mailinglists/listname/year), you may find it convenient that you can store most of the m4 files in the (common) parent directory of the list's main directories, in my case, in $HOME/public_html/mailinglists (that's the reason for -I.. in M4 invocation in the shell script).

So, all that' missing is the shell script that takes all these files and does "the magic". It is invoked in the main archive directory, with one argument that indicates the language of the list. Some of the m4 files above have names something_en.m4. I also have something_de.m4 for German lists. For the English lists, I call update_compact en, for the German lists I call update_compact de.

How it all works together

To be completed.

Hans-Albert Schneider

Last modified: Mon Jan 21 23:50:11 CET 2002