Suggesting both long/short options for commands

[EmilyGraceSeville7cf]

What do you think about suggesting both long/short options for commands like in the sample below:

# awk
- Execute a script:

`awk {{--file|-f}} {{path/to/script.awk}}`

- Check a script for syntax errors:

`awk {{--lint|-L}} {{--file|-f}} {{path/to/script.awk}}`

? There is just one reason why I am not sure this is a good idea: such options may be interpreted by users as some arbitrary values. Maybe it would be better to define special syntax for declaring joined long/short options and a way how clients can switch between long/short options while displaying pages smth like tldr -so|--short-options awk. While personally I prefer long options due to their readability short options are faster to type and there are too many commands providing short options too (or just them). 🤔

[blueskyson]

I think this feature is doable by defining a long/short dictionary such as:

dicts/awk.md

--file: -f
--lint: -L

Switch tokens according to dictionary file when one runs tldr --short-options awk.

But I feel few people need this feature...

[sbrl]

Hrm, while a dictionary idea sounds cool, remember that some commands that variants depending on platform (rename is just 1 example). Also, it complicates the format pages are stored on disk, which would make them less human-readable.

Traditionally, we've used short options for pages where the command is used very frequently (e.g. ls), and long options elsewhere / where it's ambiguous. There's not a hard and fast rule to it.

[genivia-inc]

I like this suggestion to include both long and short option forms, but it may perhaps be too much grammatical baggage for the casual reader to digest. The dictionary idea is cool too.

The short options only make sense if they have a common meaning among a group of tools in a certain category of utilities, @sbri is right about this and I've hinted at this in #7750. For example, file system manipulation and search tools cp, rm, mv, ls, grep and others use -r and -R for recursion. Option -l is often used for long listing (ls) or for producing a list of results (grep). Option -v is often verbose output and -V is often version information. Options -P (or -p) and -S (or -H) have traditionally meant to (not) follow symlinks, though as you can see the choice of short option in this case is not unique, so this case is debatable. The point is that to always require long options for common short options with a well-defined meaning is not helpful for users to digest and looks frankly odd to me.

It would perhaps go too far to define a pre-defined list of short option meanings? If the meaning of the short option of a tool matches an item on the list, then it can be used in favor of long options. This could sort out any confusion. It allows a short option for a tool if the option is common among a category of commands to which the tool belongs. I think that by itself such a list might be useful to remember.

A short list of standard command line short options is published here: https://tldp.org/LDP/abs/html/standard-options.html

Just my 2c.

[genivia-inc]

Another possibility is to highlight the short option letter in the long option name, for example with an underline:

A white background makes this more visible:

The red and blue colors are hard to see on a terminal with dark background. I always prefer to use green and magenta, with red and cyan only when boldface (highlight). In any case bold/highlight makes green, red, magenta and cyan pop and much better visible.

PS. I made a typo in the last diff line, should be --unified with underlined u.

PPS. this is what it looks like with bold ANSI SGR color schemes and replacing blue with cyan:

Or what about this color scheme, which separates the command from the options and arguments more clearly:

[EmilyGraceSeville7cf]

The syntax may be:

# awk
- Execute a script:

`awk --[f]ile {{path/to/script.awk}}`

and for a letter with different case ([upper:<letter>] or [lower:<letter>]):

- Check a script for syntax errors:

`awk --[upper:l]int --[f]ile {{path/to/script.awk}`

Escaping must via \ be allowed for [ and ]. For the first case we can just highlight single letter in [ ] and for the second we can expand code sample to two examples:

- Check a script for syntax errors:

`awk --lint --[f]ile {{path/to/script.awk}`
`awk -L --[f]ile {{path/to/script.awk}`

In the situation when there are no intersecting letters in short and long options we can write smth like this: command [-<short-option>|--<long-option>] and also expand one code sample to the pair while rendering page.

[sbrl]

@genivia-inc a cool idea, but remember that we can't enforce a single colour scheme on the user's terminal.

@EmilySeville7cfg Interesting syntax ideas, but I feel we need to be wary of 2 things:

1. Breaking client spec change (remembering also the https://distrowatch.com/dwres.php?resource=man-pages client which probably hasn't been updated in a loooong time)
2. Beginner users who will most likely type a command out exactly as they see it in a tldr page, and then wonder why it doesn't work

[genivia-inc]

@genivia-inc a cool idea, but remember that we can't enforce a single colour scheme on the user's terminal.

It is not my suggestion to create multiple color schemes. Sorry if this is confusing, but the current color scheme doesn't work for me, showing blue on black that is almost unreadable. It is far worse for blue backgrounds. Blue backgrounds are not uncommon. Bold cyan (my suggestion) works for both dark and light backgrounds, unless someone uses cyan as a background, which is unlikely IMHO.

[EmilyGraceSeville7cf]

2. Beginner users who will most likely type a command out exactly as they see it in a tldr page, and then wonder why it doesn't work

This problem is already exist: some pages suggest alternative syntax for command line arguments and we can't just copy this commands and make them work because used | character is likely to be interpreted in shell as "pipe". Also we can't completely guarantee that any chosen char instead of | is safe because different shells have different syntax (maybe very strange). ;)

[sbrl]

Sorry if this is confusing, but the current color scheme doesn't work for me, showing blue on black that is almost unreadable.

Right, but that's a client-specific issue, @genivia-inc. I recommend either looking for documentation on changing the colour scheme of your client, or filing a bug against it.

This problem is already exist

True

[genivia-inc]

Sorry if this is confusing, but the current color scheme doesn't work for me, showing blue on black that is almost unreadable.

Right, but that's a client-specific issue, @genivia-inc. I recommend either looking for documentation on changing the colour scheme of your client, or filing a bug against it.

So, you're basically saying that we, the users & contributors are wrong?

Where does the tldr man page tell me how to change the color scheme? I should reconfig my terminal instead? Just so I can use tldr?

I never heard of tldr before. It was disappointing that it wasn't legible on my terminal with a common color scheme. No offense, but this leaves a bad smell, an impression of an amateurish project.

[sbrl]

No, I'm not saying that you as a user are wrong here, @genivia-inc. I'm simply saying that if you have an issue with the colour scheme of tldr pages, this is not the right place to report it. This repository is exclusively for the tldr pages themselves. tldr pages has an extensive list of clients, all of which work differently, have different default settings, and different default colour schemes.

The only thing in this repository that governs their functionality is our official client spec, which as far as I know makes no mention of colour schemes.

We're happy to help, but it's important to report issues to the right place :-)

Where does the tldr man page tell me how to change the color scheme?

Without knowing which client you're using, I can't advise on this issue as I've explained. If you're unsure which client you're using, we can help you determine this if you can remember how you installed tldr.

Finally, we're happy to discuss your issues with colour schemes further, but I'd advise that you open a separate issue to do this.