
TLDR pages: Simplified, community-driven man pages - lordgrenville
https://tldr.sh/
======
b3kart
Shout out to [http://cht.sh](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](http://cht.sh/jq)

[https://www.systutorials.com/docs/linux/man/1-jq/](https://www.systutorials.com/docs/linux/man/1-jq/)

~~~
fiatjaf
The jq manual is very very good.

~~~
pgwhalen
Completely agreed. I find my jq answers there more than anywhere else, and I
am continually amazed by its balance between accessibility and thoroughness.

I would also say though that this cheat sheet looks great as well - cheat
sheets absolutely have their place next manuals.

------
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```

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

~~~
SanchoPanda
I would just make it into one function, and call each one every time, with
headings seperated by figlet.

It would make a straightforward gui app for rofi or zenity or yad etc, with
only one input and just a list of output.

------
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?

~~~
reaperducer
_It may contain all information, but a clear F on UX._

What I find annoying is the number of command line programs that don't even
have man pages anymore. Or maybe that's just an artifact of installing them
with brew?

What I find interesting is that for the most part (there are exceptions), the
older the man page, the more useful it is. Realistic examples. Succinct
descriptions. User-friendly terminology. Too many of the newer man pages seem
inflated and full of jargon to make themselves seem important or worthy.

~~~
wongarsu
I don't think I've encountered anything on Ubuntu that doesn't have a man
page, but it also seems like many of the man pages are created or improved by
Debian or Ubuntu/Canonical. Homebrew probably wouldn't have those.

~~~
ilammy
> I don't think I've encountered anything on Ubuntu that doesn't have a man
> page

Ubuntu pull most of its packages from Debian, and Debian Policy says that
every package that provides binaries should provide manpages for them as well.
It is not a hard requirement but their absence is considered a bug.

------
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.

~~~
xorcist
There's no reason man pages can't be both.

Many man pages contain examples and common usages. See for example the rsync
man page, with complete examples of how to backup common file systems.

~~~
catalogia
One of the nice qualities of man pages is comprehensiveness, while one of the
nice qualities of tldr docs is succinctness. Both are mutually exclusive; man
pages cannot be both.

An examples section in a manpage is a fine idea which I would certainly
encourage, but that wouldn't render tldr obsolete.

~~~
jcl
Many man pages have examples, but they consistently bury them at the end,
after exhaustively covering every flag, file, or environment variable that
could possibly affect execution.

It might not be crazy to move the examples section to the top, since it would
more quickly provide what most readers are looking for: a sample command line
to tweak. Anyone who is genuinely looking for what a particular flag does is
just going to search for it anyway, so it doesn't really matter if that flag
appears on the 24th screen instead of the 23rd.

~~~
catalogia
Something I like about tldr is that tldr pages are short enough to not
necessitate using a pager, so you can print the tldr of a command and read it
while typing the command in the same terminal emulator.

I know you can disable the pager for man, but the typical manpage is going to
be fairly long anyway so the pager is generally desired. I suppose you could
pipe man through head to just print out the first section, but honestly tldr
seems to fill this niche better than I see that working.

~~~
jopsen
But they are not system specific... I don't need `tldr opkg` on my system.

In fact, having pages I don't need just causes confusion.

Moreover, commands can have system specific names.

~~~
catalogia
My tldr client has a --platform flag that takes 'linux, osx, sunos, or
common'. So there is some support there for platform-specific tldr pages at
least.

Also my tdlr-pages checkout is only 19MB, so I'm not too concerned about
bloat. I'm not really sure how having tldr's for irrelevant commands would be
a problem, maybe with some shell autocompletions? Maybe there is a way you
could prune the tldr-pages checkout?

I guess all I can really say is tldr works really well for me and I like it a
lot. Nothing is perfect, but tldr is quite nice despite some warts.

------
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](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://tldr.ostera.io/man)

[https://linux.die.net/man/1/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.

~~~
omaranto
I don't think tldr is a _small_ CLI program unless you already have Node.js
installed. :)

And I also don't see why installing that is easier than installing man pages,
if appropriately packaged. (I'm not claiming they are currently appropriately
packaged, I'm just saying that's what they could have done instead of writing
a client.)

~~~
therealjumbo
Debian has a package "tldr" implemented in haskell, that's under 1 MB.
[https://packages.debian.org/search?keywords=tldr](https://packages.debian.org/search?keywords=tldr)

I just found that and installed it after reading this thread. It looks like on
first run, like "tldr tar", it calls "git clone" on some repo. Thereafter,
other incantations like "tldr grep" use the already local repo. And the repo
can be updated with tldr --update. Seems very fast.

------
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](https://news.ycombinator.com/item?id=7121268)

~~~
fredley
tldr has a better name.

~~~
stared
Was BroPages name the only reason it hasn't gone mainstream?

~~~
capableweb
Yes, just like the only reason Facebook went mainstream was because of the
incredible 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/](https://github.com/dbrgn/tealdeer/)

------
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/](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.

~~~
b5n
It's just text - so all the text formatting/search/manipulation commands are
available to you. Manpages are really easy to use and navigate, given you use
them how they're meant to be used.

man man | grep -A 10 EXAMPLES

man tar | awk -F , '/-v,/ {print $2}'

~~~
Brave-Steak
Or I type ‘tldr’ and don’t waste my time? I swear to god, engineers are so
focused on efficiency and yet are so eager to waste so much time and effort on
repeating crap like this unnecessarily. Just think about the context switches
alone necessary to type all that.

~~~
b5n
It was easy for me, no context switching. I assume basic use of grep and awk
shouldn't be too much of a stretch for most Linux savvy engineers.

I'm happy TLDR fits your needs. I was just demonstrating how I use manpages
effectively in hopes it might assist you.

------
brudgers
a lively previous discussion,
[https://news.ycombinator.com/item?id=15779382](https://news.ycombinator.com/item?id=15779382)

~~~
dang
Also 2015:
[https://news.ycombinator.com/item?id=10797303](https://news.ycombinator.com/item?id=10797303)

Related from 2014:
[https://news.ycombinator.com/item?id=7166257](https://news.ycombinator.com/item?id=7166257)

------
overcast
[http://bropages.org/](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.

~~~
Brave-Steak
tldr doesn't remove man pages. You're free to check the man page for what
whatever flags used in a command in tldr mean.

------
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?

~~~
read_if_gay_
Of course some information will be omitted, that is the entire purpose of this
tool. What’s your point?

~~~
kccqzy
It doesn't just omit portions of the man pages deemed to be too long (detailed
descriptions). It omits entire man pages. That's the distinction.

I would expect such a tool to work so that whenever `man X` produces a long
document, searching for X in the tool produces a shortened, example-focused
documentation. This is not the case.

------
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](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://cr.yp.to/daemontools/multilog.html)

* [http://jdebp.uk./Softwares/djbwares/guide/commands/multilog....](http://jdebp.uk./Softwares/djbwares/guide/commands/multilog.xml)

------
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/](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.

------
kfrzcode
Laziness is surely not always the answer. I advise learning how to read man
pages. Eating your Wheaties, so to speak.

------
nathias
I've been using them for a while, they replace/improve man for most cases/

------
presiozo
Nice idea. Also, I think that an ELI5 command would be really useful, too

------
brian_herman__
[http://bropages.org/](http://bropages.org/)

------
Jemm
Fantastic.

Now please someone do something similar with Apple developer documentation.

------
FabHK
FWIW, can be installed on macOS with brew:

    
    
      brew install tldr
    

EDIT to add: and so can the faster (caching) Rust version (note: install one
or the other, not both, since they use the same `tldr` command)

    
    
      brew install tealdeer

~~~
ashton314
Woah. That's way faster. Thanks for mentioning this! I'll switch all my
machines over to tealdeer now.

------
drdebug
man pages sometimes have an EXAMPLES section, may be at some point these could
be merged (both ways?)

------
gyoza
Am I the only one who thinks... This is based on npm and this is the sole
reason to not even consider using it??

------
dvfjsdhgfv
[https://github.com/tldr-
pages/tldr/blob/master/pages/common/...](https://github.com/tldr-
pages/tldr/blob/master/pages/common/cpdf.md)

\- this is advertising dressed up as a "community man page"

------
zie
or just use a BSD which has this all built in.

------
BrianB
I would still reference man pages to see what the flags do in the tldr
examples.

------
bostonvaulter2
I love using tldr, it is great to have some nice succinct examples at the tip
of your fingers. And I love that the whole database is downloaded rather than
making a network request.

------
ajsharp
This is such a great idea. Praise fucking be.

------
ausjke
tldr is the tool I recommend to linux beginners, so they're not afraid of CLI

