UmbrellixInterface 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.