Minimalist Online Docmentation

Tips for using MOD

Tips for using MOD

Separate auto-generated files from manually-maintained files

Don't mix MOD output with other HTML files that are maintained by hand. When you're designing your site, try to keep all of the MOD output files in a single tree so that no one accidently edits an automatically generated html file, and then loses their changes the next time mod2html is run. This also allows you to easily delete and recreate your destination tree if you suspect that it contains stale or corrupt files (use the "-a" option to mod2html to recreate the entire destination tree). Keeping things organized is usually as easy as making sure that all images and downloadable files are stored in a separate directory, such as "/images".

Use good file and directory names

Name your files and directories descriptively, using all lowercase and underscores. Use directories to separate categores.

=use_topic_index to keep the index from wrapping

Try to use short file and directory names so that lines don't wrap in the index. If you have long topic and subtopic names (such as in a FAQ), put the =use_topic_index tag at the top of your document to move the topic/subtopic links to an alternate location (such as the top or bottom of the page) specified by the $Topic_Index$ template variable.

The dynamic index_style option in the config file can also be of use if your indexes start to get too large; it allows expandable and collapsable folders, files, and bullets.

How to force mod2html to regenerate files

To have mod2html recreate a single file, use the touch command to update the source file's modification time. mod2html will see that the file has changed and it will recreate it.

To force mod2html to recreate your entire destination tree (such as after you've deleted it), use the "-a" option to mod2html.

You can use the verbose (-v) flag to mod2html to get more information about what it's doing.

Use a separate userid for your destination if you have multiple authors

Handling file permissions in a reasonably secure manner when you have multiple authors can be difficult. Check out the section on permissions for some recommendations.

Use the verbose flag

mod2html is usually pretty quiet. The -v option will produce lots of status and debug information, and can be very helpful if it's not doing what you expect.

How to quickly get a text document into a MOD web site

Let's say you have a text document that's already formatted using spaces, and you don't have the time (or need) to add html and/or mod formatting to it. To get it into your mod site quickly, you can just descriptively rename the file with a .txt extension, and put it in the mod tree.

Mod will index the name of the document as usual, but since it has a .txt extension, it won't do any processing of its content; it will insert it as-is into the html template, surrounded by <pre> </pre> HTML tags to tell the browser to use a non-proportional font and preserve the spacing in the document.

Nedit syntax highlighting for MOD documents

If you use the nedit text editor, a pattern file has been provided with the most recent MOD distributions to add syntax highlighting for MOD source files and templates to nedit. The .pats file is located in the misc/ directory when you expand the MOD tarball. To load nedit with the new patterns, use the command:

% nedit -import MOD-5.1.pats

Now the running nedit program will recognize your MOD source files and templates, and highlight them appropriately (you may need to turn on syntax highlighting under the "Preferences" menu). If you want to save the changes permanently, choose "Save Defaults" under the "Preferences" menu to add the changes to your ~/.nedit file.

Note: as of this writing, there appear to be some versions of nedit that won't accept my patterns. I'll have to work on this.