From 1e63b9127a34d0f3d396d5c4ad420074a04f5a55 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Tue, 29 Sep 2026 17:37:09 +0200 Subject: 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 --- CHANGELOG.md | 13 +++++++ README.md | 35 ++++++++++++++++++ translations/qtmaildir_it_IT.ts | 81 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 129 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 534411b..bc81425 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,19 @@ point at which they are stable. ## [Unreleased] +### Added + +- `--account`, `--thread` and `--message` on the command line, so another + program can open qtmaildir at a particular account's view, conversation or + message. The three combine, and Qt's own options are accepted beside them. +- A second launch now hands its selectors to the already-running window over a + local socket and asks it to raise itself, rather than opening a second + window. One process, and so one notmuch database handle. + +### Changed + +- The status bar renders its messages as plain text. + ## [0.30.0] - 2026-09-29 A calendar window over the vdirsyncer vdir, with a month grid, an agenda and 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 Open this account's view + --thread Open this thread + --message Open this message, inside its thread +``` + +The three selectors combine: `--account work --message ''` +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: ` 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 diff --git a/translations/qtmaildir_it_IT.ts b/translations/qtmaildir_it_IT.ts index eff6754..51bf793 100644 --- a/translations/qtmaildir_it_IT.ts +++ b/translations/qtmaildir_it_IT.ts @@ -842,6 +842,75 @@ Il messaggio È stato inviato. Non inviarlo di nuovo. La sequenza '%1' è associata sia a '%2' sia a '%3' in [keys]; viene mantenuta '%2' + + LaunchSelectors + + Open this account's view. + Apre la vista di questo account. + + + Open this thread. + Apre questa conversazione. + + + Open this message, inside its thread. + Apre questo messaggio, nella sua conversazione. + + + Unknown option: %1 + Opzione sconosciuta: %1 + + + qtmaildir %1 - a Qt6 mail client for notmuch-indexed Maildirs + +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. When qtmaildir is already running, +a second launch hands its selectors to that window and exits rather +than opening a second one. + +Configuration: ~/.config/qtmaildir/qtmaildir.conf +qtmaildir reads a notmuch-indexed Maildir. It does no network +protocol work: fetching and sending are external commands. + + qtmaildir %1 - un client di posta Qt6 per Maildir indicizzate con notmuch + +Uso: qtmaildir [opzioni] + + -h, --help Mostra questo aiuto ed esce + -v, --version Mostra la versione ed esce + --account <key> Apre la vista di questo account + --thread <id> Apre questa conversazione + --message <id> Apre questo messaggio, nella sua conversazione + +I tre selettori si combinano. Se qtmaildir è già in esecuzione, +un secondo avvio passa i selettori a quella finestra ed esce, +invece di aprirne una seconda. + +Configurazione: ~/.config/qtmaildir/qtmaildir.conf +qtmaildir legge una Maildir indicizzata con notmuch. Non usa alcun +protocollo di rete: il recupero e l'invio sono comandi esterni. + + + + Launch payload too large + Dati di avvio troppo grandi + + + Unrecognised launch payload + Dati di avvio non riconosciuti + + + Truncated launch payload + Dati di avvio troncati + + MainWindow @@ -1895,6 +1964,18 @@ Il messaggio È stato inviato. Non inviarlo di nuovo. The sync failed (exit %1), so your changes are still unsynced. The window has been left open. La sincronizzazione non è riuscita (uscita %1), quindi le tue modifiche non sono ancora sincronizzate. La finestra è stata lasciata aperta. + + No account named '%1'. + Nessun account chiamato '%1'. + + + No thread matched '%1'. + Nessuna conversazione corrisponde a '%1'. + + + No message matched '%1'. + Nessun messaggio corrisponde a '%1'. + Background sync running... Sincronizzazione in corso in background... -- cgit v1.2.3