Proposal: Interpret {{-*|--*}} in the client

[Managor]

As discussed in #13466, this is to make it user configurable to show either longform or shortform options. It would allow for more pasteability. This would also be backwards compatible as we already use that notation. It would not break any existing clients.

[sebastiaanspeck]

This has also been discussed in #13466 which is closed with a reason

[Managor]

I don't see any closing statements about interpreting {{-*|--*}} in the client in that discussion. Only closing statements I see is that any metadata files are not worth it.

[SethFalco]

{{-*|--*}}

Do you want this syntax to actually be in the .md files in this repository?

I think the best way to implement this would be to create an offshoot project that has a new format

— #13466 (comment)

I see you proposed that we could also fork the project to do this, to avoid breaking clients. But imo, this has far more downsides than upsides.

For example:

• Unnecessary fragmentation of the community.
• Inevitability that most users/clients won't migrate, it'll just be tldr and botched-tldr.
• Annoying for client maintainers, creating forks isn't really a great alternative to breaking backward compatibility. If the spec introduces a breaking change (which we should minimize) a better approach would be to spec it first, and work with client maintainers to support it, then we can start using the syntax once enough users are on compatible clients. (And if we're in a rush, we can at least ask them to hard-code the latest compatible commit reference in their client.)

Is there any rush to get something like this in? Why not leave it on the backlog until a time we want to do an incompatible overhaul of the syntax in a new spec version. (If such a time ever arises.)

We're allowed to break compatibility sometimes, but there's no need to rush into it for a single change. tldr-pages is perfectly usable, and I'm not aware of any major complaints/demand regarding this, so it's probably worth leaving it on the roadmap.

---

Overall, I'm not against the idea, just against rushing into the idea. Though I do think it's worth getting more insight from users to see if it's actually valuable to them in practice. (Maybe a poll on Mastodon?)

In the end, the aim is to help people pick up the most common command-line arguments for tools they have installed, not to copy and paste commands blindly. I believe our current convention is to prefer long-form for that purpose, so users have more context on the command, which already achieves our goal quite well and is perfectly usable.

[Managor]

Do you want this syntax to actually be in the .md files in this repository?

We already use that syntax so only thing left is for the client to interpret it. This proposal is not about forking because it's not necessary.

[kbdharun]

@SethFalco Thanks for the comment, the previous discussion was about introducing a separate file to track the long/short option examples separate from the page/examples but it was dropped due to the infeasibility and risk of breaking clients.

The current discussion is a proposal to client specification to use our current {{-s|--long-option}} format and optionally display only the short/long options based on the user's configuration/flag passed, the default behaviour can be displaying both options as it is now.

[SethFalco]

Oh, I see! Sorry for missing the point there then, my fault!

We already use that syntax so only thing left is for the client to interpret it.

I honestly didn't know we had such a use for that syntax. (Goes to show how inactive I've been.) I was under the impression {{…|…|…}} was already formalized as an OR. That's how we use it in many places at least.

For example:

- Enable or disable remote administration:

`cupsctl {{--remote-admin|--no-remote-admin}}`

Do we have a good way for clients to tell apart OR from short/long-form alternatives? And what would we want to do if I wanted to write a page with an OR that uses a short or long form arg that aren't alternatives? 🤔

[kbdharun]

I honestly didn't know we had such a use for that syntax. (Goes to show how inactive I've been.) I was under the impression {{…|…|…}} was already formalized as an OR. That's how we use it in many places at least.

I totally forgot about the OR usage (thanks for reminding me of it xD), it's a valid use case for a lot of advanced pages. So I think clients implementing this flag/variable can distinguish it based on the presence of - or --, i.e. for short options it can be {{-a|-b|...}} and for long options, it could be {{--apple|--blackberry}}.

The original page implementation here can be {{-a|--apple|-b |--blackberry}} but we currently don't have any pages having something like this (so this combination would need to be documented in the style guide as a special case). I think for cases like there with multiple long/short options mnemonics would work the best since the above suggestion might be confusing to users.

[Managor]

For the initial implementation, I think it's safe to just make the detection as strict as possible. Only two options and only when one is has one hyphen and the other has two hyphens.
Now that I think about it, there are some commands that might have {{-s|-long-option}}, but I can't remember what those commands are.

[spageektti]

For the initial implementation, I think it's safe to just make the detection as strict as possible. Only two options and only when one is has one hyphen and the other has two hyphens. Now that I think about it, there are some commands that might have {{-s|-long-option}}, but I can't remember what those commands are.

We could also check the number of characters after - so the -long-option will work

[Managor]

Just throwing it out there. For the initial implementation we should still be as strict as possible and require one and two hyphens on each side.

[sbrl]

The character | generally suggests a boolean OR operation to me. As @SethFalco notes this isn't specific to long/short options, but can have many other uses as well. In a sense the convention you propose of {{-o|--output}} could be interpreted by both humans and machines using existing syntax - no client spec change needed.

My only concern would be causing some pages for some commands with lots of options to become visually cluttered, reducing readability.

As with our longform/shortform preference, I don't necessarily think this is a clear-cut thing. It's best down to people making their own judgement.

If we can reasonably assume that a command may be used a large number of times (obvious example here could be ls and others of a similar nature), then it is worth displaying the shortform options there.

Perhaps on other pages that are borderline we could adopt this {{-o|--option}} syntax?

tldr: the proposed long/short option syntax is used in other scenarios too. Could be useful as a convention though that doesn't require a client spec change to implement. Worth using judgement based on whether long/short or a combination of both arguments are worth showing in a tldr page while maintaining readability.

[Managor]

Perhaps on other pages that are borderline we could adopt this {{-o|--option}} syntax?

Git pages. This all started with a pull request where I tried to convert git pages to longform

#13441

In a sense the convention you propose of {{-o|--output}} could be interpreted by both humans and machines using existing syntax - no client spec change needed.

As said by @kbdharun this would be a configuration thing. It's an addition to existing functionality.

[SethFalco]

Thinking more on this, we have multiple collaborators referring to this feature as OR, not short/long-form alternatives. I think adding new meanings to an existing syntax will create too much confusion.

We can use the syntax in this way internally if that's desirable, it still adheres to the idea of being an OR. However, I think it's bad idea to formalize any distinction between OR and short/long-form alternatives for client implementors to deal with. It should just be treated as an OR and have no special or implied meaning based on flawed heuristics.

Part of the appeal to tldr-pages is its simplicity, and adding rules like this undermine that imo.

Clients may choose to implement such an idea, but I don't think that scenario should be covered by our spec.

I also like sbrl's take, to not use short/long-form alternatives everywhere, but more selectively. Maybe for commands that are used very often, or where the long-form variant brings more clarity to what the command does.

[fazlearefin]

Just want to point out not all applications follow -s (single dash) for short and --long (double dash) for long options.

Nuclei is such as example. See their usage section.

[Managor]

This has actually been discussed before #5092