Commands that have different names among distros

[blueskyson]

For #7578. There exist some commands which have different name in different distros. For example:

Distro	lid in libuser	lid in id-utils
Debian	rename to libuser-lid	lid
Redhat	lid	no package
Arch	lid (AUR)	rename to lid-idutils (AUR)

Currently there is no document for dealing with such situation. I personally think that making a new template for the rare cases is not a good idea, because it only makes guideline more complex. Here are 2 solutions I thought about:

1. Create pages of different names with almost same examples.
2. Create alias page to deal with different names. (Maybe add some information about distro.)

Any idea?

[sbrl]

If I recall, there's was a command a while back where we had some serious trouble like this, but I can't remember what it was called, or the solution we put in place.

I'd advise giving the variants different names, and use a see also to reference them - assuming that the variants have different incompatible functionality and there is not a common denominator.

Should there be a common denominator though, it's perhaps better to document that instead and have 1 page instead of multiple.

[cyqsimon]

There are several ways we can view this issue:

1. From the binary perspective: same binary, but packaged under different names
2. From the distro perspective: different binaries having a naming conflict
3. From the "naive user" perspective: TLDR is misleading me

What I'm trying to say is that the solution is not straight-forward at all. It's not easy to implement a system that's both "clean" from a code perspective, and make it easy and convenient to use from a user perspective, not to mention the effort required to update the protocol/format/standard and have various clients implement them.

[cyqsimon]

A potential solution I'm thinking of is "the Wikipedia solution". I.e. Simply have a disambiguation page as the main landing page for the name in question, which lists tldr commands to show the actual pages for the respective binaries. So that would look something like this, using lid as an example:

lid.md

# lid (disambiguation)

> Two packages provide binaries named `lid`: `libuser` and `id-utils`.

- libuser-lid: Display a user's groups or a group's users.

`tldr libuser-lid`

- id-utils-lid: Query ID database and report results.

`tldr id-utils-lid`

libuser-lid.md

# libuser-lid

> Display a user's groups or a group's users.
> Alias on Debian-based distros: `libuser-lid`
> More information: <https://manned.org/lid.8>.

- Show a user's groups (primary and secondary):

`sudo lid {{user}}`

- Show a group's users:

`sudo lid --group {{group}}`

id-utils-lid.md

# id-utils-lid

> Query ID database and report results.
> Alias on Arch-based distros: `lid-idutils`
> More information: <TODO>.

- Examples here

`echo todo`

This solution has the advantage of not requiring clients to be updated. Old TLDR clients can simply treat the disambiguation page as any other regular page, and it only requires one extra command from the user, which I don't think is that big of a deal.

Of course, clients can be updated to simply match on the string (disambiguation) (or any other string, as long as we standardise it) in the title line, and display a selection interface to the user. But that would be an optional feature that's up to the client to implement.

[blueskyson]

@cyqsimon Your solution is great.

[cyqsimon]

A few checklist items, if the Wikipedia solution is to be adopted:

