Status

P1
normal
VERIFIED FIXED
8 years ago
8 years ago

People

(Reporter: erik, Assigned: erik)

Tracking

unspecified
Dependency tree / graph
Bug Flags:
in-litmus ?

Firefox Tracking Flags

(Not tracked)

Details

(Assignee)

Description

8 years ago
Implement showfor syntax for small inline chunks. For example, something like...

    Press <showfor os="mac">Apple</showfor><showfor os="windows+linux">control</showfor>-N to open a new browser window.

Comment 1

8 years ago
Michael, Kadir: did we decide on the syntax to use for SHOWFOR? I'd really prefer if it was as simple to read and type as possible.

In an internal email thread, this syntax came up which I really like:

{mac}From the menu bar, select {menu}Firefox{/menu} and then select
{menu}Quit Firefox{/menu}.{/mac}
{/noMac}From the menu at the top of the Firefox window, select
{menu}File{/menu} and then select {/noMac}
{menu}
{win}Exit{/win}
{linux}Quit{/linux}
{menu}

For the keyboard shortcuts we could just do:

{mac}{key|Cmd}+{key|LeftArrow} or {key|Delete} or {key|Cmd}+[ {/mac}
{linux}{key|Alt}+{key|LeftArrow} or {key|Ctrl}+[{/linux}
{win}{key|Alt}+{key|LeftArrow} or {key|Backspace}{/win}

That way it's really clear what goes in each OS without the super
complex if-else logic.
There are two issues with the syntax you propose: there's no facility for handling things in {braces}, we can either do [[Namspaced:links]] or <custom> HTML-like tags; and even if we replace the braces with <> in your first example alone--which is far from comprehensive--we'd have to implement 5 different handlers. It's just not sustainable to support every variation with its own tag like that.

As for the second example, the {key|} syntax is being addressed by our template work. [[Template:key|args]] (or equally a shortcut: [[T:key|args]]) would use the "key" template. (This gives you a lot more flexibility. You could set up a template that like [[T:command|K]] that would print out a showfor Command/Ctrl/Ctrl-K already marked up as key strokes, and create and modify these templates without waiting on a code push.)

The syntax we're working on right now is the HTML-like version:

<showfor os="mac">Command</showfor><showfor os="linux+windows">Ctrl</showfor>-K.

<showfor version="3.6">Personas</showfor><showfor version="4.0">Themes</showfor>

<showfor os="mac" version="3.6">Only shows for Mac *and* 3.6.</showfor>


We were initially looking at something similar but using the [[Showfor:]] syntax. We think the HTML-like version is significantly easier to use.
(Assignee)

Comment 3

8 years ago
The HTML version also gives you the ability to include markup within micro-showfor tags--something we weren't going to be able to do with the [[link:handlers]].
(Assignee)

Updated

8 years ago
Blocks: 593306

Comment 4

8 years ago
I'm commenting without really understanding what is possible and what's not (and also without an understanding of the backend implications of what I'm suggesting). 

In general, I'd say it's confusing to be using both wiki and html styles here. Personally I prefer html but what I want more than one or the other is consistency.

My other comment is I'd like the syntax to be as short as possible so that the sentences are easier to read. So for example:
<showfor os="mac">Command</showfor><showfor os="linux+windows">Ctrl</showfor>-K.

That block just looks like the word "showfor" repeated over and over. You have to really look to see that there is some content in there.

Could we do something like:
<s mac>Command</s mac><s nomac>Ctrl</s nomac>-K.
or 
[s mac]Command[/s mac][s nomac]Ctrl[/s nomac]-K.

Again, I apologize because I don't know the difference in implementing < vs. [ vs. { vs. [[, etc. or why "" are required around things.

Comment 5

8 years ago
Can it even be simplified more and just use [mac] instead of [s mac] because showfor would be implied?
(In reply to comment #4)
Well there are two levels: there's what's theoretically possible, and then there's what our toolset makes easy for us. There are tools to read mediawiki markup (as mediawiki defines it) and there are tools to read HTML. There aren't tools to read things that are *similar* to either of those.

In theory, we could write a parser for things like you've suggested but it's difficult and time consuming, and since we have tools--good tools--that handle already-defined markup like mediawiki and HTML, it seems like a bad use of our time.

> Could we do something like:
> <s mac>Command</s mac><s nomac>Ctrl</s nomac>-K.
> or 
> [s mac]Command[/s mac][s nomac]Ctrl[/s nomac]-K.

No. Both of those syntaxes have other meanings already and those suggestions are broken. Angle brackets are HTML, and you're then forming the HTML incorrectly. Single square brackets are already defined as external links.

> Again, I apologize because I don't know the difference in implementing < vs. [
> vs. { vs. [[, etc. or why "" are required around things.

Because are tools are already aware of <tags> and [[Links]], but they are _not_ aware of the other syntaxes--except the single square bracket.

If we use HTML or wiki-links, all we have to do is something like:

    registerHandler('name', callbackFunction)

If we want to use {}, we'd have to first make our parser understand that those are special characters. It doesn't know that at the moment.

(Actually, it does know that {{x}} and {{{1}}} are special, but that's because they are used in mediawiki's template language. That makes using curly braces extremely difficult, because we have to work around the extra cases.)

(In reply to comment #5)
> Can it even be simplified more and just use [mac] instead of [s mac] because
> showfor would be implied?

Nope, since [s mac] is valid external link syntax.


We could replace <showfor os=""> with <s os=""> (or probably allow both) if you really think that's better.
(Assignee)

Updated

8 years ago
Blocks: 586456
(Assignee)

Comment 7

8 years ago
QA: ended up going with a syntax of "{for mac,win}You have a Mac or a Windows machine!{/for}". For browsers, it'd be "{for fx4,m11}You're running either FF 4 or Fennec 1.1.{/for}".

Landed in http://github.com/jsocol/kitsune/tree/dff12cc67a9b1b73816f9e3c2bedd5b9f39875dd
Status: NEW → RESOLVED
Last Resolved: 8 years ago
Resolution: --- → FIXED

Comment 8

8 years ago
I've noticed some inconsistency in discussions in #sumodev and comments here about using FX or FF as the abbreviation for Firefox. Let's use FX, since that's most widespread and used in e.g. #fxhelp among other things. 

I couldn't tell from that link which one was checked in -- could someone verify this please? Thanks!
(Assignee)

Comment 9

8 years ago
fx was checked in. I'll note it on https://wiki.mozilla.org/Support/Kitsune/KB/WikiSyntax.
Awesome; thanks Erik!
Verified implemented
Status: RESOLVED → VERIFIED
Flags: in-litmus?
You need to log in before you can comment on or make changes to this bug.