
Simplified and community-driven man pages - akras14
http://tldr.sh
======
chao-
I was lucky to first be introduced to man pages by someone who often just
called them "manuals" and (to my best recollection) explained them by telling
me "Manuals are to be read, top to bottom, contemplated, and maybe read again,
before you act."

Thus I was never under the delusion that man pages were, or should strive to
be, How-To's of some sort.

This TLDR tool definitely needs to exist, but in conjunction with man pages,
not as a replacement. Manuals should continue to exist in a form that explores
and explains the depths of a utility or command in whatever length that might
require. I will make adequate use of both.

~~~
dfabulich
The traditional structure of man pages (Synopsis, Description, Options, and
maybe Examples at the end) is just Bad. No documentation expert would write
doc this way, not even as a reference, say nothing of a tutorial.

The synopsis typically lists a bunch of command-line variations with literally
no context, not even a line of commentary to tell the difference between the
variations.

Then comes a description, which is fine, and then a list of options in
_alphabetical order_ which is almost always the least useful ordering.
Categorize the parameters. Juxtapose confusingly similar options.

And only then do we get any examples, if any. The examples should have come
first, in the synopsis.

There's nothing inherently wrong with man pages, but nobody has to follow this
tradition. Put real examples in your synopsis and manually sort your options;
you'll have a man page that's 20x better than most.

~~~
jmfayard
Man is like javadocs: useless unless you already know what you are doing, and
then usually a wordy paraphrase of the method signature :(

Even as a reference manual, man is bad though.

If I'm looking for option "-e" of the test command, why can't I do

    
    
        $ man test -e
         -e file       True if file exists (regardless of type).
    
    

That seems more efficient, more unix-friendly and not too much to ask.

I get this is an historical tool that only cares about displaying the output
of nroff. We would need a new tool with more empathy ($ woman? )

~~~
kleiba
_De gustibus non est disputandum._

I've found javadocs enormously helpful when I was learning Java 20 years ago.
But then again, I also like man pages and use them a lot.

If I'm looking for option "-e" of the test command, here's what I would do:

    
    
        $ man test
    

and then "/-e". Searching within a document is a commonly required skill in so
many situations that I don't even think twice when applying it in man pages.

Of course, you could also just define a bash function for the functionality
you're after like so:

    
    
        mano() {
            man "$1" | grep -A1 -- "$2"
        }
    

and then do

    
    
        $ mano test -e
    

or something along those lines.

~~~
jmfayard
That's full text search, not having directly the argument definition. If you
search "-l" in "man ls", it will be only your 8th occurence.

~~~
kleiba
Sure, you're right, it's not the same thing. I just gave a simple example of
something that's close, but I'm not even using a bash function like that
myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my
book, since the results can be scanned rather quickly.

You could always make your function more clever, e.g.:

    
    
        function mano() {
            man "$1" | grep -A1 -- "$2\\b"
        }
    

or

    
    
        function mano() {
            man "$1" | grep -A1 -- "$2  "
        }
    

but most probably, you will still run into edge cases that won't work
properly. For instance, only one of the two versions above still works with
"test -e".

------
begriffs
When people think of manpages, they tend to think of Linux. At least that's
what I thought of, until a few months ago when I discovered OpenBSD. Their
manual is concise and coherent, unlike the rambling hodgepodge on Linux.

Of course it's always nice to have a bunch of curated examples like TLDR or
"bro" pages, but just wanted to point out that the manpage situation isn't
universally grim.

~~~
IgorPartola
By Linux do you mean GNU? Because those are the wordiest and least
straightforward. BSDs tend to have excellent documentation as do some
individual projects (git), while others (OpenSSL) leave something to be
desired. And of course GNU tar is a special little hell. But Linux just
happens to run on a GNU userland most of the time so you get those a lot.

~~~
jlebar
> BSDs tend to have excellent documentation as do some individual projects
> (git)

Should we really point to git as an example of great documentation? I mean,
this exists and has to have a giant banner at the top saying "these are NOT
REAL": [https://git-man-page-generator.lokaltog.net/](https://git-man-page-
generator.lokaltog.net/)

