Issue with "touch-action": linked bars in formal syntax

[Ryuno-Ki]

MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action

What information was incorrect, unhelpful, or incomplete?

The formal block has bars as links

Specific section or headline?

Formal syntax

What did you expect to see?

Either a BNF-free format or at least not linked bars.

Did you test this? If so, how?

I hovered the bar and noticed the link in the bottom edge of my browser.

---

It looks like the macro is doing something weird: https://github.com/mdn/content/blob/e38501179a65ec21528f264a22c3f5822d865ad2/files/en-us/web/css/touch-action/index.html#L84

produces

Code block (formatted by me)

```html

auto
|
none
|
[
[
pan-x
|
pan-left
|
pan-right
]
||
[
pan-y
|
pan-up
|
pan-down
]
||
pinch-zoom
]
|
manipulation

```

MDN Content page report details

* Folder: `en-us/web/css/touch-action` * MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action * GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/css/touch-action/index.html * Last commit: https://github.com/mdn/content/commit/68abfca3e8e50a1e143214bfaf90d33ae61fe42e * Document last modified: 2021-04-13T21:31:59.000Z

[Ryuno-Ki]

@peterbe Ping, since it involves a macro, so might be relevant in other places as well.

[rachelandrew]

@Ryuno-Ki the links go to an explanation, and a title also explains what they are. This seems correct unless I'm looking at something else.

[peterbe]

@Ryuno-Ki What is the problem? It's a special block of syntax definitions where individual characters in there are anchor links. E.g.

<a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a>

Is it wrong? Is it ugly? Is it confusing?

[Ryuno-Ki]

It's ugly. It confuses me, since the values are not marked as links. Being bars / pipes, they get hard to touch with a finger.

I can accept if it is on purpose, though. (Would like to read through the PR that introduced them to understand the rationale)

[peterbe]

@schalkneethling I don't think it's super ugly but yes it certainly looks a bit odd. Can you have a 5min think of if there's a way to control the styling of those of characters in there that would look a bit nicer?

[schalkneethling]

@Ryuno-Ki @peterbe What if we did something like in the screenshot below?

[Ryuno-Ki]

My ache stems from the UI. You still have links in the UI. I just checked with TalkBack on Android on the current syntax:

Formal syntax. Heading level 2 auto Link. Single var. Exactly one of the entities must be present. Double click to select. none Link. Single var. Exactly one of the entities must be present. Double click to select. Link. Brackets. Enclose several entities, combinators and multiples to transform them into a single component. Double click to select. Link. Brackets. Enclose several entities, combinators and multiples to transform them into a single component. Double click to select. pan-x Link. Single var. Exactly one of the entities must be present. Double click to select.

and so on.

That dosn't make for a nice UI.

If you go with the explanation before, I'd wrap the formal syntax symbols into a span and assign an aria-describedby pointing to the respective explanation. https://www.tpgi.com/describing-aria-describedby/ I think, some screenreaders allow for turning them off.

At least, it should be possible to comprehend the formal syntax without all those link announcements in between.

[schalkneethling]

@Ryuno-Ki That was my exact intent. Definitely not to keep the links in the syntax/code example as well.

[Ryuno-Ki]

Yay! The underlines in the formal syntax box throw me off. Let me know if I can check something out with a screenreader.

[schalkneethling]

@chrisdavidmills Thoughts on this idea? https://github.com/mdn/yari/issues/3603#issuecomment-828567091

I do not know how many pages this would impact but, perhaps it is just the one?

[Ryuno-Ki]

It's not. But I thought, opening more issues wouldn't add value. The other day, I wondered, whether a line ragged to the right and below the formal syntax box („What does this mean :grey_question:”) might be a nice UX. That could lead to a page explaining the syntax. It could also be linked via aria-describedby as above. (Make sure it's referring the same element if the box appears multiple times)

[chrisdavidmills]

@chrisdavidmills Thoughts on this idea? #3603 (comment)

I do not know how many pages this would impact but, perhaps it is just the one?

I quite like the idea of neatening up the formal syntax sections, although I'm not convinced it's the highest priority job in the world.

Would you also remove all the links from the bits of syntax that are linked on the syntax line (e.g. I, ||, &&)? They would no longer be needed if we did this.

I was also thinking that maybe an even quicker solution would be to just include a link at the bottom of each formal syntax section linking to https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax, with link text of "CSS Value definition syntax explained" or similar?

[schalkneethling]

Would you also remove all the links from the bits of syntax that are linked on the syntax line (e.g. I, ||, &&)? They would no longer be needed if we did this.

Yes, that is the plan.

I was also thinking that maybe an even quicker solution would be to just include a link at the bottom of each formal syntax section linking to https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax, with link text of "CSS Value definition syntax explained" or similar?

Would these be part of a macro? i.e. once we add it to the macro, it will be set everywhere on the next build?

[chrisdavidmills]

Yes, that is the plan.

Awesome.

Would these be part of a macro? i.e. once we add it to the macro, it will be set everywhere on the next build?

Yes, absolutely! We can add these links to the macro that generates the formal syntax in each case, so we only have to code it once.

[schalkneethling]

@chrisdavidmills Good stuff, I can take this one then.

[chrisdavidmills]

@chrisdavidmills Good stuff, I can take this one then.

awesome, nice one man!