Umbrellix Left politics, programming, and self-hosted Internet services: experiences, lessons and hope

Interface of the utility

The main-stream input format of ussg is modified Markdown. The modification is that headers, à la email message headers, are added previous to the markdown text, separated from the Markdown text by two system linefeed (that is, LF on UNIX, and CR,LF on MS-DOS and Windows. Unknown as to what it is on Plan 9) instances. This is inserted as article text. Your Markdown implementation will govern other details. I prefer ‘discount’ de gh:Orc.

The first side-stream input format of ussg is the ussg headers only. These can be stored in a file with an arbitrary name. On UNIX, to “hide” the file from regular viewing in directory listings, it may start with a full stop. This doesn’t bear on how ussg uses it.

Headers in the main-stream override single-use headers of the same name in the first side-stream. The first side-stream is read before the main-stream headers.

The second side-stream input format of ussg is template, tbd.

The third etc. side-stream input formats of ussg is HTML. These are printed verbatim to the output file in their template-appropriate locations, and the recommended template (which also includes some verbatim HTML5) has 4 such positions. These side-stream inputs are pointed to from headers.

A header name is separated from its value by one colon, and exactly one space. The space may be any character, but for readability it should be a space.

The names and purposes of the headers are thus:

Name Type Purpose
Title-Separator Once When guessing the title, this is used with X-Site-Title to esthetically improve the path. If not specified, defaults to ‘::’.
Title Once Set head::title, instead of guessing. If not specified, the title will be guessed. This should be specified per-page so that guessing can occur on pages where ussg-page must be invoked with -N.
X-Site-Title Once Set site title (shown between header nav, and opt sidebar nav)
X-Site-Description Once Set site subtitle
X-Synoptic-Title Once Set meta og:title (synoptic title of the content)
X-Synoptic-Sitename Once Set meta og:site_name (synoptic site name)
X-Synoptic-Text Once Set meta og:description (synoptic description of the content)
X-Synoptic-Image Once Set meta og:image (synoptic image of the content)
X-Synoptic-URL Once Set meta og:url (synoptic URL of the content)
Favicon Once Favicon in vnd.microsoft.icon format
Template Once, Mandatory Template. This defines the basic HTML layout of the
Style inf times CSS style, relative to the webpage
Verbatim n times HTML printed verbatim where the Template requests %n, where n is the number of Verbatim headers
Plugin inf times Load a template command plugin
Url-Prefix Once (Only used by Navbar, but globally defined) Output filenames in the web server will have this prefix, which is not part of their filename on disk. This is mainly to be used for tilde space websites, where you don’t have control to the root domain, where you are specifying links in navbar-type plugins relative to the root of the web server.
Raw-Head inf times Insert the following text at the position of the %heads template command, after synoptics, favicon and style
Navbar-Prefix Once Output filenames as they are being generated will have this prefix, which is not part of the URL. Co-opted from Navbar plugin.

Plugins, which alter the template processing engine, can process headers, but cannot set that a header may only occur once. They must, instead, select the last occurrence of a given header in their processing routine.

The names and purposes of the headers used by the Navbar plugin are thus:

Name Type Purpose
Navbar-Prefix Once Output filenames as they are being generated will have this prefix, which is not part of the URL.
Navbar-Source Once The name of a file, tab separated values, which contains path and label data for the navbar.
Navbar-Title Once Add a title to the navbar. Blatant imitation of werc

The invokation of the utility is thus (program name subject to change):

ussg-page [-hvN] [-HM headers markdown] input [output]

It is meant to be invoked from a makefile, and its output, if on standard output, is supposed to be redirected to a temporary file, then moved atomically over the intended name. This is done automatically if you use a filename output.

All input text should be properly HTML entity encoded, including the article segment after it has been processed by the markdown processor. Failure to do so will result in corruption.