~~~
fiddlerwoaroof
Yeah, I use the git manpages all the time when I need to do something unusual
and have generally found them to be very helpful, but they aren’t written for
people who don’t know how to use git.

------
PaulRobinson
Hilariously, ITT are lots of comments saying that man is awful, in response to
a pot about a "simplified and community-driven" alternative.

Breaking news: man pages are community-driven already. You can make them
better in your distro of choice. The BSD projects are a little better IMHO at
this than Linux because each project has a dedicated team trying to raise the
bar and make their docs better than the next distro.

So don't make it simplified, don't hail "community-driven", just go and start
making suggested changes with the rest of your favourite OS community!

~~~
iuguy
People who complain about man pages tend not to understand man pages. Man
pages aren't howto documentations. They're very specifically designed to
document the different components of a command, call or configuration file.

OP is absolutely spot on about man pages being community driven. At least half
the time someone complains to me about a man page, the man page is the wrong
place to look. Usually, the answer they're looking for is in an info manual or
somewhere like /usr/share/doc/.

~~~
coldtea
> _People who complain about man pages tend not to understand man pages._

That's their very issue with them.

> _Man pages aren 't howto documentations. They're very specifically designed
> to document the different components of a command, call or configuration
> file._

Then people who designed man pages didn't understand what the users want first
and foremost: howto examples.

Besides, whether they document "the different components of a command" and
whether they have howto examples is orthogonal. They could do all the formal
documentation they want and still include howto examples.

That they don't (well, most don't, some man pages are decent enough to indeed
include example sections) is their failure.

~~~
scaryclam
I don't think it's fair to say that the originators of man pages didn't
understand what their users were looking for. In most cases, the authors _are_
the users, and when they were first created, that was pretty much the only
user base they had. Man pages are _manual_ pages, not howto pages.

