Client spec: Clarify behavior of special platforms

[niklasmohrin]

Hey everyone, I am back with another client spec topic 😅

In our effort to make tealdeer behave closer to the client specification, we came to adding support for tldr --list --platform all as described in the row for the --list flag in the Arguments table. While the behavior for --list --platform all is clear to us, we don't agree on how the platform all should behave when used in other contexts like simple page lookup. Mainly, there are two different approaches that came up so far:

1. The platform all behaves like the current platform / as if no platform was specified at all, but for --list we keep in mind whether it was actually all or not.
2. We accept --platform all only for --list and error if the special platform is passed for other uses.

(some arguments for either side may be found in the linked comment)

I saw that the platform all is in the spec since the beginning (#2706) and there have been other issues about the behavior when several (independent) subsystems are used together (#4290). While I don't necessarily agree with all the details in the latter, I think that the specification should specify behavior for the special platform type and its meaning in all contexts in the platform section and explain the desired behavior. In a more general sense, the Arguments table should at least list all the possible values for each flag in the row of that flag itself - it was rather unintuitive to find a mention of --platform all for me at first.

Thank you for your work, I hope we can work something out :)

[dbrgn]

Thanks @niklasmohrin for creating this issue! I agree, this should be clarified.

I think that treating all like current - except for the places where considering all platforms makes sense (which is only --list, I think) - would be a very logical and easy to implement approach. If someone would specify -p all for another command, then it would simply work as it would without any -p argument (so it's essentially being ignored).

[sbrl]

Ah, great spot here. I wrote the original spec, so this is probably my fault as I probably didn't think of / foresee this problem at the time - so sorry about that haha 😅 This probably means that technically this is undefined behaviour in the context oft he current specification.

Indeed, we should absolutely clarify this. Both of those solutions would work - which one would you prefer? I feel like option 2 would be more semantically correct here since all doesn't make sense in the context of the page resolution algorithm?

Alternatively, we could update the spec to:

1. Remove the special platform all altogether
2. Add a new separate --list-all argument that lists all pages.

I feel like this option might make it cleaner and reduce confusion? Which solution would you prefer @dbrgn and @niklasmohrin?

[dbrgn]

Hm, if that's up for discussion, your suggestion 2 (--list-all) sounds like a much cleaner solution, because it avoids this whole ambiguity.

[niklasmohrin]

I personally don't like the "all = current" approach, I would be fine with --list-all or only accepting all when --list is used. I agree, --list-all would probably be the easiest solution. That would mean that --platform all would be removed and make that a breaking change, right?

[dbrgn]

PR: #7561

[dbrgn]

#7561 was merged! So this issue can be closed.