TLDR pages: Simplified, community-driven man pages

[b3kart]

Shout out to http://cht.sh, which could be used without installing anything:

  curl cht.sh/tr

[zackmorris]

Wow that's pretty great. There are so many powerful console utilities with overly opaque manuals that make them hard to jump into when you just want to do a simple thing. Compare these for example:

http://cht.sh/jq

https://www.systutorials.com/docs/linux/man/1-jq/

[streb-lo]

For .bash/.zshrc:

function cht() { curl cht.sh/$1 }

[GordonS]

Been using this for years, it's great!

Note that https://cheat.sh works too (I find that easier to remember than cht.sh)

[ivanfon]

Thank you, this is amazing! Simple ZSH/Bash function if anyone wants it:

  cheat () {
    curl "cheat.sh/$1"
  }

[SamBam]

Awesome. It looks like for the shell commands it uses content straight from TLDR, right?

e.g. http://cht.sh/tar

[hyperpallium]

How can I remove the colors from the output? It's hard to read on mobile (termux).

[bostonvaulter2]

Looks nice, although a benefit of tldr is that it can download the database so all when you look up a command it's not making a network request (which is good for both privacy and speed/reliability)

[ausjke]

amazing, just tested it out, i hope it can add devdocs.io support, and update vim plugin to newer ones. this will likely replace my tldr soon

[SanchoPanda]

  cheat() { 
   curl "http://cheat.sh/$1"
  }

  man2txt() {
    man "$1" | col -bx
  }

  manflags(){
    man "$1" | awk '{$1=$1;print}' | grep "^\-"
  } #man pages just the flags more or less, captures some extra 

  ubuman() { 
   w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/"$1".1.html"
  } # ubuntu web manpages note bionic, update with do release up

  ubumanflags() { 
   w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/$1.1.html" | \
   awk '{$1=$1;print}' | grep "^\-"
  } # ubuntu web manpages

  explain () {
    if [ "$#" -eq 0 ]; then
      while read  -p "Command: " cmd; do
        curl -Gs "https://www.mankier.com/api/v2/explain/?cols="$(tput cols) --data-urlencode "q=$cmd"
      done
      echo "Bye!"
    elif [ "$#" -eq 1 ]; then
      curl -Gs "https://www.mankier.com/api/v2/explain/?cols="$(tput cols) --data-urlencode "q=$1"
    else
      echo "Usage"
      echo "explain                  interactive mode."
      echo "explain 'cmd -o | ...'   one quoted command to explain it."
    fi
  }

# notetoself: check ```info``` check ```help``` check ```apropos``` check ```whatis```

[deadbunny]

You could improve the ubuman calls so you don't have to change every release:

  ubuman() { 
   w3m -dump "https://manpages.ubuntu.com/manpages/$(lsb_release -cs)/en/man1/"$1".1.html"
  }

[hultner]

Is there any app that combines all these alternative man-pages?

[SanchoPanda]

--

  tldr-web() {
   w3m -dump "https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md"
   w3m -dump "https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/linux/$1.md"
  }

[stared]

I would be happy to see such a thing taking off.

Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors).

However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_history / .zsh_history). Do you know any datasets with longer such?

[ddevault]

A heartfelt plea:

The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.

[diebeforei485]

No, they serve two different purposes.

Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept.

This is something different. It's a tutorial of how to do the most common things using that tool.

It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples?

Unless you've read formal specs for other languages with a similar paradigm before, it's way easier to learn from examples first, which gets you to the level of understanding where the formal specs start to make sense.

Improvements to man pages should be made, but not at the cost of beginner-friendly projects.

[overcast]

It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.

[jlg23]

Yes. The given example shows exactly what I would expect in the EXAMPLES section of a man page anyways. If not, it's worth a patch.

[topspin]

> The maintainers would be thrilled to have them.

Would they?

The tldr.sh site prominently offers a sample of usage examples for a command; tar specifically. If one checks the tar man page there are no examples. This is policy, apparently promulgated by GNU et al. in favor of "info". I haven't the time right now to hunt down the official position, but here[1] is a SO discussion.

Should this TLDR thing correct that long standing mistake I'm all for it. Also, info is one of the most hostile TUI programs I've ever encountered and I resent using it.

[1] https://unix.stackexchange.com/questions/306189/why-dont-man...

[omaranto]

I don't understand why this needs a client. Why not just install these as man pages in their own section and read them with man?

EDIT: My idea is of course not new, see https://github.com/joelekstrom/tldr-man for a way to convert these docs to man pages.

[rgoulter]

I've not used man enough to know the how to look up a particular section.

This is a good opportunity for me to compare the out-of-the-box results from tldr vs man:

https://tldr.ostera.io/man

https://linux.die.net/man/1/man

"Why not just install these as man pages in their own section and read them with man?" Because downloading the default program is much easier, most users aren't that concerned about adding a small CLI program on their computer, and most aren't that purist about right way to read documentation is through manpages.

[FabHK]

There was a previous HN discussion of "bro", can anyone comment on the differences?

