Minimalist Online Docmentation

Overview

A template file is basically a plain HTML file with some extra MOD template variables that mod2html will replace with your page's content.

All MOD source trees have a default template, which is usually called ".mod/default.tmpl", located at the root of your source tree (this can be overridden in the config file).

If you would like to specify a different template for a particular page, you can create a template in the same directory with the same name, only with a ".tmpl" extension instead of a ".mod" or ".txt" extension. For example, to give the file "doc/install.mod" a different template than the default one, you would call it "doc/install.tmpl".

Similarly, if you create a template that has the same name as a directory, all files below that directory will use that template instead. For example, to have everything under "doc/books/" use a different template than the default one, I would name the template "doc/books.tmpl".

Format

The template file is just a plain html file. The variables can occur anywhere (with a couple exceptions (bugs) noted below), and will be replaced with the appropriate value. The example at the bottom of the page probably explains things best.

Variables

The template variables start and end with a '$', similar to RCS variables (there are no variable name collisions, in case you're keeping the template under RCS control). The interpreter will replace these with the appropriate value for each html output page. You can use them as many times as you want, although it only makes sense to use most of them once. It's noted if you shouldn't use a particular variable on the same line as other variables.

$Title$

This is replaced with the hierarchical text title for this document. The information is either gleaned from the name and path of the source file, or was overridden using the =title tag. The most common place for this variable is within the <title> HTML tags so that it gets displayed in the browser's titlebar.

$Description$

This is replaced with a full-sentence description of the page, supplied by the =description tag. The most common use for this variable is to generate <meta> HTML tags.

$Keywords$

This variable is replaced with a comma-separated list of all of the values collected from the =keywords tags in the page. The most common use for this variable is to generate <meta> HTML tags.

$Index$

This variable is replaced with the indented html representation of the whole source tree. The current page appears with a special "you are here" icon, and the topics and subtopics for that page are expanded (unless the =use_topic_index tag was specified). The most common use for this variable is to generate a navigation tree on the left-hand side of the screen, usually using tables.

Don't use any other variables on the same line as this one.

$Topic_Index$

If the =use_topic_index tag was specified inside a page, this tells the interpreter that the topic and subtopic names for this page are too large to display in the usual $Index$, and should be displayed as nested unordered lists (which wrap more nicely) in the $Topic_Index$ variable instead.

If the current page specified =use_topic_index, then the topics and subtopics will be displayed by this variable, and not in the normal index. Otherwise, nothing is written for this variable, since the topics and subtopics will be displayed in the normal index.

The most common location for this variable is at the top and/or bottom of the main portion of the page, so that there's room to display the long names.

Don't use any other variables on the same line as this one.

$Body$

This is where the all of the html-ized content from the .mod or .txt file will be inserted.

Don't use any other variables on the same line as this one.

$MOD_Source$

This variable will be replaced with the full path to the source file. For security reasons, you probably don't want to use this variable in any web pages that will be accessible to the internet, since it can give away too much information about your computer's filesystem organization.

$Last_Modified$

This variable is replaced with the last modification time of the source file.

$Next$

$Prev$

These variables are replaced with links to the next and previous documents in the same directory.

Example

Here is a suggestion for a template file. It's more or less the same as the template used for the ECF web pages. The $Index$ is in a left pane, and the $Topic_Index$ (if it's used in a particular page) will have the room it needs at the top of the main pane.

One of the biggest concerns when making a template is making sure that the index will never need to wrap lines. Since the indentation isn't currently created using any sort of block tag (just non-breaking spaces, yuck), it winds up looking pretty bad when the lines wrap. This was one of the reasons for creating the =use_topic_index tag. Since the topic_index is created using unordered lists, it can wrap without negatively affecting the formatting of the page.

The MOD variables appear in bold.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>
<head>
    <title>ECF: $Title$</title>
    <meta name="description" content="$Description$">
    <meta name="keywords" content="$Keywords$">
</head>

<body bgcolor="#FFFFFF">

<table border="0" cellpadding="0" cellspacing="0">
<tr>
  <td valign="top" width=280>
    <A href="http://www.psu.edu"><IMG src="/images/psu.gif" 
    alt="Penn State"></A>
  </td><td valign="top" align="left">
    <A href="http://www.emsei.psu.edu"><IMG src="/images/title.gif" 
    alt="EMS Environment Institute" border="0"></A> 
  </td>
</tr>
</table>

<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
    <!-- Start of link menu column -->
    <td valign="top" width=300>

    $Index$

    </td>
    <!-- End of link menu column -->

    <!-- Start of body column -->
    <td align="left" valign="top">
    <br>

    <!-- Print Topic Index, if any -->
    $Topic_Index$

    $Body$

    </td>
    <!-- End of body column -->
</tr>
</table>

</body>
</html>