diff options
| author | eudoxia <uplink@distress.network> | 2022-04-25 02:26:06 -0400 |
|---|---|---|
| committer | eudoxia <uplink@distress.network> | 2022-04-25 02:26:06 -0400 |
| commit | 04518819d5916cd4d024b4c6c777d23c75407e60 (patch) | |
| tree | 5e65492c73bfb06e2d12c166c0faa4d85ebe8828 | |
| parent | aa372c0ed6ca775f603a535d8bad70f172751a29 (diff) | |
added license headers
| -rw-r--r-- | data.lp | 9 | ||||
| -rwxr-xr-x | doc/data.html | 12 | ||||
| -rw-r--r-- | doc/freestanding/data.html | 12 | ||||
| -rw-r--r-- | doc/freestanding/log.html | 12 | ||||
| -rw-r--r-- | doc/freestanding/tangle.html | 12 | ||||
| -rw-r--r-- | doc/freestanding/weave.html | 12 | ||||
| -rwxr-xr-x | doc/log.html | 12 | ||||
| -rwxr-xr-x | doc/tangle.html | 12 | ||||
| -rwxr-xr-x | doc/usage.md | 97 | ||||
| -rwxr-xr-x | doc/weave.html | 12 | ||||
| -rwxr-xr-x | gen-docs.sh | 2 | ||||
| -rw-r--r-- | log.lp | 9 | ||||
| -rw-r--r-- | src/data.zig | 5 | ||||
| -rw-r--r-- | src/log.zig | 5 | ||||
| -rw-r--r-- | src/tangle.zig | 5 | ||||
| -rw-r--r-- | src/weave.zig | 5 | ||||
| -rw-r--r-- | tangle.lp | 9 | ||||
| -rw-r--r-- | weave.lp | 9 |
18 files changed, 243 insertions, 8 deletions
@@ -1,6 +1,8 @@ This file contains the various data processing-related constants and functions referenced by the tangling and weaving processes. @: * +@= License + @= Imports @= Processing limits @@ -28,6 +30,13 @@ This file contains the various data processing-related constants and functions r @= Text generation function @. +@: License +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +@. + ## Constants We first import the standard library and the logging function from `log.zig`. diff --git a/doc/data.html b/doc/data.html index 7b5e079..d66a5d9 100755 --- a/doc/data.html +++ b/doc/data.html @@ -21,7 +21,9 @@ <h3 id="section">*:</h3> -<pre><code><span class="lp-ref">(Imports)</span> +<pre><code><span class="lp-ref">(License)</span> + +<span class="lp-ref">(Imports)</span> <span class="lp-ref">(Processing limits)</span> @@ -48,6 +50,14 @@ <span class="lp-ref">(Text generation function)</span> </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <h2 id="constants">Constants</h2> <p>We first import the standard library and the logging function from <code>log.zig</code>.</p> diff --git a/doc/freestanding/data.html b/doc/freestanding/data.html index 5217927..9b029f1 100644 --- a/doc/freestanding/data.html +++ b/doc/freestanding/data.html @@ -33,7 +33,9 @@ ul ul,ol ol {margin: 0;} <h3 id="section">*:</h3> -<pre><code><span class="ref" >(Imports)</span> +<pre><code><span class="ref" >(License)</span> + +<span class="ref" >(Imports)</span> <span class="ref" >(Processing limits)</span> @@ -60,6 +62,14 @@ ul ul,ol ol {margin: 0;} <span class="ref" >(Text generation function)</span> </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <h2 id="constants">Constants</h2> <p>We first import the standard library and the logging function from <code>log.zig</code>.</p> diff --git a/doc/freestanding/log.html b/doc/freestanding/log.html index 61b66b8..f8e2994 100644 --- a/doc/freestanding/log.html +++ b/doc/freestanding/log.html @@ -33,13 +33,23 @@ ul ul,ol ol {margin: 0;} <h3 id="section">*:</h3> -<pre><code><span class="ref" >(Imports)</span> +<pre><code><span class="ref" >(License)</span> + +<span class="ref" >(Imports)</span> <span class="ref" >(Level setting)</span> <span class="ref" >(Logging function)</span> </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <p>We first import the standard library, and the <code>Level</code> type which is an enum representing the possible log levels.</p> <h3 id="imports">Imports:</h3> diff --git a/doc/freestanding/tangle.html b/doc/freestanding/tangle.html index 3be082c..2966ef1 100644 --- a/doc/freestanding/tangle.html +++ b/doc/freestanding/tangle.html @@ -33,7 +33,9 @@ ul ul,ol ol {margin: 0;} <h3 id="section">*:</h3> -<pre><code><span class="ref" >(Imports)</span> +<pre><code><span class="ref" >(License)</span> + +<span class="ref" >(Imports)</span> pub fn main() !u8 { <span class="ref" >(IO initialization)</span> @@ -54,6 +56,14 @@ pub fn main() !u8 { } </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <p>First we import the other files containing the core functions.</p> <h3 id="imports">Imports:</h3> diff --git a/doc/freestanding/weave.html b/doc/freestanding/weave.html index 364d084..73ea3d5 100644 --- a/doc/freestanding/weave.html +++ b/doc/freestanding/weave.html @@ -33,7 +33,9 @@ ul ul,ol ol {margin: 0;} <h3 id="section">*:</h3> -<pre><code><span class="ref" >(Imports)</span> +<pre><code><span class="ref" >(License)</span> + +<span class="ref" >(Imports)</span> pub fn main() !u8 { <span class="ref" >(IO initialization)</span> @@ -52,6 +54,14 @@ pub fn main() !u8 { } </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <p>First we import the other files containing the core functions.</p> <h3 id="imports">Imports:</h3> diff --git a/doc/log.html b/doc/log.html index 89f861a..ea19845 100755 --- a/doc/log.html +++ b/doc/log.html @@ -21,13 +21,23 @@ <h3 id="section">*:</h3> -<pre><code><span class="lp-ref">(Imports)</span> +<pre><code><span class="lp-ref">(License)</span> + +<span class="lp-ref">(Imports)</span> <span class="lp-ref">(Level setting)</span> <span class="lp-ref">(Logging function)</span> </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <p>We first import the standard library, and the <code>Level</code> type which is an enum representing the possible log levels.</p> <h3 id="imports">Imports:</h3> diff --git a/doc/tangle.html b/doc/tangle.html index 3fd4c02..14a834c 100755 --- a/doc/tangle.html +++ b/doc/tangle.html @@ -21,7 +21,9 @@ <h3 id="section">*:</h3> -<pre><code><span class="lp-ref">(Imports)</span> +<pre><code><span class="lp-ref">(License)</span> + +<span class="lp-ref">(Imports)</span> pub fn main() !u8 { <span class="lp-ref">(IO initialization)</span> @@ -42,6 +44,14 @@ pub fn main() !u8 { } </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <p>First we import the other files containing the core functions.</p> <h3 id="imports">Imports:</h3> diff --git a/doc/usage.md b/doc/usage.md new file mode 100755 index 0000000..3a5bd0d --- /dev/null +++ b/doc/usage.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. diff --git a/doc/weave.html b/doc/weave.html index 81ef1d6..2f9c044 100755 --- a/doc/weave.html +++ b/doc/weave.html @@ -21,7 +21,9 @@ <h3 id="section">*:</h3> -<pre><code><span class="lp-ref">(Imports)</span> +<pre><code><span class="lp-ref">(License)</span> + +<span class="lp-ref">(Imports)</span> pub fn main() !u8 { <span class="lp-ref">(IO initialization)</span> @@ -40,6 +42,14 @@ pub fn main() !u8 { } </code></pre> +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +</code></pre> + <p>First we import the other files containing the core functions.</p> <h3 id="imports">Imports:</h3> diff --git a/gen-docs.sh b/gen-docs.sh index ed371ff..6dcd149 100755 --- a/gen-docs.sh +++ b/gen-docs.sh @@ -1,5 +1,7 @@ #!/bin/sh -e +# This script solely generates the formatted code as hosted on the distress.network website. It is thus not intended for actual use by anyone other than the site owner. + tmp=$(mktemp -p /tmp) css="h3,.lp-ref {font-family: neue-haas-grotesk-text, var(--fs-sans); font-size: 1rem; font-weight: normal; font-style: italic;} h3 {margin: 1rem;}" @@ -1,6 +1,8 @@ This file contains a simple logging function. It is a modified version of the example logging function implementation provided in `std.log`. @: * +@= License + @= Imports @= Level setting @@ -8,6 +10,13 @@ This file contains a simple logging function. It is a modified version of the ex @= Logging function @. +@: License +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +@. + We first import the standard library, and the `Level` type which is an enum representing the possible log levels. @: Imports diff --git a/src/data.zig b/src/data.zig index 824d36c..c791daf 100644 --- a/src/data.zig +++ b/src/data.zig @@ -1,3 +1,8 @@ +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. + const std = @import("std"); const log = @import("log.zig").log; diff --git a/src/log.zig b/src/log.zig index 661b97f..0212885 100644 --- a/src/log.zig +++ b/src/log.zig @@ -1,3 +1,8 @@ +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. + const std = @import("std"); const Level = std.log.Level; diff --git a/src/tangle.zig b/src/tangle.zig index 1b967c7..92a2200 100644 --- a/src/tangle.zig +++ b/src/tangle.zig @@ -1,3 +1,8 @@ +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. + const std = @import("std"); const data = @import("data.zig"); const log = @import("log.zig").log; diff --git a/src/weave.zig b/src/weave.zig index 8a1f5c4..de5353c 100644 --- a/src/weave.zig +++ b/src/weave.zig @@ -1,3 +1,8 @@ +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. + const std = @import("std"); const data = @import("data.zig"); const log = @import("log.zig").log; @@ -1,6 +1,8 @@ The structure of this file is quite similar to that of `weave.zig`, only differing in terms of which functions are used to transform the input data. @: * +@= License + @= Imports pub fn main() !u8 { @@ -22,6 +24,13 @@ pub fn main() !u8 { } @. +@: License +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +@. + First we import the other files containing the core functions. @: Imports @@ -1,6 +1,8 @@ The structure of this file is quite similar to that of `tangle.zig`, only differing in terms of which functions are used to transform the input data. @: * +@= License + @= Imports pub fn main() !u8 { @@ -20,6 +22,13 @@ pub fn main() !u8 { } @. +@: License +// Copyright 2022 DistressNetwork° <uplink@distress.network> +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at https://mozilla.org/MPL/2.0/. +@. + First we import the other files containing the core functions. @: Imports |