# gloss

a glossary-style wiki program. with a formatting language like markdown but worse.

it is designed to maximize nonlinear browsing.

***

the central gloss.py script translates each .gls file in its input directory to a .html in its output.
to run it, you will need a python runtime and a C compiler. make sure to download the entire repo.

.gls files are composed of a names section, a set of blocks, and an optional "see also" section.

the names section consists of the first non-empty non-comment lines in a file.
each line becomes a name for the file.
a file's names are automatically turned into links,
the first time it is referenced in another document.
matching is performed at word boundaries: a file with name "foo" will not be linked from "foobar".
the names section is terminated with a blank line.

blocks can be either paragraph blocks or quote blocks, and they are terminated by blank lines.
a block is a quote block if its first line begins with a '>'.
to begin a paragraph block with '>', escape it with a backslash.

if any line in a block begins with ~, it will become the block's metadata.
only quotes have metadata, for authorship info.
the format is thus: `<source> @@ <time> // <url>`.
if `@@` is omitted, the signature will have no time associated.
if `//` is omitted, the signature will have no URL associated.

within a block, one can write a link of the form `<https://example.com>`, or `<https://example.com|example page>`.
one can also escape `<` and `>` with backslashes. regions of text can be italicized by putting them `/in slashes/`.

if a block begins with `***`, the "see also" section is entered.
each subsequent non-empty line should be the slug (filename, minus .gls) of an article.
it will be linked in a "see also" list at the bottom.

if a template.html is present in the source directory, it will be the template for all rendered pages.
run gloss.py with no arguments for more information.