TLDR pages: Simplified, community-driven man pages | Hacker News Reader

TLDR pages: Simplified, community-driven man pages

tldr.sh

628 pointslordgrenville167 comments

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

  curl cht.sh/tr

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

I have yet to see node.js API support from any REPL or shell or vim or tldr, the only option is access it from browser, which is not enough.

https://zealdocs.org is another great source, similar to https://devdocs.io

Grandparent just showed how to use it on the command-line, with curl.

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/

The jq manual is very very good.

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.

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

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

For .bash/.zshrc:

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

Been using this for years, it's great!

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

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

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

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

Aside from things like ansifilter you can add a ?style=bw parameter to remove the colors, e.g.

    $ curl cht.sh/ls?style=bw

Or if you do like colors but not the defaults you can try other styles, see http://cht.sh/:styles

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)

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

  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"
  }

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"
  }

I like that, thank you.

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

If you want, you can alias man to call `tldr $1` or `curl -s "cht.sh/tar" 2>&1` first, then call man, then pipe the output into `cat` and again into `less`, like so:

  man() {
      (tldr $1 ; man $1) | cat | less
  }

Edit: rewrote without the `&&` conditional

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.

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?

Also, I see that there are other similar projects: https://www.ostechnix.com/3-good-alternatives-man-pages-ever...

Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out.

tldr caters to an entirely different heuristic: I have this use case, give me a list of use cases and the corresponding combination of switches, options and arguments for each respective use case. tldr won't explain to you what each individual switch, option or argument does, turning the provided commands into black boxes.

Here's the trade off:

The former has a steep learning curve and figuring out how a tool works doesn't solve your immediate problem. But if you commit the meaning of switches, options and arguments for common tools such as awk, sed, tar, ls,... to memory, you will become proficient at solving any problem with a few tools over time.

The latter has a low learning curve and you just have to copy/paste a command to solve your problem. But tldr won't tell you how those switches and options work. And you will just use them as incantations that magically help you to solve a limited number of cases. If you end up with a use case that isn't listed, you are left in the dark as far as tldr is concerned.

So, is tldr a bad tool then? No! If you are confronted with the command line sparingly, then tldr helps to lower the bar and solve your immediate problem. But if you hope to grow into a proficient shell user, then you're still going to have to grok the man pages one switch, option and argument at a time.

I'm a polyglot. Studying a language by opening a dictionary and starting alphabetically, is arguably, the worst way to get there. You would start with learning a set of common words and basic grammatical rules, and then expand over time through practice and instruction: speaking, reading and writing.

The same applies to command line tools and man pages: they are reference materials first and foremost.

I frequently use TLDR, and I wouldn't describe it as an incantation. It's for the case where, say, I know there's a grep flag for inverse match or case-insensitive, but don't use it often enough to remember it. It surfaces the (community-driven) top use cases, and it's pretty clear from the context what the flags are doing. (As seen here: https://github.com/tldr-pages/tldr/blob/master/pages/common/... ) If I don't see my use-case in tldr I'll move on to the man page.

OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)

> it's pretty clear from the context

I think that largely depends on who's using the tools and how acquainted they are with command line tools. An absolute beginner likely will not know what tar's 'f' flag does, or assume something else.

> OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)

And I absolutely have no qualms doing the same when push comes to shove. Ain't nobody always got the time. ;-)

I will bite - I have been using linux for 4 years. I have used tar a lot and I don't know what v means. I switch between -xvf, -xvz, etc.

x - extract | f - file | z - operating on tar.gz or similar.

Edit: v - verbose

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

On OpenBSD (and other systems using mandoc as the default “man” program), I can jump to an unknown flag right away with the pager’s tag support: “:tv”

    -v      Verbose operation mode.  If -v is specified multiple times or if
            the -t option is also specified, tar will use a long format for
            listing files, similar to ls(1) -l.

Or I can tack #v onto the end of the web URL: https://man.openbsd.org/tar.1#v

That doesn't preclude them from including examples of the most commonly used flags and scenarios.

Man pages for newer tools, like all of the lvm utilities, include examples at the end.

