
TLDR pages - tkfx
http://tldr-pages.github.io/
======
teddyh
That project is a symptom of manual pages not having good “EXAMPLES” sections.
The examples on that web page should be contributed upstream to the manuals
pages of the software that they are for.

If you want a fast way to _read_ the EXAMPLES section _only_ for a command,
here is a shell function which creates an ‘eg’ command which only displays the
“EXAMPLES” section of manual pages:

    
    
      eg(){
          MAN_KEEP_FORMATTING=1 man "$@" 2>/dev/null \
              | sed --quiet --expression='/^E\(\x08.\)X\(\x08.\)\?A\(\x08.\)\?M\(\x08.\)\?P\(\x08.\)\?L\(\x08.\)\?E/{:a;p;n;/^[^ ]/q;ba}' \
              | ${MANPAGER:-${PAGER:-pager -s}}
      }
    

Usage:

    
    
      $ eg tar
      EXAMPLES
           Create archive.tar from files foo and bar.
                 tar -cf archive.tar foo bar
           List all files in archive.tar verbosely.
                 tar -tvf archive.tar
           Extract all files from archive.tar.
                 tar -xf archive.tar
      $
    

(Previously:
[https://news.ycombinator.com/item?id=10025216](https://news.ycombinator.com/item?id=10025216),
[https://news.ycombinator.com/item?id=7123328](https://news.ycombinator.com/item?id=7123328))

~~~
vitd
I don't mean to sound cynical, but if oft-used man pages haven't already added
"EXAMPLES" sections over the last 30 years, how likely is it that they'd add
them now? This project exists because man has failed to as useful as it needs
to be for current users. I don't think that adding this info to the "EXAMPLES"
sections will help anything, personally.

~~~
teddyh
That’s like saying “We haven’t needed ‘TLDR pages’ for the last 30 years, why
do we need them now?”. Times change.

~~~
alexwebb2
The fact that something hasn't been done doesn't mean there isn't a need for
it.

------
coldtea
I do find TLDR useful, but is there anything preventing adding it as a
standard section of the actual manpages we all use?

Perhaps with a switch (man --tldr) or something?

Wouldn't a project to add those short examples to manpages be good?

~~~
nikcub
You can add a section 0 to man pages for example (tldr) versions. Man also
already supports rendering HTML if that is the preferred format that
contributors want to write.

With a handful of commands i've got the tldr pages rendering in man:

    
    
        mkdir /usr/local/share/man/man0/
        pandoc -f markdown_github -t html https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/tar.md > /usr/local/share/man/man0/tar.0.html
        export MANPAGER="`which lynx` -stdin"
        man 0 tar
    

tada.

We really shouldn't be rewriting tools and fragmenting community effort to fit
a new feature that is already 90% implemented.

edit: one idea I do like is having content that is easy to contribute to, such
as man pages, in separate repositories. Contributing to open source projects
for content writers can often be intimidating - having a pure text separate
man page repo that all the distro's use would be great.

~~~
mch82
Generally agree that augmenting existing man pages is then way to go. However,
using a new number to categorize "use cases" or "examples" is probably
incorrect.

man page categories (1, 2, 3, etc.) are organized by type of command. See:
[http://www.schweikhardt.net/man_page_howto.html#q2](http://www.schweikhardt.net/man_page_howto.html#q2)

Reviewing the convention for man pages, it seems like adding an EXAMPLES
section to existing man pages is the correct way to augment the documentation.

Definitely support your position that improving existing documentation is the
way to go. Just wanted to share my research on how man pages are supposed to
work.

~~~
nikcub
Thanks, I remembered it being extensible. Turns out that section is a char in
the man code so it could easily be a new section or a switch to extract the
examples.

I might do some work on this - import the examples from tldr and bro and get
them into the man pages, and hopefully find a way so that man pages are easier
to contribute to.

------
ravicious
Maybe instead of creating something entirely new we could improve the existing
thing, that is prepend man pages with some examples?

~~~
ymse
There have been discussions in the past about "standardizing" on an _Examples_
section. It is usually what I miss the most in any manual.

~~~
nailer
The man maintainers, at least from my own dealings with them, often don't like
contributors. "Examples are nice, and I like your changes, but what if Paul
Vixie doesn't?" It's easier to fork man completely and take it away from them,
Xorg style.

------
niuzeta
I find it rather redundant to bropages:
[http://bropages.org/](http://bropages.org/)

Still, a readable manpage alternative is always welcome!

------
no_gravity
Instead of installing one of the clients, it might be easier to just put this
line into your bash.rc:

    
    
        function tldr { curl https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md; }

~~~
pervycreeper
Internet access is not a given at all times. One is often more likely to need
manuals when there is a problem with it.

~~~
dyladan
Well to be fair, you can just use the man pages if you don't have network
access. Or you could git clone the repo and print it from the repo. I think
his point is that this is a problem that is easy to overengineer and really
doesn't need that much work to be done.

------
sergiotapia
Also see bropages! [http://bropages.org/](http://bropages.org/)

Very interesting tools. I still don't know how to navigate man pages to find
what I need.

~~~
krick
Yep, also have used them for a while and even though they're lacking content
still, the concept I'd say is rather better than tldr-pages. Contributing is
easier and documentation is specifically focused on examples, not trying to
replace the original documentation, which should be improved separately, if
needed.

------
masukomi
To everyone suggesting people send patches in to the original repos instead of
using this, or anything like it:

Have you ever tried hunting down the canonical source repo for any of those
ancient commands? It's nigh-impossible for many (most?). Seriously, give it a
try for one of the small ones that haven't been touched in a few years.

~~~
joshstrange
If if you do good luck getting your patch merged, wait a year for the next
release, and then sit back and wait a few years (if ever) for the versions to
trickle into real distributions

Just look at the timeline of the last 4 releases of Tar:

Tar 1.28 - 27 Jul 2014

Tar 1.27.1 - 17 Nov 2013

Tar 1.27 - 20 Oct 2013

Tar 1.26 - 12 Mar 2011

------
peteretep
One thing I love about Perl, which has seemed sorely lacking in many other
languages, is the habit of documenting all modules with a "Synopsis" section,
which is essentially short examples of use. A good 50% of modules I use I
don't need to read further!

------
Buetol
As a side note, `dtrx` is a sane alternative to `tar` that do the right thing
by default.
[http://brettcsmith.org/2007/dtrx/](http://brettcsmith.org/2007/dtrx/)

Just `dtrx yourarchive.tar.xz`.

~~~
tazjin
I honestly don't understand the meme of "tar is so hard to use". You only need
to know like five parameters (xcvfz) for 99% of use cases, and they're pretty
easy to understand.

~~~
TuringTest
From the manual:

"In UNIX or short-option style, each option letter is prefixed with a single
dash, as in other command line utilities. If an option takes argument, the
argument follows it, either as a separate command line word, or immediately
following the option. However, if the option takes an optional argument, the
argument must follow the option letter without any intervening whitespace, as
in -g/tmp/snar.db. Any number of options not taking arguments can be clustered
together after a single dash, e.g. -vkp. Options that take arguments (whether
mandatory or optional), can appear at the end of such a cluster, e.g. -vkpf
a.tar."

When you have several alternative optional syntaxes for the commands, and you
mix them with several different mandatory syntaxes for the parameters, the
result is way more complex than merely "know five simple parameters for 99%
use cases".

The following are all valid ways to do _exactly the same thing_ :

tar cfv a.tar /etc

tar -cvf a.tar /etc

tar -c -v -f a.tar /etc

tar --create --file a.tar --verbose /etc

tar --cre --file=a.tar --verb /etc

This offers lots of flexibility, but also means that it will be hard to
remember the exact syntax, and that examples that you come by on the net will
all look wildly different, making it hard to learn the commands and create a
habit by exposure to examples.

------
awalGarg
I think man pages aren't always verbose or unreadable. In fact, most of the
time, they are pretty easy on eyes for me.

But generally, it is not a "tl;dr" that I am looking for in man pages, it is
_that one thing_ I need not very often, but can't remember, like "what switch
does `git pull` take to rebase" (ok, not very good of an example, but since
these are things I "can't remember", I can't pull one out of my head right
now). And for these cases, `less`, my default pager, has excellent searching
capabilities.

For instance, I needed to check how to tell OpenVPN CLI client to take
username and password from a file instead of stdin. I knew I had done it
before, but didn't know which flag it was... just the third instance of
"username" on the openvpn manpage called it out (--auth-user-pass). Such
things, are IMO, more often needed, but not something a tl;dr would cover.

Great project anyways :)

------
morenoh149
reminds me of [http://bropages.org/](http://bropages.org/)

------
brillenfux
Man pages are really already TLDR pages. They suck for introductory
documentation (most times) but are really useful if you just can't quite
remember the switch or its parameters.

I don't know what niche this is supposed to fill?

~~~
jehna1
This.

[https://xkcd.com/1168/](https://xkcd.com/1168/)

~~~
hk__2
Tar options are actually very easy once you take the time to understand them.
Want to create an archive? use `-c`. Want to extract? It’s `-x`. From that you
know you can use `tar -cf foo.tar foo` (`-f` lets you pass the archive name)
and `tar -xf foo.tar`. Want to be verbose? Add `-v`. Want to use gzip
compression? Add `-z`. There are a bunch of other options to do more, but just
with that you can already understand 99% of what tar is used for.

~~~
coldtea
> _Tar options are actually very easy once you take the time to understand
> them._

That's not the experience of many people. Or maybe, "taking the time to
understand them" is not how they want to spend their time, and the mnemonics
are bad because the use is not that frequent anyway.

~~~
tazjin
But the time we're talking about to understand this is less than 5 minutes.

Those same people spend more time joking about how complex the options are and
linking that xkcd anyways.

~~~
coldtea
Let me rephrase. There's nothing much to "understand". This is not a logical
puzzle or a physics lecture.

It's an arbitrary set of command line flags and argument order.

So what's meant by "understanding" it, is basically "memorize".

Sure, if one devoted some time, they could memorize it. Like people can learn
the PI to the nth digit.

But first, it's not just tar they use -- it's tens of other commands too.

Second, a lot of them have clashing flag order or slightly different names for
the same arguments.

Third, most don't use them that frequently to make it worth it to sit and
memorize it. Besides the infrequence of use means that simple memorizing once
wont work, as they'll forget them without sitting down again later to refresh
their memory. We can memorize complex vim commands because we use them
everyday. Commands that we need once a month or once every 3 months, not so
much.

It would be better for all if tar just did the obvious and intuitive thing.

~~~
marcosdumay
> It would be better for all if tar just did the obvious and intuitive thing.

And what is that obvious and intuitive thing?

Are you complaining about the need for a "-f" flag? If so, I'll agree, tar
could take files the same way cat does. Tar's showing its age here, and would
get a better interface without it.

But all the other flags are there for a reason, are the obvious mnemonic
choices, and are the same ones used on other similar commands.

------
hk__2
The issue I have with this kind of projects is that people quickly accept that
reading manpages is boring and that they should only use `tldr gcc` or a quick
stackoverflow lookup instead of actually learning how to use their tools. It’s
like learning how to fish vs. bying fish at the supermarket. Sure, if you know
how to fish you can still buy at the supermarket if you’re lazy. But if you
don’t you’re stuck with what’s at the supermarket.

~~~
coldtea
> _It’s like learning how to fish vs. bying fish at the supermarket. Sure, if
> you know how to fish you can still buy at the supermarket if you’re lazy.
> But if you don’t you’re stuck with what’s at the supermarket_

If you're already down to the command line, running UNIX commands, and using
TLDR you are way beyond "buying fish at the supermarket".

And why should you "learning how to use those tools", when what you really
want from those tools are the use cases TLDR already covers?

~~~
jordanpg
Agreed 100 times over.

My eyeballs are strained from rolling every time I read some _very sage_
person on SO or HN reply to a well-phrased question or comment with a terse
"it's all in the docs".

As if 90% of use cases aren't covered by 5 examples. As if we all have
unlimited time to spend on reading docs and manpages and "learning how to use
the tools". As if there is some intrinsic virtue to "learning how to use the
tools". As if the very purpose of sites like SO are something other than
distilling the information in docs into some other, more readable form. As if
there are no man pages or docs that are absolutely incomprehensible and worth
ignoring.

No, sorry, this attitude is just another manifestation of standard tech
machismo: "real men do it the hard way". Good luck with that!

~~~
hk__2
I’m not saying you shouldn’t use TLDR or StackOverflow. I’m just saying you
_could_ benefit from reading the manpage once instead of TLDR 10 times a day.
That doesn’t mean you won’t forget most of the stuff and will use TLDR/SO to
find it again but at least you’ll be more comfortable using the tool.

In the `tar` case if you know what c, x, v, z and f stand for you can cover
99% of the tar use cases because those can be combined. You learn 5 letters
and have now access to 8 different commands (`{c,x}[v][z]f`). Learn one more
letter, `t`, and you can combine it with your existing knowledge to have 3
more commands (tf, tvf, tzvf).

~~~
ryandrake
Great. Then put those options near the top. Why are options on man pages
organized alphabetically? What common use case drives that decision?

~~~
hk__2
Well, in a dictionary words are not listed at the beginning. The alphabet
itself doesn’t have the most common letters at the beginning. What we should
do is put the manpage examples at the beginning instead of the end.

------
mch82
What if we put community energy into contributing improvements to existing man
pages for open source projects?

As many commenters have noted, it is possible to accomplish the goals of TLDR
by improving existing man pages, without establishing a separate documentation
system. A man page can be formatted to include any number of sections. All
that is needed is an EXAMPLES section that lists examples for typical command
usage.

Here are instructions for creating a man page:
[http://www.schweikhardt.net/man_page_howto.html#q3](http://www.schweikhardt.net/man_page_howto.html#q3)

Side note... isn't the usage of TL;DR in this project incorrect? TL;DR is a
synonym for "abstract", "synopsis", and "executive summary". It is already
confusing enough to use TL;DR in place of those words without overloading the
term to mean "tasks", "example usage", or "typical use cases".

~~~
kevan
Projects like this happen because it's easier to contribute here than to the
existing manpages. As someone who came of age in a Github world, there's
(perceived) friction preventing me from trying to contribute to a lot of tools
from the old guard. Let's say I want to add some examples to the tar man page:

* How do I create a man page? (you answered this one)

* Where is the vcs repo for tar? (I think it's this one git.savannah.gnu.org/tar.git)

* I cloned the repo, but I don't see a contributing guide. Looks like I need to create an account and submit a patch online?

* Do I need to let the mailing list know about it? How do code reviews work?

None of these steps are dealbreakers, but together it all adds up to more
unknowns I need to figure out before I can contribute. If existing projects
make their contributing process smoother then I think we'll see more of this
effort go directly to them.

~~~
mch82
The friction you feel likely is more than just perceived. Perseverance can
often break past it and sometimes a disruptive spinoff proves to be required.

I work at a company where the typical employee is 20-30 years older than I am.
It is often a struggle to get people to adapt to change, the key is to
persevere. As an example, I just finished participating in a 4-year effort to
get my organization to adopt Git!

Often, projects like TLDR are necessary as proofs of concept to help the old
guard understand the value of an idea or initiative. Even something as simple
as this discussion existing might help people see an unmet need or expectation
exists. And sometimes, when the old guard fails to respond, it is worth
spinning those projects off with a group who sees the "new way" as clearly as
breathing oxygen and replacing the old way of doing things completely.

Your list of bullets is a good one. To be honest with you, I've only
contributed to open source docs a small number of times, submitting merge
requests to Canonical. So, I will give updating a man page a try and see if I
can figure it out.

------
Paul_S
These should be appended to the top of regular man pages.

~~~
runarberg

        function man {
            cat <(tldr $1) <(/usr/bin/man $1) | less
        }

------
jkire
How does this deal with different versions of a utility having different
flags/commands?

~~~
LeonidasXIV
By only supporting the Mac OS X version, apparently, because neither my
Debian, Fedora nor Arch have this `brew` tool mentioned on the home page.

------
ap22213
Cool idea - but like others allude, it would be useful if the TRDR content was
organized _along with_ the man page content.

Even better: it'd be nice if there was a repository of _just content_ that was
structured in some standardized way. Then, some MVC-like system could easily
consume _all of_ the content.

------
haenx
What about
[https://github.com/chrisallenlane/cheat](https://github.com/chrisallenlane/cheat)
?

~~~
waldir
Didn't know about that one, thanks for the link! I've added it to the
discussion at [https://github.com/tldr-
pages/tldr/issues/266](https://github.com/tldr-pages/tldr/issues/266)

------
cheshire137
Yes! Thank you, all I want is an example of how to use the command. Man pages
never help me, they give a bunch of non-concrete examples. I always just
Google for the command and someone's blog post helps me out.

------
skimmas
love the simplicity put in this little tool. Incredibly easy to remember,
gives the answer you need 95% of the times, makes it very easy to contribute
with new stuff.

------
ajones
TL;DR a collection of TL;DRs for common *nix commands with clients to display
the shorter docs

------
geff82
most useful thing ever. All you need in 90% of the time. Hope to see it in
Redhat soon :)

------
debaserab2
Seems like most tools basically provide this with a -h or --help switch.

------
reitanqild
Brilliant idea!

Now, did I misunderstand or does this need npm?

~~~
hit8run
As far as I see there are different clients available as options. You don't
necessarily need npm but I don't know in what shape the clients are. For
example the go client seems broken to me (hard coded wrong tldr-page url, no
caching, platform is always set to common)
[https://github.com/pranavraja/tldr](https://github.com/pranavraja/tldr) I
like the idea. Maybe I will create a better Go client.

------
humility
there's also a ruby gem called bropages!(gem install bropages)

example usage:

bro man

even allows user submission/voting on answers

------
dcposch
looks just like bro pages

bropages.org

------
draw_down
Seems like a good idea, man pages can be almost comically obtuse at times.

~~~
jay-saint
I feel like the examples tldr entries should be required to be written by a
third party other than the creator of the software. In my experience the
creator of a piece of software or machine always thinks it is simple and
writes the man page accordingly.

------
oldmanjay
If there was anything the frozen computer interface of the 70s needed to
complete itself, it was silly Internet neologisms. Thanks, author, for
bringing the worst of several eras together.

