Tldr: Document difference between folders

[aaronjanse]

We could put a README.md in linux, common, osx, etc, to document what each folder is intended to contain.

https://github.com/tldr-pages/tldr/pull/2808#issuecomment-468363191

[waldyrious]

It may be more appropriate to have the information in CONTRIBUTING.md, especially since one would have to scroll down quite a bit to get to the readmes in those folders, which typically have lots of files.

[aaronjanse]

How about this as a starting place for file placement recommendations:

1. If a command is shared between two or more of windows, linux, osx, and sunos, put the file in the commons folder (duplication is hard to maintain). If not, the file goes in the relevant folder (is _which_ folder self-explanatory?)
2. If an OS has a command with the same name as one correctly placed in the common folder, the OS-specific folder should have a file "overriding" the command in the commons folder.

folder | examples
--|--
common | echo, whoami-unix, zip
linux | distro package managers, tlp
sunos | svcadm, svcs
windows | choco, reg, whoami-windows

Is there a reason that the commons folder shouldn't be named "unix"? I can't think of any command shared between osx/linux/sunos and windows.

[agnivade]

1. If an OS has a command with the same name as one correctly placed in the common folder, the OS-specific folder should have a file "overriding" the command in the commons folder.

Yeah, but we don't need to rename the file to append the platform name. It is the job of the client to figure this out. In your example, the filename will be whoami.md in both common and windows folder.

Is there a reason that the commons folder shouldn't be named "unix"? I can't think of any command shared between osx/linux/sunos and windows.

Most(if not all) Python, Ruby, Node.js commands are shared between all platforms.

[aaronjanse]

That makes sense. I agree about what you said regarding the second part—the wording needs to be improved.

-------- Original Message --------
On Feb 28, 2019, 20:39, Agniva De Sarker wrote:

• If an OS has a command with the same name as one correctly placed in the common folder, the OS-specific folder should have a file "overriding" the command in the commons folder.

Yeah, but we don't need to rename the file to append the platform name. It is the job of the client to figure this out. In your example, the filename will be whoami.md in both common and windows folder.

Is there a reason that the commons folder shouldn't be named "unix"? I can't think of any command shared between osx/linux/sunos and windows.

Most(if not all) Python, Ruby, Node.js commands are shared between all platforms.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[sbrl]

As far as I'm aware, things in the common/ folder should work on _all_ defined platforms. If not, then we currently make a copy of a page in the folders for the platforms it _does_ support. Symbolic links have been suggested before in #787, but I'm unsure how far we got with that. I think there's a bug in the reference node client. It's certainly something we should consider for the client spec in #2706.

[aaronjanse]

Is there a reason we don't want to use a tag-based system, where the header of a file specifies which operating systems it works on?

That would solve the problem of duplication maintenance.

-------- Original Message --------
On Mar 1, 2019, 04:28, Starbeamrainbowlabs wrote:

As far as I'm aware, things in the common/ folder should work on all defined platforms. If not, then we currently make a copy of a page in the folders for the platforms it does support. Symbolic links have been suggested before in #787, but I'm unsure how far we got with that. I think there's a bug in the reference node client. It's certainly something we should consider for the client spec in #2706.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[agnivade]

As far as I'm aware, things in the common/ folder should work on _all_ defined platforms. If not, then we currently make a copy of a page in the folders for the platforms it _does_ support.

Yeah, I thought that too. But @waldyrious had a different thinking. And I think it's easier to just keep a page in common even if it does not work in windows, rather than making copies.

Is there a reason we don't want to use a tag-based system, where the header of a file specifies which operating systems it works on?

It's too late to change the core architecture now. All the clients look into folders for a specific platform. Let us just document the intended functionality and move on.

[sbrl]

Hrm. What happened with thee symlink idea? I think they should Just Work™ on Windows, but I don't have a Windows machine to test on.

[aaronjanse]

Perhaps each folder has a copy of a given command and a bot reminds contributers if a PR modifies only one of a set of files got a command?

Someone could then decide if it is intentional (i.e. the command should be have differently on different operating systems) or if a commit should be made manually to update the other pages before merging.

[sbrl]

Sounds like a good idea, @aaronduino! Maybe a message like this:

Hey! I've detected that there's another copy of the page for this command in {{platform}}.

It may need updating too.

We've actually got a bot that posts messages about linting errors over in https://github.com/tldr-pages/tldr-bot. Would you like to open a PR to add the functionality there?

[aaronjanse]

Thanks, I'll open a PR when I get home, unless someone else wants to do so sooner.

[aaronjanse]

Thanks, I'll open a PR when I get home, unless someone else wants to do so sooner.

Turns out I didn't end up doing something. I'm busy; if someone else is willing to make the PR, please do.

[sbrl]

An update: We now have a client spec that documents some of this, which is worth a look.