Proposal: mechanism for command aliases

[bl-ue]

We need a system for command aliases. For a very few examples:

• Some shells have a chdir command which is internally aliased to cd
• Docker Desktop (for Mac, at least), provides a command com.docker.cli which is aliased to docker
• On macOS (with Homebrew, at least), gcc has aliases gcc-10 and x86_64-apple-darwin20-gcc-10
• many, many, many more, particularly with commands and versions of those commands.

Our current solution to this issue is to duplicate the pages, updating the page title and the command itself in the examples. We haven't officially decided to do this; it's just what happens.

It's not a very good solution though because then we have to maintain two copies of the page, which means more work for translators, normal contributors, and maintainers alike.

I've thought of a few solutions so far:

1. ❌ I've thought before of an idea where all pages have YAML front matter at the top which defines some metadata about the page. It would be applied to every page, because there are opportunities where we might want to store metadata like that. We could store a key alias: true and source: source_cmd (or original: original_cmd). The then clients would check for that and read the source page and print it out, updating the page title and the command used in the examples. Unfortunately however, this requires a major change to the client spec. So we've discarded this idea.

2. 🥇 My latest idea is that instead of duplicating the source page and updating the title and command names, we create a new page with contents such as these:

   # speedtest
   
   > This command is an alias of `speedtest-cli`.
   
   - View documentation for the original command:
   
   `tldr speedtest-cli`

   with the link intentionally omitted.
   The pros with this idea is that it's still simple and valid markdown, and requires no changes to the clients in order to be applied.

---

Note: per #5300 speedtest is not an alias for speedtest-cli, it's actually the official CLI as opposed to a non-official (but very popular, 10.5k ⭐s) alternative. But I'll just keep the example above to get the point across.

[sbrl]

I like this idea, though this is almost a duplicate of #787. It uses the existing syntax, and doesn't necessitate a client update.

It doesn't handle copies of a command across multiple platforms, but this issue was previously resolved by putting anyn pages for commands that are present on more than 1 platform in common, instead of limiting common to commands that run on all existing platforms.

If this gets a positive response from others, I think we can close both this issue and #787 too.

I support!

[bl-ue]

Does anyone have a preference of the wording: This command is an alias of ... vs. This command is aliased to ...?

I prefer the former, as the latter implies that this command is actually a real alias (in the shell sense) to an existing command, but in reality, most 'aliased' commands are either shell scripts which run the original, or, in the more unfortunate cases, duplicate binaries.

[bl-ue]

We might need a new label, too, because users may very well add missing aliases. I think we should definitely do that.

I think this is a good color: #778004

[sbrl]

This command is an alias of ...

Sounds better.

Hrm, I'm not sure a new label will really be needed.

[bl-ue]

Are you sure? because what if someone opens a new PR just to add an alias. Actually, I think new command would probably work for that 👍🏻

[sbrl]

I think new command would be fine.

[bl-ue]

Well, with #5368, I guess we've integrated the system. Here's a test:

$ tldr -u
✔ Updating...
✔ Creating index...
$ tldr mscore

  mscore

  This command is an alias of musescore.

  - View documentation for the original command:
    tldr musescore


See also: musescore


$ tldr musescore

  musescore

  MuseScore 3 sheet music editor.
  More information: https://musescore.org/en/handbook/3/command-line-options.

  - Use a specific audio driver:
    musescore --audio-driver jack|alsa|portaudio|pulse

  - Set the MP3 output bitrate in kbit/s:
    musescore --bitrate bitrate

  - Start MuseScore in debug mode:
    musescore --debug

  - Enable experimental features, such as layers:
    musescore --experimental

  - Export the given file to the specified output file. The file type depends on the given extension:
    musescore --export-to output_file input_file

  - Print a diff between the given scores:
    musescore --diff path/to/file1 path/to/file2

  - Specify a MIDI import operations file:
    musescore --midi-operations path/to/file


$ 

[waldyrious]

Hmm, I'm tempted. On the one hand it would be nice to save users an unnecessary step to reach the information they want; on the other hand, making an automatic jump (as a symlink would do) can be a little bit too magical, and obscure the fact that the user is seeing the content for a page that's not exactly what they typed.

