Minimalist Online Docmentation

File and directory names

One of the features of MOD is that it is self-indexing; it will discover the structure of your documents, and create a navigation tree for you. This means you don't have to maintain a navigation tree yourself, and you don't have to do anything special to add new files to your site -- just rerun mod2html, and it will find them and update your site appropriately.

Each MOD source file will have a template applied to it, and will result in one finished HTML file. The navigation tree will wind up looking very similar to your source tree, with similar file and directory names and organization.

Since MOD uses the file and directory names of your source tree to create the index of your documents, it makes sense to organize your topics logically in well-named files and directories. As mod2html walks through your source tree generating the navigation index, it will convert underscores in names to spaces, and will capitalize the first letter of each word. This means that you probably want your file and directory names to be all lowercase, with words separated by underscores ("_").

File extensions

The usual file extension for files in the source tree is ".mod". This tells the interpreter that the file contains MOD tags to be indexed and converted to html, and that it should format the document by adding HTML spacing for any blank lines that occur.

If you have files that contain plain formatted text, such as bulleted lists or text graphs, you can have MOD respect the existing formatting by giving them the extension ".txt" instead. The interpreter will still index the page and insert it into the navigation tree, but it won't look for MOD tags or perform any processing on it. When it's inserted into the html template, it will be surrounded by <pre> </pre> HTML tags to tell the browser to use a fixed-width font and preserve the spacing in the document.

Contents of a MOD file

Paragraphs

When you write a normal HTML document, the web browser will ignore blocks of whitespace -- this means that if you separate paragraphs with blank lines, they'll get ignored, and everything will flow together.

To make writing documents a little easier, when mod2html is interpreting your source file, it will replace all consecutive blank lines with <p> HTML tags so that they appear spaced in the finished web page as well (this behavior can be turned off using MOD tags). So as you're writing your documents, just write normal paragraphs with blank lines between each one.

Since this is the only modification that mod2html will make to the plain text of your document, things like indentation will continue to be ignored by your browser. However, you can include as much or as little HTML in your MOD document as you'd like (including things like javascript), and mod2html will pass them along unmodified to the finished page.

Tags

The MOD tags that you'll include in your source files are used by mod2html to figure out the document structure of your file. To get started, you only need to know the two most common tags, =topic and =subtopic. MOD tags start flush with the beginning of the line, and these specific tags are followed by the name of your topic or subtopic. mod2html will convert the tags to html and add the items to the index. Here's an example:

=topic Introduction

This is the text that introduces this topic

=topic First Subtopic 

Here is the text that goes with the subtopic

There are only about eight other mod tags, so it doesn't take long to learn how to use all of mod's functionality. You can learn about the rest of the tags from their page in the reference.

Overview

After you've created some source files, your MOD source tree should start to take on the organization that you have in mind for your finished site. After adding some source files to our sample tree, we might have something that looks like this:

  dog_site/     <--(source directory)
    |
    +-.mod/              <--(this directory and its contents get created by
    |   |                    mod2html the first time you run it. Don't worry about
    |   |                    it for now).
    |   +-config         <--(default config file for this tree)
    |   +-default.tmpl   <--(default template for this tree)
    |
    +-index.mod          <--(contains a =title tag)
    +-dog_breeds/
    |   +-german_shepherd.mod
    |   +-beagle.mod
    |   +-bouvier_des_flanders.mod
    +-dog_training/
        +-index.mod      <--(contains a =title tag)
        +-hunting/
        |   +-overview.mod
        |   +-techniques.mod
        +-recommended_trainers.txt
        +-show/
            +-overview.mod
            +-techniques.mod

It's helpful to have "index.mod" files in directories that will turn into "index.html" files in the destination, so that a URL can be specified with the directory name instead. To override the title given to that page in the navigation index (rather than "Index"), you can add a =title tag to that document that will specify an alternate name to use.