If I'm looking at a man page, it's pretty much always because I want to look
up one of the options, not how to use the command itself. Adding that sort of
howto clutter would make it a whole lot harder to use the pages properly. Why
not leave man pages alone and just focus on info pages again
([http://www.troubleshooters.com/linux/info.htm](http://www.troubleshooters.com/linux/info.htm))?
That was always the go-to for more verbose descriptions and has much more of a
howto vibe about it.

~~~
coldtea
> _Man pages are manual pages, not howto pages._

Isn't that a made-up distinction though?

Who said manuals can't have representative examples for how to do certain
tasks?

Product manuals (including software product manuals) almost always do. They
don't just enumerate features and flags.

~~~
iuguy
> Who said manuals can't have representative examples for how to do certain
> tasks?

Dennis Ritchie defined what goes into the manual in the 3rd edition of UNIX,
at the behest of Doug McEllroy. Ken Thompson also did some work on man pages,
and I believe Lorinda Cherry was involved too. As I understand it (and I could
be wrong though) the terseness of man pages was Ritchie's design, with input
from Thompson.

~~~
coldtea
Which might have been good for late 70s -- and the main users being academics
and the designers of the system itself, but might not be as good for late
2010s.

Besides, we already have the Examples section, would it be too much to ask to
have it better (or at least somewhat) utilized in all manpages?

We could even have different sections, shown with flags, and keep regular
output as it is.

man --examples foocommand

~~~
iuguy
You clearly don't understand core Unix philosophy[1]. It's this that drives
commands like man, that have been around since 3rd edition Unix.

You're failing to understand who the main users of Unix were (Bell, a telecoms
company. Academics didn't start using Unix in anger until the late 70s, by
which point Unix had been established for about 3-7 years within AT&T/Bell
depending on whether you count Berkeley and Illinois's initial use as
academia, or it's more widespread adoption following the release of the BSD
distribution and V7/V32).

Before you start complaining about man pages, consider that in order to access
them on your shiny new computer that it simulates a 1970s era virtual
terminal, which itself emulates an advanced 1960s era teletype terminal to
display it.

The problem isn't man pages. They do their job generally well. The problem is
that you want man pages to do something they aren't designed for, and will not
change to. Use /usr/share/docs or info instead. That's what these things are
there for.

[1] -
[https://en.wikipedia.org/wiki/Unix_philosophy](https://en.wikipedia.org/wiki/Unix_philosophy)

~~~
coldtea
> _You clearly don 't understand core Unix philosophy[1]._

That's because it's trite cargo cult. And even worse, it's totally
unapplicable to our discussion, as it pertains to program design, not how to
write or what to include in a man page. man, the program, would still just be
a simple manpage showing program.

Besides it, and other basic unix core utils and userland programs, have
adopted 10,000s of flags and new functionality over the years, to the point
that shooting down my --examples suggestion for "breaking the unix philosophy"
is total BS.

Heck, Emacs includes everything AND the kitchen sync, but it's a much beloved
part of Unix tradition.

> _It 's this that drives commands like man, that have been around since 3rd
> edition Unix._

Tradition doesn't make it right. Where's the science? How about some actual
measurements of levels of head-banging of users between different approaches?

Also note that I started on Sun OS, when Solaris was a new unstable OS, and
have used HPUX, IRIX and other such flavors in workstations of the time (and
actual VT terminals). I'm not some teenager that got into Linux with the
latest Ubuntu.

> _The problem is that you want man pages to do something they aren 't
> designed for, and will not change to._

Sorry, you've already lost that battle. Lots of manpages already have EXAMPLES
sections. It's just that not enough attention has been paid to their content.

~~~
iuguy
> it's totally unapplicable to our discussion

Wait, we're talking about the Unix man command, and you're saying that the
fundamental philosophy upon which this command's entire design and purpose is
based is somehow unapplicable? Really?

> but it's [EMACS] a much beloved part of Unix tradition.

No. EMACS is not part of the Unix tradition. EMACS was invented before Unix at
MIT. Unix was invented at Bell Labs. EMACS was designed for an OS called ITS
as a successor to the TECO editor (developed in 1962). You're getting mixed up
with vi, which was created for Unix by Bill Joy in the 70s as a separate mode
for ex, which was a successor to ed.

You're possibly thinking of GNU EMACS, which would be ironic, considering that
GNU is an acronym that stands for "GNU's Not UNIX".

The Operating Systems you or I have used aren't really relevant to the
discussion. I can see that you may have filled in context that wasn't there
and assumed I'm some old unix beard telling you to get off my lawn. That's not
the case.

I have two points:

1\. Man exists because of specific documented conventions. Man pages are the
way they are because they're expected to follow conventions built over the
past 40 years.

2\. There are places that howto documentation belongs in most Unix-derived
OSes, certainly for anything BSD derived and anything following the Linux
Filesystem Hierarchy Standard.

Take a step back and try to see what I'm seeing. I see someone who seems to
insist that we should change a specific 40+ year old convention to suit
environments that implement other 40+ year old conventions, when there's
already a place for the things they want (again thanks to explicit and
implicit convention and documentation). It's not going to happen.

You are not going to get Apple, Red Hat, Debian, Ubuntu and the BSDs to change
the way they've done things _forever_ to suit your whims. You're also
definitely not going to get them to change them when perfectly functional
alternatives already exist.

------
kccqzy
The main thing about man pages is that it is a "manual": reference material
for people who already know the basics.

If you are just getting started, don't read the man pages, but read one of the
many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will
generally be tailored to beginners, including features such as discussions of
unifying themes between different commands, historical references and more
beginner-friendly organization. Beginners don't need to know all the details
at first (which are what the man pages provide), but just the big picture.

~~~
tnoerlcnt34
Sure, but what usually happens is you sit down at a Unix command line for the
first time and have no idea what to do. You ask someone (after seeing that
`help` does nothing useful), and they tell you "use 'man' instead of 'help'".
And you have no idea why, but you try it and it kind of helps and is better
than nothing. You don't have any idea you should `read one of the many
"Getting Started" or "Quick Guide" or "Beginning XXX" books.` (Likewise, you
wouldn't know at first to install something like this, either.)

~~~
dfabulich
I think this is how it used to be, but now people just Google their problems,
and typically they get Stack Overflow as a result.

Earlier this year, they announced that they have helped over one million
developers to exit vim, for example.
[https://stackoverflow.blog/2017/05/23/stack-overflow-
helping...](https://stackoverflow.blog/2017/05/23/stack-overflow-helping-one-
million-developers-exit-vim/)

In my experience, the top-rated SO answer is typically better than the man
page, because it answers the specific question I have, rather than listing all
of the options in alphabetical order, forcing me to search the page itself for
the information I really wanted.

~~~
JdeBP
... or Wikipedia.

Interestingly, Stack Exchange answers are sometimes constructed by people
using search engines to find phrase matches, sometimes with ridiculous
results. (-:

* [https://photo.stackexchange.com/questions/94238/who-or-what-...](https://photo.stackexchange.com/questions/94238/who-or-what-is-an-uncle-bob#comment171027_94238)

That Stack Overflow web log entry is poorly researched, by the way. As I can
attest from my own WWW site's statistics, there are reasons that a WWW site
can have Ukraine at the top that have _nothing_ to do with real people viewing
relevant WWW pages, so conclusions such as

> It looks like developers in Ukraine, Turkey and Indonesia are getting stuck
> in Vim quite a bit:

are complete rubbish. One has to account for WWW browsers that pre-load pages,
and WWW sites that feed stuff scraped from the likes of Wikipedia, Stack
Exchange, my WWW site, and lots of others to WWW spiders: something that
seems, from my statistics for this month so far, to be very popular for
banking and pharmaceutical scam WWW sites in the Ukraine and the Russian
Federation.

Here is how to exit emacs, by the way:

* [http://jdebp.eu./Humour/exiting-emacs.html](http://jdebp.eu./Humour/exiting-emacs.html)

~~~
bmn__
Off-topic:

What do you hope to achieve by expressing domain names with a dot at the end?
That's only required in zonefiles. No one else does that in hyperlinks and I
wish you would stop doing it. It's annoying because your alternative notation
is so rare that browsers don't normalise the equivalency, and now I have
multiple divergent entries in the browser history.

------
Xunxi
This is a very interesting project. Years ago when I wanted to learn how to
use Linux, my friend who was a system admin at the time just told me to read
Man Pages. It was so overwhelming and confusing to say the least, it made me
give up on Linux for a long while.

Times have changed and I will definitely love to contribute as well as
recommend this project.

~~~
IgorPartola
Heh. Should have told you to go read the FreeBSD manual. That’s the first OS
that made sense to me because of it. I actually ended up translating parts of
it to Russian because I enjoyed it so much.

NetBSD was the first thing I got running reliably on my ancient hardware.
Linux eventually worked but it was process. And man pages don’t explain what
the system does at all.

~~~
JdeBP
Of course, as people have pointed out already, a user manual is not a
tutorial, and the two are distinct _and complementary_. This is something that
one finds in many spheres, from Microsoft operating systems to Linux ones.

One of the things that MSDN and TechNet doco does is have both "X reference"
and "using X" sections. Manual pages are reference doco, in this way of
organizing things. The BSD worlds put the "using X" doco into what are often
called "handbooks" or "guides".

* NetBSD Guide: [https://netbsd.org/docs/guide/en/](https://netbsd.org/docs/guide/en/)

* FreeBSD Handbook: [https://freebsd.org/doc/handbook/book.html](https://freebsd.org/doc/handbook/book.html)

* DragonFlyBSD Handbook: [https://www.dragonflybsd.org/docs/handbook/](https://www.dragonflybsd.org/docs/handbook/)

* TrueOS User Guide: [https://www.trueos.org/handbook/trueos.html](https://www.trueos.org/handbook/trueos.html)

* PC-BSD User Guide: [http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html](http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html) (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/)

Some parts of the Linux world do the same. upstart had the _Upstart Cookbook_
for example:

* [http://upstart.ubuntu.com/cookbook/](http://upstart.ubuntu.com/cookbook/)

My nosh toolset comes with user manual pages for the individual commands,
written in DocBook XML as I just mentioned in
[https://news.ycombinator.com/item?id=15779321](https://news.ycombinator.com/item?id=15779321)
, and a _nosh Guide_.

* [http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html](http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html)

* [http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-soc...](http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-socket.html)

* [http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatshe...](http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatsheet.html)

* [http://jdebp.eu./Softwares/nosh/guide.html](http://jdebp.eu./Softwares/nosh/guide.html)

The Linux Documentation Project was supposed to contain a wealth of this
stuff, but large parts of it are seemingly moribund, and incomplete after
decades or woefully outdated. Wikibooks tried to take up the slack with an
"anyone can edit" _Guide to Unix_ and a _Linux Guide_ :

* [https://en.wikibooks.org/wiki/Guide_to_Unix](https://en.wikibooks.org/wiki/Guide_to_Unix)

* [https://en.wikibooks.org/wiki/Linux_Guide](https://en.wikibooks.org/wiki/Linux_Guide)

For examples and doco that works from the basis of what one usually wants to
do, then these handbooks and guides are the places to go, not reference
manuals.

------
coldsauce
Man pages feel like RFCs for tools. They have a lot of information about how
to use them but they're sometimes pretty difficult to parse. I'm really
excited about this project. Whenever I don't know how to use a tool I look at
a StackOverflow answer for an example. I've been doing this for as long as I
can remember. I'm glad there is a dedicated service for this now.

------
dilawar
Lovely.

I just wrote a bash client. It uses curl to download the page, pandoc to
convert md to html and lynx to display the html page.

[https://github.com/dilawar/Scripts/blob/master/tldr](https://github.com/dilawar/Scripts/blob/master/tldr)
.

------
menacingly
I've always felt like it's a ding on my nerd credentials that I hate man
pages. A lot of them feel deliberately opaque.

2-3 good examples are what joe blow is looking for when he types "man", and he
rarely gets them.

~~~
reikonomusha
This wasn’t always true, when software was less replaceable and felt more
valuable. Part of this cake from the fact that software distribution was more
difficult. If you ever have purchased a compiler for example you might find
yourself interested in everything you can learn about it from the manual.

Now developers are trigger-happy Googlers looking for the single salient
example atop StackOverflow answers.

~~~
chickenfries
The browser is a much nicer environment for consuming manuals than the
terminal.

~~~
apsdsm
True, unless you're actively working in the terminal, in which case it's kind
of a pain to switch to, I'm gonna say.

~~~
JdeBP
Nonetheless, it was the reasoning that underpinned Daniel Bernstein's slashdoc
idea from the turn of the century.

* [https://cr.yp.to/slashdoc.html](https://cr.yp.to/slashdoc.html)

------
shmerl
tar makes a lot more sense if you use long options instead of completely
cryptic short ones.

tar command I've been using recently (scripted of course):

To compress:

    
    
        tar --create --verbose --use-compress-program="pixz" --file foo.tar.xz --directory <bar_dir> .
    

To extract:

    
    
        tar --extract --verbose --use-compress-program "pixz -d" --file foo.tar.xz
    

Unlike bz2 or xz, pixz it uses all CPU cores both for compression and
decompression, and as well allows extracting individual files fast. It's also
compatible with xz itself.

~~~
gboudrias
By the way, at least for the ones I've tried, --extract now figures out the
compression algorithm, so --use-compress-program is possibly redundant.

With the cryptic short options it's only one letter, but I find it makes it
easier to remember a distinct "4-letter scrabble" for creation versus a "3
letter scrabble" for extraction.

(For the long options you save a lot of typing!)

~~~
shmerl
tar wouldn't be able to figure out to use pixz instead of xz in this case just
using implicit deduction.

I don't really type those options, but use some simple wrapper scripts :)

Something like pixzcompress / pixzextract. Scripts also take care to
differentiate between directory and a single file.

~~~
imiric
If you're OK with wrapper scripts, take a look at dtrx[0]. It can extract many
different formats, so assuming you have the tools already installed,
extracting anything can be done with `dtrx <filename>`.

[0]: [https://brettcsmith.org/2007/dtrx/](https://brettcsmith.org/2007/dtrx/)

~~~
shmerl
Interesting, but pixz is too new for it, plus it looks like it's using
extension to determine the type, so it won't work for the same reason as
above. The benefit of pixz is much faster compression / decompression.

------
harry8
I'm not following. The most useful thing on first read (and at other times) of
man pages are the examples section. Frequently this section is pretty bare
which is unfortunate. We should fix that. Yep with all of that.

npm install a thing with multiple clients. Um, huh? Where did that come from?
At best now we have 2 competing man page systems, one for the "complete"
information and one for the examples section? This is crazy, surely? You're
not going to be able to stop using man pages! A replacement that can't be a
replacement.

But sadly the examples themselves will probably have licensing problems to be
able to be incorporated as documentation patches to the man pages - I hope I
turn out to be wrong about that.

~~~
exogen
The meat of the project is a crowdsourced database of examples for each
program. So naturally there can be multiple clients for that database
implemented in various ways. That doesn't seem too complicated. You choose and
install one of them. Kind of like how POSIX systems have dozens of pagers,
text editors, etc. to choose from.

It also seems way less crazy to crowdsource good examples than get each
individual program's maintainer to add examples to the official man page
(which could take decades to actually get onto people's systems, if they're
even accepted), and then _still_ require people to scroll down to the examples
section.

~~~
Spivak
It's less crazy but more error prone. 3rd-party documentation has a tendency
of being wrong and out of date quickly. It's not bad but it always needs to be
taken with a grain of salt unless you really trust the maintainers of the
docs.

~~~
jmfayard
That would be a very good point if this was documenting javascript frameworks,
but I doubt the usages of "tar" and "find" change too often.

------
nikisweeting
There are a bunch of projects like this, check out `cheat` and `bropages` as
well.

~~~
omegaham
All I can say with stuff like this is "The more the better."

------
exception_e
Thank you, TLDR authors for this tool. It solves a real problem and can
coexist with traditional man pages.

I may have missed it in the discussion already, but would it be possible for
TLDR to favor editable online sources for its content (e.g.:
WordPress/Mediawiki with Markdown)? This Wikipedia style of editing may be a
big game changer.

Caveat: Of course, content would have to be packaged locally for offline use.

------
DC-3
If anyone doesn't want to install `npm` and wants to know what client to use,
the Haskell/Stack one is nice. It's pretty snappy and has a sane syntax † and
data directory (~/.tldr/).

† Unlike `tldr.py`, which requires you to do `tldr find <command>` instead of
`tldr <command>`

------
IgorPartola
Anyone ever get anything useful out of info pages (vs man pages)? I never
quite got what their deal was.

~~~
mjw1007
As far as the content and organisation goes, they're basically doing
everything right that manpages do wrong.

They separate tutorial and reference documentation, don't collapse under their
own weight when they get large, and have a way to find the documentation for a
particular short option.

The original standalone terminal reader was pretty poor, though. These days
use pinfo or the html version if you're not an emacs user.

For a good example, compare `man sed` with `pinfo sed`.

~~~
jwilk
> have a way to find the documentation for a particular short option

How?

~~~
mjw1007
There's an index, usually a separate one for command-line options.

For example in the sed info pages it's under "Command and Option Index" at the
bottom of the top-level menu.

And, at least in the emacs viewer, there's a keyboard shortcut so you can just
type something like « i - n » to see the docs for -n.

~~~
jwilk
"i" works also in stand-alone info. I was hoping pinfo can do this too, but I
can't see such functionality. :(

------
gravypod
It would be very nice to have some way of integrating this into OhMyZSH as a
plugin. OMZ can already do extraction of command line arguments by tab
completion (and it will attempt to make a brief description of what the flag
does) [0][1].

It might be nice to be able to type "tldr compress a folder into a tarball"
and click tab to have a set of templates suggested to you. You can navigate to
them and click enter to replace your current command line contents with the
template.

[0] - [https://i.imgur.com/qFnvvaU.png](https://i.imgur.com/qFnvvaU.png)

[1] - [https://i.imgur.com/usOwgw2.png](https://i.imgur.com/usOwgw2.png)

~~~
agnivade
Maintainer here.

The node client already has autocompletion for OMZ users -
[https://github.com/tldr-pages/tldr-node-client#zsh](https://github.com/tldr-
pages/tldr-node-client#zsh).

It also supports command search. So you can do `tldr search "compress a folder
into a tarball"`. And you will be shown the top 10 matches. Yes, its not
exactly autocompletion. It's more of a match to the apropos command.

------
baddox
This is a cool idea, but I’ve seen several similar tools and for some reason
have never managed to integrate them into my workflow, so I still just google
“scp examples” or use my shell history to find previous times when I figured
out how to use a command.

------
Annatar
So rather than learning a little bit of nroff and making the manual pages
better by adding to the EXAMPLES section (or using SmartOS whose manual pages
have high quality EXAMPLES sections), it was decided to just re-invent yet
another documentation system. I don’t get it: an investment in learning nroff
is incredibly valuable, as very high quality typeset documents can be produced
with it, so it’s a triple win: better manual pages, no alternative
documentation systems and knowledge how to write high quality output in the
future. What strange times we live in...

------
webreac
I think man pages should be bound to the code. For example chapter 2 should be
part of kernel. When a new system call is added, the associated man page
should be in the same commit. If a maintainer see a commit that would have an
impact of man page without an update of man page, he can easily refuse the
commit.

For me the first aims of man pages are to be complete and to be in sync with
installed software. The orignal virtue of being terse was to be complete
without requiring a lengthy description. If a man page is not complete, it has
no excuse for being terse.

------
sethammons
On the live demo, it uses a handlebars like template for examples. 'dig
{{hostname.com}}'. I think it would be better to have 'dig $HOSTNAME', but
maybe that is my bash showing.

------
urmish
Sweet. Added this to my bashrc file.

    
    
      tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md  | less ; }

~~~
explainplease
If you have Pandoc and w3m:

    
    
        curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | pandoc --from=markdown --to=html | w3m -T text/html

------
whitef0x
I find that what helps me the most are the '\--help' commands, especially if
it has multilevel support, like seen with the docker cli tool.

The problem with just providing examples is it doesn't always tell me what
each argument does, especially if I have multiple arguments, making it seem
like the tool works by having a 'magical' combination of arguments, instead of
explaining what each argument does.

------
otherflavors
they aren't man(ual)s nor are they written in man(7) or mdoc(7), so not really
man pages, wish they had gone with roff rather than markdown. tldr ls would be
something like this:

    
    
       .Dd $MDocDate$
       .Dt LS tldr common
       .Sh NAME
       .Nm ls
       .Nd List directory contents.
       .Sh EXAMPLES
       .Bl -hyphen -offset ds
       .It
       List files one per line
       .Pp
       .Nm ls Fl l
       .Pp
       .It
       List all files, including hidden files
       .Pp
       .Nm ls Fl a
       .Pp
       .It
       Long format list (permissions, ownership, size and modification date) of all files
       .Pp
       .Nm ls Fl la
       .Pp
       .It
       Long format list with size displayed using human readable units (KB, MB, GB)
       .Pp
       .Nm ls Fl lh
       .Pp
       .It
       Long format list sorted by size (descending)
       .Pp
       .Nm ls Fl lS
       .Pp
       .It
       Long format list of all files, sorted by modification date (oldest first)
       .Pp
       .Nm ls Fl ltr
       .El

------
digi_owl
While reading all the complaints about the man page layout, i find myself
thinking that it likely made perfect sense back when teletypes were the
predominant terminal.

look up something via man, tear off the output, and put it next to you. Maybe
collect the most used ones in a binder to bring with next time.

Then again, man man may be "enlightening"...

------
bitwize
As others have mentioned, the BSD man pages are the gold standard.

Man pages should _not_ be "simplified". They should be easy to read, but
comprehensive. How comprehensive? I _literally_ learned NetBSD kernel
programming by reading man pages. The same with learning how to write X
programs two decades ago.

------
sunstone
MAN pages that start with a few of the basic use case examples would be a
breath of fresh air.

------
sethammons
Not a fan of needing npm. Why not provide a binary? Or did I miss that?

~~~
digi_owl
Welcome to the world of webdev, where every damn language has their own
snowflake "package manager"...

------
xtiansimon
I tried to comment and add my own useful examples to Man pages, but the
compression on the files caused some Man pages to break. Maybe this will let
me annotate my own Man pages for once.

------
est
Oh my, someone please document tc, iptables and ffmpeg.

~~~
agnivade
Maintainer here. iptables and ffmpeg are already there. You are most welcome
to send a PR for tc :)

