Minimalist Online Docmentation

Rules for using MOD tags

A tag must be the first thing to appear on the line; there can't be any leading whitespace.
The tagged line is only processed up to a newline, e.g. you can't split topic names across lines.
If the tag requires text (such as =topic or =description), the text must be separated from the tag by at least one tab or space.
Don't use any html tags inside any tag lines.

Valid tags

These are the tags that the interpreter recognizes.

=subtopic

Usage:
=topic Topic Name
=subtopic Subtopic Name

The =topic and =subtopic tags form the core of the mod functionality. Use these tags to organize your documents. When the interpreter processes the source files, it will look for these tags to learn about the structure of the document and generate an index for it. The tagged lines will be replaced with the appropriate html to make them appear correctly in the browser.

The =topic or =subtopic tag should be followed by the title to be associated with that section. Do not include any html in this text, it will have undesired effects.

The interpreter will create "<a name=" links for each of your topics and subtopics. To make it a valid and predictable link, it will convert all letters to lowercase, and all spaces and punctuation to underscores.

If you need more subtopic levels, you can append a number to the =subtopic tag, such as =subtopic2, =subtopic3, up to =subtopic5. =subtopic1 is recognized, and is considered to be the same as =subtopic.

A topic/subtopic specification remains in effect until another one is encountered or the end of the document is reached.

=ignore

=end_ignore

Usage:
=ignore
    Some text and tags that shouldn't be processed
=end_ignore

Any tags that occur between =ignore and =end_ignore won't be processed. Note that whitespace formatting (controlled by the =no_format and format tags) will not be affected by these tags.

You can have as many =ignore =end_ignore blocks as you'd like. Don't nest or overlap them, though.

=no_format

=format

Usage:
=no_format
=format

By default, the processor will replace one or more consecutive blank lines with a <p> html tag to make docmuent creation easier. If you are starting out with valid html files that already have <p> tags or if you're a control freak, this may not be what you want. You can toggle this feature off and on using the =no_format and =format tags.

If you're using <pre> blocks in your pages, you probably want to turn off formatting so that you don't get <p> symbols in the middle, which can confuse some browsers.

They take effect from their first appearance in the document, and will remain in effect for the rest of the document, or until the opposite tag is encountered which toggles the action again.

=title

Usage:
=title Document Title

Ordinarily, mod2html will decide on the document title based on the filename. It will convert any underscores to spaces, and capitalize the first letter of each word, if it isn't already.

You can use the =title tag to override this behavior and specify the exact title by hand. This is useful for when you want or need to have index.html files, which wouldn't be very informative as a title. Naturally, there should only be one =title tag per file. The logical place for it is at the top of the file, although this is not required.

Be aware that in all cases, the processor will also prepend the names of the higher level directories to give a sense of position within the hierarchy.

=description

Usage:
=description Short description of the contents of the current page.

Use this tag to specify a general description of the current page. Depending on your template, this description will not visibly appear on the page, but will be used to create <meta> tags, which are used by search engines to index information about your site.

There should only be one =description tag per file. Remember that tag processing stops at a newline, so your description should only consist of one line.

=keywords

Usage:
=keywords List, of, comma-separated keywords, and, short phrases

Use this tag to specify keywords that can be used by search engines to index your document. Like the =description tag and depending on the template for the given page, this content may not visibly appear in your browser, but it will appear in the html <meta> tags.

For the sake of organization and maintenance, you can specify the =keywords tag as many times as you'd like in your document. This allows you to put the tags in close proximity to the subject matter. The processor will collect all of them and separate them with commas to generate the <meta> tags.

=use_topic_index

Usage:
=use_topic_index

Sometimes you'll have a document that has lots of long topic and subtopic names which start to wrap in the index pane, making the index unreadable (such as a FAQ). The =use_topic_index tag tells the MOD interpreter not to expand the topics and subtopics for this page in the regular $Index$ variable, but to put them in an unordered list to be expanaded in the $Topic_Index$ variable. This will allow you to put them in a different location that can accomodate long link names and wrapping.

The =use_topic_index tag should only appear once in a document. It can appear anywhere in the document, but putting it at the top of the file probably makes the most sense.

=me_first

=me_last

Usage:
=me_first
=me_last

Since MOD uses the file and directory layout to determine the index contents, there isn't really any way to control the order in which documents appear in the index beyond their default alphabetical ordering. For the most part, this doesn't seem to be a problem. Sometimes, though, it's nice to be able to specify that a particular document should be listed before or after the other ones in the same directory, such as an introduction, or a set of references.

The =me_first and =me_last tags let you specify that a particular document should appear before or after the rest of the documents in that directory. Naturally, it should only appear once a single document, and it probably should only appear in one document in a particular directory. If a =me_first (or =me_last) tag appears in more than one document in a directory, those documents will appear before (or after) the others, but exactly which document will come first is undefined.