Well, there are litterally dozens of Python HTML preprocessors out there (see Parnassus or Freshmeat), and I've looked at a good many of them. So how come I've finally decided to write "yet another" ?... Two (main) reasons :

• to code is to learn, and I've got a lot to learn :-)
  All the simple stuff has already been done, so you either start with the hard stuff or duplicate. QED...

• OVERKILL ! A lot of what I saw was way over my head, or way above my needs. Python gurus do tend to be heavy-hitters... friendly, but not always easy to decrypt :-)
  I wanted something simple to solve my simple problem, so I bit the bullet. It may grow into another redundant monster over time, of course, but at least I (think I) know how it works :-)

So if you're in the market for something basic, easy to set up and reasonably documented right now, you might give MMyW a spin...

----- mysite.org ----- src ----- ...
      | mmyw.py   |--- html ----- ...

Note : this is the simplest, hands-off setup. By changing two variables at the top of mmyw.py you can set these directories to whatever values suit you, use absolute paths, etc. You can even make the source and destination identical if you prefer...

So, what do you put under the src tree ? Right now, MMyW understands three types of files :

• .inc (include) files
• .src (source) files
• global.vars (declaration) files

So, what goes into these files ? HTML code mostly, mixed with some mmyw markup described below. The inc files hold boilerplate code and templates, repetitive items that make up most of your pages. The src files hold the original content you type for each page ; one HTML page will be created for each src file, with the same name, by assembling the source, included chunks and variables. global.vars files are more specific, they only contain variable declarations.

So, what is this mmyw markup ? It's a set of HTML-like tag pairs you add into the three families of files above to tell MMyW what needs to be done.. Right now there are also only three tag pairs in the set, with simple effects :

• <mmyw-include>filename</mmyw-include> is replaced by the contents of filename.inc. This file is sought in the same directory as the including file, then in the parent directory, and so on up to the root (src). If no such file is found the tag pair is just deleted. Note : include files can themselves include others.

• <mmyw-set>variablename value</mmyw-set> shockingly creates a variable named variablename (must be a valid Python variable name) and astonishingly gives it the value value (an arbitrary string). If this occurs in a .src or .inc file, the variable is "local" to the resulting page. If it occurs in a global.vars file, the variable is "global" to all files in the same directory, and in directories below. The statement is deleted after evaluation.

• <mmyw-var>variablename</mmyw-var> is replaced by the value of variablename (if it exists, else is just deleted). The variable is first looked up among the "local" page variables, then the "global" variables for the directory, then those one directory up, etc.

So that's all ? Yes, that's all. These simple statements, combined with the "scoping rules" for include files and global variables, are enough to take most of the grunt work out of maintaining a small site like this one, and that was my initial goal.

All you need to know now is what happens in what order when MMyW is run, a few caveats and limitations, and you can try it out yourself.

* MMyW program flow *

• MMyW first walks down the src directory tree, and builds a list of all the .inc files it finds, along with their timestamp (last modified date). It also parses any global.vars it finds, building a list of global variables by directory.

• Next it walks down the source tree again, opening all .src files in turn, doing the following for each file :

• All include directives (tag pairs) are processed, in the order in which they appear in the text (but recursively if include files themselves contain include directives ).

• Once all the include directives have been substituted, a decision is made on "dependencies" and whether or not to output an HTML file. The rules are simple : if no HTML file with the same name as the .src file exists, it is written. If it exists but the .src file is more recent, it is overwritten. Lastly, if any of the .inc files substituted in the previous step is more recent, it is also overwritten. In all other cases, processing stops here for this source file.

• If the HTML file is to be updated, processing continues with the set directives, building a list of "local" variables for the page.

• Lastly, the var directives in the page are processed and replaced with actual values. The completed HTML file is then written to the html tree. On to the next source file...

That's all there is to it. It doesn't look subtle, and it isn't, but somehow it works. There are, however, a few interesting side-effects you should know about before you dive in :

* Caveats, tips 'n tricks, etc. *

• don't nest directives inside each other. Given the primitive tag parser and the processing order above, it either won't work or won't do anything useful...

• careful with include directives in include files ! If spam.src includes foo.inc, and foo.inc includes bar.inc (legal and useful), and bar.inc somehow includes foo.inc (even indirectly)... well, you get the picture. Something inside your computer will give way before that infinite page is created :-)
  I really need to put some sort of safeguard in there somewhere...

• let me emphazise this again : changing global variables (global.vars files) does NOT cause HTML pages to be rewritten ! The only dependencies MMyW knows is timestamps on .src and .inc files. If you need files to be refreshed after a global variable change (say, an e-mail address) you must either resave the specific source files concerned, or launch MMyW with the --force option to regenerate all HTML files in the tree.

• from the link at the top of this page you can download a copy of the actual source tree I use to generate this site at the time of writing. This will give you a good idea of how the three types of files and directives can be used to achieve the desired effect (especially regarding local/global variables and file placement).

• if you do give MMyW a test ride, comments and feedback are appreciated. There is of course a lot of room for improvement, but I would also like to confirm that what little is there, works for others : if you use a different test set than my own sources you might find bugs that escape me... Thanks !

• a note on speed : on my home PC (Pentium Classic 200 Mhz) this script chews through my source tree quite fast -- enough that I can edit a source file in one window, save and launch MMyW from another, and check the results in the browser, all in about the time it takes to Alt-Tab between the three. So you can still experiment with your HTML code in edit/save/reload mode if you want, your creativity will not be unduly stifled by the intermediate build step (just like in Python :-).