------
krock
This is great! I was surprised to find that even a stupid cli that I wrote has
a tldr page.

------
carlosrg
I don't get the point of this. Man pages already have a "description" section
where they give a simplified explanation of the tool, an "examples" section
where they give typical usage, etc.

~~~
more-coffee
"Description", yes, "Examples", not always;
[https://linux.die.net/man/1/sed](https://linux.die.net/man/1/sed)
[https://linux.die.net/man/1/grep](https://linux.die.net/man/1/grep)

I think the tldr client can be immensely helpful as a quick cheatsheet in
daily operations, whereas manpages will remain to be go-to references for
those with time and patience to learn all about the tool in question.

~~~
JdeBP
Only looking at GNU manual pages gives you a wildly incorrect impression of
things.

* [https://news.ycombinator.com/item?id=15780296](https://news.ycombinator.com/item?id=15780296)

Try looking at manual pages that are _not_ GNU.

* [http://nixdoc.net/man-pages/HP-UX/man1/sed.1.html#EXAMPLES](http://nixdoc.net/man-pages/HP-UX/man1/sed.1.html#EXAMPLES)

* [https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i...](https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds5/sed.htm)

* [https://www.freebsd.org/cgi/man.cgi?query=sed#EXAMPLES](https://www.freebsd.org/cgi/man.cgi?query=sed#EXAMPLES)

* [http://man.openbsd.org/sed#EXAMPLES](http://man.openbsd.org/sed#EXAMPLES)

------
MichaelMoser123
why don't they turn man/info pages into a wiki?

~~~
JdeBP
As mentioned elsewhere on this very page
([https://news.ycombinator.com/item?id=15780117](https://news.ycombinator.com/item?id=15780117))
"they" did; or rather "they" started two guidebooks on a public wiki.

------
JdeBP
Duplicates
[https://news.ycombinator.com/item?id=15769046](https://news.ycombinator.com/item?id=15769046)

~~~
detaro
please don't point out empty discussions without upvotes as duplicates, unless
there are tons of those recently. Reposts are explicitly allowed on HN under
these circumstances.

~~~
JdeBP
At the time that I wrote that _this_ was an empty discussion too. You should
bear in mind when things are written.

~~~
detaro
I don't see how that makes the reference more useful. (I see two purposes for
linking to other submissions: point out duplicates that mean the current
discussion should be marked dupe (post the link and flag = [dupe] if it's the
first comment, otherwise mods add it later), or point other commenters to old
but maybe still interesting discussions. Neither case applies when pointing to
empty discussions)

