Dorward's Ramblings

The Dolt

First published on

Updated on

Deprecated

I wrote this tool many years ago, and I does what I needed it to do at the time. The first version was the second useful program I'd ever written — and it shows.

If you are looking for something simple to include common content in your pages, then Dolt might be for you, but I keep this page live mostly for historical interest.

These days I tend to use Template Toolkit, and inject content into it using Perl, but it comes with tpage and ttree which don't require you to do any programming. Ttree supports exciting concepts missing from dolt, such as directories!

Introduction

The dolt is a cross platform HTML preprocessor, it is used to replace specially formatted HTML comments with the contents of another file. This lets you, for example, have the same menu on every page and update it by changing just one file. The dolt gives you the main benefit of frames but without the vast number of problems

The dolt processes files before they are uploaded to a web server. If you can install software on the computer you sit at to write web pages you can use the dolt.

It is only fair to point out that The Dolt is a very primitive tool, it can only cope with a flat directory structure, any files that it is to process must be targeted to be in a single directory, with no subdirectories. Unprocessed files can be placed in subdirectories.

System Requirements

The Visitor

The end user needs a web browser.

The Web server

The web server needs the ability to serve static html pages, this is what web servers are for and all web servers will do this.

Because this message doesn't seem to make it through, I'll repeat: You do not need to be able to run cgi scripts on your server.. Not!

The Author

The dolt is a Perl script, before you can use it you need a (free) Perl interpreter installed on your system. Linux and other *NIX users probably have one installed already. Microsoft Windows users can download a free Perl interpreter from ActiveState.

Getting the Dolt

The dolt is published under the GNU General Public License. You can download it from my github. Rename it from dolt.plx to dolt.pl.

Using the Dolt

Directory Structure

You need separate directories for your source files and generated files. You may find it helpful to keep your include files separate from your HTML source files. This image shows a sample directory structure, each box contains three lines:

  • Purpose of directory
  • Example UNIX path
  • Example Windows path
Diagram of example directory layout [Sorry no text representation possible]

You can find a screenshot of dolt in action (under Windows) below. You should be able to work out how to use it from that if these instructions aren't clear enough. Note that the console window displayed is command.com, not the Perl shell included with ActivePerl.

File Format

The dolt will read through every html (not htm, just html) file in the HTML Source directory, it will create a duplicate of that file in the HTML Output directory, however it will check every line and if it encounters a line that looks like this:

<!--* filename.txt *-->

It will not copy that line, but instead look in the Include Files directory for a file of that name, it will then insert the contents of that file instead of the comment.

So any content you want to appear on multiple pages (such as a menu) should be placed in a separate file in the Include Files directory, and called with <!--* filename.txt *--> on a line by itself. The format of the command is designed to be treated as a comment by any syntax highlighting HTML editors you may use, and therefore not cause errors to be displayed which would vanish upon running the dolt.

Generating your output

Issue the command perl dolt.pl, unless you renamed it, and you will get the following summary of commands:

usage: dolt -s {dir} -i {dir} -o {dir} [-q -l {file}]
options: -s [dir]  : Directory containing HTML source files
         -i [dir]  : Directory containing files to include
         -o [dir]  : Directory to output files to
         -l [file] : Log file to record to (if wanted)
         -q        : Turn quiet mode on (suppress screen output)
         -i and -s may be the same directory

You must use -s to specify the directory containing the HTML files, -i to specify the directory containing the include files (which can be the same as the directory containing the source files), and -o to specify the output location. Optionally you may use -q to turn of messages to the screen, and -l to output messages to a specified log file.

Notes

The majority of people who have problems with dolt, do so because they don't know how to issue the command properly. You need to do it at the command prompt, in Windows this is done by running (Start > Run) either command or cmd (depending on the version of Windows).

Questions? Comments? Bugs? Fixes?

I wanted to make sure this program is bug free and as easy to use as possible but, as mentioned at the top of the page, have abandoned it in favour of much better software. If you have a problem, then I recommend you use template-toolkit instead.