I'm tentatively in favor of this, but I'd call @chrisallenlane from cheat, @srsudar from eg, and @denisidoro from navi for comments, as they might have pondered this as well. Feel free to ping others who may have thoughts on this!

[srsudar]

We first considered literal symlinks but decided against it because git apparently doesn't handle them well on windows. I didn't have a windows machine to try on myself, but you can see a collaborator's comment here.

In the end we went with an aliases.json file that contains the mappings. So eg fgrep opens directly to grep. This is slightly magical, as you mention, but the first line of all the example files states # command right at the top, so hopefully you don't completely miss it. The examples are static as well, so you don't see fgrep "foo" but grep "foo". A similar approach for you wouldn't require a client update, I don't think, as old clients would just ignore the aliases.json file (that is a total guess, so I might be wrong).

I don't really have any strong opinions on that approach. It works so smoothly that I'd forgotten we'd added it. It's definitely better than duplicating the commands, I think. It's also an easy thing for users to edit themselves if they have their own aliases. I don't know enough about how tldr works to know if that is relevant to you.

A potential benefit is one less click, as it were. Any command that is normally used by an alias might be frustrating for users that prefer one or the other. Eg I thought that rg was an alias for ripgrep (though apparently it's not), and I always use rg. If ripgrep were the canonical one, I might find tldr rg followed by a reminder and then tldr ripgrep mildly tedious.

Whatever you go with, though, sounds like a great improvement!

[bl-ue]

I like the aliases.json approach for mainly one reason: it would allow us to effectively document subcommands even if there are aliases for the parent command (see #5407 for details)

A similar approach for you wouldn't require a client update, I don't think, as old clients would just ignore the aliases.json file (that is a total guess, so I might be wrong).

Of course, client updates prevent us from moving quickly (which isn't always wrong). The benefit of this approach is that, though clients will need to be modified to support this, you're right, they would just ignore aliases.json (unless they do odd things), and so they wouldn't be broken and we can take our time as needed.

A potential benefit is one less click, as it were. Any command that is normally used by an alias might be frustrating for users that prefer one or the other. Eg I thought that rg was an alias for ripgrep (though apparently it's not), and I always use rg. If ripgrep were the canonical one, I might find tldr rg followed by a reminder and then tldr ripgrep mildly tedious.

I completely agree with this sentiment. "mildly" at first, perhaps, but more and more it can become quite exasperating, I'd say.

I'd warrant it wouldn't be difficult for the clients to intercept the title and change it to the correct, e.g. print the title fgrep even though the page (and its title) is grep, since it's being linked to as fgrep.

[waldyrious]

Thanks for the great insights, @srsudar! If I may just add a small note: one of the things in favor of @bl-ue's proposal of alias pages is that they're "low-tech", i.e. even a very dumb "client" that simply cats the contents of the pages/ directory (or, for that matter, any client that hasn't migrated to support aliases.json) would be able to provide the value of aliases to the users.

[srsudar]

Yeah that makes sense, it's a very nice middle ground. I didn't realize you supported such diverse clients.

One thing I didn't mention but I'm remembering now is that we also display the aliases like so when we eg --list (note clang -> gcc).

This still doesn't help your very simple clients, but might help reduce the magic factor I think (although I have no idea how many actually care about the fact that we display this).

Legend:
    + only custom files
    * custom and default files
      only default files (no symbol)

Programs supported by eg:
adb
awk *
brctl
brew
cat
cd
chmod
chown
clang -> gcc *
clang++ -> gcc *
conda +
cp *

[sbrl]

Haha yeah @srsudar, we have an absolutely enormous list of clients lol, and they are all developed by different people :P

[patricedenis]

Hi, all.
I approve as well the low-tech approach.
Sound's really nice and friendly approach both for users and clients specs (that don't need to evolve for this issue to be solved).
In that case, everyone would benefit the aliases just by updating the index database.

[sbrl]

It looks like we've decided on the alias page mechanism we're going with, and it's already in use (e.g. aria2).

Does everyone agree we can close this issue now?

[patricedenis]

That's OK for me !

[sbrl]

Ok, I'm going to close this issue for now. However, if anyone has something else to mention, we can always re-open and continue the discussion.