Version 1.91
Introduction - Tags - Parameters - Commands - Creating a Site - Release Notes

Maintaining a 100+ page web site based in a MySQL database, with PHP and Apache on the latest Linux based servers is far from easy, but it is straightforward.

However, maintaining a simple static HTML file-based website of only 20 pages is an exercise in opening, pasting, and closing files. Somewhere beyond the 1 page mark, making site-wide changes becomes more pain that it is usually worth, and until now, the only options given to a web developer were to either make the changes and lose hours of useful time, or leave the page with a sub-par design.

Introducing DML, an HTML developement platform tailored towards creating large websites based entirely in static HTML files for use any place where PERL, PHP, and other useful technologies are not available (for example, application documentation, like this file you're reading).

Using a simple templating language, site-wide design elements may be reduced to strings of 8 or less characters for simple page creation. The HTML-style notation is instantly familiar to any experienced web developer, so you'll be up and templating in minutes. The templates may be used to almost completely separate a page's design from its content.

Note that this is free software software licensed under the GNU General Public License (see "COPYING"). (The license has no impact on how you use template files for DML or what you do with files generated by DML).

DML markup tags are very similar to HTML both in visual appearance and function. DML may be considered a set of tags or functions that are parsed from a page. A tag is surrounded by a less-than sign, followed by a beginning parenthesis, then a tag name followed by parameters, ended by an end parenthesis and a greater-than sign. The whole thing looks like this: <(DMLTag)>.

DML tags are the main feature of DML and are very useful in encapsulating repetitive design elements in a single place so that you do not have to edit every single HTML file on your site.

There are a couple hard-coded DML tags which serve some useful (and not so useful) functions.

<(_DMLversion)> returns the version of DML you are using.
<(_DMLhomepage)> returns the homepage of DML (if you want to give me credit on your site =).
<(_DMLdate)> returns the current date (that is, when DML is being executed, not when the page is being viewed) in the format "April 01 2002" (useful for "Last modified: " things).
<(_DMLtime)> returns the current time in the format "01:23:05 PM".
<(_DMLbuildname)> returns the build name of the version of DML you're using. The build name serves no useful purpose, it's really just a clever/catchy little title I came up with, for example, your build name is: Seeing Eye.

A DML tag may receive 3 different types of arguments or parameters: Unnamed, Named, and Tag parameters. Each tag may utilize any or all of these three types of parameters at the same time. It is important to note that DML tags may be placed inside any and all parameters and they will be processed when the page is generated (i.e. they are recursive). Also, if you would like to use a quotation mark inside of the quotation marks required by DML, you must write \" instead. If you want to have a backslash, you must instead write \\ (2 backslashes).

Parameters are accessed in a way similar to calling a DML tag. A parameter is called by making a DML tag with a name beginning with an @ sign followed with the name of the parameter (explained below).

Unnamed parameters look like this: (similar to JavaScript or C++ syntax)

<(aDMLTag("Parameter 0", "Parameter 1"))>

The parameters are enclosed in parentheses. Each parameter is encased in a set of quotation marks and the individual arguments are separated by a comma and a space. You'll notice that, just like most programming languages, the parameters start being numbered from zero. So if there are 3 parameters, the first parameter will be "0" the second will be "1" and the third will be "2"

To access an unnamed parameter, just write <(@0)> where the zero is the number of the parameter.

Named parameters are similar to HTML parameters and look like this:

<(aDMLTag param="true" anotherParam="A named parameter")>

As shown in the code displayed above, a named parameter is made of a parameter name (which may contain no spaces) followed immediately by an equals sign (no spaces!) then the parameter's value enclosed within quotation marks.

To access a named parameter, just write <(@nameOfParameter)> where "nameOfParameter" is the name of the parameter.

Tag parameters require a special definition (more on that later) and yield a mechanism that is very similar to HTML-style enclosure:

<(aDMLTag)>Text which will be in the parameter (which may include newlines)<(/aDMLTag)>

As explained, the text between a tag and an end tag (<(/endTag)> will be passed as a parameter to the DML function/tag (functions and tags mean the same thing as far as DML is concerned.)

To access the parameter (that is, the space between the opening and closing tags) simply type <(@_tag)>

Any and all 3 types of parameters may be used at the same provided that the unnamed parameters are a list inside parentheses immediately after the tag name and then named parameters may optionally follow. (The tag parameter is outside the tag itself, so it is not mentioned here)

DML commands are used for defining tags that will be used, output files, and directing a file to load defined tags from another file. The basic format for a DML command begins at the beginning of a line (tags may occur inside a line, but commands must be located at the beginning of a line). The command begins with @DML followed by a short code that tells DML what command to execute.

Defining a Tag is very simple and consists of a line that has @DMLdef, a space, then the name of the tag. If you want the tag to receive a tag parameter, you must follow the name with a slash (with no space between the name and the slash). Everything on the following lines is considered part of the tag (which may consist of HTML, plain text, DML elements, etc.) until a line that contains only @DMLend is encountered. An example should explain all of this:

@DMLdef aDMLTag/
This tag will receive a tag parameter because of the slash after the tag name. If you do not want this, just don't put a slash after the function name.

The actual parameter will go here: <(@_tag)>

Now everywhere that the DML parser finds <(aDMLTag)> the code written above will be inserted. Note that DML tags may be included in the text that defines a tag, so tags may contain other tags may contain other tags and so on.

Defining output files is also easy enough: inside of a ".dml" file, just add a line beginning with @DMLout followed by the desired output file's filename in quotation marks (this name may contain a path of directories to the desired file, if the directory does not exist, DML will create it for you automatically). Everything starting on the next line until a line that contains only @DMLendout will be output into the file (after DML elements have been parsed, of course). Here's an example:

@DMLout "files/index.html"
The text in here will be output to a file called "index.html" in the directory "files"
And <(bold)>yes<(/bold)>, DML elements will be parsed!

If you plan on outputting the file to a different directory, it is important that you realize that you do not need to adjust relative references for links, images, etc. since DML automatically corrects for this (a very handy feature!)

If you have used DML prior to v1.8, you might have heard of a different way to define an output file using the set command. This is still supported, but is not recommended.

If you have defined tags in an external file, but wish to access them in the current file, simply type @DMLinc followed by a space and then the name of the file in quotation marks. If the specified file contains output file definitions, they will not be written.

It is important to note that a file called "template.dml" (or "default.dmlt" for historical purposes) will automatically be scanned for definitions when DML begins parsing. Also, the second (optional) parameter to the "DMLbuild" program can specify a "template.dml"-like file to load.

Creating a Site
Creating a DML-based web site is a simple affair (that's kind of the idea, after all). When beginning a site, be certain to create the page design as though it were located in the root/base/top-level directory of the site (for images and relative links) so that DML can automatically moves links along with your files. Next, you'll want to create a DML file called "template.dml" which will define most (if not all) of the DML tags you plan to use. This file will automatically be scanned for tag definitions when DML starts parsing.

Store your main template file (probably "template.dml") and all DML files in a "dmlsrc" directory based off of the top-level directory of your website.

To parse a single DML file, use the DOS prompt or command shell to move to your "dmlsrc" directory and type the following command (with the appropriate path to your DMLbuild executable)

DMLbuild file.dml

If you would like to rebuild all of the DML files in your current directory, type this:

DMLbuild all

If you would like to use a different template instead of "template.dml" use a command similar to this:

DMLbuild file.dml template2.dml

Curious as to how a DML-based site should look? Take a glance at the "dmlsrc" directory that came with the DML archive, it generated the file you're currently reading!

Release Notes
      + DML is now licensed under the GNU General Public License (see "COPYING"). The change of license will have no impact on end users that do not want the source code. That is, you can still do whatever you'd like with the DML executables.

      + If you would like to see an example of a DML-based site, take a look at the included "dmlsrc" directory, its the source that this readme's HTML file was built off of!

      + The v1.8 output format (which allows multiple files to generated from a single DML file is the result of a request by FatChuck, thanks!)

      + Even though I have successfully built 4 websites using DML, there may still be some bugs in the program. If you find a bug, be sure to email me with the bug (the code that causes it) and I'll work on fixing it.

      + If you have a complaint or suggestion, please go to Deraj DeZine and contact me. (My email is probably deraj at outgun dot com but you might like to double-check)

Seeing Eye
All content (c)2002 Jared Krinke