Under the hood

Like git, USSM is a collection of command line utilities. That way, you don’t have to learn Ocaml if you want to enhance or extend USSM.

general principles

Every ussm-utility assumes that the current directory is a USSM web site. Meaning, _ussm/ exists and is a directory. The only exception is ussm-init, which populates the current directory to make a web site.

If you call a utility from the _/ussm/ussm script by using the main ussm command, you don’t have to worry about that: ussm will temporarily change the current directory to the right one.

Modules

The modules are directly responsible for the creation of intermediate files in the _ussm/tmp directory. As a general rule, a ussm-foo module will generate a _ussm/tmp/bar.foo for each bar.txt source file. So, The ussm-core module will generate .core files, the ussm-menu module will produce .menu files, and so on.

The content of the temporary file depends on each module. For each source file:

• ussm-core extracts the main content and convert it to HTML.
• ussm-title extracts the title header.
• ussm-description extracts the description header.
• ussm-menu generates a hierarchical menu, which help navigation.

Utilities

Most utilities are UNIX filters. Originally, they helped me build the other programs (like the modules). They should help you as well if you want to modify USSM.

Here is quick summary. Report to the source code for the details (I promise you, it is rather well documented).

• ussm-heading extracts a header from the standard input (or from a file) and prints it to the standard output. It takes one or two arguments.

• ussm-setting extracts a header from the _ussm/settings configuration file. (It calls ussm-heading internally).

• ussm-remove-boring reads a newline separated list of file names from the standard input, and prints that same list on the standard output, without files considered “boring”. Its behaviour depends on the boring parameter in the _ussm/settings configuration file.

• ussm-source-dirs prints a newline separated list of all directories that contains a source file. I use it in the main script to copy the directory structure in _ussm/tmp/ and _ussm/www/.

• ussm-source-files prints a newline separated list of all source files in the current USSM directory. Modules typically loop over this list.

• ussm-strip-header prints the content of a given file to the standard output, except without its header. Useful to write modules which act on the content of a source file, but not on its header.

Others

Those two programs, I couldn’t fit them in a neat category.

• ussm-init populates the current directory with the necessary files to make a USSM web site. It creates the _ussm/ directory, and a set of files that act as an example. You can call ussm immediately after to see the result.

• ussm-assemble generate the final web pages by assembling the necessary module files. The way it assemble them is specified by the _ussm/skin.html template file.