diff options
| author | eudoxia <uplink@distress.network> | 2022-04-25 01:49:05 -0400 |
|---|---|---|
| committer | eudoxia <uplink@distress.network> | 2022-04-25 01:49:05 -0400 |
| commit | 935837cd569784da2546d140e22713068674baae (patch) | |
| tree | eee0ae28de22e90e91ea4bb73b7b296e5cc637fc | |
| parent | bca585386877d125019b332190d4868c28acff26 (diff) | |
software/literary: main documentation
| -rw-r--r-- | software/literary/index.html | 175 | ||||
| -rwxr-xr-x | software/literary/src.md | 97 |
2 files changed, 272 insertions, 0 deletions
diff --git a/software/literary/index.html b/software/literary/index.html new file mode 100644 index 0000000..4620076 --- /dev/null +++ b/software/literary/index.html @@ -0,0 +1,175 @@ +<!doctype html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<link rel="stylesheet" href="/fonts/fonts.css"> +<link rel="stylesheet" href="/css/main.css"> +<link rel="apple-touch-icon" sizes="180x180" href="/favicon/apple-touch-icon.png"> +<link rel="icon" type="image/png" sizes="32x32" href="/favicon/favicon-32x32.png"> +<link rel="icon" type="image/png" sizes="16x16" href="/favicon/favicon-16x16.png"> +<link rel="manifest" href="/favicon/site.webmanifest"> +<title>Literary — DistressNetwork°</title> +<meta http-equiv="last-modified" content="2022-04-25 01:40:46-04:00" /> +</head> +<body> +<div class="contentlevel"> +<main> +<div class="leading">A lightweight, extensible literate programming tool.</div> +<hr> +<nav class="toc"> +<ul> +<li><a href="#overview">Overview</a> +<ul> +<li><a href="#usage">Usage</a></li> +</ul></li> +<li><a href="#dependencies">Dependencies</a></li> +<li><a href="#file-structure">File Structure</a> +<ul> +<li><a href="#section-commands">Section Commands</a></li> +<li><a href="#configuration-commands">Configuration Commands</a></li> +</ul></li> +<li><a href="#literate-source-code">Literate Source Code</a></li> +<li><a href="#caveats">Caveats</a></li> +<li><a href="#future-work">Future Work</a></li> +</ul> +</nav> +<h1 id="overview">Overview</h1> + +<p>This tool consists of two programs, <code>tangle</code> and <code>weave</code>, both of which accept an input file from stdin and write output to stdout. There are no command-line arguments or other sources of input data. The literate programming interface is language-agnostic with respect to both the source code language and the document formatting language used.</p> + +<h2 id="usage">Usage</h2> + +<p>These programs are intended to be intermediary text processing functions, used as components within build automation routines or shell scripts. The build processes for this tool itself, <code>build.sh</code> and <code>gen_freestanding.sh</code>, serve as example use cases.</p> + +<h1 id="dependencies">Dependencies</h1> + +<p>For compiling the executables:</p> + +<ul> +<li><a href="https://ziglang.org">Zig</a> (0.9.X)</li> +<li><code>binutils</code></li> +</ul> + +<p>For building the (freestanding) documentation:</p> + +<ul> +<li><a href="https://kristaps.bsd.lv/lowdown">lowdown</a></li> +</ul> + +<h1 id="file-structure">File Structure</h1> + +<p>A literate programming file consists of plain text sections, code sections, and output configuration commands. Inclusion of the top-level code section, named <code>*</code>, is mandatory within input to <code>tangle</code>, and certain configuration commands are mandatory within input to <code>weave</code>, described in a later section.</p> + +<h2 id="section-commands">Section Commands</h2> + +<p>Code sections are created as follows:</p> + +<pre><code>@: <section name> +<section content> +@. +</code></pre> + +<p>Source code may also be later appended to previously defined sections:</p> + +<pre><code>@+ <section name> +<additional content> +@. +</code></pre> + +<p>Code sections may contain references to other sections, written as follows:</p> + +<pre><code>@= <section name> +</code></pre> + +<p>References may be prepended by any amount of whitespace, whereas other commands must be placed at the immediate start of the line.</p> + +<h2 id="configuration-commands">Configuration Commands</h2> + +<p>These commands define the format of the code sections and references as they would appear in the output of <code>weave</code>, written as follows:</p> + +<pre><code>@start <str> +@add <str> +@end <str> +@ref <str> +</code></pre> + +<ul> +<li>The <code>@start</code> command defines the format of the start of a new code section. + +<ul> +<li>This configuration is mandatory.</li> +</ul></li> +<li>The <code>@add</code> command defines the format of the start of an appended content section. + +<ul> +<li>This configuration is optional, and defaults to the value given in <code>@start</code> if not supplied.</li> +</ul></li> +<li>The <code>@end</code> command defines the format of the end of a code section. + +<ul> +<li>This configuration is mandatory.</li> +</ul></li> +<li>The <code>@ref</code> command defines the format of a reference to another code section. + +<ul> +<li>This configuration is mandatory.</li> +</ul></li> +</ul> + +<p>The format strings may contain the following control sequences:</p> + +<ul> +<li><code>\n</code>, which represents a newline character,</li> +<li><code>@@</code>, which represents the name of the current section being defined, if it occurs within the format string for <code>@start</code>, <code>@add</code>, or <code>@end</code>, or the name of the section being referenced, if it occurs within the format string for <code>@ref</code>.</li> +</ul> + +<h1 id="literate-source-code">Literate Source Code</h1> + +<p>The source code of this tool is rendered as a set of literate program documents, listed below. Additionally, freestanding versions of these documents exist in the <code>doc/freestanding</code> source directory for offline use.</p> + +<ul> +<li><a href="/software/literary/data.html">data.lp</a></li> +<li><a href="/software/literary/log.html">log.lp</a></li> +<li><a href="/software/literary/tangle.html">tangle.lp</a></li> +<li><a href="/software/literary/weave.html">weave.lp</a></li> +</ul> + +<h1 id="caveats">Caveats</h1> + +<ul> +<li>The text generation routine performed by <code>weave</code> does not verify the correctness of the section commands within the input file; as such, its output upon receiving malformed input should be considered undefined behaviour. It is therefore recommended to pass newly created or modified files into <code>tangle</code> first, which performs the necessary input validation.</li> +<li>The defined control sequences within configuration format strings are not able to be escaped; that is, the literal character sequences “<code>\n</code>” and “<code>@@</code>” are unable to be reproduced within formatted code section commands in the output.</li> +<li>Attempting to use the Texinfo typesetting language in conjunction with this tool results in namespace collisions with multiple command names.</li> +</ul> + +<h1 id="future-work">Future Work</h1> + +<ul> +<li>The treatment of whitespace within formatting and configuration commands is currently rather strict, as no trimming of leading or trailing whitespace around the command contents is applied. This may be changed for the sake of convenience, at the expense of added parsing complexity.</li> +<li>In a document with duplicate section names, references to such sections are resolved to the section with that name which appears first within the document. It may be more useful to have these resolve to the matching section which appears last in the document instead, which would permit some amount of name reuse.</li> +</ul> +</main> +<nav> +<pre> +<a href="/" aria-label="root">·</a> +<span aria-hidden="true">├───</span><a href="/info">info</a> +<span aria-hidden="true">├───</span><a href="/meta">meta</a> +<span aria-hidden="true">│ ├───</span><a href="/meta/sitemap">sitemap</a> +<span aria-hidden="true">│ ├───</span><a href="/meta/styletest">styletest</a> +<span aria-hidden="true">│ └───</span><a href="/meta/todo">todo</a> +<span aria-hidden="true">├───</span><a href="/software">software</a> +<span aria-hidden="true">│ └───</span><a href="/software/web">web</a> +<span aria-hidden="true">├───</span><a href="/visual">visual</a> +<span aria-hidden="true">│ ├───</span><a href="/visual/composite">composite</a> +<span aria-hidden="true">│ └───</span><a href="/visual/logotype">logotype</a> +<span aria-hidden="true">└───</span><a href="/written">written</a> +</pre> +</nav> +</div> +<footer> +<p><a href="/info">About.</a> <a href="mailto:uplink@distress.network">Contact.</a> <a href="/cw.html">Content Warning.</a> <a href="https://git.distress.network">Git.</a> <a href="/meta/sitemap">Sitemap.</a> <a href="https://creativecommons.org/licenses/by-sa/4.0">CC BY-SA 4.0.</a></p> +<img src="/media/distressnetwork-w.svg" alt=""> +</footer> +</body> +</html> diff --git a/software/literary/src.md b/software/literary/src.md new file mode 100755 index 0000000..3a5bd0d --- /dev/null +++ b/software/literary/src.md @@ -0,0 +1,97 @@ +title: Literary +leading: A lightweight, extensible literate programming tool. +opts: ch + +# Overview + +This tool consists of two programs, `tangle` and `weave`, both of which accept an input file from stdin and write output to stdout. There are no command-line arguments or other sources of input data. The literate programming interface is language-agnostic with respect to both the source code language and the document formatting language used. + +## Usage + +These programs are intended to be intermediary text processing functions, used as components within build automation routines or shell scripts. The build processes for this tool itself, `build.sh` and `gen_freestanding.sh`, serve as example use cases. + +# Dependencies + +For compiling the executables: + +- [Zig](https://ziglang.org) (0.9.X) +- `binutils` + +For building the (freestanding) documentation: + +- [lowdown](https://kristaps.bsd.lv/lowdown) + +# File Structure + +A literate programming file consists of plain text sections, code sections, and output configuration commands. Inclusion of the top-level code section, named `*`, is mandatory within input to `tangle`, and certain configuration commands are mandatory within input to `weave`, described in a later section. + +## Section Commands + +Code sections are created as follows: + +``` +@: <section name> +<section content> +@. +``` + +Source code may also be later appended to previously defined sections: + +``` +@+ <section name> +<additional content> +@. +``` + +Code sections may contain references to other sections, written as follows: + +``` +@= <section name> +``` + +References may be prepended by any amount of whitespace, whereas other commands must be placed at the immediate start of the line. + +## Configuration Commands + +These commands define the format of the code sections and references as they would appear in the output of `weave`, written as follows: + +``` +@start <str> +@add <str> +@end <str> +@ref <str> +``` + +- The `@start` command defines the format of the start of a new code section. + - This configuration is mandatory. +- The `@add` command defines the format of the start of an appended content section. + - This configuration is optional, and defaults to the value given in `@start` if not supplied. +- The `@end` command defines the format of the end of a code section. + - This configuration is mandatory. +- The `@ref` command defines the format of a reference to another code section. + - This configuration is mandatory. + +The format strings may contain the following control sequences: + +- `\n`, which represents a newline character, +- `@@`, which represents the name of the current section being defined, if it occurs within the format string for `@start`, `@add`, or `@end`, or the name of the section being referenced, if it occurs within the format string for `@ref`. + +# Literate Source Code + +The source code of this tool is rendered as a set of literate program documents, listed below. Additionally, freestanding versions of these documents exist in the `doc/freestanding` source directory for offline use. + +- [data.lp](/software/literary/data.html) +- [log.lp](/software/literary/log.html) +- [tangle.lp](/software/literary/tangle.html) +- [weave.lp](/software/literary/weave.html) + +# Caveats + +- The text generation routine performed by `weave` does not verify the correctness of the section commands within the input file; as such, its output upon receiving malformed input should be considered undefined behaviour. It is therefore recommended to pass newly created or modified files into `tangle` first, which performs the necessary input validation. +- The defined control sequences within configuration format strings are not able to be escaped; that is, the literal character sequences "`\n`" and "`@@`" are unable to be reproduced within formatted code section commands in the output. +- Attempting to use the Texinfo typesetting language in conjunction with this tool results in namespace collisions with multiple command names. + +# Future Work + +- The treatment of whitespace within formatting and configuration commands is currently rather strict, as no trimming of leading or trailing whitespace around the command contents is applied. This may be changed for the sake of convenience, at the expense of added parsing complexity. +- In a document with duplicate section names, references to such sections are resolved to the section with that name which appears first within the document. It may be more useful to have these resolve to the matching section which appears last in the document instead, which would permit some amount of name reuse. |