Rework man format slightly

README.md

@@ -91,6 +91,8 @@ The harness for shell-based definitions enables two primary toolkits for setting
   - Provide arbitrary additional arguments to pass to `podman run`
   - Apply several prepackaged presets (such as copying a user from the host into the container, or applying security options to fix bind mounts with SELinux)
 
+Once you have a definition, run `tankctl build` to compile it into an OCI image, followed by `tankctl up` to create a container from the image.
+
 Complete details on all commands can be found in the `man` pages bundled with Fishtank. Alternatively, you can view their Markdown versions [here](https://github.com/Colonial-Dev/fishtank/tree/master/doc).
 
 ___
@@ -201,14 +203,36 @@ end
 buildah commit $ctr localhost/(status basename | xargs basename -s .tank)
 ```
 
-The file layout for this particular definition looks something like this:
+The file layout for this particular definition looks similar to this:
+
 ```sh
+# Using symbolic links for "branching builds" like this is one of my pet tricks, but it's not required!
 base.tank # Singular authoritative definition
 p438.tank # Symbolic link to base.tank
 rust.tank # Symbolic link to base.tank
 ```
 
-Using symbolic links for "branching builds" like this is one of my pet tricks, but it's not required!
+While Fishtank may be branded as an "interactive" container manager, it works just as well for containerized services. This definition is all I need for my Jellyfin server, including support for AMD hardware acceleration:
+
+```sh
+#!/usr/bin/env fish
+
+set ctr (buildah from jellyfin/jellyfin:latest)
+
+tankcfg preset bind-fix
+
+tankcfg device /dev/dri/renderD128 
+tankcfg mount type=bind,src=$HOME/Executable/Jellyfin/config,dst=/config
+tankcfg mount type=bind,src=$HOME/Executable/Jellyfin/cache,dst=/cache
+tankcfg mount type=bind,src=$HOME/Videos/DLNA,dst=/media,ro=true
+
+tankcfg args "--net=host" 
+tankcfg args "--group-add=105" 
+tankcfg args "--user=1000:1000"
+
+buildah commit $ctr jellyfin
+```
+
 
 ## FAQ
 
@@ -235,6 +259,14 @@ So:
 - If you don't mind the above caveats and want containerized environments that Just Work with the host, use Toolbx or Distrobox.
 - If you *do* mind the above caveats and/or want some declarative-ness in your containers, give Fishtank a try.
 
+
+### "Why not just use Kubernetes YAML or `compose`?"
+A few reasons:
+
+1. Separating the information on how to *build* the image from information on how to *run* it is lame, especially for Fishtank's target use case of "bespoke interactive containers."
+2. Kubernetes YAML is massively overcomplicated, and the `podman` version of `compose` was somewhat buggy when I tried it.
+3. YAML sucks.
+
 [^1]: Only ~1000 lines of pure Fish shell code.
 
 [^2]: Fishtank was developed on a system that uses GNU Coreutils and GNU `libc` - if you find that Fishtank doesn't work with alternative implementations, please file an issue!

do

@@ -50,6 +50,14 @@ function format
     end
 end
 
+function manual
+    mkdir -p ./doc/man
+
+    for file in (find doc/ -name "*.md")
+        pandoc --standalone --to man --from markdown-smart -o $file man/(basename -s .md $file)
+    end
+end
+
 switch $argv[1]
     case "build"
         build

doc/tankctl-build.md → doc/tankctl-build.1.md

@@ -1,21 +1,36 @@
-# NAME
-```
-tankctl build
-```
+% FISHTANK(1) Version 1.0 | User Manual
+
+NAME
+====
+**tankctl-build** - compile Fishtank-managed container definitions into OCI images.
+
+SYNOPSIS
+========
+
+| **tankctl build** \[**-f**|**--force**\] *container* ...
+| **tankctl build** \[**-h**|**--help**\]
+
+DESCRIPTION
+===========
 
-# DESCRIPTION
 `build` compiles container definitions (either Containerfiles or harnessed `fish` scripts) into ready-to-run container images. 
 
 By default, any new or changed definition will be built, but specific definition names can be passed to only build those definitions.
 
-# SYNOPSIS
-**tankctl build**
+Options
+-------
 
-```
--f/--force: build definitions regardless of whether or not they have changed
-```
+-f, --force
+
+: Specify an existing definition to symlink to rather than creating a new file
+
+-h, --help
+
+:  Displays this manual page.
+
+EXAMPLES
+========
 
-# EXAMPLES
 Build all "out of date" definitions:
 ```
 tankctl build
@@ -34,4 +49,9 @@ tankctl build cpp
 Build only the definition called `cpp`, even if it hasn't changed:
 ```
 tankctl build --force cpp
-```
+```
+
+SEE ALSO
+========
+
+**tankcfg(1)**, **podman(1)**, **buildah(1)**

doc/tankctl-create.md → doc/tankctl-create.1.md

@@ -1,21 +1,36 @@
-# NAME
-```
-tankctl create
-```
+% FISHTANK(1) Version 1.0 | User Manual
+
+NAME
+====
+**tankctl-create** - create a new container definition, or a symbolic link to an existing one.
+
+SYNOPSIS
+========
+
+| **tankctl create** \[**-l**|**--link-to** *definition*\] *name*
+| **tankctl create** \[**-h**|**--help**\]
+
+DESCRIPTION
+===========
 
-# DESCRIPTION
 `create` creates a new file or symbolic link for a container definition in `$XDG_CONFIG_HOME/fishtank/` (typically `$HOME/.config/fishtank/`) and opens it for editing using `$EDITOR`.
 
 All edits are performed in a temporary file; upon saving and exiting, `tankctl` will perform a syntax validity check before writing any changes back to the original file.
 
-# SYNOPSIS
-**tankctl create**
+Options
+-------
 
-```
--l/--link-to: specify an existing definition to symlink to rather than creating a new file
-```
+-l, --link-to *definition*
+
+: Build images even if the definition has not changed.
+
+-h, --help
+
+:  Displays this manual page.
+
+EXAMPLES
+========
 
-# EXAMPLES
 Create a new definition called `cpp`:
 
 ```
@@ -26,4 +41,9 @@ Create a new definition called `cpp` that symlinks to an existing definition cal
 
 ```
 tankctl create --link-to c cpp
-```
+```
+
+SEE ALSO
+========
+
+**tankcfg(1)**, **podman(1)**, **buildah(1)**

doc/tankctl-down.1.md

@@ -0,0 +1,47 @@
+% FISHTANK(1) Version 1.0 | User Manual
+
+NAME
+====
+**tankctl-down** - stop and remove one or more managed containers.
+
+SYNOPSIS
+========
+
+| **tankctl down** \[**-a**|**--all**\] *container* ...
+| **tankctl down** \[**-h**|**--help**\]
+
+DESCRIPTION
+===========
+
+`down` stops and removes containers managed by Fishtank. By default, you must explicitly pass the container(s) you wish to remove; the `-a/--all` flag can be used to override this behavior.
+
+Options
+-------
+
+-l, --link-to *definition*
+
+: Build images even if the definition has not changed.
+
+-h, --help
+
+:  Displays this manual page.
+
+EXAMPLES
+========
+
+Create a new definition called `cpp`:
+
+```
+tankctl create cpp
+```
+
+Create a new definition called `cpp` that symlinks to an existing definition called `c`:
+
+```
+tankctl create --link-to c cpp
+```
+
+SEE ALSO
+========
+
+**tankcfg(1)**, **podman(1)**, **buildah(1)**

doc/tankctl.1.md

@@ -0,0 +1,121 @@
+% FISHTANK(1) Version 1.0 | User Manual
+
+NAME
+====
+**tankctl** - entrypoint for Fishtank, a simple interactive container manager
+
+SYNOPSIS
+========
+
+| **tankctl** \[subcommand\]
+| **tankctl** \[**-h**|**--help**|**-v**|**--version**\]
+
+DESCRIPTION
+===========
+
+Defers to the provided subcommand for managing OCI images and containers. See below for the list of available subcommands; run **man tankctl \[subcommand\]** for detailed individual information.
+
+Options
+-------
+
+-h, --help
+
+:  Displays this manual page.
+
+-v, --version
+
+:  Displays the current version number.
+
+Subcommands
+-----------
+
+build
+
+: Compile Fishtank-managed container definitions into OCI images.
+
+create
+
+: Create a new container definition, or a symbolic link to an existing one.
+
+down
+
+: Stop and remove one or more managed containers.
+
+edit
+
+: Edit an existing container definition using **$EDITOR**.
+
+enter
+
+: Execute **$SHELL** inside a container.
+
+exec
+
+: Execute an arbitrary command inside a container.
+
+list
+
+: List all managed containers and their status.
+
+restart 
+
+: Restart one or more managed containers.
+
+reup
+
+: Remove and re-create one or more managed containers.
+
+start
+
+: Start one or more managed containers.
+
+stop
+
+: Stop one or more managed containers.
+
+up
+
+: Create managed containers from stored images.
+
+GETTING STARTED
+===============
+
+Fishtank requires a definition ("tank") for each container you'd like to create. Definitions can be in two different formats:
+- Standard Container/Dockerfiles - just add `# fishtank containerfile` to the text and you're good to go.
+- `fish` shell scripts that run in a special harness. This injects additional functions and wraps a few others to provide additional functionality not present in Containerfiles, like the ability to declare runtime arguments such as mounts.
+
+Either type must be stored under `$XDG_CONFIG_HOME/fishtank/` (typically `~/.config/fishtank/`) with the file extension `.tank`.
+
+To create and edit a new definition, you can simply run `tankctl create <NAME>`. This will create the file and open it using your `$EDITOR`.
+
+`tankctl edit <NAME>` can be used to alter existing definitions; both commands will use a temporary file for editing and perform syntax checks before finalizing any changes.
+
+Shell-based definitions run in the same directory as the definition, and should look something like this:
+
+```sh
+# Create a new working container.
+set ctr (buildah from fedora-toolbox:latest)
+
+# Set up the new container...
+RUN dnf install gcc
+
+# Commit the configured container as an image.
+buildah commit $ctr toolbox
+```
+
+The harness for shell-based definitions enables two primary toolkits for setting up your container.
+- All Containerfile directives like `RUN` and `ADD` are polyfilled as Fish functions, and generally act the same as their real counterparts. 
+  - (The most notable exception is pipes and redirections in `RUN` - you must wrap them in an `sh -c` to execute them wholly inside the working container.)
+- The `tankcfg` script, which lets you:
+  - Set various build-time (some of which are duplicated from the above) and runtime switches
+  - Provide arbitrary additional arguments to pass to `podman run`
+  - Apply several prepackaged presets (such as copying a user from the host into the container, or applying security options to fix bind mounts with SELinux)
+
+Once you have a definition, run `tankctl build` to compile it into an OCI image, followed by `tankctl up` to create a container from the image.
+
+Complete details on all commands can be found in the `man` pages bundled with Fishtank. Alternatively, you can view their Markdown versions [here](https://github.com/Colonial-Dev/fishtank/tree/master/doc).
+
+SEE ALSO
+========
+
+**tankcfg(1)**, **podman(1)**, **buildah(1)**

src/tankctl/00-help.fish

@@ -15,6 +15,7 @@ Commands:
   down    - stop and remove one or more containers
   edit    - edit a definition
   up      - create and start one or more containers
+  reup    - remove and recreate one or more containers
 
   [ Work with live containers ]
   enter   - execute \$SHELL inside a container

src/tankctl/20-build.fish

@@ -151,5 +151,9 @@ function tankctl_build
         set defs (filter_unchanged $defs)
     end
 
+    if [ (count $defs) -eq 0 ]
+        abort "no valid definitions found - did you make a typo or forget --force?"
+    end
+
     map do_build $defs
 end