Make(1) a webpage for your code

CHUM is an unholy program is a (GNU)makefile that embeds awk, html, and css to generate a static HTML viewer for your code, à la stagit, repo2html or whatever powers depp.brause.cc.

However, CHUM is more versatile than these: it can work with any source repository, under any version control—or indeed, under no version control whatsoever. It just reads a .chum file in the current directory for its configuration, and builds a snapshot of the current state of your repo with HTML, source code, and an index.

Sadly, it cannot do anything with history, but really, someone should clone your repository to get that, shouldn’t they?

CHUM dependencies

GNU Make (POSIX just doesn’t cut the mustard)
Rsync
Awk (POSIX should be fine)

Using CHUM

Using CHUM can be as simple as running chum in your project root. That will build the project and place the generated site in OUTDIR (see below). You can also run the following recipes included in CHUM:

chum serve: build the site and serve it locally.
chum publish: build the site and publish it to REMOTE.
chum clean: remove the generated output directory.

Because CHUM is a makefile, you can also set variables on the commandline to override variables in your .chum file at run-time. And whatever other funky stuff GNU make lets you do with the commandline!

Configuration

By default, CHUM doesn’t do a lot. You’ll want a .chum file in your project root to tell CHUM what to do. This file is included as CHUM does its work, so it’s a (GNU)makefile declaring variables and what-not. Here are the variables you can set:

NAME: the project name.; Default: the basename of the current directory.
AUTHOR: the project author(s).; Default: none.
DESCRIPTION: the project description.; Default: none.
OUTDIR: where the built site will reside.; Default: out.
SERVER: a command to serve the out directory locally.; Default: none.
SOURCES: all the files to include in the generated site.; Default: none.; Notes: README and LICENSE are included automatically.
README: the README file for the project – included in the generated index.; Default: none.
READMEFILTER: a Unix-style text filter to pass README through for rendering html.; Default: cat.
LICENSE: the license file for the code.; Default: none.
TARBALL: the name of a generated tarball for downloading.; Default: OUTDIR/NAME.tar.gz
STATICS: any extra static files to copy to the site.; Default: none.; Note: could be used for images or other binary files.
REMOTE: the remote ssh server to rsync the site to.; Default: none.
URL_ROOT: the root URL of the site. Useful in templates.; Default: none.
URL_CLONE: a URL where a user can clone the repository.; Default: none.
URL_DOWNLOAD: a URL where a user can download a repository snapshot.; Default: URL_ROOT/BASENAME(TARBALL).
TEMPLATE: the HTML template for each page. See TEMPLATES, below.; Note: use the GNU make define…endef format for this variable.
STYLE: the site style, included on each page.; Note: use the GNU make define…endef format for this variable.

Templates

You can also define a template for your pages to fit within. The template format should be vaguely familiar to you if you’ve ever worked with templates before — it has {{VARIABLES}} to replace with well, variables:

STYLE: STYLE
CLONE: URL_CLONE
DOWNLOAD: URL_DOWNLOAD
DESCRIPTION: DESCRIPTION
AUTHOR: AUTHOR
ROOT: URL_ROOT
DIRECTORY: the last component of the current directory name
FILENAME: the current filename
OUTFILE: the output filename
RAWFILE: the raw-text filename

To differentiate between normal pages and the index page (e.g. for including a list of files in the index only), you can also use  ...  and  ...  tags to guard content. Text between the NORMAL comments will only appear in normal pages, and text between INDEX comments will only appear on the index page.

For completeness’s sake, here is the default TEMPLATE:

<!DOCTYPE html>
<html><head>
<meta charset="utf-8">
<title>{{FILENAME}}</title>
<style>{{STYLE}}</style></head>
<body>
<h1><!--NORMAL-->{{DIRECTORY}}/<!--/NORMAL-->{{FILENAME}}</h1>
<!--INDEX-->{{DESCRIPTION}}<!--/INDEX-->
<!--NORMAL-->
<nav><ul>
<li><a href="{{ROOT}}">index</a></li>
<li><a href="{{RAWFILE}}">source</a></li>
</ul></nav>
<!--/NORMAL-->
<main>{{CONTENT}}</main>
<footer><p>(C) {{AUTHOR}}.
<a href="{{CLONE}}">clone</a>
<a href="{{DOWNLOAD}}">download</a>
</p></footer>
</body>
</html>

And for extra completeness’s sake, here’s the default STYLE. Note the styling of .ll (line number links):

#readme{max-width:48em;}
.ll{display:inline-block;width:3em;text-align:right;
padding-right:0.5em;margin-right:0.5em;}

License

Basically, you’re good. See COPYING for details.

Contributing

Email me with comments, suggestions, complaints, or praise!