How to handle mixed casing of titles and filenames

[MasterOdin]

Typing this issue up from recent discussion on gitter.

Currently, most pages use filenames that are lowercased, even if the command that they document utilizes capital letters.

common/pages/R.md is an example of a page who has the file name and title using capitals.

windows/pages/get-content.md is a page where the file name is lowercased and the title/command uses capitals.

While man itself is case sensitive (presumably given Linux's case sensitivity), I do not think it makes sense to apply this to tldr, given that people are using this repo on a range of systems, some case sensitive and some case insensitive. For example, macOS is case insensitive, and so it's possible to refer to any command listed with any capitalization (e.g. I could always use
Python3 /path/to/script.py), and so mandating memorization of capitalization does not really make sense. Similarly, I could use r to refer to R.

My vote on the resolution of this would be:

1. Mandate all pages file names are always lowercased
2. Page title / command examples can be mixed case per whatever the recommended usage examples from developer are
3. (page file name).toLowerCase() === (page title).toLowerCase()

The benefits of this approach imo would be:

1. Easier to implement on clients if page file names are always lower cased (e.g. Commands with uppercase names are not supported leostera/tldr.jsx#166 would not happen)
2. Users can type any case for a string and get information back, leading to easier discoverability

[sbrl]

I think for the linter to work the page name must exactly and case-sensitively match the page name, but I can't remember. So the linter needs to be considered here.

I like the idea of having page name in lowercase, but I'm somewhat concerned that if we encounter 2 commands with different functions but the same name and different casings we'll have an issue.

Murphy's Law: If it can happen, it will happen.

[bl-ue]

+1 for title = pagename = lowercase. @sbrl I can't think of any example where two commands with the same name, but different casing, have different functionality. That does not seem likely at all, to me.

[MasterOdin]

To add to this, letting in pages with different cases, but same letters (say common/R.md and common/r.md) will lead to weird irregularities in working on this repo (and maybe also clients) for people on Windows and macOS.

[sbrl]

Oops, looks like my previous comments didn't come out right. I'm in favour of:

• filename: lowercase (but an exact match here would be better)
• page title: exactly matching the command name (case-sensitive)

[sbrl]

Example of different commands, same letters:

$ r
Command 'r' not found, but can be installed with:
sudo apt install r-cran-littler
sbrl@Ramblewood:~$ R
Command 'R' not found, but can be installed with:
sudo apt install r-base-core

[bl-ue]

Hmm...that's tricky. I'm not sure what to do about that. As @MasterOdin said, macOS is case-insensitive, and so is Windows, so that situation isn't possible on those OSes.

[MasterOdin]

I think for the linter to work the page name must exactly and case-sensitively match the page name, but I can't remember. So the linter needs to be considered here.

@sbrl The linter currently does not do anything with file names. Support for that is being added in tldr-pages/tldr-lint#32 which I will update to support with the decision on this topic.

[MasterOdin]

I have updated the PR above to include a rule mandating lowercase file names. Similar to what was done with 0.0.9 release, once 0.0.10 (or whatever) is released, I will make a new issue that bundles all pages that now fail validation into a single master issue to track updating them all.

[bl-ue]

Nice.

[waldyrious]

According to this comment, a consensus hasn't been reached yet. Let's reopen and close once there's a clear agreement on how to proceed.

[waldyrious]

My 2 cents: yes, there will be pages with the same name and different casing, but it's equally possible for two tools to exist with exactly the same name in the same platform (see Homebrew/homebrew-core#65438 for an example). That means that allowing case differences may alleviate the problem somewhat, but will not solve it completely, while making things way too nuanced and potentially confusing for those used to case-insensitive platforms (not to mention potential git issues as @MasterOdin mentioned above).

My vote, then, is to force all filenames to be lowercase, but allow the page titles to match the command's preferred name, as originally proposed above, as well as in the opening comment. Any objections?

[MasterOdin]

The situation already exists within tldr of multiple commands with the same name:

• https://github.com/tldr-pages/tldr/blob/master/pages/linux/file-rename.md
• https://github.com/tldr-pages/tldr/blob/master/pages/linux/rename.md
• https://github.com/tldr-pages/tldr/blob/master/pages/linux/perl-rename.md
• https://github.com/tldr-pages/tldr/blob/master/pages/linux/prename.md

I would also like to express that it's not just git that will be a problem, it will also be actual usage of the clients. If you have two pages R.md and r.md, I will be unable to view them with how the node client (and others) works. When the zip is downloaded and expanded, one of those files will clobber the other one (no guarantee which probably), and at best, trying to see tldr R and tldr r will show the same page, but at that point, I'd consider this undefined behavior so who knows.

[bl-ue]

Here's some more commands with the exact same name and casing (and different functionality entirely), for example the more popular bat and less popular bat, and the relevant issue: sharkdp/bat#164 😄

[schneiderl]

My opinion on this would be similar to @waldyrious.
But when this issue does happen, when someone tries to create a document with a name that is already being used by another command, how we plan on fixing it?
Or will we consider that the first command to get there will own that page forever?

[sbrl]

My vote, then, is to force all filenames to be lowercase, but allow the page titles to match the command's preferred name, as originally proposed above, as well as in the opening comment. Any objections?

That sounds like a sensible thing to do. The filename should match the command name in lowercase then, I take it?

[waldyrious]

The filename should match the command name in lowercase then, I take it?

In most cases, yes, but we we can't make that an absolute rule because of the additional cases that @MasterOdin mentioned in his comment. More on this below.

But when this issue does happen, when someone tries to create a document with a name that is already being used by another command, how we plan on fixing it?
Or will we consider that the first command to get there will own that page forever?

A better approach IMO would be to handle these in a case-by-case basis. But maybe we can come up with a strategy that allows for disambiguation in all cases. Typically package managers use namespacing to resolve this issue, i.e. the tool is referred in the format @owner/tool or @project/tool. We already a version of this, somewhat, by splitting the tools by platform. We could further use the owner/project prefix for those that still conflict (i.e. project-tool.md, or tool.project.md). Thoughts?

[MasterOdin]

This discussion is now veering into territory covered by #5071, which is directly discussing how to handle an actual existing instance of this (rename commands) that exists in the tldr repo.

[sbrl]

Hrm. Sounds like the issue is complex enough that we can't really enforce any of this via linter rules, except maybe the "always lowercase" bit.

[waldyrious]

This discussion is now veering into territory covered by #5071, which is directly discussing how to handle an actual existing instance of this (rename commands) that exists in the tldr repo.

Drat! Sorry for the diversion. I'll try to follow the discussion there. In any case, for this one, I think we can all agree with (1) making all filenames lowercase, and (2) not forcing the filename to match the title within. All in favor say "aye"! :P

[bl-ue]

Aye! 😄

[schneiderl]

Aye! 😃

[sbrl]

Aye!

lol

[waldyrious]

In retrospect, I should have asked whether anyone has objections :)

Anyway, there doesn't seem to be objections, so the only thing left to do is to implement the rules in tldr-linter. We can close this issue once that's done :)

[bl-ue]

@waldyrious I didn't notice this part—

and (2) not forcing the filename to match the title within.

You mean they don't have to match case or they don't have to match at all?

[sbrl]

@bl-ue I think the idea there is that they don't have to match case.

[schneiderl]

This got closed after thisgot merged.

I believe the merged PR covers all the topics we discussed here.
Fixes for the aforementioned pages will be kept track of here.

If anyone still have anything to discuss on this matter, please reopen the issue.

[bl-ue]

I wonder if clients will support this. e.g. tldr eye3D might fail for some clients because eyeD3 is documented in eyed3.md 🤔