WebMake
WebMake Documentation (version 2.2)

Concepts

Here's a list of the main concepts behind WebMake's design and implementation. Before using WebMake, it'll probably help to have a read of this, so you can understand where the functionality is coming from.

1. Templating

When you start working with the web, it's easy enough to write a few pages and put them on your site. However, you quickly realise that they all look different; there's nothing binding them together as one "site".

The next step is to add some common elements to tie the pages together, so you add some header text or graphics, and maybe a table on one side listing the other pages in the site, allowing your users to quickly find the other pages. Maybe you add some information at the bottom of the page, describing who you are, that kind of thing.

After a while, you'll have quite a few pages, each with a different piece of main content, but a lot of them sharing some, or all, of the shared elements -- the templates.

One day, you need to change the templates -- but there's no easy way to do this, without manually editing each of the files and changing them by hand. Wouldn't it be easier to just change this once, and be done with it?

That's one of the main features of WebMake: templating. It allows you to define the templates in one place, then generate pages containing the content wrapped in those templates.

There's quite a few products that do this; WebMake differs in that it's very flexible in how you can include your content text in the templates. Often, other products are limited to just setting a header and a footer to be added to each page; WebMake takes its cues from traditional UNIX tools by allowing very deep recursion in its templating, so your templates can include other templates, etc. etc.

2. Edit Text As Text, Not HTML

In some situations, you'll want to write HTML; but in others, text is best, for ease of editing, and reading while you're editing. WebMake supports Text::EtText and POD formats, converting them to HTML on-the-fly.

Text::EtText aims to support most of the de-facto conventions we've been using in mail and in USENET for years, converting them into HTML in a sensible way.

3. Breaking Down the File-Per-Page Mapping

Another annoyance comes from the default way a web servers serves web pages; normally, each web page is loaded from a separate file.

This is fine for some sites, but in other circumstances you might want to produce lots of small pages, or include identical text in several pages; or you may just prefer editing your entire site in one editor, rather than having to switch from one window to another.

WebMake allows you to specify several content items inside a single WebMake .wmk file (the .wmk file uses WebMake's XML-based file format), and/or load content from a data source, such as a comma-separated values file, a directory tree, or (possibly in future) an SQL database.

You can then include these content items into the generated web pages, whichever way you wish, based on the outputs and templates you specify in the WebMake file.

4. Support URL Changes

At some stage, you may feel like rearranging your site, changing one URL that's always bothered you, so that it becomes more aesthetically pleasing or descriptive. Or maybe some directive might suddenly appear, ordering you to do so for policy reasons (ugh). Whatever!

WebMake allows you to track output pages or media, such as images, or non-WebMake generated pages, using URL references; references to the name will be converted to the correct URL for that page or image.

5. Site Mapping and Indices

The obvious next step is to allow site maps, indexes, and navigational information to be generated automatically.

WebMake accomplishes this using metadata; in other words, if you tag your content items with information like its title, its "parent" content item, and its precedence compared to its neighbours (to specify the order of items), WebMake can automatically use this information to generate the following maps:

6. HTML Cleaning

Often, the HTML you'll have to work with may be crufty, with img tags that have no size information, or other inefficiencies.

WebMake includes a HTML cleaner which will rewrite your HTML until it sparkles. It can also be turned off for a "HTML verite" effect, if you feel so inclined. (Alright, it's also a little faster with the cleaner off. Not much though ;)

7. Plugins, User-Defined Tags And Perl Code

You can define your own tags, similar to how JSPs support taglibs; this provides a way to add scripted components to your pages, without making things too messy or confusing, or arbitrarily peppering code into the text.

Or, if you like peppering code into your text, WebMake provides support for Perl code embedded directly into the text or WebMake file, similar to PHP, ePerl, HTML::Mason, or ASPs. It also provides an API for that code to examine or alter WebMake's behaviour.

There's a plugin architecture as well, providing an easy way to load code on demand from self-contained components.

8. The Web Is "Read-Mostly": Bake, Don't Fry

Several other similar web site management systems revolve around dynamic code running on the web server, which assembles the pages as they're requested by the client. In the terminology used by Ian Kallen of Salon.Com, they "fry" the pages on-demand.

For most sites, the pages do not change based on which client is accessing them, or if they do, they don't change entirely; perhaps an extra set of links becomes available in the page footer allowing a logged-in user to make modifications using CGI, or PHP or Perl code, but that would be it. The page just isn't volatile enough to require continual re-generation for each request.

As a result, all this churning about, generating pages on the fly from its raw components each time, is wasted; it just eats the server's CPU and memory for no real gain, and introduces yet another breakage point (databases, memory usage, the /. effect...) where things can go wrong, just when you're not looking at it.

WebMake takes the "baking" approach, generating virtually all its output before the web server gets involved. The web site admin runs the webmake command, and this generates the pages.

Note that WebMake doesn't preclude dynamic content in the pages, however. PHP, CGI, ASP or embedded Perl code can be used, and WebMake will not interfere. In fact, a future version of WebMake will probably provide some "fried" features of its own...

9. Site Replication

You can replicate web sites quickly, easily, and securely over the internet. WebMake does this using CVS and SSH, two standard UNIX utilities that have been used for years to do exactly the same thing for other types of data; why not web sites?

A bonus of using CVS is that you also get seamless version control and conflict management, so users can edit a WebMake site at any replicated point, check in the changes, and it won't overwrite everyone else's modifications.

10. Edit-In-Browser

The WebMake distribution includes a CGI script which provides a simple interface allowing a WebMake site to be edited over the web, and the changes to be checked in to CVS. At the moment, it's not too user-friendly, so it's not quite suitable for a newbie to use without some instruction -- but it's getting there, and it'll improve.

It's certainly handy for an experienced user who wishes to correct a typo or add a new page to their site, without requiring command-line access to the server; so if you check out your site in an internet cafe and spot a typo, you can immediately fix it without downloading an SSH client! ;)

WebMake Documentation (version 2.2)
Built With WebMake