And what exactly is your rationale for going to 2.0? I kinda get that we might want to make a new client spec release with a few changes having accumulated, but why would it be a major? Because it's breaking for some clients?

The main motive behind the change is that the master branch got removed, not all tldr clients are listed in the wiki, and there are many clients, extensions and plugins which still use master in order to notify them I planned on making a tagged release, I have bumped the client specification for it here, there are other additions too like one of the long options you added.

No change to date was as breaking/has a larger impact as the current one because we never removed branches before, so I think this deserves a major version bump, if other maintainers suggest a smaller bump (to v1.6) then I am open to updating it.

I don't think we need to fight over who has the worse English, but all wording/grammar/... changes seem debatable at best to me.

I want to make it clear, I am not pointing towards someone and starting a debate about whose English is better, I just made some QoL improvements which I think is right. Feel free to review it, as the client specification must be as professional as possible to the client authors, you don't need to take my word you can run the same checks through any third-party proofreading tools and you will get almost the same suggestions.

If we're bumping the major version, maybe we could fix #10040 while we're at it?
It's been laying around for quite a while now, this is the earliest mention I could find.

If we're bumping the major version, maybe we could fix #10040 while we're at it? It's been laying around for quite a while now, this is the earliest mention I could find.

Anybody working on this?

If we're bumping the major version, maybe we could fix #10040 while we're at it? It's been laying around for quite a while now, this is the earliest mention I could find.

I don't know if this spec is the place to define the tldr pages syntax. But if so, it should be more clear that is the intent and not just an aside note. This is why I suggest restructuring the Page structure chapter of the spec, with something like the following:

The tldr examples pages structure are written in the standard CommonMark. However, it needed the addition of a syntax to show values the user may edit to adapt the example to its needs. These parts are indicated by surrounding double parentheses, {{ for opening and }} for closing. These parentheses might need to be escaped and can be done with a backslash (\) right before the first opening tag. 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"

I've removed the notice at the beginning

Although this specification is about the interface that clients must provide, [...]
It seems out of place. Either, we can create another spec for the format the tldr pages MUST follow and point both this spec and the contributor guide to it, either we define the format here but assume it.

I'm not sure that we need the examples if this is clear enough, you can choose whether to include them.

In any case, I think that having a place where the format is clearly defined would be nice. I use tldr on a daily basis, and I'm very glad this exists. Thanks

Marking the PR as a draft, later today I plan on updating it to highlight #10555

Has changing the syntax for escaping highlight expressions been considered ?

Has changing the syntax for escaping highlight expressions been considered ?

Currently no, but we will look into it (and other related issues) in the future.

Offtopic:

Since this PR has been open for a while now (with new changes like translation archives), I will request final reviews in the chatroom and once the green light is given, I will create a release soon.