butytho.md

Related: flameshot-org/flameshot#1480 , flameshot-org/flameshot#1468

Motivation: flameshot is the only screenshot tool I could find that worked on gnome3 + wayland and will output to stdout. This is cool and good, but there are some improvements I would like to see.

This issue covers three somewhat related problems:

• inconsistencies in the CLI output target selection,
• issues with the CLI ergonomics,
• the unnecessary requirement of the CLI using a background process under certain circumstances. Solving the issues listed here should make flameshot somewhat more amenable to scripted usage, make the CLI nicer to use, and most importantly, make it compose better with other applications (https://en.wikipedia.org/wiki/Composability , https://en.wikipedia.org/wiki/Unix_philosophy).

Introduction: The proposal is split into two support tiers:

• Tier 1 for the MVP: better behaved single -target selection
• Tier 2 for functionality that makes sense, but is not required, and can be reasonably worked around with other tools: multi-target selection with incremental last-setting-wins. Each tier has a section for a) functionality b) error handling. The tier specification is intended to be implemented incrementally, so that Tier 2 is not needed for Tier 1, but Tier 2 SHOULD be implementable without changes to Tier 1 functionality after Tier 1 is implemented first.

flameshot-org/flameshot#1480 (comment) shows that there is currently some amount of multi-target functionality, but the goal is to get the single targets working nicely first.

User's mental model ?? It's not obvious, nor does it seem to be comprehensbly documented (or at least, I didnt understand) that the cli is only a frontend to a running background process 1) this should be made more obvious 2) a more intuitive model can be supplied to the user by allowing usage without a background process, and documentation and flags for handling bg proces behaviour, and ..??this is getting too complicated. What should be the behaviour? ---ok there are multiple models: cli-bgprocess spawning/interaction, the single target models, the multitarget model user doesnt think about bg process by default, unless they already know the tray icon. even then they can assume that the cli just spawns a separte process. he question is if simple-model break is unavoidable, and how to give the user a path to understanding when it does break down, e.g. warning on the cli

Tier 1: Improved Single-Target Selection

Error handling

Tier 2: Multi-Target Selection with Last-Setting-Wins

Error handling

??There should be a flag for the clipboard target that handle the starting of the background process. If the bg process is disabled and the clipboard is a selected target, the process should raise a warning and a nonzero exit code should be returned (if any target fails). If the clipboard is the only target/all targets fail, theprocess should raise an error and return a different nonzero exit code. The exist codes MUST be documented in the manual. and SHOULD be handled by having a separate python file with all the exit codes enumerated and documented/specified, the exit codes should be referred to by name in the source code. flags for handling failing targets: ?? Tier1a, Tier1b, Tier2a, Tier2b (error handling(

Premise:

1. The -r, -c, -p or similar flags, set the output targets of flameshot from the CLI.
2. When running flameshot gui, the -p is more of a configuration option than a target setting, it only sets the output directory when clicking "output to file" button. -p doesn't provide a mechanism to set the exact output file name.
3. -c is the only target that needs the background process running, however currently it is always required. Other issues say the background process exists because it is necessary to implement clipboard functionality. My guess is the background process is always required because all the CLI commands are taken as "frontend" commands, which send the actual task to run over dbus, to the background process. All of them require

Requirements:

Proposal:

1. It would make sense to be able to select multiple targets at once, and also to disable targets that are enabled by default, such as the clipboard. 1.a. passing any combination of -r, -c, -p should output to those targets and override any previous setting (including being passed times on the CLI), or error if multiple are passed, or be passable multiple times for multiple targets (an alternative possibility is to accept multiple arguments to -p, for example.). This is a design decision. 1.b. passing any combination of some sort of prefix, such as --no-r, -R, --no-c, -C, --no-p, -P should disable the specified targets, and override any previous settings. 1.c. flameshot gui must provide an option to ignore/hide the target settings in the GUI, and allow binding a keyboard key such as Enter to "continue" saving to the targets pre-selected on the CLI. When this option is set, the target selection buttons will be hidden. When it is not set, the target selection buttons

For example:

flameshot gui --no-C -r -p ./ should output an image on stdout, as well as saving a file to the current working directory, but should not save to the clipboard. This is with the current -p behaviour, proposed changes to that are in point 2..

flameshot gui -c -r --no-C should output an image on stdout, but not to the clipboard.

flameshot gui -c

Testing: None of flameshot gui, flameshot screen, or flameshot full work, without the background flameshot process running. Please check that you don't have any flameshot processes running in the background when you test these, or you can probaby kill it with echo Killed: $(kill -9 $(pgrep -f '/flameshot$')). You should probably prepend this to every test command you run.