Bug#1074360: debian-policy: document sensible-terminal

On Thu, 27 Jun 2024 at 09:45:41 +0000, Bastien Roucariès wrote:
>sensible-utils will carry in trixie sensible-terminal.
>
>It will allow one user to custumize the terminal to be used like sensible-
>editor do.
>
>Could you document it, in policy ?

Unfortunately I think the design currently implemented in 
sensible-terminal has some significant limitations, and I think we can 
do better.

A specification for what terminal to run needs to take into account 
three groups of stakeholders:

* Consumers of the spec: applications/libraries that want to run a
   terminal
* Providers: terminal emulators
* Configuration UIs like gnome-control-center and KDE's systemsettings
   that should presumably offer a way to configure this choice per-user

The current design of sensible-terminal appears to be this:

* Users may configure their preferred terminal by setting environment
   variable SENSIBLE_TERMINAL_EMULATOR or TERMINAL_EMULATOR.
   Its value is a command, escaped as if in a shell script, to which
   the options documented in Policy for x-terminal-emulator can be
   appended.
* If users didn't configure this, each desktop environment may configure
   its preferred terminal by creating a program in the PATH named
   sensible-terminal-$desktop, where $desktop is the desktop 
   environment's name from $XDG_CURRENT_DESKTOP folded to lower-case
   (for example sensible-terminal-gnome).
* If that doesn't exist, the default is the x-terminal-emulator 
   alternative.

If my summary is correct, then this interface is easy to use for 
consumers and providers, but has some problems, especially around 
configuration:

* Configuration is via environment variables. Because of how environment 
   variables inherit from parent to child, setting an environment variable
   can't be "instant-apply": after changing it, the user has to terminate
   all processes that already inherited it (in practice, log out and log
   back in, or reboot).

* Configuration is via environment variables. There's no universal,
   declarative way to set an environment variable for all login sessions,
   which UIs like gnome-control-center and systemsettings would need
   if they wanted to make this configurable. The closest I'm aware of
   is environment.d(5), which I think only systemd implements (although
   I would encourage non-systemd session managers to implement it too,
   because it's a completely reasonable non-systemd-specific spec).

* A desktop environment can only nominate one preferred terminal.
   GNOME would ideally say "ptyxis, gnome-console or gnome-terminal,
   whichever one is installed", but there's no way to express that
   declaratively. (We could make sensible-terminal-gnome be another layer
   of imperative script, but I'd really rather not.)

* The terminal emulator has to accept the xterm-compatible "-e" syntax
   where argument parsing stops at "-e", which is not straightforward to
   implement in typical GNU-style command-line parsing (it requires "-e"
   to behave like the conventional behaviour of "--"). For terminal
   emulators that don't implement that syntax, like gnome-terminal, this
   means SENSIBLE_TERMINAL_EMULATOR or TERMINAL_EMULATOR must be set to
   an x-terminal-emulator-compatible wrapper (gnome-terminal.wrapper),
   not to gnome-terminal itself.

* It's Debian-specific:
   - Upstream configuration UIs are unlikely to offer configuration for
     it unless specially patched by Debian, adding non-trivial
     Debian-specific code.
   - Upstream terminal emulators aren't going to integrate with it unless
     Debian-specific code is added.
   - Upstream consumers of the interface (like GLib) similarly aren't
     going to integrate with it unless patched to do so; this is only
     a small change, but could touch a large number of packages.

I would suggest that a better mechanism for choosing a terminal emulator 
would be the one used by xdg-terminal-exec(1), in the package of the 
same name, which avoids all of the problems I mentioned above:

* It can be configured on a per-user basis by writing files into
   $XDG_CONFIG_HOME, without needing to set new tool-specific environment
   variables like $TERMINAL_EMULATOR or $SENSIBLE_TERMINAL_EMULATOR,
   which means that configuration is instant-apply and
   non-session-specific. Advanced users can even configure a different
   choice per (user,desktop) pair, although UIs aren't really expected
   to offer this.

* A desktop environment can nominate a sequence of preferred terminals,
   in priority order.

* It can cope with any "exec argument", typically "-e" (the default) or
   "--". Terminal emulators can/should specify in their .desktop file
   what their equivalent of "xterm -e" is, and several already do:
   https://codesearch.debian.net/search?q=X-TerminalArgExec&literal=1

* It isn't Debian-specific: it already exists in other distros, and
   various upstream projects already use/support it.

Unfortunately the configuration design that xdg-terminal-exec implements 
is currently only a freedesktop.org proposal and has not been published 
as a formal spec by freedesktop.org, but it's the best thing we have 
available right now. It's modelled on the way that fdo MIME-type 
handlers and URI scheme handlers are registered, which gives it a lot of 
good properties "for free". Like the other related fdo specifications, 
its design assumes that there could be any number of implementations, 
with xdg-terminal-exec(1) merely being the reference implementation.

It's possible that freedesktop.org will end up recommending that 
terminals are registered via the more general Intent Apps spec 
<https://specifications.freedesktop.org/intent-apps/latest/>, which is 
similarly modelled on how MIME-type and URI-scheme handlers already 
work. If it does, then I would expect xdg-terminal-exec(1) to switch to 
using that, plus backward compatibility to its previous draft spec.

When the specification to use has settled down, I would expect that 
consumers of the interface (like GLib) are likely to stop exec'ing 
xdg-terminal-exec as a program, and instead implement the spec directly 
themselves, similar to how they implement fdo MIME-type handlers.

I'd recommend that any attempt to standardize this should be upstream 
so that it benefits all distros, rather than being a downstream, 
Debian-specific effort that is likely to end up being superseded by 
whatever de facto standard has emerged upstream in the meantime.

In the short term, my suggestion would be for sensible-terminal to try 
running xdg-terminal-exec, if installed (#1140004).

     smcv