search

tldr-pages / tldr

📚 Collaborative cheatsheets for console commands
https://tldr.sh
Other
51.09k stars 4.21k forks source link

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

Open Managor opened 2 months ago

Managor commented 2 months ago

As discussed in https://github.com/tldr-pages/tldr/issues/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 commented 2 months ago

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

Managor commented 2 months ago

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 commented 2 months ago

{{-*|--*}}

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

— https://github.com/tldr-pages/tldr/issues/13466#issuecomment-2322621911

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:

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 commented 2 months ago

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 commented 2 months ago

@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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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

https://github.com/tldr-pages/tldr/pull/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 commented 2 months ago

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 commented 2 months ago

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 commented 1 month ago

This has actually been discussed before https://github.com/tldr-pages/tldr/issues/5092