Tldr: Criteria for supported platforms should be documented in contributing guidelines

[colinmorris]

Forking this as a separate issue off #1960 (/#1930).

When creating a new command, it's not always clear what pages subdirectory(s) it should go in.

I think it's especially tricky to judge whether a command is considered to run on Windows. Since it has almost no native commands that overlap with those on the other (unix-based) OSes, but it does have various ways to run many of them via ports, emulators, compatibility layers, virtualization, etc. It's not at all clear which among these are considered legitimate for the purposes of this repository, and different contributors seem to have different ideas about this.

So it'd be great to have a canonical, consensus definition written down somewhere for what it means for command X to run on platform Y.

[agnivade]

@waldyrious - Do you want to take this up ?

[waldyrious]

@waldyrious - Do you want to take this up ?

I'd be happy to add the note to the docs, and I agree that this is a problem. But do we have a "canonical, consensus definition written down somewhere for what it means for command X to run on platform Y"? I believe the main issue here is to reach that consensus -- writing it down is the easy part. :)

So with that said, does anyone want to make a proposal we could discuss/refine?

[agnivade]

The primary problem is with windows. Since there are bash emulators and then you have things like cygwin. We just need to draw a hard line on what is and what is not permissible by the definition.

Just my thinking.

[waldyrious]

I'm not sure I'm convinced that the common folder should be for commands that are available (installable? compilable? runnable?) on all platforms. For one, the list of platforms we cover is not exhaustive and can always expand as long as people are up to contribute the content.

More importantly, unless we're going for "native" or "traditionally available" definitions, technically pretty much all commands can be used in all platform, with more or less work, so the distinctions start to vanish. At least I can't think of a "hard line" that wouldn't be kind of arbitrary.

I feel like a more useful system is to use the common folder for all commands that have a single variant, and the platform-specific folders for the outliers (e.g. GNU vs. BSD commands that show up commonly in linux vs. macos differences, and the Windows-specific commands like dir).

This is a hard problem (see #816 for some additional nuances regarding BSD), but I can see that you guys have already thought a great deal about this, so I'm looking forward to hear your opinions.

[sbrl]

Personally, I like the ideas presented in #190. Would that solve this issue too? What do you think, @colinmorris?

[colinmorris]

That's an interesting proposal, but I don't think it eliminates the problem described here, because it still entails making decisions about which commands are supported by which platforms. e.g. in order to judge whether ${foo}.osx.md should exist. It also talks about putting platform constraints in the pages. e.g.

To clear up platform constraints, the description for emerge for example could say "for Linux" or "Gentoo specific command".

[agnivade]

A more recent issue was opened https://github.com/tldr-pages/tldr/issues/2813 on this. Let's track that there.