WebMeister Manual

The Programmer's Web Site Generation Tool
Edition 0.1, August 1996 for WebMeister 0.1

Jared L. Reisinger

This is a portion of my pre-implementation design notes for WebMeister. The current implementation differs somewhat from these notes---not the least of which is that many of the open issues have since been resolved. Nevertheless, these notes should serve to explain some of what WebMeister is until I write some better (read: "actual") documentation.

Design Notes

At first I had thought that WebMeister was going to be a site generation tool, but further thought has me leaning towards making it a page generation tool. Mostly this is because site generation/administration is a complex task, and my initial goal---page generation---is feature-full enough for its own project.

The other reason for this change comes from thinking about where page meta-information should live. There's some rationale for having all information that's page-specific be specified in the datafile for the page itself. The downside of this design is that there's now no convenient place for settings that are site-specific, and apply to all pages (or at least all pages within a related group). If WebMeister's goal is simply page generation, though, it's easier to draw the distinction about whether a particular piece of information belongs within WebMeister's jurisdiction or not.

Given the switch to a per-page processing system, it became clear that the cc/make system was an analogous separation of file and project separation, and thus WebMeister, as the file component, should take design/option cues from cc.

For starters, one of the pieces of information I had considered for inclusion in the WebMeister datafile was the name/path of the output file. The problem with this is that multiple pages could conceivably specify the same output file, and a specific output path would have to be replicated to every datafile (and so on). Instead, using cc 's model, WebMeister will default to outputting an HTML file with the same base name as the original datafile, and in the same directory. Also like cc, it will have some options for explicitly specifying the output file name and path.

As for project management, it seems that make itself offers a decent starting place. There are already conventions in Makefiles for dealing with multi-directory, complex projects. All that's needed to make make "WebMeister aware" is the addition of a WebMeister-to-HTML suffix rule. (Speaking of which, I need to decide on a convention for WebMeister file name extensions. At present, there are two kinds of files---datafiles and templaces---though whether these are really fundamentally different files for not (I suspect they are) remains to be seen. Perhaps ".wmd" for datafiles and ".wmt" for templates.)

In the current model, a datafile's content---and format---depends critically on the template file. For WebMeister to be a coherent system, some further abstraction needs to be put in place. In some sense, I wish each datafile was a row in a table in a relational database. Page generation would then simply be a matter of running through the template until a page-specific replacement is required, then plugging in the appropriate value from the database. Note that this is very template driven (the datafile is just passive data) and not at all like C source. However I think this makes more sense than requiring each datafile to bootstrap the template into place. (Doing the latter does not provide a clean a distinction between content and format---or function and form---in my opinion.)

Back to format... I'd like to make the datafile format clean in the sense that it's easy to specify/detect where a "field" begins and ends. Fields won't necessarily contain HTML, and it may be important that the exact contents of the field be specifiable. It's also useful to be able to name the fields---so that they can occur in any order, or even be missing (in which case the template can have a blank section, or optionally a default replacement). Similarly, template file replacements need to be able to specify the name of the replacement field, its type (maybe), the manner of replacement (whether it needs to be escaped, etc.---these are really just the output flags to OutputStream::Write() in liboutput.a), and other options (default replacement, etc.). Whereas the datafile may look nothing like HTML overall, the template file most likely will. Additionally, the template file might support server-side---or "process-time"---scripting, so that it can be intelligent, not just passive.

The idea of "process-time" scripting open up a whole 'nother can of worms. If this is a sound and feasible idea, it would be useful to make this as much like other "smart HTML" systems as possible. For example, it could take after Microsoft's IIS ".asp" files and use <SCRIPT RUNAT="ProccessTime">...</SCRIPT>. It would also be nice to include options for common existing scripting to be handled as well... so actual ".asp" RUNAT=Server files could be easily pre-processed. Because of this requirement, the replacement tag (currently <*...*>) should be consistent, yet separable from, the replacement tags on existing systems (like ".asp"s <%...%>). In other words (i.e. after some more thought) this means that WebMeister's tags must be distinct from those of existing systems, unless there is a system identical to WebMeister already out there. (And it's okay to be distinct then, as well.) At present, I don't know whether a HTML-ish <*...*> escape, or a SGML-comment-ish <!--*...*--> makes more sense. It's probably safest to use SGML comments---except that might lead to the expectation that a template file should/could be viewed directly. HTML-ish tags put less syntactic trash in the way (and may be easier to parse).

It would also be nice to have some predefined replacement keywords (or a keyword with options for which value/format to use). Things like datafile modification date/time, file process date/time (i.e. "now"), username/id or processor, path to datafile/output file, and other stuff I can think of right now.

Here's an idea for what the template file replacement tags could look like:

<* var="internal variable name" fmt="format" ost="output flags" *>
<* fld="field name" ost="output flags" *>
<* env="environment variable name" ost="output flags" *>
<* cfg="configuration setting name" value="configuration setting" *>

I'm not sure whether this is better or worse (or just different) than a model like HTML <META> tags:

<* TYPE="var" VALUE="internal variable name" OST="output flags" *>
<* TYPE="fld" VALUE="field name" OST="output flags" *>
<* TYPE="env" VALUE="environment variable name" OST="output flags" *>
<* TYPE="cfg" VALUE="configuration setting" *>

I guess it's pretty easy to change, once the underlying functionality is in place. (I could even support both, I suppose.)