718962 - TB: Wrong markup used in Keyboard Shortcuts Documentation: Should use {key Ctrl+keyx} instead of {button Ctrl} + {button keyx}, and conflate OS selectors: {for win,linux}

Status: RESOLVED FIXED

(Thunderbird :: Help Documentation, defect)

Description

[Thomas D. (:thomas8)]

+++ This bug was initially created as a clone of Bug #686436 +++

sreepriya1111 intuitively did the correct thing in Bug 686436 Comment 3, and made me realize that we've done the wrong thing all along in the current markup of Keyboard Shortcuts documentation (1), since its inception (2): What a revelation!

Current Markup (e.g. for "Previous Tab" on Win/Unix):
{button Ctrl} + {button Shift} + {button Tab} 

Expected Markup:
{key Ctrl+Shift+Tab}

Explanation:

As documented in the Markup-chart (3), there's a logical difference between the following:

{key keyx+keyy} explicitly for keyboard shortcuts (which will be parsed correctly as two separate buttons joined with a plus: [keyx] + [keyy]}
{menu caption} for menus and
{button caption} for normal buttons with a textual caption (dialogue or toolbar buttons)

Obviously, applying the correct markup will make the source of this document a *LOT* easier to maintain. Fixing this will go a long way in ensuring a better quality of this document in the future. Heck, I was wondering why the source of this had to be so complex, for a simple thing like keyboard shortcuts. And there's more to simplify, like combining Win & Unix into a single {for} where applicable, but that needs a separate bug.

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts
(2) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/76
(3) https://support.mozilla.org/en-US/kb/Markup-chart

Comment 1

[Thomas D. (:thomas8)]

If I read Bug 686436 Comment 6 correctly, sreepriya1111 has volunteered to fix this one.

I'm sure this can be done in a semi-automatical manner, e.g.
- copy the whole source code into a text editor like notepad++
- use several rounds of find+replace (Ctrl+H) to semi-automatically edit the markup (strip quotes when you copy this into the find+replace dialogue, and mind the space at the end of search term), in this order:

find:         "{button Command} + {button Shift} + {button "
replace with: "{key Command+Shift+"

"{button Ctrl} + {button Shift} + {button "
"{key Ctrl+Shift+"

"{button Command} + {button Option} + {button "
"{key Command+Option+"

...and any other three-key-combinations in the same manner. Make sure you have covered *all* three-key combinations before proceeding with the two-key combinations:

"{button Command} + {button "
"{key Command+"

"{button Ctrl} + {button "
"{key Ctrl+"

...and any other two-key-combinations in the same manner, then the one-key shortcuts:

"{button "
"{key "

Comment 2

[Thomas D. (:thomas8)]

Wow! sreepriya1111 has already filed a new revision which fixes this shortly after I filed this bug. Furthermore, he also fixed a similar major problem: {for win} and {for linux} should be combined into {for win,linux} where applicable to streamline the markup. Altogether, this has shrinked the markup to about less than half.
sreepriya1111, that's great!

With changes of that size, it's natural there are some small issues:

1) Increase Text size	[Ctrl] +[ ]+[ ], expected: [Ctrl] + [+]
Unfortunately, {key++} doesn't render correctly.
{key++} works (2x, in Message functions and Writing Messages)

2) View Message Source	Ctrl + key U: missing { or something like that in this corner

3) Quit	Ctrl + Q{ <- a bracket too much

4) Nitfix under the hood(!): Please remove all extra spaces inside {key...} markup:
E.g. we need {key Ctrl+Shift+Tab}, no more than a single space in all of the {key...} markups. Pls remove extra spaces before and after the +, and after "{key", i.e. between "{key" and the actual shortcut key sequence. Ensure single keys like {key F} or {key F5} are also trimmed to single space.

Because of 1)-4), I'll have to "reject" this revision so that it can be fixed.
While we are here, pls include:

5) change some captions for Ctrl++/-/0, and remove one entry Ctrl+0, per Bug 716214 Comment 2 (please find the details there)

6) re-include Ctrl+H and Ctrl+Alt+H for MAC, per Bug 716098 Comment 4 (please find the required markup in that comment!); does this work on Linux?

7) make Quit:Ctrl+Q show for mac,linux only (if it works on Linux?), per Bug 716101.

I think that's enough for this revision... ;)
Thank you very much for your efforts.

Comment 3

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #2)

...and:
8) replace
"down arrow" -> ↓
"right arrow" -> →
"left arrow" -> ←

> Wow! sreepriya1111 has already filed a new revision which fixes this...
> Because of 1)-4), I'll have to "reject" this revision so that it can be fixed

Comment 2 is the review for
https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5544

Comment 4

[Thomas D. (:thomas8)]

...and:
9) modify Next/Previous tab for MAC, per Bug 686436 Comment 8

Comment 5

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #2)
> 1) Increase Text size	[Ctrl] +[ ]+[ ], expected: [Ctrl] + [+]
> Unfortunately, {key++} doesn't render correctly.
> {key++} works (2x, in Message functions and Writing Messages)

Typo fix:
{key Ctrl++} doesn't render correctly.
{key Ctrl++} works (2x, in Message functions and Writing Messages)

Comment 6

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #2)
> Wow! sreepriya1111 has already filed a new revision which fixes this shortly
> after I filed this bug. Furthermore, he also fixed a similar major problem:
> {for win} and {for linux} should be combined into {for win,linux} where
> applicable to streamline the markup. Altogether, this has shrinked the
> markup to about less than half.
> sreepriya1111, that's great!

All of these goodies (as listed in comment 2, comment 3, and comment 4), and many more, have now been landed and made current in 
https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5614

> I think that's enough for this revision... ;)
> Thank you very much for your efforts.

Indeed :)

Comment 7

[Thomas D. (:thomas8)]

Excellent teamwork with sreepriya, thank you!

-> Fixed.