I would like to see it similar to what powershell has with their examples built into the documentation.

> Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out.

No, thankfully.

Try `man man | col -b | grep EXAMPLES`

(As an example, grep was finding EX but not EXA. Man told me I could pipe to col -b to strip formatting, hinting the issue might be special characters. This was quite helpful of them, even if it isn't strictly "man's responsibility".

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.

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.

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

I have added packages to Homebrew, and they install man pages when available. Homebrew provides a pretty simple mechanism for doing so. The problem is that many projects just prefer web documents to man pages, likely because the man page tooling is not great.

and because it doesn't work on windows

Some ecosystems even eschew manpages. For example, I wouldn't know how to ship manpages as part of a Ruby gem, it's discouraged iirc

For a ruby gem you would most likely use the --help flag. This has the advantage of working on sub commands so you can do `gemname command --help` and get more specific help.

Git has subcommands and still ships man pages. They just put a dash into the name. E.g. `man git-fetch`

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

A messed-up MANPATH environment variable can also cause man pages to not be found. In ‘man’ used on many flavors of Linux, MANPATH behaves differently from, say, PATH: an empty colon-delimited section means something like “use the system’s regular ‘man’ configuration for finding man pages”. Without that, it seems like a bad MANPATH setting will cause default mannpages not to be found.

> inflated and full of jargon to make themselves seem important or worthy

It's simply a lot harder to explain things in simple language, so I'd hesitate to ascribe such intent.

I'm also interested in a `.bash_history` kind of dataset. If you become aware of this, I'd love to see such a thing.

It's true that the man pages aren't meant to be the primary method of learning Unix. But they are indeed a spectacular and irreplaceable resource.

One of the best things that ever happened in my career was having a desk across from the entire SunOS manual set. I'd pull them down one at a time and read them, cover to cover. It paid off, big time, and I strongly recommend it.

I was a bio major who would hang out in rooms with terminals in the early 90s.

One day I saw “type ‘man man’” and “apropos” written on a chalk board.

That is how I learned Unix.

Interestingly, actual bona fide AT&T System 5 Release 3 Unix had a "help" command, which was a full-screen menu-driven interactive help system.

* https://unix.stackexchange.com/a/448799/5132

There was also "learn", in BSD as I recall.

This is sadly the case with lots of Linux tools, but it's not really man's fault. Next time you need help with a UNIX tool, try reading the OpenBSD man page instead and see how it compares.

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.

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.

On Linux that has been my experience. man pages on Mac are a little better, I've heard the BSDs do better as well.

Do you have examples of that refusal? I'm unfamiliar.

Based on my experience, the problem may be that man pages are often not where one learns how to use a tool. I still remember from long, long ago when I told a greybeard that I was trying to learn sed by reading the man page. He replied, "God help you," and guffawed.

While some man pages have examples, I don't know if man page writers see their job as teaching readers how to use a utility. The goal of man pages more often seems to be _reminding_ a person already familiar with the tool how to use a tool.

I'm, umm, _reminded_ of project READMEs. I've come to assume that when I go to a project on GitHub, I'm going to get everything I need (or pointers to everything I need) to get started with a project, but often there's a project web site that is intended to serve that purpose. I just ran into this yesterday with Falcor.

Not all man pages are like this obviously. Specifically, the section three man pages on C functions do a good job fully documenting functions.

The more complex a tool, the less likely a man page is going to be a good way to distill and impart the information of how to use it. Bash's mane page is so large I can almost never find what I'm looking for.

At the same time, that means a TL;DR type page is also likely to be useless. For the vast majority of software run from a shell, a man page is sufficient, and examples can be (and often are) added to good effect.

I will note that some projects split very large man pages into sub-pages, and that can work well. For example, ip, and much of the man pages on BSDs that explain how different technologies are implemented (for example, follow the references in the man page for ifconfig on OpenBSD).

By virtue of the fact that TLDR and bropages exist? People are creating 3rd party solutions, because no one does anything with man pages.

Doesn't GNU still scoff at man pages and foist texinfo? Honestly who wants to waste their time with roff etc?

The focus has been making it easier for the developers to write literally anything. One thing uses sphynx another uses man another uses doxygen or what the hell ever. Users aren't developers. This is why everyone ends up on google and ends up on stackoverflow or random blog or watching youtube.

The barrier to entry is much lower with some simple markdown thing. Hell, I was thinking about how to abuse this thing to make my own notes about commands.

I maintain my man pages in markdown format, and convert them to roff at build time. There are plenty of tools that can do that: pandoc(1), ronn(1), ...

The maintainer of the manpages project, Michael Kerrisk, is quite responsive and interested in improvements. I've generally found the maintainers of other software to be receptive to documentation patches, as well.

I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.

I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.

Just start with the assumption that no one understands how to read a man page and how to translate that into a full command line operation. A simple example goes A LONG WAY.

Back in 2000-2005 I worked on the SQL Server documentation.

If I remember correctly, when we instrumented the docs we found that the VAST majority of users skipped over all the descriptions and parameter definitions, and jumped straight to the examples of usage. Turns out observation is the fastest way to learn/remember. We redoubled our efforts to include examples of more obscure usage patterns, rather than relying on wordy explanations.

That's EXACTLY what I do. I imagine there are some that are great at reading white papers, but I am not one of them, and I'm not alone. Experience > Education.

You don't need to know what other people don't know. Just provide a copy/paste of the most common use cases and a line explaining what they do.

> I'm not sure what this has to do with Kerrisk

Because the man-pages project that he maintains provides the largest set of third-party manpages (outside the project trees themselves). The majority of manpages live either in the project they document or in the man-pages project.

> I don't know why this has to be met with so much friction.

The point of this thread is that it will often not be met with friction. Examples should be in a combination of the summary and examples sections of the manpages. (Distinct modes of operation belong in the summary, more fine-grained examples go in the examples section.

> They know best how it works

But they don't necessarily know best what usage patterns work well for people who are not maintainer-level experts.

I see a strong case for having separate texts for documenting the interface (striving for completeness and low redundancy) and introductory teaching. I don't think that I'd like seeing each man page prepended with a wordy ELIF and two pages of trivial examples. And I'm not saying this because I'd not need the ELIF, quite the opposite, I just don't think that it would be wise to mix them.

Having them maintained in one place, passed through the same distribution channels and available on the command line, now that would great of course. The minimum almost-requirement for a crowdsourcing effort for that content could be a contribution licence that is 100% compatible with the real thing, not 99%, not 99.99. Just in case.

Doesn't each project maintain its own man pages? There is a huge variation in quality between them with some being excellent while others are lacking.

Have you tried talking to any of the projects?

I use manpages frequently, seems easier to learn how to read manpages than create a new project dedicated to adding examples to manpages. I find them incredibly user friendly, but I cared enough to learn how to use them.

I dunno, the TLDR page highlighted tar which seems a bit odd since tar has always gone out of its way to have a very strong and useful manpage - specifically having several examples[1] at the top of the page before diving into all the intricacies of the arguments.

1. Including tar -cf and tar -xf probably the two you want to run in most cases. See: https://linux.die.net/man/1/tar

I'd guess this is a xkcd reference.

https://www.xkcd.com/1168/

it's not the same use-case, manpages are detailed instructions, tldr is just the 7 most used commands

manpages often have an examples section on OpenBSD showcasing different ways to use programs. It can be done...

How is this "rapidly decaying third-party documentation" in any way that man isn't?

man is universally known in the industry, and supported (to some extent, at least) by project authors/maintainers; this project will be forgotten by almost everyone (and start decaying) as soon as this post is off the front page here.

They're often used, but I suspect most people who read them don't know how to write or even modify a man page. (What format is it?) Also, Stack Overflow probably gets more traffic.

Whether documentation gets read or not probably depends on its Google ranking more than anything.

This is the second time it's been on the front page, and the last time was years ago. Doesn't seem to be decaying. Actually, it seems to be improving.

man pages are first-party, are they not?

Documentation by the makers of a program would be first-party.

Something definitely can't be both first-party and community.

Ideally this information would be controlled by the individual package maintainers, I agree.

However, realistically at the moment I don't see man pages competing with the spirit of tldr/bro/whatever, and I suspect that PRs geared towards making them compete would in fact be rejected by most projects.

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.

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

I'm aware of GBU's preference for info but systems vary. Just to use your example, I'm typing this on Slackware and when I pull up man tar there are three examples, right after Synopsis and Description. Examples for extracting, both gzipped and regular archives, and creating a tar file are given.

And when I shell into an OpenBSD server their man page for tar has several examples at the bottom of the page.

Man, IMO, is a lot like Linux distros in that they are not all created equal, pull from a lot of different sources and can be inconsistent if you're not looking at the correct ones for whatever system you are on.

I too think TLDR is a good idea but that's no reason not to encourage that some of their work be ported back to man pages in their examples' sections.

A quick survey of GNU tar man pages, by program version and the date that appears in the page itself:

   1.23 March, 2012:    no examples (RHEL 6)
   1.26 March, 2015:    no examples (OpenSUSE 13.1)
   1.26 February, 2016: no examples (CentOS 7)
   1.29 March, 2016:    limited examples (Ubuntu 1804)

The last has no actual "EXAMPLES" section in the man page; only some incidental examples appearing among a discussion of "Option styles." I suspect this is also what you see; it's in the same position in the page. So there is some evidence that examples aren't entirely prohibited in GNU man pages, at least in recent years. Progress, I guess. The latest work on this man page (release 1.32) shows no further progress.

TLDR goes well beyond those incidental examples and is far closer to what I'd hope to see; first class, worked example forms eagerly supplied. Without suffering info.

Fair enough and as mentioned this was Slackware and the maintainer, Patrick, is known to have a fondness for BSD so maybe his influence can be seen here.

For what it's worth the Slackware page does have an Examples section so it's not exactly what your seeing on Ubuntu but the examples themselves may be the same. As mentioned there are only three but they are probably the three examples needed most by 95% of users.

And, since I wasn't clear in my previous post, I absolutely agree about info. It may have been a nice thought when hypertext based systems were young and new things needed to be tried but it should have quietly died by now IMHO.

> If one checks the tar man page there are no examples.

* https://www.freebsd.org/cgi/man.cgi?query=tar#EXAMPLES

* https://man.openbsd.org/tar#EXAMPLES

* https://illumos.org/man/1/tar#examples

* https://www.ibm.com/support/knowledgecenter/ssw_aix_72/t_com...

* http://osr507doc.sco.com/cgi-bin/man?mansearchword=/usr/man2...

You are clearly very limited in your user manuals. (-:

I certainly should have qualified with "GNU tar". This raises the question; does TLDR exist simply because of GNU's dysfunction? Would TLDR exist if one could simply 'man tar' on a GNU tar system and pop down to the Examples section as one apparently can in just about every other *nix?

(and one currently can't, given the unmodified man page from the most recent 1.32 release)

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.

> they serve two different purposes

I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.

That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor and don't use mandoc (which is... exactly only AIX and HP-UX at this point), so they write all their text in man so that they render correctly everywhere.

For tagging, the formatting would need to be redone to be mdoc, which breaks both the OSes mentioned above and would be an immensely arduous task at this point. Probably not going to happen.

Note GNU and and the Linux man-pages project are mostly outliers; everyone else that lives in BSD/illumos land has long since moved on to mdoc since like the 80s. See also https://www.usenix.org/system/files/login/articles/141-dzons...

> That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor

Sudo supports such systems even though its manuals are written in mdoc.

The source tarball contains both the original mdoc manuals and man manuals, autogenerated by mandoc (https://mandoc.bsd.lv) which can convert mdoc to man—easy to do, since mdoc is a semantic format.

Then at build time one format or the other will be installed depending on how capable the system manpage formatter is.

Any project using mdoc pages could do the same thing. Projects using autotools could even copy Sudo’s autoconf macros for this.

It would be quite nice to have that quick tutorial in a new section at the top of man pages, in addition to what's already there.

> No, they serve two different purposes.

I don't see why they could not serve both purposes.

Man pages should start with a tldr section followed by the full reference/spec.

Yes, put both things in the man page!

Looking at some examples of tldrs, it mostly boils down to the most common use cases as examples. So well written man pages already have an "examples" section, and that really helps!

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.

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.

Ideally I would like to see an additional section in man pages devoted to examples. The TLDR pages could then be moved into the man pages.

tldr didn't choose tar as their front-page demo by accident. The tar manpage is a classic example of the CLI gods apparently going to some effort to design the Examples section to effectively tell new users to bugger the hell off.

https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt...

This reads fine to me: https://man.openbsd.org/tar

Only to people who erroneously think that there is such a thing as "the" tar manpage. (-:

* https://news.ycombinator.com/item?id=22122279

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.

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.

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.

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.

I often have this difficulty with man pages. But man page format allows examples, contributing many examples to original man pages would make them more accessible.

Also, a gentle, human oriented intro can be a part of man page I think.

I disagree. Plenty of man pages have very excellent examples that serve as a beginner tutorial. Ones that are just as good (and easy to understand) if not better than what I've seen from TLDR. There's no reason manpages can't be both.

Yeah, no. The use cases for man and tldr are completely different, and trying to convince every single project to make their man pages more friendly to people who just want to get their work done is just ... well, an impossible amount of effort. tldr coalesces a community around a common goal, and they can work towards that goal without fighting hundreds of different maintainers on making man pages more accessible.

It would be interesting to take a step back and consider what man pages actually are. Are they documentation structured in a specific way, dating back to Unix origins, or are they what the user sees if they type "man command" on the command line? Because if we consider the latter, I think it will be much easier to see radical improvement of the "man experience"

If I type "man ps" I see

    Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this)
     * ps (1)
       ps (1p)
    Man: What manual page do you want?

What if I instead saw

    Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this)
     * ps (1)
       ps (1.tldr)
       ps (1p)
    Man: What manual page do you want?

where the man command retrieved that information from the TLDR-pages site?

In the last years we have seen many innovative Rust re-implementations of classical commands such as cat, find, grep. Maybe the man command is next up?

man apropos

+1 ... we should be working on improving "the actual" man pages. There is an "Examples" section in OpenBSD man pages that help out quite a bit. I'd rather have one definitive place for man pages (rather than many), and I'd rather have them be accessible from the OS (and not require an internet connection).

manpages would be awesome if more pages had examples.

Since they don't, we use bropages, tldr, etc.

To really improve them, the man format needs to be changed. For example, those blue underlined words... they arent links. Markdown (or better, a subset) would work.

And many (or most) of the TLDR project pages are wrong because they refer to the GNU-variant reimplementation instead of the actual tool.

With a man page you know you're getting the right info because it came bundled with the tool.

Given the general attitude of the GNU/Linux community, I could see most examples/edits being rejected with elitists saying "RTFM!"

Remember, these are the same people that claim the Emacs and Vim are better to code in, and that IDEs are for inexperienced/lazy coders.

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.

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.

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

I don't think you need Nodejs.

There are a large number of clients listed here

https://github.com/tldr-pages/tldr#clients

Debian has a package "tldr" implemented in haskell, that's under 1 MB. 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.

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

tldr has a better name.

Having skimmed the endless discussion about the "bro" name, I have to agree.

I can think of about four other projects called bro so without context the name is fairly useless and it appears this is a competitive space, I wouldn't hold much hope for the tdlr esc bro

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

Yes, just like the only reason Facebook went mainstream was because of the incredible name.

No it never went mainstream because it a tool with worse ui and less content than a search engine + stack overflow.

I can find simple instructions for almost any tool with a search like "Convert flac to opus ffmpeg"

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

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

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

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.

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.

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}'

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.

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.

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

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

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

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

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.

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.

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.

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?

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

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.

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

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

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

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

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.

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

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

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/

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

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

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

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

http://bropages.org/

Fantastic.

Now please someone do something similar with Apple developer documentation.

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

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

Yeah cargo install tealdeer was worthwhile. Really good.

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

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

https://github.com/tldr-pages/tldr/blob/master/pages/common/...

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

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

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

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.

This is such a great idea. Praise fucking be.

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

Reply on news.ycombinator.com