Add a manual page, and explain every setting in plain words

Every setting now carries a paragraph saying what it is in everyday terms
and why someone who does not already speak radio would turn it up, down,
on or off: what the squelch knob actually is, why automatic gain is a bad
idea for scanning, why a bias tee can damage equipment, why setting the
transcription language matters on noisy audio. The menus and
`config --describe` show it alongside the existing technical detail.

packaging/make-man.py generates bandsaunter(1) from that same table, so the
manual cannot document a setting the program lacks or miss one it has --
tests check both, that the page renders through groff without a single
warning, and that the guidance survives into the rendered output. Around
it are hand-written sections on the commands, entering frequencies, the
band plan, lock-outs, the keys during a scan, HF, single sideband, files,
environment variables and worked examples.

The .deb regenerates and installs it rather than shipping a copy, so an
installed manual always matches the installed program.

The README picks up what the last few commits added: the plain display as
a saved setting, what the settings tests now guarantee, and where to read
the manual before installing.

Version is the day's build: 2026-08-22_01.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
The Dust Council 2026-08-22 00:01:00 -07:00
parent 44c98b11e3
commit ba6c925351
8 changed files with 1711 additions and 4 deletions

View file

@ -283,6 +283,8 @@ def setting_help(console: Console, setting: st.Setting,
"", setting.help.capitalize() + "."]
if setting.detail:
body += ["", setting.detail]
if setting.guidance and setting.guidance != setting.detail:
body += ["", f"[grey62]{setting.guidance}[/grey62]"]
body.append("")
body.append(f"[grey62]now:[/grey62] "
f"{st.format_value(setting, getattr(cfg, setting.key))}"