I'm opening this to serve as a discussion thread to decide whether we might want to simplify the pages' syntax.

The proposal is inspired on Inkscape's man page (source code), and uses a format that I believe is more readable for humans and machines alike, for several reasons:

• the main heading is changed from a # prefix to a row of ==== underneath, which makes it stand out more in plain text mode;
• the current syntax involves bullet (unordered) lists of command descriptions with code samples --the actual commands-- between them (rather than within each list item), which is both visually distracting in most markdown renderers, and semantically incorrect;
• the bullet list syntax was changed to plain paragraphs, which solves both the semantic issue, and a syntactic issue with some renderers not recognizing the code block if preceded by a list entry (case in point, from PR #758)
• the example code is now indented, so each description/code pair stands out better in the markdown source, and we can easily jump visually from example to example;
• the adding of indentation triggers markdown's code block formatting, so now we don't have to wrap the examples in backticks (which have been the source of many linting errors)
• by forgoing the backticks, the examples can be directly copied from the source markdown without the need to remove the backticks manually, which is more cumbersome than e.g. replacing tokens;
• since the markdown is more readable, clients don't need to be as sophisticated, opening the door to dumb "clients" like the one proposed in #527.

All in all, I believe this makes the pages be more inline with the markdown philosophy, which is to be human-readable, without the need for a renderer/client. Compare the plaintext source: before, after; and the github-rendered output: before, after.

But before this is discussed, we must come to agreement regarding which clients are officially supported, and what benchmark we'll hold third-party clients to in order to consider them semi-supported (i.e. we'd pledge not to break them without ample prior warning). Such an agreement might result in the clients currently in the tldr-pages umbrella going back to their original authors, or important third-party adopted under the tldr-pages umbrella (e.g. @ostera's tldr.jsx). Either option would simplify the way the project handles clients, by having a single client management model and a clear standard for clients to match. I'll open the discussion later (probably in a few weeks, as I currently don't have the time to get involved too deeply).

I noticed many names are used for this project, so I think it should be clarified. For example, you can find TL;DR pages, tldr, tldr pages and TLDR pages in various documents and website.

My suggestion is to use and tldr for the name of npm package and TLDR pages or tldr pages for everything else. How does that sound?

(copied form the conversation at #147)

The current folder structure looks like:

pages
  |__ common
  |   |__ tar.md         # gnu command everyone should have
  |   |__ ssh.md         # gnu command everyone should have
  |   |__ npm.md         # just a tool that could be installed on any OS
  |__ linux
  |   |__ emerge.md      # clearly a linux-only tool
  |__ osx
      |__ ssh.md         #  OSX has a different version with different flags

This has worked so far, but

• the split can feel arbitrary
• you need to jump around to see if a command is already covered
• clients potentially need to make a lot of requests to get a given page

There seems to be a consensus among clients to move to a flatter folder structure, that would look like this:

pages
   |__ tar.md
   |__ ssh.md
   |__ ssh.osx.md
   |__ emerge.md
   |__ npm.md

By default, we can display <command>.md, but <command>.<os>.md should have precedence if available.

This means the clients would let OSX users query Linux commands, but after all why not, they might just be curious about it. Or they might be using tldr on a Mac while SSHing on a Linux box that doesn't have it.

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

This would be a breaking change though, so we need a plan of attack. One option is to address all open PRs to get to a stable state, then copy all pages to the new structure. The old structure can live on for a while until all clients update. The PR guidelines would say to push changes to the new structure only.

Attempt to correct and normalize Chinese punctuation across all Chinese pages.

Note: I'm not a Chinese speaker, so there may be mistakes.

cc @einverne @mebeim cc @gyli @wizarot @starccy @ChungZH @zhouLion @xiaolong-666 @sandylaw @shanoaice @telnetning

Refs: #2897 #3426 #3442

What I've done so far:

• Change colons before "More information" links to Chinese colon
• Change colons at the end of example descriptsion to English colon per @mebeim's comment

Questions:

• What should period be at the end of page sentences in page descriptions? for sentences that end with English letters? for sentences that end with Chinese letters?

GitHub have recently added a new feature to the repository settings known as social preview:

Here's the associated blog post.

Should tldr-pages have a social preview image? If so, what image or screenshot should we use?

Background:

• https://github.com/tldr-pages/tldr/pull/744
• https://github.com/tldr-pages/tldr/wiki/Minimum-specifications-for-TLDR-command-line-clients

The tldr c client is now in the homebrew core available, and can simply be installed via

brew install tldr

without any taps required.

What's your opinion on promoting it more?

Hello @sbrl Pull request is created as you asked. I also generate an initial POT file for translators. More information in https://github.com/tldr-pages/tldr/issues/2339#issuecomment-451690015.

It would be nice if tldr pages existed in other (human) languages too, and not just English. Is there any plan for tldr pages to support multiple languages?

This is something that came up from a mention of the Sponsor button by @mebeim in Gitter: https://gitter.im/tldr-pages/tldr?at=5cf6cc683dcdab4003ed929d

This is part of the new GitHub Sponsors program, which is in beta.

At the moment, the GitHub Sponsors program probably isn't the best solution for tldr pages as it is more suited for individual sponsorships, and only supports up to 4 usernames per repository. Quite a few other projects are using OpenCollective as this works better for more people in an organisation. Although, GitHub mentions in their FAQ that:

GitHub is exploring ways to introduce sponsorships for teams of people that work on a single project.

To get started with adding sponsorship, we'd need to add a new YAML config in .github/FUNDING.yml. Currently it supports the following entries:

github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: # Replace with a single Open Collective username
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
custom: # Replace with a single custom sponsorship URL

Firstly, great tool. Thanks for creating it.

Some tools are pretty obsucure. In my case it was x_x. I came accross it by acident but I'm glad I did. The description caught my interest but searching for the repo wasn't as easy as a websearch.

It would be very helpful in this case, and I am sure others, if the pages included a link to a repo or a project page.

• [x] The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• [ ] The page(s) have at most 8 examples.
• [x] The page description(s) have links to documentation or a homepage.
• [x] The page(s) follow the content guidelines.
• [ ] The PR title conforms to the recommended templates.
• Version of the command being documented (if known):

• [ ] The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• [ ] The page(s) have at most 8 examples.
• [ ] The page description(s) have links to documentation or a homepage.
• [ ] The page(s) follow the content guidelines.
• [ ] The PR title conforms to the recommended templates.
• Version of the command being documented (if known):

Notes

This PR addresses this problem when it's not specified how to describe collection of characters (or other unsplittable objects). It's not possible to write smth like this: {{char1 char2 ...}} as it will be interpreted as a collection of space delimited characters which breaks expr index command. Or even worth it can be interpreted (it's not a generic placeholder, so interpretation is undefined and is up to contributors) as a some string literal consisting of 4 characters: c, h, a and r and some suffix (possibly number).

• [x] The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• [x] The page(s) have at most 8 examples.
• [x] The page description(s) have links to documentation or a homepage.
• [x] The page(s) follow the content guidelines.
• [x] The PR title conforms to the recommended templates.
• Version of the command being documented (if known):

#3953

• [ ] The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• [x] The page(s) have at most 8 examples.
• [x] The page description(s) have links to documentation or a homepage.
• [x] The page(s) follow the content guidelines.
• [x] The PR title conforms to the recommended templates.
• Version of the command being documented (if known):

closes #2068

Signed-off-by: K.B.Dharun Krishna [email protected]

• [x] The page(s) are in the correct platform directories: linux.
• [x] The page(s) have at most 8 examples.
• [x] The page description(s) have links to documentation or a homepage.
• [x] The page(s) follow the content guidelines.
• [x] The PR title conforms to the recommended templates.
• Version of the command being documented (if known): 1.1.4

Closes #9726

All options on this page are listed at https://documentation.vanillaos.org/docs/vso/manpage (I wrote the manpage myself ?? )

• [x] The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• [x] The page(s) have at most 8 examples.
• [x] The page description(s) have links to documentation or a homepage.
• [x] The page(s) follow the content guidelines.
• [x] The PR title conforms to the recommended templates.
• v2.1.0-RC4