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

Assisted-by: GLM 5.3 Flash
2026-09-19 21:18:43 +02:00
parent 708d0a0a5e
commit 93c47a312a
19 changed files with 956 additions and 1 deletions
@@ -0,0 +1,52 @@
+.TH GASM-FMT 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.SH NAME
+gasm-fmt \- canonicalise the formatting of Plan 9 assembly sources
+.SH SYNOPSIS
+.B gasm fmt [\-w|\-l|\-d] [path...]
+.SH DESCRIPTION
+Canonicalise the formatting of Plan 9 assembly sources: indentation,
+operand spacing, per-function mnemonic alignment and blank-line layout
+(exactly one blank line before each label, TEXT and GLOBL block).
+Formatting is idempotent and preserves every line, comments included.
+.PP
+With no paths, or a directory path, every
+.I .s
+file below it is reformatted in place and the changed files are listed,
+the way
+.B go fmt
+does;
+.B .
+and
+.B _
+directories are skipped.  Explicit file paths print to stdout unless
+.B \-w
+is given.
+.PP
+.B \-l
+and
+.B \-d
+rewrite nothing:
+.B \-l
+prints the paths whose formatting differs from gasm's (empty output
+means everything is formatted, which is what a CI check wants),
+.B \-d
+prints the diffs.  They are mutually exclusive.
+.SH OPTIONS
+.TP
+.B \-d
+Print diffs instead of rewriting files.
+.TP
+.B \-l
+List files whose formatting differs from gasm's.
+.TP
+.B \-w
+Write the result to the source file.
+.SH EXAMPLES
+.nf
+gasm fmt                                reformat every .s below here
+gasm fmt \-w kernel_amd64.s              canonicalise one file in place
+gasm fmt \-l *.s                         list files whose formatting differs
+gasm fmt \-d kernel_amd64.s              print a unified diff instead
+.fi
+.SH SEE ALSO
+.BR gasm (1)