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
Makefile s 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.)
|