Man pages, and --help for all three binaries #15

New issue

Open

opened 2026-08-19 23:57:40 +00:00 by dusan · 0 comments

dusan commented

2026-08-19 23:57:40 +00:00

Owner

Context

Three binaries are installed (meson.build, and build-aux/terminalko.spec):

Binary	Options today
`terminalko`	none — no command line handling at all
`terminalko-agent`	`--idle-timeout SECONDS` (`crates/terminalko-agent/src/main.rs`)
`terminalkoctl`	`list`, `start`, `stop`, `signal`, `--help` (`crates/terminalko-ctl/src/main.rs`)

There are no man pages. terminalkoctl --help prints usage; the others print
nothing useful.

The behaviour that a man page would describe is already written down, in
docs/spec/command-line.md and docs/spec/session-agent.md — including the
environment variables (TK_AGENT_PATH, TK_RUNTIME_DIR), the socket path, and
what the exit status means.

Work

Write pages in scdoc (small, readable, one dependency) or asciidoc — pick
one and put the reason in the commit. Three pages:
- terminalko(1) — what it is, that it starts an agent on demand, the
  keyboard shortcuts (the list already exists in
  crates/terminalko/src/shortcuts.rs), where the configuration lives, and a
  SEE ALSO to the other two;
- terminalko-agent(1) — what it does and why it exists, --idle-timeout,
  the socket and lock paths, TK_RUNTIME_DIR, the environment it strips from
  sessions, and that sessions do not survive logout without
  loginctl enable-linger;
- terminalkoctl(1) — the commands, how a session may be named, what list
  prints, and that a non-zero exit means the reason was printed.
Install them with meson (install_man), and add them to %files in the rpm
spec — rpmbuild will fail if a listed file is missing, which is a useful
check.
Add --help and --version to terminalko and terminalko-agent; a man page
for a binary that cannot describe itself is half a job. terminalko currently
parses no arguments at all, so this also decides what it should do with any:
at minimum refuse unknown ones rather than ignore them.

Acceptance criteria

man terminalko, man terminalko-agent and man terminalkoctl work from an
installed build.
Each page's options match what the binary accepts — check by running each
documented option.
--help and --version work for all three binaries.
The rpm builds with the pages in %files.
No documentation is duplicated: where the specs already say something, the man
page can be brief and point at the installed docs rather than restating them.

Notes

Keep them short. A terminal emulator's man page nobody reads is worse than a
short one somebody does.

## Context Three binaries are installed (`meson.build`, and `build-aux/terminalko.spec`): | Binary | Options today | |---|---| | `terminalko` | none — no command line handling at all | | `terminalko-agent` | `--idle-timeout SECONDS` (`crates/terminalko-agent/src/main.rs`) | | `terminalkoctl` | `list`, `start`, `stop`, `signal`, `--help` (`crates/terminalko-ctl/src/main.rs`) | There are no man pages. `terminalkoctl --help` prints usage; the others print nothing useful. The behaviour that a man page would describe is already written down, in `docs/spec/command-line.md` and `docs/spec/session-agent.md` — including the environment variables (`TK_AGENT_PATH`, `TK_RUNTIME_DIR`), the socket path, and what the exit status means. ## Work 1. Write pages in **scdoc** (small, readable, one dependency) or asciidoc — pick one and put the reason in the commit. Three pages: * `terminalko(1)` — what it is, that it starts an agent on demand, the keyboard shortcuts (the list already exists in `crates/terminalko/src/shortcuts.rs`), where the configuration lives, and a `SEE ALSO` to the other two; * `terminalko-agent(1)` — what it does and why it exists, `--idle-timeout`, the socket and lock paths, `TK_RUNTIME_DIR`, the environment it strips from sessions, and that sessions do not survive logout without `loginctl enable-linger`; * `terminalkoctl(1)` — the commands, how a session may be named, what `list` prints, and that a non-zero exit means the reason was printed. 2. Install them with meson (`install_man`), and add them to `%files` in the rpm spec — `rpmbuild` will fail if a listed file is missing, which is a useful check. 3. Add `--help` and `--version` to `terminalko` and `terminalko-agent`; a man page for a binary that cannot describe itself is half a job. `terminalko` currently parses no arguments at all, so this also decides what it should do with any: at minimum refuse unknown ones rather than ignore them. ## Acceptance criteria - `man terminalko`, `man terminalko-agent` and `man terminalkoctl` work from an installed build. - Each page's options match what the binary accepts — check by running each documented option. - `--help` and `--version` work for all three binaries. - The rpm builds with the pages in `%files`. - No documentation is duplicated: where the specs already say something, the man page can be brief and point at the installed docs rather than restating them. ## Notes - Keep them short. A terminal emulator's man page nobody reads is worse than a short one somebody does.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

dusan/terminalko#15

No description provided.

Rows
Columns