Tldr: Pages where the title does not match the filename

[MasterOdin]

I originally posted this in https://github.com/tldr-pages/tldr-lint/issues/32#issuecomment-753515366, but moving this into an issue in the main repo to give it more visibility and community feedback.

One of the open issues for tldr-lint is https://github.com/tldr-pages/tldr-lint/issues/26: "Assert that the filename is the same as the page title". On implementing this lint rule, it introduces the following error against 7 pages. I have listed the 7 pages below, and what I think might make sense to resolve each.

The pages probably have a straight forward solution:

• ../tldr/pages/common/g++.md:0: TLDR108 Page title should match file name
  
  
  
  • Page is titled gplusplus, this could probably just rename title to g++?
  
  
• ../tldr/pages/common/gpg2.md:0: TLDR108 Page title should match file name
  
  
  
  • Page is titled gpg, this could probably just be change title to gpg2? All examples use gpg2, though convention between gpg and gpg2 at this point is muddled as increasingly gpg == gpg2 while the original gpg is just referenced as gpg1.
  
  
• ../tldr/pages/common/rg.md:0: TLDR108 Page title should match file name
  
  
  
  • Page is titled ripgrep, probably just rename title to rg and then add ripgrep to the description?
  
  
• ../tldr/pages/common/stolonctl.md:0: TLDR108 Page title should match file name
  
  
  
  • Page is titled Stolon which is the name of the service, probably just change title to Stolonctl and add Stolon to description?
  
  

These three pages are a bit weird:

• ../tldr/pages/linux/file-rename.md:0: TLDR108 Page title should match file name
• ../tldr/pages/linux/perl-rename.md:0: TLDR108 Page title should match file name
• ../tldr/pages/linux/prename.md:0: TLDR108 Page title should match file name

In each case, the installed command is rename, but the different filenames is necessary as these are all floating around and in common-use. Probably just rename the title in all cases, and not sure how important that the title matches the command in the examples versus matching the filename?

[bl-ue]

@MasterOdin, it's interesting that you brought this up, because I was earlier today thinking about proposing to remove the title entirely. It really doesn't make that much sense to have it, because the clients themselves can easily add it. It would also prevents discrepancies like the ones you've pointed out.

[bl-ue]

Page is titled ripgrep, probably just rename title and then add rg to the description?

Do you mean "add ripgrep to the description"?

[bl-ue]

@navarroaxel thoughts?

[MasterOdin]

Page is titled ripgrep, probably just rename title and then add rg to the description?

Do you mean "add ripgrep to the description"?

Yup, fixed.

[navarroaxel]

I think the title is a basic lint rule when you create a markdown file, so if someone wants to use the pages from tldr to build some website (e.g using jekyll) we need to have a title to avoid extra code.

[bl-ue]

I never thought of that. Good point. I wasn't even thinking of the pages in terms of basic markdown files.

[bl-ue]

@MasterOdin, here's what I've concluded, please correct me if I'm wrong:

1. For g++/gplusplus, change the title to match the filename, g++. If the filename can have +'s in, so can the title.

2. For gpg2/gpg1/gpg, gpg.md and gpg2.md are identical execept for example and wording choices. I think one of them should be removed, and the other one renamed to gpg.md. The title should match.

3. For rg/ripgrep, as the command is rg, so should the page name and title. I think mentioning that it's ripgrep in the description is a good idea.

4. For stolonctl/Stolon, the title should be stolonctl since that's what the filename and command name are. The description should probably contain something like manages the Stolon service somewhere.

5. For file-rename/perl-rename/prename, I agree with you that they're weird. They're all the exact same command, but with different names. Since on the different Linux distros they have different command names, make each title the same as the page name, since that's what the command itself is. It seems like @principis forgot to change the titles.

[bl-ue]

@navarroaxel do we support symlinks, so gpg2.md -> gpg.md? It seems like we should. Maybe I should open a separate issue for that.

[MasterOdin]

I am very much against symlinks in git repos as they do not work on Windows machines using cmd.exe (which I use here and there). I would ask very much that they do not be added here. If anything, I would suggest modifying gpg2.md to just say "Please refer to gpg instead for documentation" instead of the symlink.

[bl-ue]

I think so too @MasterOdin, I was just wondering if we have some solution that I'm not familiar with that @navarroaxel would point out. As for modifying gpg2.md, it seems to me like we should probably just make them indentical, because that's what we do here. (That should eventually be improved...)

[owenvoke]

I think it's worth keeping the seperate gpg and gpg2 pages. 👍🏻 And we can just have the title as the same as the page title. I think there's nothing wrong with it being gpg2 (people still know it's GPG). We could even have a note in each page saying something such as this:

See gpg2 for GNU Privacy Guard 2.