Dealing with name collisions (in the same platform)

[pixelcmtd]

As was mentioned in #8674 (review), we should really consider what to do with multiple pages/commands of the same name (in the same platform). If you think that this is not a problem, a few examples:

• just and just
• q and q
• sm and sm (and sm)
• snap and snap
• gdu and gdu

Unfortunately, I hardly have any good idea of how to deal with these, but hopefully some of y'all are more creative on that side :)

[kbdharun]

Same issue with #9176 where both commands have snap name.

[blueskyson]

I suggest we rename just-js.md as just.1.md and release a new client spec, so that old clients won't break down and the collision page can still be found by tldr just.1. cc @marchersimon @sbrl @navarroaxel .

[kbdharun]

I suggest we rename jsut-js.md as just.1.md and release a new client spec, so that old clients won't break down and the collision page can still be found by tldr just.1.

This is a great idea. It would work just like man pages. But I am not sure if it would be feasible.

@navarroaxel @CleanMachine1 @mfrw @marchersimon What do you think about this?

[waldyrious]

I don't really like the use of numeric suffixes since they're pretty opaque and impossible to guess. We should find a pattern that is clearer yet still broadly applicable.

One such way to disambiguate the commands could be to prefix the author as a namespace (possibly with a @, like e.g. npm does). However, this would result in some cumbersome names, like @GoogleChromeLabs/sm (which doesn't even match the repository name, so would be extra confusing) and @natesales/q (instead of the much shorter q).

Perhaps an alternative that may work in practice is disambiguating based on the programming language used to write the tool, assuming that would be sufficient to avoid most collisions (e.g. just.js and just.rs, q.go and q.py), or even better, using the full name of the tool if one exists: sm would be screen-message (yes, the sm page we have is a third duplicate that doesn't match either of the ones listed above!), and rg (if hypothetically there was another tool with the same name) would be at ripgrep.

I would then suggest we reuse our existing approach for page aliases, and do something similar for disambiguation pages, which would be under the shared name, and would point to the disambiguated names as proposed in the previous paragraph. So we could have something like this:

# just

> `just` can refer to multiple commands with the same name.

- View documentation for the `just` command written in JavaScript:

`tldr just.js`

- View documentation for the `just` command written in Rust:

`tldr just.rs`

[sbrl]

I agree with @waldyrious here. We want to keep things as simple and transparent as possible. tldr-pages is almost like a wiki here - so it makes sense to have disambiguation pages too :-)

[waldyrious]

@pixelcmtd added stalebot ignore

Sorry for the off-topic, but I think we might want to add decision to the list of labels that stalebot ignores. WDYT?

[EmilyGraceSeville7cf]

There are several solutions I see.

Extend our page syntax to be able describe multiple commands with the same name

Commands should be delimited via smth like --- in this case:

{{first-command-page-content}}
---
{{second-command-page-content}}
...

But it results in the following issue: all commands with the same name will be listed at once for clients not supporting this feature. How to request a command examples in this case? Answer: assign tags to pages like Tags: one, two, three. (almost as we refer to other pages in See also) and filter pages by tags.

Using directories with command names with pages inside them

For instance if there are two commands bla and bla we:

• create a directory named bla
• create two pages inside it like bla/js.md and bla/perl.md (as two commands for instance are designed to work with JS and Perl respectively).

And again it requires changing our clients (but it's not an argument against such changes). 😄

[waldyrious]

@EmilySeville7cfg what are your thoughts regarding what I proposed above?

[EmilyGraceSeville7cf]

@waldyrious, it LGTM. :) I've just wanna add that it will not always work. What if there are two commands written in the same language but doing different things?

[waldyrious]

I don't think that is going to be a common occurrence, but in case it happens, we can always use a different disambiguation filename. This is how Wikipedia handles it: if there are two people named John Smith with different professions, the articles are titled "John Smith (astronaut)" and "John Smith (zoologist)"; if there are two people with the same name and profession, another criterion is used, e.g. "John Smith (American astronaut)" and "John Smith (Australian astronaut)", etc. So I don't think that would be a problem.

[pixelcmtd]

Sorry for the off-topic, but I think we might want to add decision to the list of labels that stalebot ignores. WDYT?

I'm probably the wrong one to comment on that as I think stalebot is one of the worst things that ever happened to open source, in general. But at least not closing some things is better than closing everything 🤷🏻‍♀️

We don't have pagers, which could make @EmilySeville7cfg's first suggestion an accessibility problem. For the second one: Breaking clients is an issue. If we can as easily avoid it, like here, I think we must not break clients as getting something into the client spec and then getting all clients to support it takes a lot of time and effort.

I've been wanting to make a suggestion very similar to @waldyrious's since early November. Imo using programming languages as suffixes doesn't make any sense, because why would I as the user care or even know what language a program is written in, also conflicts are still possible. My suggestion would be something like this:

# just

> `just` can refer to multiple commands with the same name.

- View documentation for the JavaScript runtime:

`tldr just.js`

- View documentation for the command runner:

`tldr just.rs`

# q

> `q` can refer to multiple commands with the same name.

- View documentation for the DNS client:

`tldr q.dns`

- View documentation for the SQL runtime:

`tldr q.sql`

# sm

> `sm` can refer to multiple commands with the same name.

- View documentation for the JavaScript runtime:

`tldr spidermonkey`

- View documentation for the command runner:

`tldr simplemake`

- View documentation for the tool to display large text:

`tldr screen-message`

If the colliding name is an acronym, using the expansion of that sounds like a good idea (especially if the colliding name is an alias of the expansion, like with spidermonkey). Otherwise we can use suffixes that are appropriate for the functionality, not the language. (I tried coming up with something better for just.rs, but it's sometimes hard)

[EmilyGraceSeville7cf]

There is just one problem with using extension IMO - editors will incorrectly recognize them as programs or scripts and suggest wrong syntax highlighting when we are dealing with TlDr pages. I guess we need smth to suppress such behavior (at least for this repo). No other issues I see.

[pixelcmtd]

There is just one problem with using extension IMO - editors will incorrectly recognize them as programs or scripts and suggest wrong syntax highlighting when we are dealing with TlDr pages. I guess we need smth to suppress such behavior (at least for this repo). No other issues I see.

Where does that happen? The real extension of the file is still .md, afaik all editors recognize just.js.md correctly as Markdown.

[EmilyGraceSeville7cf]

Ah, sorry. I thought that plain .js is going to be used. 😄

[waldyrious]

Good points, @pixelcmtd. As I mentioned to @EmilySeville7cfg in my previous comment, I didn't mean for programming languages to be the only disambiguation method, just the default one.

As a human consumer, I definitely think there's value in being able to disambiguate on more semantically relevant keywords: the full name (spidermonkey, simplemake, ...) is ideal if there's one, followed by the use case (dns, sql), and only then the programming language (js, rs) or user/org name.

However, we should consider the writing aspect as well: by not having a standard choice of disambiguation suffix, we are essentially kicking the can down the road, and then the decision needs to be taken every time a new disambiguation needs to be created, requiring more time and effort in the long run. Secondly, the programming language is not completely useless to the consumer — it's common for the programming language to determine the (primary) installation method, so it is indeed a semantically relevant token for the user. Thirdly, a free-form pattern could lead to suffixes that apply poorly to other languages, whereas the language extension is typically the same regardless of language.

That said, I suspect these disambiguation cases will be rare enough that the downsides I list above may not justify optimizing the filename for now. And in any case, we can adopt a different pattern later and rename the pages if we do decide it makes sense. So I'm ready to adhere to a standard of deciding the filename on a case-by-case basis (that's what you're suggesting, right?), if that's what emerges as the consensus in this discussion.

[waldyrious]

Regarding the extension ambiguity that @EmilySeville7cfg raised above: if we want to avoid the confusion with file extensions, we could perhaps use a different separator: instead of q.foobar.md, we could use, say, q-foobar.md or q_foobar.md, [email protected], etc.

[pixelcmtd]

However, we should consider the writing aspect as well: by not having a standard choice of disambiguation suffix, we are essentially kicking the can down the road, and then the decision needs to be taken every time a new disambiguation needs to be created, requiring more time and effort in the long run.

I've already had similar thoughts while writing up my suggestion above. With how few cases there are, it's definitely doable, but it's still an important consideration.

a free-form pattern could lead to suffixes that apply poorly to other languages

That's an important concern, thanks for raising it.

So I'm ready to adhere to a standard of deciding the filename on a case-by-case basis (that's what you're suggesting, right?), if that's what emerges as the consensus in this discussion.

No, that's not really what I was trying to suggest. I think we could write down some guidelines and leave the details to the page authors. My suggestions would look like this:

• If an instance of a command is an alias of another command, it shall refer to said other command (like an alias page, e.g. sm=spidermonkey)
• If an instance of a command is an acronym (needs some specifier, like "that is commonly associated with it"), its documentation shall reside at the long form of said acronym, with said instance referring to it (e.g. sm=simplemake)
• If an instance of a command has a use case (scenario/whatever) that can be summarized in one word (might need something like "that does not need translation in most languages"), its documentation shall reside at said command and use case interposed with a period (.), with said instance referring to it (e.g. just=just.js)
• Otherwise, it is up to the authors and maintainers to come up with a sensible name

While that would, of course, still kick the can down the road for the otherwise case, that's ⅐ of what I had above, which I'd be very much comfortable with.

if we want to avoid the confusion with file extensions, we could perhaps use a different separator: instead of q.foobar.md, we could use, say, q-foobar.md or q_foobar.md, [email protected], etc.

I already thought a bunch about that, too.

The problem with - is that it's already used (e.g. git-commit) and while that might allow for some cool syntax (tldr just js), it could also be hella confusing or at least, at times, annoying.
. is, unfortunately, pretty unusable, too. We already have a bunch of commands, like mkfs.*, which could cause some confusion.
There are like twice as many pages using _ already.
@ has not been used so far, the problem for me really is that it doesn't make any sense, there isn't a just "at" JavaScript or anything like that. I'd like it for an npm-like @org/tool syntax, but obviously we can't have that.

Idk maybe someone else has ideas for how to deal with that, it's New Year I got other stuff to do (drinking)

[pixelcmtd]

I had this in my head while writing the above but forgot to mention it in the end: We might be able to define disambiguation pages in a way so that they incorporate alias pages as a special case, superseding our old rules on them.

I was reminded of this because among some 1y old tabs I found #6367, in which I suggested an lld page that could look something like this:

# lld

> `lld` is a collection of multiple commands.

- View documentation for `ld.lld`, a replacement for GNU `ld`:

`tldr --platform linux ld`

- View documentation for `ld64.lld`, a replacement for Apple `ld`:

`tldr --platform osx ld`

- View documentation for `lld-link`, a replacement for Microsoft `link`:

`tldr --platform windows link`

- View documentation for `wasm-ld`, a WebAssembly linker:

`tldr wasm-ld`

That might look quite a bit different, but in essence it's the same idea that I think could be applied nicely in some other places. The only question is how to define all of that well...

[EmilyGraceSeville7cf]

The problem with - is that it's already used (e.g. git-commit) and while that might allow for some cool syntax (tldr just js), it could also be hella confusing or at least, at times, annoying.
. is, unfortunately, pretty unusable, too. We already have a bunch of commands, like mkfs.*, which could cause some confusion.

What about two consecutive dashes --?

[pixelcmtd]

What about two consecutive dashes --?

I don't really like the idea of having multiple characters as the separator, but it doesn't look too bad and works, so maybe

If I have too much free time later, I might check all clients I can for whether they support subdirectories of platforms, like you suggested earlier. / as a separator honestly sounds cooler and cooler the more I honestly think about it

[waldyrious]

I really like the idea of unifying disambiguation and alias pages! As long as we can come up with a phrasing that works well for both cases, I'm all for it :)

@ has not been used so far, the problem for me really is that it doesn't make any sense, there isn't a just "at" JavaScript or anything like that. I'd like it for an npm-like @org/tool syntax, but obviously we can't have that.

I actually find it pretty intuitive: if you think of e.g. email addresses (the original use case before it got somehow taken over to mean a username prefix, even though we already had ~ for that...), the part after the @ specifies precisely the domain, and this aligns nicely with our intent of disambiguation.

There are downsides I do see, though: one is that it makes the target pages seem like they're special, even though they're just regular pages. Another is that the character may be a little inconvenient to type (in my keyboard layout I have to press AltGr+2 to input it).

I would be more inclined to go with @EmilySeville7cfg's double-dash proposal than with subpages. IMO it would be good to keep the door open to directory structure changes in the future, and introducing a subpage functionality just because we don't like the separator characters would put us in a potentially more challenging situation regarding such changes in case we ever get around to implement them.

[Managor]

I have created a pull request to document this in the style guide. Review it if you have the time. #15749