720243 - [kitsune] Simplify {for} syntax for multiple subsequent product versions: support {for tb5-tb9} instead of clumsy {for =tb5,=tb6,=tb7,=tb8,=tb9}

Status: RESOLVED WONTFIX

(support.mozillamessaging.com Graveyard :: General, defect)

Description

[Thomas D. (:thomas8)]

STR

- Write KB article with some information that applies only to a *limited subset of multiple versions* of the product, e.g. Thunderbird Keyboard Shortcuts documentation (1).
- For example, write markup to document changes of TB keyboard shortcut for Quick Filter:
TB 3.1 to TB 7: Ctrl+F
from TB 8 onwards: Ctrl+Shift+K
- Use {for} syntax to tell the versions apart

Actual Result
- Current syntax requires this:
{for =tb31,=tb5,=tb6,=tb7}Ctrl+F{/for}
{for tb8}Ctrl+Shift+K{/for}

Expected Result
- Simplify the syntax and parse the following notation to the same effect:
{for tb31-tb7}Ctrl+F{/for}
{for tb8}Ctrl+Shift+K{/for}

Reasons:

With rapid release cycle and up to almost 9 release versions per year, we will most likely have more and more cases where some information only applies to a limited subset of *multiple subsequent versions*, while it may no longer apply to the most recent version(s). Currently, the respective {for} syntax for such cases is very clumsy, as shown above; hence it should be simplified.
Which will also make the respective markup shorter and more easy to read.

Caveat:

Perhaps STR above is not the best example because of the unfortunate version selector "tb31" for TB 3.1, which is not sustainable in the long run as it will clash with "tb31" for TB 31 (but that's about 2.5 years from now). Think of something less extravagant where the selectors are more obvious, like tb5-tb9, or tb5-tb15 (which for a subset of only one year would currently require listing of 10 separate versions in the {for} statement). For this bug, we either need to read "tb31" as TB 3.1 if subsequent version numbers are lower, or pick another internal selector like "tb3_1" and update that selector for the whole site.

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts
(2) https://support.mozilla.org/en-US/kb/how-to-use-for

Comment 1

[Roland Tanglao needinfo please :rolandtanglao, :mohnkuchen, :adobo, :sinigang, :roland]

0. The right place to file bugs like this is in the upstream, i.e. whatever component SUMOdev uses for their Kitsune bugs since we get the software from SumoDev's Kitsune repo. I am pretty sure that SUMODev will set this to WONTFIX so I offer workarounds below.

1. re: "{for =tb31,=tb5,=tb6,=tb7}Ctrl+F{/for}"
doesn't:
"{for tb31,tb5,tb6,tb7}Ctrl+F{/for}" work? - This is still cumbersome but it's less typing, full info:
https://wiki.mozilla.org/Support/Kitsune/KB/WikiSyntax#.7Bfor.7D.2C_the_new_SHOWFOR
https://support.mozillamessaging.com/en-US/kb/markup-and-templates?redirectlocale=en-US&redirectslug=markup#w_showfor-for
http://support.mozilla.org/en-US/kb/how-to-use-for

2. by the time we get to TB31, TB3.1 will be EOL'd, in fact TB 3.1 will be end of life'd by mid 2012, so getting confused by the ambiguity of TB31 shouldn't be an issue

Comment 2

[Thomas D. (:thomas8)]

(In reply to Roland Tanglao :rolandtanglao from comment #1)
Hi Roland,

> 0. The right place to file bugs like this is in the upstream, i.e. whatever
> component SUMOdev uses for their Kitsune bugs since we get the software from
> SumoDev's Kitsune repo.

...if you don't know the right product/component for this, how am I supposed to know? ;) So can you CC somebody who knows?

> I am pretty sure that SUMODev will set this to
> WONTFIX so I offer workarounds below.

Why so pessimistic? You yourself are saying that the current syntax is "cumbersome" and unfortunately, your workaround doesn't work, which clearly makes this "very cumbersome" bordering to "useless UI". I'll provide a current scenario below.

> 1. re: "{for =tb31,=tb5,=tb6,=tb7}Ctrl+F{/for}"
> doesn't:
> "{for tb31,tb5,tb6,tb7}Ctrl+F{/for}" work? - This is still cumbersome but
> it's less typing,

No, that still cumbersome "workaround" doesn't work, and it's not supposed to.
{for tb31,tb5,tb6} is a pointless syntax which however will "correctly" be read as: {for tb31 and above, tb5 and above, tb6 and above}. So the result is the same as just {for tb31}, which is short for {for tb31 and above}.

Sample scenario from real life:

I'm changing keyboard shortcut documentation (1) to reflect the changes of Bug 738194. For ages, we've had Ctrl++ and Ctrl+- in composition to change font size, but starting from TB18, it will be Ctrl+< and Ctrl+>.
So I need the old shortcuts to show up for TB31 up to TB17, and the new shortcuts to show from TB18 upwards. The only correct and working syntax to achieve that is this:

|Increase Text Size||*{for =tb31,=tb5,=tb6,=tb7,=tb8,=tb9,=tb10,=tb11,=tb12,=tb13,=tb14,=tb15,=tb16,=tb17}*
{for win,linux}{key Ctrl+&#43;}{/for}{for mac}{key Command+&#43;}{/for}{/for}
{for tb18}{for win,linux}{key Ctrl+&#62;}{/for}{for mac}{key Command+&#62;}{/for}

Even if I decide to let the documentation break for older version selectors (for which there is no reason), the shortest possible variant of this would be:

|Increase Text Size||*{for =tb31,=tb14,=tb15,=tb16,=tb17}*
{for win,linux}{key Ctrl+&#43;}{/for}{for mac}{key Command+&#43;}{/for}{/for}
{for tb18}{for win,linux}{key Ctrl+&#62;}{/for}{for mac}{key Command+&#62;}{/for}

...which still sucks, compared to the simplicity and version-flexibility of my proposal in this bug:

|Increase Text Size||*{for tb31-tb17}*
{for win,linux}{key Ctrl+&#43;}{/for}{for mac}{key Command+&#43;}{/for}{/for}
{for tb18}{for win,linux}{key Ctrl+&#62;}{/for}{for mac}{key Command+&#62;}{/for}

Add to that the totally broken UI of the "Show for..." button dialogue (Bug 720249) which encourages production of the invalid, useless syntax described above ({for tb31,tb5,...}), and I believe this is really ripe for second thoughts and fixes.

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts

Comment 3

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #2)
> ...which still sucks, compared to the simplicity and version-flexibility of
> my proposal in this bug:
> *{for tb31-tb17}*

Which, to avoid the ambiguity of that silly extraordinary version selector for TB3.1, should be better presented and understood as:
*{for tb5-tb17}*

That's a truly flexible and lasting syntax which will never break, neither for old nor new version selectors.

Another unfortunate problem in this corner (needs a new bug):
Adding sections for future versions whose version selectors are not yet listed (Daily TB18, at the time of this comment), but require updates (e.g. bug 738194) will always show those sections, instead of hiding them when the current version selector is lower. So instead of just adding these sections now with correct version selector and just letting them fall into place as the current versions increase, I have to out-comment that {for tb18} section as <!--{for tb18}...--> and then revisit the document again later to remove the comment marks. That's really cumbersome... :(