Documentation file structure

The content management system, or CMS, converts human-written documentation (text files) into machine-displayable documentation (XHTML and CSS). This is managed by a short Python script and makefile.

In the documentation root, there is a makefile and some directories:

articles/
bin/
lit/
makefile
omit/
site/

In a nutshell, articles/ and lit/ are documentation inputs, and site/ is the output tree that gets uploaded to an HTTPS server.

Files and directories in lit/ are hardlinked into site/ by the CMS. These include fonts, graphics, CSS, icons, and whatever else.

Files and directories in articles/ are converted from a lightweight markup language into HTML before writing into site/.

Menu definition

A plain text file at articles/menu has three purposes.

1. It describes the contents of the two-level menu on in the left column.

2. It indicates where, within articles/, contents reside in the filesystem.

3. It indicate the order of the menu items.

Were it not for the need to arrange menu items in a sensible order, there wouldn’t be any need for menu, because a filesystem walk would have sufficed. Although schemes exist for indicating order within filenames (such as used in init scripts), they are too cumbersome to use here.

Here is a sample menu file, followed by some explanation.

Architecture
    Overview of documentation
    Terminology
    Download
Assemblers
    Old assembler
    Cross assembler
    Self-hosted assembler

This indicates there are two topic directories, Architecture/ and Assemblers/, within articles. These directories must exist, or the CMS will abort. If the topics contain characters other than alphanumeric, hyphen, or period, those other characters will be replaced with underscores when forming directory names. Any trailing underscores are removed. These two topic directories contain a mandatory file index.html, which is not actually HTML but is markup that will be converted into HTML and written to index.html under those directories. This is the content that will be displayed when a topic is navigated to instead of an article underneath a topic. The CMS relies on the HTTPS server checking for and serving index.html when presented with a directory URL.

Beneath the menu topics and within the topic directories are article files. These are also written in markup, and become XHTML files of approximately the same name in the output. There is no file extension in the URLs or within the filesystem, so the CMS relies on either the HTTPS server to be configured with a default Content-Type: text/html response (preferred), or the visiting browser can do content type sniffing, which may not work for all visitors.

Thus for the above menu example, the corresponding files and folders under both articles/ and site/ will be these:

Architecture
Architecture/index.html
Architecture/Download
Architecture/Overview_of_documentation
Architecture/What_is_Dauug_36
Assemblers
Assemblers/index.html
Assemblers/Cross_assembler
Assemblers/Old_assembler
Assemblers/Self-hosted_assembler

Because the contents of site/ are machine-generated, it can be treated as a cache directory; i.e., site/ does not need to be backed up. Moreover, any edits you make within site/ will be lost the next time the CMS is run. Lastly, the static files in lit/ are not copied to site/, but only hardlinked, so if you edit them within site/, the changes will persist forever, because the originals are changed.

Note that the CMS does not create any files or directories outside of site/. The documentation writer gets that honor.

Unadvertised material

In articles/menu, a topic or article name may be preceded by an asterisk (*) to denote it’s a work-in-progress that is not being advertised yet. Here’s a hypothetical example:

Architecture
    Overview of documentation
    Terminology
    *Download
*Assemblers
    Old assembler
    Cross assembler
    Self-hosted assembler

Above, the topic Assemblers has been starred. This removes the Assemblers topic and all articles under it from menus that are visible from non-starred topics and articles. For example, if you’re visiting Terminology, you won’t see the Assemblers category in the menu at all. You also won’t see the Download article, because that is also marked as a work-in-progress.

Despite generally not appearing in menus, work-in-progress items are generated and accessible via the website. If a visitor happens to navigate to a non-menu topic or article, two things happen. First, that topic or article displays as normal. Second, the menu as viewed from that “hidden” topic or article has all items visible! This lets a documentation maintainer quickly navigate among the hidden and non-hidden material, as well as check for differences between the public and not-so-public menu versions.

A subtle type change is made between the starred and non-starred items in the menu display, so that a maintainer can easily assess whether an item is or is not publicly visible.

What’s in the `omit/` directory?

The omit/ directory is a place where a documentation maintainer can keep files she needs to do her job, but does not need to convert or upload to the HTTPS server.

Fonts

The CMS is regrettably heavy on font files (nearly a megabyte), because this documentation also serves a marketing function. Moreover, I haven’t taken any time to subset the font files as I might.

Scripts