feat(docs): man pages for gasm and every command, guarded against CLI drift

Assisted-by: GLM 5.3 Flash

justfile

@@ -13,6 +13,10 @@ packages := "./arch/... ./asm/... ./ast/... ./disasm/... ./format/... ./lexer/..
 
 bindir := env_var_or_default("BINDIR", env_var("HOME") / ".local" / "bin")
 
+# Where `install-man` puts the gzip-compressed pages (man1 below it). Exported because
+# the Perl recipes read it from the environment.
+export MANDIR := env_var_or_default("MANDIR", env_var("HOME") / ".local" / "share" / "man")
+
 default:
     @just --list
 
@@ -84,6 +88,37 @@ install: build
 uninstall:
     rm -f "{{bindir}}/{{binary}}"
 
+# Install the man pages under docs/man into mandir/man1, gzip-compressed. Not a gate: a
+# convenience for the person at the keyboard; man finds them through ~/.local/share/man.
+install-man:
+    #!/usr/bin/env perl
+    my $out = $ENV{MANDIR} . q{/man1};
+    system(q{mkdir}, q{-p}, $out) == 0 or die qq{mkdir $out: $!\n};
+    for my $p (glob q{docs/man/*.1}) {
+        open(my $g, q{-|}, q{gzip}, q{-c}, $p) or die qq{gzip $p: $!\n};
+        my $content = do { local $/; <$g> };
+        close($g);
+        my $base = $p;
+        $base =~ s{docs/man/}{};
+        open(my $o, q{>}, qq{$out/$base.gz}) or die qq{write $out/$base.gz: $!\n};
+        print {$o} $content;
+        close($o);
+        print qq{$out/$base.gz\n};
+    }
+
+# Remove the installed man pages.
+uninstall-man:
+    #!/usr/bin/env perl
+    for my $p (glob q{docs/man/*.1}) {
+        my $base = $p;
+        $base =~ s{docs/man/}{};
+        my $f = $ENV{MANDIR} . q{/man1/} . $base . q{.gz};
+        if (-f $f) {
+            unlink($f) or die qq{unlink $f: $!\n};
+            print qq{removed $f\n};
+        }
+    }
+
 # Run the program. The flag is there because `go run` does not stamp the build otherwise.
 run:
     go run -buildvcs=true {{package}}