• Formalise the marker string for a disambiguation page
  • Current proposed: (disambiguation)
  • Or should we considering using a special symbol? (Probably not but it's worth asking)
• Formalise the package-binary delimiter
  • Current proposed: - (e.g. libuser-lid.md)
  • Should we perhaps consider using _ instead? I'm suggesting this because some binaries contain -(s) in their names
• Update documentation regarding policy and recommendation for client programs

I'll add more if they come to mind.

[cyqsimon]

No no, you're completely misunderstanding the relationship between libuser-lid and id-utils-lid. They are two completely different binaries in two completely unrelated packages, NOT simple aliases. I would encourage you to get several VMs (Arch, Fedora, Debian) and play around a bit.

As of why I suggest we have a "disambiguation string", this is so that from a client perspective it's easy to differentiate a normal page from a disambiguation (or you may call it "redirection") page. The client program may be modified to handle such pages differently, so you might get something like this:

$ tldr lid
  Two packages provide binaries named `lid`: `libuser` and `id-utils`.
    1. libuser-lid: Display a user's groups or a group's users.
    2. id-utils-lid: Query ID database and report results.
  Please select one by its id:
> 1
  Display a user's groups or a group's users.
  Alias on Debian-based distros: `libuser-lid`
  More information: <https://manned.org/lid.8>.
  Show a user's groups (primary and secondary):
      sudo lid user
  Show a group's users:
      sudo lid --group group

Of course old clients without a special implementation for disambiguation pages will still work - they can simply treat the disambiguation page as a regular page since it conforms to all the specifications of a regular page. Then the user simply has to run the tldr command suggested by the disambiguation page to get the actual documentation.

[cyqsimon]

What I am implicitly saying, is that the markdown file name should be a unique identifier for a binary, rather than a 1-to-1 match for its actual name on a particular distro. Much like how on Wikipedia, https://en.wikipedia.org/wiki/Python points to the disambiguation page, while python (as in snake) resides in https://en.wikipedia.org/wiki/Pythonidae, and Python (as in language) resides in https://en.wikipedia.org/wiki/Python_(programming_language).

[blueskyson]

Oh, I understand the concept of Wikipedia solution. Then you can just implement it in your PR. You may explain this with the Wikipedia python example to other maintainers since this is a new idea of tldr.

[cyqsimon]

Doesn't tldr have a formal RFC-like process for big changes like this? I'm happy to implement my PR this way of course, but I would like to see more discussion before merging my changes, just in case there are pitfalls we haven't managed to catch.

After all, this would set a precedence and if so, it would be nice if we first formalise it as a standard.

[CleanMachine1]

I think we should keep this simple and un-reliant of clients being updated since that will cause a lot of issues since some which are used aren't actively updated.

My suggestion, doesn't match the page name unfortunately however, my suggestion is to add a note to the lid.md page and mention a See also like in other pages

then make some new pages called lid-arch.md and then lid-redhat.md

The ubuntu page should probably be the top lid page since ubuntu is the most used Linux distro

edit, didn't read the other solutions but some of this suggestion still stands.

[EmilyGraceSeville7cf]

Create alias page to deal with different names. (Maybe add some information about distro.)

Creating alias is the right option just in case two commands are identical in their behavior and the only difference is their names. :)

[Waples]

Sup other mods? Are you still working on this or can we clean this up?

[sebastiaanspeck]

Any update on this? So we can close/merge #7578

[sbrl]

Hey there, @sebastiaanspeck, @Waples! It looks like this issue was created more as a discussion point about what to do in a specific case. It seems like a decision was reached by @MasterOdin, so this is really just blocking on #7578.

I would agree with @MasterOdin in that a See also is the best solution in this specific case.

[kbdharun]

Any update on this? So we can close/merge #7578

We can follow the same approach as just page I guess.

[sebastiaanspeck]

It has been a month and nothing happened to the PR or this issue. When are we going to take over the PR and close this issue?

[sbrl]

@sebastiaanspeck I've commented on the PR. Thanks for the reminder, I think we've all been avoiding the messiness of this specific issue.

I wouldn't rush this one, but thanks again for the reminder.

[sebastiaanspeck]

Absolutely no need to rush, just a friendly reminder we still have some work to do :)

[sbrl]

Now that #7578 is closed, I believe we can close this one too.

The adopted solution is to align page names to Debian's binary names, due to the fact that Debian is the most popular base distro. Then,

if the binary is shipped under an alias on another non-Debian-based distro:

We add the following line before More information::

> On <insert distro>, this program is installed as `<insert alias>`.

if the name is taken by another program on another non-Debian-based distro (i.e. needs disambiguation):

We add the following line before More information::

> On <insert distro>, the binary name `<insert name>` is taken by another program. See `tldr <insert Debian name for that program>`.

---

Consider the command lid from the id-utils package, and lid from the libuser package.

The solution here is to document id-utils's lid under lid.md, and document libuser's lid under libuser-lid.md. This is in alignment with Debian's naming.

Then, we added a disambiguation note to lid.md pointing to libuser-lid.md. Conversely, we added an alias note to libuser-lid.md pointing to lid.md.

---

Note that this solution ONLY covers the very specific case of "commands that have conflicting names across various linux distros", NOT the more general case of "commands have conflicting names". That should probably be discussed and decided on a case-by-case basis.

If this explanation is incorrect, I hereby give permission for maintainers to edit this comment to keep the history of this issue tidy, so long as you leave a changelog behind.

[cyqsimon]

@sbrl I've made quite a few amendments and clarifications. Also I've reduced the scope of applicability because I'd rather this solution be narrow and well-defined than broad and loose. Please take a look, thanks.