CLIENT-SPECIFICATION: fix typo, add a way to escape the placeholder syntax

[acuteenvy]

Examples proposed by @mrnossiom in #10148 (comment).
Closes #10125.

[mrnossiom]

I would personally lighten the syntax to only one backslash:
docker inspect --format '\{{range.NetworkSettings.Networks\}}\{{.IPAddress\}}\{{end\}}' {{container}}.

This is maybe easier to parse than what I had proposed, but still not too heavy for reading source pages (even though this isn't done often). The drawback could if we needed to render something like \{{ <...> }}

But since I've seen only 3 occurrences of this problem, maybe this change is not needed. 🤷🏻

[SethFalco]

I favor a backslash for each curly brace. I think it's much more intuitive to treat things per character, rather than by our special definition attributed to combinations of characters.

In Markdown, \{ already means a literal {. So we should run with it. This will also be more backward compatible. When we don't mean the placeholder syntax, {{ is never found, so even if the client doesn't know to ignore it, it'll inadvertently ignore it anyway.

This will be simpler than giving {{ conditional meaning based on an escape sequence multiple characters away.

If a client finds \{{range.NetworkSettings.Networks\}}, and processes placeholders before delegating to the CommonMark library, it's probably going to mess up unless it knows to check for a backslash. If a client finds \{\{range.NetworkSettings.Networks\}\} without any special handling, it knows it's not a placeholder, and the CommonMark library will just do its magic.

For nested curly braces inside the placeholder syntax:

Syntax	Arg (curly braces removed)	Rendered
{{uwu}}	uwu	uwu
{{\{uwu\}}}	\{uwu\}	{uwu}
{{\{\{uwu\}\}}}	\{\{uwu\}\}	{{uwu}}

The main difference, here, is that having a single escape sequence affect multiple characters would require special handling from clients, while doing one escape sequence per character is already supported/expected by clients and CommonMark parsers. The benefits assume the client is using a CommonMark library to parse the page.

[acuteenvy]

I found a big issue with this. Currently, everything inside an example is treated literally, so rendering backslashes in any position is not a problem. But if we want to allow every { and } to be escaped, then what about Windows paths?

For example, how would this be rendered (Windows page for mount)?
mount \\{{computer_name}}\{{share_name}} {{Z:}}

One solution is to only allow double brackets to be escaped (\{\{) and treat everything else literally. But then putting a single pair of curly brackets inside a placeholder is impossible, because {{{...}}} is undefined even by the current specification. Are the literal brackets inside or outside the placeholder? Some clients even render one inside, and one outside, because they use the first braces they encounter as placeholder marks ( i.e. {{{ ... }}} ):

this is the official C client, trying to render {{{something}}}

---

No page requires a single pair of curly braces inside a placeholder as of now, but it would be great to cover everything. The PR as it is now would require escaping every brace that is supposed to be literal, but then also every backslash must be escaped, resulting in the need to rewrite all Windows pages like this:

\\{{path\to\file}} => \\\\{{path\\to\\file}}

and to complicate every client's page parser to allow for this, which is not a very good solution at all.

[blueskyson]

I think \{ and \} are special cases to escape {{ and }} syntax. As for path\to\file for Windows should remain the same for clarity. After all, a client is a tldr parser, not a standard markdown parser.

[sebastiaanspeck]

Is this one ready to be merged?

[kbdharun]

Is this one ready to be merged?

Nope, Client specification PRs (especially new requirement ones) are usually kept open the longest (in some cases months) to allow maintainers and community members (client authors, etc) to comment and propose additions/removals to the PR.

We can set a tentative merge date for this next month probably on the 17th.

[kbdharun]

@acuteenvy Let me know if the applied changes are fine. I am planning to merge this tomorrow. Will work on some other related PRs for the Client Specification.

[acuteenvy]

There's still a problem with Windows paths. If \{\{ means escaping and \{{ should be a literal backslash, we have to make it unambiguous.