"Bro pages: like man pages, but with examples only"

https://news.ycombinator.com/item?id=7121268

[fredley]

tldr has a better name.

[josephernest]

1) Great project!

Is there a simple way to install it without having to install Node.js or Haskell or Ruby? (I don't want to install Node.js just for it)

Is there a

    apt-get install tldr

solution on recent Debian / Ubuntu distros without installing another additional package manager?

I mean even the bash solution:

    bpkg ... 

does not work out of the box.

(bpkg or brew or npm aren't installed by default)

2) Is TLDR linked with the project cht.sh? e.g curl cht.sh/tar? Does it share a common source of documentation are they two totally different projects?

3) Few people won't remember tldr.ostera.io (I won't)... Ok we have bookmarks, but still, it would be more convenient if we could just do:

    tldr.sh/tar
    tldr.sh/git_push

instead of having to remember ostera.tldr.io oh no ostera.tldr.sh oh no tldr.ostera.sh no...

[dbrgn]

Regarding 1: Tealdeer provides static binaries for Linux. https://github.com/dbrgn/tealdeer/

[techplex]

There are many clients that are open source that you can use check these out: https://github.com/tldr-pages/tldr#clients

[upofadown]

This tends to be more of an issue with GNU programs that have info pages. You are not really supposed to use the man pages in that case. The info pages for GNU tar have lots of examples scattered throughout:

* http://www.gnu.org/software/tar/manual/

BSD systems, for example, have much better man pages that have an actual "EXAMPLES" section near the bottom.

[Brave-Steak]

The thing is - I don't want to go to some website or pour through pages and pages of documentation when I want to do one specific thing. I want to do something and move on with my life. My job isn't learning every command line switch under the job.

[brudgers]

a lively previous discussion, https://news.ycombinator.com/item?id=15779382

[dang]

Also 2015: https://news.ycombinator.com/item?id=10797303

Related from 2014: https://news.ycombinator.com/item?id=7166257

[overcast]

http://bropages.org/ is usually my goto. I learn by example, so naturally I despise man pages, and this makes it tolerable.

[rkangel]

Neither this, nor the traditional man page list of options is useful on its own. You need a detailed reference of the things you can do, and then you need examples for how to pull those things together in common usages.

For a code equivalent, Rust encourages function level documentation. This gives you detailed information on the full API surface and is vital, but if you only had that you wouldn't know where to start. Rust also has the 'examples' directory (I'm talking about a library project) which usually has a few executables that use the library.

[justinhensley]

tldr has been my daily driver for 1-2 years now, almost replacing man entirely. The community has contributed very useful examples.

I go to man once or twice for tools that are entirely new to me. Then, I use tldr until I have muscle memory or using a feature that is new to me.

[kccqzy]

Well, man pages cover more than just command-line utilities. These typically go in section 1 only. What about section 2 (system calls) or section 3 (library functions)? I guess the audience of this tool doesn't really need these?

[noodlesUK]

I think this is an indictment of how awful the man pages are on GNU/Linux systems. The man pages within the various *BSDs are a fantastic resource, as are their other documentation (e.g., the freebsd handbook).

[codesections]

I like the idea of tldr pages. Unfortunately, by default, they are a bit too slow to display—I know it's under a second, but it's just enough to break my flow.

Fortunately, there are other clients, some of which are much faster. My current favorite is tealdeer:https://github.com/dbrgn/tealdeer

[dbrgn]

Thanks for the shoutout :) It's funny that my weekend project that I wrote to learn Rust suddenly has almost 500 stars on GitHub...

[avsteele]

Examples are great because they give the curious user an idea of how to use the command in new ways.

[musicale]

I learned BSD largely from the man pages, but man pages on Linux distributions always felt a bit deficient to me, partly because of GNU utilities with placeholder man pages that just said "use info instead" and partly because of (at the time at least) many missing EXAMPLES sections.

I think they've improved greatly, but man pages on Debian, Ubuntu et al. still feel a bit like second-class citizens.

What TLDR pages seem to be getting right is putting EXAMPLES first or second rather than last, and/or having a command to bring up EXAMPLES.

Also I want to put in a plug for AUTHORS/HISTORY and BUGS sections. The former can create a sense of community and context and the latter can point out annoying gotchas.

[JdeBP]

Context, definitely. I have myself found them to be very useful. This is why I added HISTORY sections to the user manuals for some of Daniel J. Bernstein's tools when I converted them.

* http://cr.yp.to/daemontools/multilog.html

* http://jdebp.uk./Softwares/djbwares/guide/commands/multilog....

[1MachineElf]

Very useful. Thank you for supporting multiple platforms, and the MIT license.

[ebfe1]

I was inspired by cht.sh and wanted to have my own notes hosted without running a python server like cheat.sh so i ended up writing a silly static site generator using consolemd and ship it to surge.sh.Let me know what you think :)

https://github.com/santrancisco/cheat/

[stageleft]

This is very useful. It's essentially command-line cheat sheets, which are very handy for cmds you don't use every day.