Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 4 commits into from
Nov 17, 2023
Merged

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

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aa10306
CLIENT-SPECIFICATION: add a way to escape the placeholder syntax
acuteenvy Sep 17, 2023
1c031e0
Merge branch 'main' into client-spec-10125
kbdharun Nov 6, 2023
24ac759
Update CLIENT-SPECIFICATION.md
kbdharun Nov 16, 2023
6db1d0d
CLIENT-SPECIFICATION: update page structure section
kbdharun Nov 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion CLIENT-SPECIFICATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,13 @@ The structure inside these translation folders is identical to that of the main

## Page structure

Although this specification is about the interface that clients must provide, it is also worth noting that pages are written in standard [CommonMark](https://commonmark.org/), which the exception of the non-standard `{{` and `}}` syntax, which surrounds values in an example that users may edit. Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.
Although this specification is about the interface that clients must provide, it is also worth noting that pages are written in standard [CommonMark](https://commonmark.org/), with the exception of the non-standard `{{` and `}}` placeholder syntax, which surrounds values in an example that users may edit. Clients MAY highlight the placeholders and MUST remove the surrounding curly braces. Clients MUST NOT treat them as the placeholder syntax if they are escaped using `\` (i.e. `\{\{` and `\}\}`) and MUST instead display literal braces, without backslashes. Placeholder escaping applies only when both braces are escaped (e.g. in `\{` or `\{{`, backslashes MUST be displayed). Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.

### Examples

- `ping {{example.com}}` MUST be rendered as "ping example.com"
- `docker inspect --format '\{\{range.NetworkSettings.Networks\}\}\{\{.IPAddress\}\}\{\{end\}\}' {{container}}` MUST be rendered as "docker inspect --format '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. 🤷🏻

Copy link
Member

@SethFalco SethFalco Sep 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

kbdharun marked this conversation as resolved.
Show resolved Hide resolved
- `mount \\{{computer_name}}\{{share_name}} Z:` MUST be rendered as "mount \\computer_name\share_name Z:"


## Page resolution
Expand Down
Loading