aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorDanilo M. <danix@danix.xyz>2026-09-29 17:37:09 +0200
committerDanilo M. <danix@danix.xyz>2026-09-29 17:37:09 +0200
commit1e63b9127a34d0f3d396d5c4ad420074a04f5a55 (patch)
tree153c0cbbbb94609258e0835f2d5984169f86f29e /README.md
parente2d677d82ee52f940fda018de9372330c87fb49a (diff)
downloadqtmaildir-1e63b9127a34d0f3d396d5c4ad420074a04f5a55.tar.gz
qtmaildir-1e63b9127a34d0f3d396d5c4ad420074a04f5a55.zip
docs: document the launch selectors and translate them
Add an Usage section to the README covering --account, --thread and --message, the hex-only thread id, Qt's own options, the exit status 2 on a bad option, and the single-instance hand-off over the local socket. Add the Unreleased changelog entries for the selectors, the second-launch behaviour and the plain-text status bar. Translate the new strings into Italian. The option names stay untranslated in the help text: they are wire format, and a translated option name is an option the user cannot type. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Diffstat (limited to 'README.md')
-rw-r--r--README.md35
1 files changed, 35 insertions, 0 deletions
diff --git a/README.md b/README.md
index 7e88526..a2288f4 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,41 @@ Verified against these versions on Slackware -current:
You also need a notmuch database that is already set up and working from the
command line. qtmaildir does not create or configure one.
+## Usage
+
+```
+qtmaildir [options]
+
+ -h, --help Show this help and exit
+ -v, --version Show the version and exit
+ --account <key> Open this account's view
+ --thread <id> Open this thread
+ --message <id> Open this message, inside its thread
+```
+
+The three selectors combine: `--account work --message '<abc@example.org>'`
+opens that message in the work account's view. `--thread` takes a notmuch
+thread id (hex digits only); anything else is reported as a miss in the status
+bar and never reaches notmuch. Qt's own options, such as `-platform` and
+`-style`, are accepted alongside them. An unknown option or a missing value
+prints `qtmaildir: <error>` on stderr and exits with status 2.
+
+**A second launch does not open a second window.** When qtmaildir is already
+running, a launch hands its selectors to the running window over a local socket
+(`~/.local/state/qtmaildir/qtmaildir.sock`), which un-minimizes, raises and
+applies them, and the second process exits 0. This is what lets another
+program, a notification or a script open a particular message in the client the
+user already has open. It also means one process, and so one notmuch database
+handle. If no socket can be created, the window opens normally.
+
+Under a Wayland compositor, raising a window is a request rather than a
+command: the compositor may honour it, or apply its own focus policy. The
+selectors are applied either way.
+
+A selector that matches nothing, a stale thread id or an account key that is
+not configured, leaves the window on its normal startup view and says what
+missed in the status bar. It is never a reason to refuse to start.
+
## Building
```bash