Clarity and structure improvements in the shortcuts documentations #786
Conversation
|
You should not merge master into topic branches, as merging the branch back into master then makes a mess of the git history. If you need to pull updates from master, use |
masterpiga
force-pushed
the
clarity_improvements_in_shortcuts
branch
from
3fe882b to
f2973a1
Compare
|
Apologies, done. |
|
Generally when making changes this large, we want to talk about them before any work is actually done. |
|
@paperdigits I had expressed my interest in updating this file. This seems the best place to have a structured conversation over an actual artifact instead of an abstract idea for a change. Also, the change is not as large as it seems. It is by and large the same content moved around to fit what I think is a better narrative. |
|
Sure, but there is a difference between an update and a complete restructure. I've started reading it, and will offer comments as I go along. |
|
For me, the problem with big restructure PRs like this is that they're essentially unreviewable using github (or really at all TBH). Yes we can make small comments on individual paragraphs/terminology/use of markdown, but it's really almost impossible to have a reasonable discussion about the broader-brush changes because there's so much of it. Such discussions almost always devolve into a dozen threads of inconclusive back-and-forth without addressing the whole. The only options from my point of view are to wait until it's stable, merge it as-is and copy-edit (which might turn into another rewrite) or reject it entirely (which would be a shame as I'm sure there are some good ideas here). I spent quite a long time structuring and rewriting this section to try and make it flow well (it's complex functionality and explaining it well and consistently is hard). That's not to say it can't be improved but I really don't have the time it would take to give such a large PR the attention it deserves. I now have much less time to devote to dtdocs than I used to and I would prefer to spend my time documenting new features. In my opinion this PR would be much better (for my sanity as much as anything) as a set of small issues raised and small PRs to resolve them one at a time. |
|
@elstoc I agree. the diffing algorithm is less than optimal, and it makes this change look much larger than it is. It is by and large just blocks of texts moved around so that concepts are explained in what, IMO, is a more logical sequence for someone who is not already familiar with the system. Working on it piecewise wouldn't really work, as the intermediate steps would lack internal consistency. As explained in the PR description, the main change in terms of content is the introduction of the concept of "discrete" vs. "continuous" actions, and the renaming of "simple" vs. "extended" shortcuts accordingly. For the rest, I just moved content around and added some examples. All subsequent changes are to integrate @dterrahe's comments, which I think were very helpful because they explain a lot of things that were not present (or clear) in the previous version of the page. For example, the fact that the repeat counter is not per-key and that you can trigger multiple shortcuts at once. |
|
The thing is I'm not sure I agree with all these changes, and the discussion would be easier if they were treated one-at-a-time |
|
@masterpiga any fixes or comments for my comments? |
|
@paperdigits Which comments? I don't see any 😮 |
| **Shortcuts must be unique within a view.** | ||
| A single action may have multiple shortcuts but a single shortcut can only be linked to one action in a given darktable view -- you can't chain actions together except by applying a preset or style. You can, however, set up a single shortcut that does one thing in the lighttable view, say, and another in the darkroom view. | ||
|
|
||
| **Additional modifiers.** As mentioned above, the only valid modifiers are the `Shift`, `Ctrl` and `Alt` keys on the keyboard. You can define additional keys (or device buttons) as modifiers by assigning keys/buttons to the "global/modifier" action. However, these will merely function as extra `Ctrl`, `Alt` or `Shift` keys -- you cannot create "new" modifiers. |
There was a problem hiding this comment.
I find this paragraph confusing. So I can add new keys, but they'll function as ctrl/alt/shift, but I can't add new modifiers?
There was a problem hiding this comment.
Correct. I rephrased it a bit. PTAL.
…le shortcuts at once.
…o trigger a continuos action.
masterpiga
force-pushed
the
clarity_improvements_in_shortcuts
branch
from
d004da3 to
2175c74
Compare
masterpiga
force-pushed
the
clarity_improvements_in_shortcuts
branch
from
968e87f to
274d83a
Compare
|
@paperdigits @dterrahe PTAL |
|
@paperdigits @dterrahe Gentle ping. |
dterrahe
left a comment
dterrahe
left a comment
There was a problem hiding this comment.
I added a few more commentaries but I didn't really thoroughly read through everything; there may be inaccuracies I didn't catch.
Since I'm far from the target audience I can't judge if this is an improvement overall or not. My "approval" here simply means I have no objection and don't want to prevent the manual maintainers from deciding.
| Similarly, you could map `e double-press + scroll` and `f double-press + scroll` to two nodes in a graph (say, `yellow` and `green` in color equalizer). You can then move both sliders at once by: | ||
|
|
||
| 1. pressing and releasing `e` once; | ||
| 2. pressing and holding `e`; |
There was a problem hiding this comment.
this should be done quickly following 1.
| If both `e + scroll` and `f + scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling the mouse wheel while holding down both `e` and `f` will move both sliders. | ||
| Similarly, you could map `e double-press + scroll` and `f double-press + scroll` to two nodes in a graph (say, `yellow` and `green` in color equalizer). You can then move both sliders at once by: | ||
|
|
||
| 1. pressing and releasing `e` once; |
There was a problem hiding this comment.
This should be a quick operation (<double click interval).
| A single action may have multiple shortcuts but a single shortcut can only be linked to one action in a given darktable view -- you can't chain actions together except by applying a preset or style. You can, however, set up a single shortcut that does one thing in the lighttable view, say, and another in the darkroom view. | ||
| # types of actions and shortcuts | ||
|
|
||
| There are two types of actions: |
There was a problem hiding this comment.
I understand it can be useful to introduce concepts for didactic reasons that don't exactly match reality. I myself find the concept of continuous vs discrete actions confusing (because slider adjustments are clearly not "continuous"; they are intentionally stepwise so that "toggling" up/down will hit the same cache entries so you can quickly decide which you like best between two fine-tune steps. Truly discrete adjustments would make the cache useless for this). The real difference is between "directional" shortcuts (up/down scroll, move etc) and "discrete" shortcuts (a press or click, double or whatever). For keyboard+mouse use you still need to be holding your last "discrete" shortcut (which must include a key press) in order to be able to combine it with a "directional" one. Since you are holding it anyway, it is easy and natural to issue a series of "directional" shortcuts from it. Does that make them "continous"? With external devices you can issue "directional" shortcuts independently.
The only reason to make the distinction is that it is natural to assign "directional" shortcuts to different "default" effects than "discreet" shortcuts. So while a key press shortcut linked to a slider will show its edit pop-up, a scroll will move it up. Or down. But those are only defaults; you can explicitly override them any way you want (both assigning discrete shortcuts to an up or adown effect or assigning one of the directions to a "discrete" effect (like the popup). With the current limitation that the other direction has to be assigned to the same action (may be different element/effect) but that's mostly to guarantee that they're both available on the same screen. Could be more generalised but I doubt there's demand.
There was a problem hiding this comment.
I'm sorry, I think I've made this comment before; I forget. Since I'm the opposite of the target audience, my review has limited usefulness.
| --- | ||
|
|
||
| You can perform almost any action in darktable with a keyboard/mouse shortcut. You can also use various other input devices, including MIDI devices and game controllers -- see the [midi device support](../special-topics/midi-device-support.md) section for details. These are referred to as _external devices_ or just _devices_ in this guide. | ||
| _Shortcuts_ are a way to control darktable using your keyboard, mouse or trackpad and other input devices. They allow you to perform _actions_ without interacting directly with a UI element. |
There was a problem hiding this comment.
I think I've said this before as well. I am not at all a gifted technical or manual writer so I don't want to second guess anybody who is. And the balance to be walked here is a fine one, I understand. Too many examples makes a messy text. This reference manual entry starts quite formal by introducing all the complicated concepts. It may make it less obvious to the more casual user that simple things are actually very simple. So they may conclude that this chapter is not what they are looking for. And maybe it isn't; maybe they should look elsewhere to see that if they simply want to link a key press to a screen button press they can do that in three/four steps:
- press shortcut mapping button
- hover over the button
- press the key
(4. right click to switch off mapping mode)
Then once their use cases evolve from there, they might want to come back here to see what more is possible. I'm just worried all the complicated text here makes them believe that dt does not have shortcut system that works for their needs at all.
| - Enable, expand or focus modules | ||
| - Click buttons | ||
| - Switch between views | ||
| By default, all key presses in a shortcut are _short_, i.e., the key is pressed and immediately released. However, the last repetition of a key in a shortcut can also be a _long_ key press, defined as holding down the key for a bit longer than the duration of a double click. Hence `e double-press` and `e long double-press` are two distinct shortcuts that can be assigned to different actions. The associated action triggers when the key is released, which entails that a shortcut ending with a long press cannot be used for a continuos shortcut. |
There was a problem hiding this comment.
continuous
Alternative:
"You can turn a normal key press or mouse click into a long press or click by simply holding it a little longer before releasing (longer than double-click speed but shorter than twice double-click speed). You can do this for the last press or click of any single/double/triple. Hence..."
|
|
||
| ## shortcuts must be unique within a view | ||
|
|
||
| A single action may have multiple shortcuts but a single shortcut can only be linked to one action in a given darktable view -- you can't chain actions together except by applying a preset or style. You can, however, set up a single shortcut that does one thing in the lighttable view and another in the darkroom view. |
There was a problem hiding this comment.
...except by applying a preset or style or lua script.
There was a problem hiding this comment.
BTW this was an extension I had been planning (multiple actions from the same shortcut) before I realised this whole thing was already more complicated than anybody has appetite for. The main complication when implementing would be whether to support an order. Say you assign actions A, B and C to the same K press. Should they happen in that order? Could it randomly be B, C, A? Could their executions overlap (and possibly generate undefined results)? Supporting all reasonable answers to that would become a configuration and user interface nightmare. And confront innocent users who simply wanted to overwrite a previously defined shortcut and now need to consider complicated options.
| Left-click on a mappable widget to open the shortcut mapping screen for that widget (see below). Left-click anywhere else on the screen to open the shortcut mapping screen, expanded (where possible) based on the part of the screen you have clicked on. This screen can be used to alter the action assigned to a shortcut and to configure shortcuts for non-visual actions. Entering the shortcut mapping screen exits visual shortcut mapping mode. | ||
|
|
||
| **To define new shortcuts:** | ||
| press a key combination while hovering over a mappable widget. A _default action_ will be assigned to that shortcut based on the type of widget and whether your shortcut includes a movement. See the [common actions](#common-actions) section for examples of some of the defaults. |
There was a problem hiding this comment.
"whether your shortcut includes a movement" you mean whether it is a continuous shortcut?
| Actions in the "views" section can only be executed from the specified darktable view. As with global actions, most do not have specific _elements_ as they are used to perform one-off operations. | ||
|
|
||
| A toggle is a button that has a persistent on/off state. It therefore has additional _effects_ to allow you to toggle it or explicitly set its state. As with a normal button the default action, when assigning a simple shortcut to a toggle, is to activate the toggle as if clicked with the left mouse button (which toggles the button on/off). | ||
| For example, the predefined shortcut `ctrl + b` triggers the action `views/darktable/guide lines/toggle`, which toggles guide lines in the darktable view. |
There was a problem hiding this comment.
views/darkroom/guide lines/toggle
It has an effect setting though which would allow you to directly simulate a right-click on the button, which in this case opens the guide lines configuration popup.
5 participants
The documentation about shortcuts was confusing to me. After a few exchanges on pixls.us, I think that I understand things better. Armed with this better understanding, I thought that I was in a good position to try to improve it.
The content is by and large the same, I have just moved things around a bit to keep the information flow more consistent and to add a bit of structure.
In terms of content changes, the only notable one is that I replaced the distinction between simple vs. extended shortcuts, which seemed a bit arbitrary and that I found confusing. Instead, I used discrete vs. continuous, as these shortcuts are associated with discrete (e.g., click) vs. continuos (e.g., change value) UI actions. This also shifts the focus from the type of shortcut that one is defining to the kind of action that one wants to trigger, which IMHO is more logical and hence more understandable and memorable.
I also added a few more concrete examples, which were lacking, and whenever possible aded captions to the paragraph to make it easier to find what one is looking for.