schwa

Source Code Htmlizer

Source Code Htmlizer Written in Awk

Here we have a tool that’s in a similar vein to stagit and others. It takes a number of files on the commandline and generates HTML for them in an output directory, then generates an index with a file listing and a readme. It’s also written completely in awk(1p). I guess that’s the gimmick.

Oh, that’s not reall the only thing. I wrote schwa because I like the idea of static git repository site generators, but I really don’t need all the git history and everything online—that’s what git clone is for. Besides, with schwa I’m not really limited to git repositories. So maybe there’s a little more than just the one gimmick.

How to use

I don’t want to figure out how to process actual command-line arguments in awk, so I’ve made all the configuration doable through awk variables. The command I’ve been running to test schwa is

./schwa.awk \
    -vreadme=README.md \
    -vreadmefilter='pandoc -thtml5' \
    -vtemplate=example/template.html \
    -vstatic=example/style.css \
    -vclone='<a href="https://git.acdw.net/schwa">https://git.acdw.net/schwa</a>' \
    -vdesc='Source Code Htmlizer' \
    example/* *

Of course, some explanation is in order.

Command-line variables

The following variables are used in schwa to fine-tune its behavior. Because it’s awk, you’ll need to pass each variable like -v <VAR>=<VALUE>. I’ve listed each variable below in the way that you would pass it on the commandline.

-v template=<FILEPATH>
This file will be used as the template for generated files. You can use template variables; those are discussed below.
Default: <!DOCTYPE html><title>{{FILENAME}}</title> "<h1>{{FILENAME}}</h1>{{CONTENT}}"
-v out=<DIRECTORY>
Output directory for generated files.
Default: out/ in the current directory
-v readme=<FILEPATH>
File to include in the code index under the file listing. Its contents will be passed through readmefilter, which see.
Default: none
-v readmefilter=<COMMAND>
Program to run on the contents of readme to generate HTML. Note that the readme text is not piped through this program; rather, readme is passed to this program as an argument. This is due to a limitation of POSIX awk that I don’t care to work around.
Default: none
-v clone=<STRING>
Clone URL to pass to template.
Default: none
-v desc=<STRING>
Repository description to pass to template.
Default: none
-v static=<FILE>[:<FILE>[...]]
A colon-delimited list of files to copy directly to the out directory root. I use this for style.css and stuff like that.

Templating

A schwa template can contain a number of variables that hold information about the current file under processing and the repo in general. Template variables are surrounded by double curly braces in the template and are expanded to the values listed below. I’ve listed each template variable as it would appear in the template file.

{{CLONE}}
The value passed to the clone variable.
{{DESCRIPTION}}
The value passed to the desc variable.
{{DIRECTORY}}
The basename of the repository’s root directory.
{{FILENAME}}
The filename of the current file, relative to DIRECTORY.
{{OUTFILE}}
The output name of the current file, including the output directory.
{{RAWFILE}}
The location of the raw text file copied to the output directory with the source of the current file.
{{CONTENT}}
The content of the current file.

“Conditionals”

To use one template for the whole repo, I had to include some conditionals in templates. Turns out, HTML comments were pretty easy to implement, so here we are. If you only want some part of a template to appear on a normal page or on the index of the repository, use one of the following.

<!--INDEX--> ... <!--/INDEX-->
Only show the contained content on the repository’s generate index.html page.
<!--NORMAL--> ... <!--/NORMAL-->
Only show the contained content on a normal (that is, code file) page.

Example

I’ve included an example template and style to show you what schwa can do. I hope that helps answer some questions.

Contributing

Email me at to contribute code, ideas, questions, or hell, complaints, why not.

License

This project is licensed under a BSD 3-clause license. See COPYING for more details.