Clarity and structure improvements in the shortcuts documentations

[masterpiga]

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.

[ralfbrown]

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 git rebase instead.

[masterpiga]

Apologies, done.

[paperdigits]

Generally when making changes this large, we want to talk about them before any work is actually done.

[masterpiga]

@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.

[paperdigits]

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.

[elstoc]

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.

[masterpiga]

@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.

[elstoc]

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