Add manpage + build step

.github/workflows/ci.yml

@@ -12,6 +12,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Install scdoc
+        run: sudo apt-get update -qq && sudo apt-get install -qq -y scdoc
       - name: Build hdi from source
         run: ./build
       - name: Check hdi is up to date

.github/workflows/release.yml

@@ -23,12 +23,11 @@ jobs:
         id: version
         run: echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      # Build a minimal tarball with just the hdi script and LICENSE
       - name: Create minimal tarball
         run: |
           tag="${GITHUB_REF#refs/tags/}"
           mkdir -p "dist/hdi-${tag}"
-          cp hdi LICENSE "dist/hdi-${tag}/"
+          cp hdi LICENSE doc/hdi.1 "dist/hdi-${tag}/"
           tar -czf "dist/hdi-${tag}.tar.gz" -C dist "hdi-${tag}"
 
       - name: Create GitHub release

README.md

@@ -110,8 +110,16 @@ No dependencies, just Bash. Works on macOS and Linux.
 
 ## Development
 
+Install dependencies:
+
+```bash
+brew install scdoc # or: apt-get install scdoc
+```
+
 After editing any file in `src/`, run `./build` to regenerate `hdi`, then commit both. CI will fail if `hdi` is out of date with `src/`.
 
+The build also regenerates the man page (`doc/hdi.1`) from `doc/hdi.1.scd` using [scdoc](https://git.sr.ht/~sircmpwn/scdoc). The scdoc source is maintained by hand; when it needs updating however, a coding agent is well-placed to regenerate it from `src/header.sh` and this README.
+
 A pre-commit hook is included that automatically rebuilds `hdi` when `src/` files are staged. To install it:
 
 ```bash
@@ -123,7 +131,7 @@ git config core.hooksPath .githooks
 Tests use [bats-core](https://github.com/bats-core/bats-core). Linting uses [ShellCheck](https://www.shellcheck.net/).
 
 ```bash
-brew install bats-core shellcheck  # or: apt-get install bats shellcheck
+brew install bats-core shellcheck # or: apt-get install bats shellcheck
 shellcheck hdi
 bats test/hdi.bats
 ```

build

@@ -29,3 +29,7 @@ done
 
 chmod +x "$OUT"
 echo "Built: $OUT ($(wc -l < "$OUT" | tr -d ' ') lines)"
+
+# Regenerate man page
+scdoc < "$SCRIPT_DIR/doc/hdi.1.scd" > "$SCRIPT_DIR/doc/hdi.1"
+echo "Built: $SCRIPT_DIR/doc/hdi.1"

doc/hdi.1

@@ -0,0 +1,195 @@
+.\" Generated by scdoc 1.11.4
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "hdi" "1" "2026-03-23"
+.PP
+.SH NAME
+.PP
+hdi - extract setup, run, and test commands from a project README
+.PP
+.SH SYNOPSIS
+.PP
+\fBhdi\fR [\fImode\fR] [\fIflags\fR] [\fIpath\fR]
+.PP
+.SH DESCRIPTION
+.PP
+hdi ("How do I.\&.\&.\&") scans a project'\&s README and extracts the commands you
+need to install, run, test, or deploy it.\& It presents them as an interactive,
+executable list in the terminal.\&
+.PP
+By default hdi looks for a README in the current directory.\& It recognises
+README.\&md, readme.\&md, Readme.\&md, README.\&MD, README.\&rst, and readme.\&rst.\&
+.PP
+No dependencies, just Bash.\& Works on macOS and Linux.\&
+.PP
+.SH MODES
+.PP
+\fBinstall\fR, \fBsetup\fR, \fBi\fR
+.RS 4
+Show install and setup commands.\&
+.PP
+.RE
+\fBrun\fR, \fBstart\fR, \fBr\fR
+.RS 4
+Show run and start commands.\&
+.PP
+.RE
+\fBtest\fR, \fBt\fR
+.RS 4
+Show test commands.\&
+.PP
+.RE
+\fBdeploy\fR, \fBd\fR
+.RS 4
+Show deploy and release commands.\&
+.PP
+.RE
+\fBall\fR, \fBa\fR
+.RS 4
+Show all matched sections.\&
+.PP
+.RE
+\fBcheck\fR, \fBc\fR
+.RS 4
+Check if required tools referenced in commands are installed.\&
+.PP
+.RE
+When no mode is given, hdi shows install, run, test, and deploy sections
+together.\&
+.PP
+.SH FLAGS
+.PP
+\fB-h\fR, \fB--help\fR
+.RS 4
+Show help and exit.\&
+.PP
+.RE
+\fB-v\fR, \fB--version\fR
+.RS 4
+Show version and exit.\&
+.PP
+.RE
+\fB-f\fR, \fB--full\fR
+.RS 4
+Include surrounding prose, not just commands.\&
+.PP
+.RE
+\fB--raw\fR
+.RS 4
+Plain markdown output with no colour.\& Good for piping.\&
+.PP
+.RE
+\fB--json\fR
+.RS 4
+Structured JSON output including all sections.\&
+.PP
+.RE
+\fB--ni\fR, \fB--no-interactive\fR
+.RS 4
+Print commands without the interactive picker.\&
+.PP
+.RE
+.SH INTERACTIVE CONTROLS
+.PP
+When running in interactive mode (the default in a terminal):
+.PP
+\fBUp\fR/\fBDown\fR or \fBk\fR/\fBj\fR
+.RS 4
+Navigate commands.\&
+.PP
+.RE
+\fBTab\fR/\fBShift+Tab\fR
+.RS 4
+Jump between sections.\&
+.PP
+.RE
+\fBEnter\fR
+.RS 4
+Execute the highlighted command.\&
+.PP
+.RE
+\fBc\fR
+.RS 4
+Copy highlighted command to clipboard.\&
+.PP
+.RE
+\fBq\fR or \fBEsc\fR
+.RS 4
+Quit.\&
+.PP
+.RE
+.SH ENVIRONMENT
+.PP
+\fBNO_COLOR\fR
+.RS 4
+When set to any value, disables colour output.\& See https://no-color.\&org.\&
+.PP
+.RE
+\fBTERM\fR
+.RS 4
+When set to \fIdumb\fR, disables colour output.\&
+.PP
+.RE
+.SH EXIT STATUS
+.PP
+\fB0\fR
+.RS 4
+Success.\&
+.PP
+.RE
+\fB1\fR
+.RS 4
+Error (no README found, no matching sections, unknown argument).\&
+.PP
+.RE
+.SH EXAMPLES
+.PP
+Scan the current directory interactively:
+.PP
+.RS 4
+hdi
+.PP
+.RE
+Show only install commands:
+.PP
+.RS 4
+hdi install
+.PP
+.RE
+Show all commands for a specific project:
+.PP
+.RS 4
+hdi all /path/to/project
+.PP
+.RE
+Copy commands to clipboard:
+.PP
+.RS 4
+hdi --raw | pbcopy
+.PP
+.RE
+Check required tools are installed:
+.PP
+.RS 4
+hdi check
+.PP
+.RE
+Parse a specific markdown file:
+.PP
+.RS 4
+hdi /path/to/file.\&md
+.PP
+.RE
+.SH AUTHORS
+.PP
+Greg Annandale <https://github.\&com/grega>
+.PP
+.SH SEE ALSO
+.PP
+Project: https://github.\&com/grega/hdi
+.PP
+Website: https://hdi.\&gregdev.\&com

doc/hdi.1.scd

@@ -0,0 +1,134 @@
+hdi(1)
+
+# NAME
+
+hdi - extract setup, run, and test commands from a project README
+
+# SYNOPSIS
+
+*hdi* [_mode_] [_flags_] [_path_]
+
+# DESCRIPTION
+
+hdi ("How do I...") scans a project's README and extracts the commands you
+need to install, run, test, or deploy it. It presents them as an interactive,
+executable list in the terminal.
+
+By default hdi looks for a README in the current directory. It recognises
+README.md, readme.md, Readme.md, README.MD, README.rst, and readme.rst.
+
+No dependencies, just Bash. Works on macOS and Linux.
+
+# MODES
+
+*install*, *setup*, *i*
+	Show install and setup commands.
+
+*run*, *start*, *r*
+	Show run and start commands.
+
+*test*, *t*
+	Show test commands.
+
+*deploy*, *d*
+	Show deploy and release commands.
+
+*all*, *a*
+	Show all matched sections.
+
+*check*, *c*
+	Check if required tools referenced in commands are installed.
+
+When no mode is given, hdi shows install, run, test, and deploy sections
+together.
+
+# FLAGS
+
+*-h*, *--help*
+	Show help and exit.
+
+*-v*, *--version*
+	Show version and exit.
+
+*-f*, *--full*
+	Include surrounding prose, not just commands.
+
+*--raw*
+	Plain markdown output with no colour. Good for piping.
+
+*--json*
+	Structured JSON output including all sections.
+
+*--ni*, *--no-interactive*
+	Print commands without the interactive picker.
+
+# INTERACTIVE CONTROLS
+
+When running in interactive mode (the default in a terminal):
+
+*Up*/*Down* or *k*/*j*
+	Navigate commands.
+
+*Tab*/*Shift+Tab*
+	Jump between sections.
+
+*Enter*
+	Execute the highlighted command.
+
+*c*
+	Copy highlighted command to clipboard.
+
+*q* or *Esc*
+	Quit.
+
+# ENVIRONMENT
+
+*NO_COLOR*
+	When set to any value, disables colour output. See https://no-color.org.
+
+*TERM*
+	When set to _dumb_, disables colour output.
+
+# EXIT STATUS
+
+*0*
+	Success.
+
+*1*
+	Error (no README found, no matching sections, unknown argument).
+
+# EXAMPLES
+
+Scan the current directory interactively:
+
+	hdi
+
+Show only install commands:
+
+	hdi install
+
+Show all commands for a specific project:
+
+	hdi all /path/to/project
+
+Copy commands to clipboard:
+
+	hdi --raw | pbcopy
+
+Check required tools are installed:
+
+	hdi check
+
+Parse a specific markdown file:
+
+	hdi /path/to/file.md
+
+# AUTHORS
+
+Greg Annandale <https://github.com/grega>
+
+# SEE ALSO
+
+Project: https://github.com/grega/hdi
+
+Website: https://hdi.gregdev.com

release

@@ -79,7 +79,7 @@ if [[ -x "$SCRIPT_DIR/bench/run" ]]; then
   "$SCRIPT_DIR/bench/chart"
 fi
 
-git add src/header.sh hdi bench/results.csv bench/results.svg site/index.html site/data.js
+git add src/header.sh hdi doc/hdi.1 bench/results.csv bench/results.svg site/index.html site/data.js
 git commit -m "Bump version to $new"
 git tag "$tag"
 git push origin HEAD --tags