docs and docks

.dockerignore

@@ -0,0 +1,14 @@
+# copied from .gitignore (keep in sync where appropriate)
+
+/target
+*.1
+*.2
+*.3
+*.4
+*.5
+*.6
+*.7
+
+# unique to docker
+
+.git

.github/workflows/lint.yml

@@ -33,3 +33,12 @@ jobs:
         with:
           command: fmt
           args: --all -- --check
+
+  shellcheck:
+    name: shellcheck
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ludeeus/[email protected]
+      with:
+        version: v0.8.0

.gitignore

@@ -1 +1,10 @@
+# keep in sync with .dockerignore where appropriate
+
 /target
+*.1
+*.2
+*.3
+*.4
+*.5
+*.6
+*.7

Brewfile

@@ -0,0 +1,7 @@
+# vim: ft=ruby
+# ^ it's not Ruby, but it's a Ruby-based DSL so we're rolling with it
+
+brew 'rustup'
+brew 'scdoc'
+
+cask 'docker'

Dockerfile

@@ -0,0 +1,32 @@
+FROM rust:1.58.0-alpine AS builder
+WORKDIR /usr/src/
+
+# we don't currently link against openssl, but due to past trauma with sigsev
+# when working with rust in alpine/musl environments, I always throw this in
+#
+# https://users.rust-lang.org/t/sigsegv-with-program-linked-against-openssl-in-an-alpine-container/52172/4
+ENV RUSTFLAGS="-C target-feature=-crt-static"
+
+RUN apk add --no-cache --update alpine-sdk
+
+COPY ./Cargo.toml ./
+COPY ./Cargo.lock ./
+COPY ./src/ ./src/
+RUN cargo install --path .
+
+FROM alpine:3.15 AS documentation
+RUN apk add --no-cache --update scdoc make
+COPY ./Makefile ./
+COPY ./manual/ ./manual/
+RUN make -j$(nproc) doc
+
+FROM alpine:3.15 AS release
+
+RUN apk add --no-cache --update mandoc libgcc
+RUN mkdir -p /usr/share/man/man1 /usr/share/man/man3 /usr/share/man/man5
+COPY --from=builder /usr/local/cargo/bin/seatrial /bin/seatrial
+COPY --from=documentation ./manual/*.1 /usr/share/man/man1/
+COPY --from=documentation ./manual/*.3 /usr/share/man/man3/
+COPY --from=documentation ./manual/*.5 /usr/share/man/man5/
+
+CMD ["seatrial"]

Makefile

@@ -0,0 +1,19 @@
+.POSIX:
+
+.SUFFIXES: .1.scd .1 .3.scd .3 .5.scd .5
+
+# teach make how to build man pages (thanks section 1.11 of
+# http://khmere.com/freebsd_book/html/ch01.html)
+.1.scd.1:
+	scdoc < $< > $@ || (rm -f $@; exit 1)
+.3.scd.3:
+	scdoc < $< > $@ || (rm -f $@; exit 1)
+.5.scd.5:
+	scdoc < $< > $@ || (rm -f $@; exit 1)
+
+.PHONY: clean
+clean:
+	rm -rf manual/*.1 manual/*.3 manual/*.5
+
+doc: manual
+manual: manual/seatrial.1 manual/seatrial.5 manual/seatrial.lua.3

README.md

@@ -18,13 +18,6 @@ indeed, for helping developers make such scale events, Non-Events).
 
 ## Usage
 
-> For further detail and commentary, see `man 1 seatrial`, or
-> `manual/seatrial.1.scd` in the source tree. While you're at it, there's also the
-> following other manual pages, accessible via the same pattern:
->
-> - `seatrial(5)`
-> - `seatrial.lua(3)`
-
 ```
 Usage: seatrial <base_url> <req_situation> [<situations...>] [-m <multiplier>]
 
@@ -41,6 +34,21 @@ Options:
   --help            display usage information
 ```
 
+Further detail, commentary, API documentation, etc. are provided in scdoc
+format in the source repo, and in Unix manual page format in installed copies
+of `seatrial`.
+
+- `seatrial(1)` documents the CLI application itself
+- `seatrial(5)` documents the configuration format
+- `seatrial.lua(3)` documents the Lua API to implement dynamic values and
+  validators
+
+In an installed copy of `seatrial`, including the Docker container, these are
+accessible with `man <section> <name>`, for example `man 3 seatrial.lua` or
+`docker run --rm -it <container tag> man 3 seatrial.lua`. From this source
+tree, provided [scdoc](https://git.sr.ht/~sircmpwn/scdoc) is installed, you can
+instead run, for example, `./read_manual_page 'seatrial.lua(3)'`.
+
 ## Development and Packaging
 
 Minimum Supported Rust Version is 1.58, as specified in `Cargo.toml`.
@@ -55,6 +63,20 @@ The source must pass `rustfmt` and `clippy` without errors. It _should_ also
 pass without warnings, unless there's good reason to leave the warnings in
 place.
 
+MacOS users can use `brew bundle` to install the development dependencies as
+found in `Brewfile` (note that this will install Docker Desktop via its Cask;
+if you've installed Docker Desktop via some other means you may need to either
+uninstall your existing copy, or remove this line from `Brewfile`. Take
+care not to submit a PR with such a change in place!). Linux users should
+install `rustup` and `scdoc` via their distribution package manager. If
+`rustup` isn't available but a Rust of at least the MSRV is, then
+system-wide Rust is fine.
+
+If you've never worked with Rust before and `rustup` is freshly installed,
+you'll need to run `rustup-init` to pull Cargo, the Rust toolchain, etc.
+
+Tangentially to all of this, a `Dockerfile` is provided if preferred.
+
 ## Legal
 
 This is released under the terms of the ISC License:

manual/seatrial.1.scd

@@ -70,8 +70,8 @@ writing, such functionality is not yet concretely planned.
 
 # SEE ALSO
 
-*seatrial(5)*++
-*seatrial.lua(3)*
+- *seatrial(5)*
+- *seatrial.lua(3)*
 
 # AUTHORS