Tldr: Should "fc" command be split?

[mflint]

Overview

The fc command for Windows is very different to fc commands for Linux and macOS:

For Windows, fc is a file-comparison tool, like diff. For Linux and macOS, it edits the most recent command in the shell history.

Representation in the index file

In the index file, it's considered a single command:

{"name":"fc","platform":["linux","osx","windows"],"language":["pt-BR","zh","en"]}

... so some list-based tldr clients will show it like this:

This is my iOS client; the implication here is that there's a single command fc with variants for three platforms - but this is misleading.

Proposal

I wonder whether this should be represented as two separate commands - one with Linux/macOS variants, and one with just a Windows variant.

{"name":"fc","platform":["linux","osx"],"language":["pt-BR","zh","en"]},
{"name":"fc","platform":["windows"],"language":["zh","en"]}

Then clients would be able to show these as distinct commands:

This would also help with search, when the platform cannot be implied. My iOS client can't know whether the user is sitting in front of a Windows or Linux box; so ideally, a search would show both the macOS/Linux _and_ the Windows fc as two distinct search results.

Concerns

I would worry that this might break some clients, who may assume that there are no duplicate name values. (Perhaps an implicit assumption, by internally using the name as a key in a hash.)

[sbrl]

Hey! Hrm, that seems a bit odd. I would agree here about the index structure.

Currently the client spec says that a page in common/ should be able to be overridden by an entry in a specific platform folder.

It looks like currently we have 3 copies of the in the 3 different platform folders though.

Which client is that please? We should @mention the author to get their opinion.

@agnivade?

Also, @pepa65, @felixonmars, @dbrgn?

[mflint]

@sbrl It's my iOS client. This isn't a fault with the client - it can't possibly know that fc (macOS/Linux) and fc (Windows) are two separate commands.

My suggestion is that the single entry in the index should be split into two. This will be particularly useful when displaying search results, as I display search results with a short description from the first platform of the command.

In this example, iOS Spotlight Search is showing "Open the most recent command and edit it", which was taken from the description for the Linux platform. This unfortunately means that the Windows fc is invisible from the search results. Ideally, I would be able to show both fc commands in these search results.

[agnivade]

One of our basic assumptions is that commands in multiple platforms with the same name are the same. This seems to be a one-off case where that doesn't seem to be the case.

To fix this, we would need to add a metadata in our page structure mentioning that windows fc is not the same as linux fc. And then consider that metadata as part of the key along with the page name.

And as @mflint has correctly pointed out, this will break client relying on the index format.

In this example, iOS Spotlight Search is showing "Open the most recent command and edit it", which was taken from the description for the Linux platform. This unfortunately means that the Windows fc is invisible from the search results.

I have a minor suggestion which might alleviate the issue to some extent. If you differentiate the variants of the commands based on platforms, this will automatically resolve the issue. i.e. - instead of showing only linux based commands, you can show commands from all platforms. If a page is in multiple platforms, show them with page (windows), page (linux). And since you are also showing the page header, a command with the same name will have a different heading and will also stand out to the user.

This has the advantage of showing more accurate information to the user if the command they searched exist in multiple platforms or not, and also differentiating between commands with the same name.

The node client also shows the platform name along with the command, when you search for something.

Given the cost vs benefits of this problem, I think this may be a possible solution. WDYT ?

[mflint]

@agnivade I wasn't proposing a change to the format of the index file - just splitting the existing fc command so it exists twice in the index.

Your idea of including the platform is worth considering - I was already considering it in-app, for favourites, etc.

[pepa65]

Nothing in the spec says that the same commandname on different platforms is the same utility. If a client has made that assumption, then the fc command can be used to check for undesirable consequences.

Now if you split the entry up, the spec doesn't say there should not be multiple names, but some clients might break. The tldr-bash-client works fine either way, and it also doesn't show any lists (like above) suggesting fc is the same command on all platforms where it exists.

So I have no objections to splitting this entry up if it helps ios-tldr-viewer, but there might be unintended/undesirable consequences for other clients!

[agnivade]

We cannot just split up the existing command without changing the logic by which the index is created. So that will involve adding a metadata in the page. Is there a way to do that without affecting the page structure ? I am afraid changing the page structure also might break some clients.

[pepa65]

@agnivade I think changing the name to fc (windows) and fc (linux/osx) would do the job and is the least likely to break clients, but it's not so versatile, and you're putting metadata where is doesn't belong. How do clients know that linux/fc and osx/fc are the same command? Diffing the pages?? But what if say the osx page includes one more example? Is it still the same command??

Maybe clients that want to show information that hasn't been put into the data structure (like the problem that just showed up on the ios-tldr-viewer with fc) should either not do that, or start diffing pages themselves..?

[mflint]

Thanks for all the ideas - I can't see a good solution here.

@pepa65 you're absolutely right about metadata not belonging in the name value, and diffing the pages will be too fragile.

@agnivade I understand now - thank-you for your patience. You're right - it's not easy to split, because the index is generated from the pages.

I'll close this :-)

[agnivade]

I am not saying clients should diff pages. To show the platform name is just an indication that there is another page with the same name in another platform. It may or may not be the same command, but just an indication. Not the best solution, but I guess that's the best we can come up given the choices we have. :)

[sbrl]

Perhaps opening an issue against the iOS client to better differentiate between different versions of the 'same' command on different platforms would be worth doing?

[mflint]

Perhaps opening an issue against the iOS client to better differentiate between different versions of the 'same' command on different platforms would be worth doing?

_I am_ the iOS client!

[sbrl]

Ah, I see! Oops lol, I didn't realise :P