Hacker News new | comments | show | ask | jobs | submit login
Simplified and community-driven man pages (tldr.sh)
369 points by akras14 20 days ago | hide | past | web | favorite | 162 comments



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.


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.


I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway.

man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addition to man pages.


A lot of us are "newbies" of "tar", "find", "[" and many others after years and years using *nix. According to the anti-usability mindset, this means that the users are wrong and ought to be changed, and not an hint that we should rethink how we write and consume documentation.

Edit: the wording was angrier than it needed to be. A concrete example of a better documentation tool : https://kapeli.com/dash


For what it's worth, find is truly awful, and tar is just a bit unconventional in terms of option parsing. These are stand-out failures of interface design, for which no documentation would be sufficient for all but the most regular of users.


Note that the commonly-used GNU implementations of tar and find both have info documentation which is much better than the manpages.


dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...


Which already makes it orders of magnitudes better than man


But why? You already can search through man pages with / key in your $PAGER (more/less/most/vimpager), and across pages with `man -k`/`man -K`, and I wouldn't really call proportional fonts as "orders of magnitude" better.


Thanks for the link to Kapeli/Dash - looks like something that could really make everyday work easier!


Good projects should have tutorials and complete references online in addition to man pages.

A well written manual page requires no additional tutorials, for they will be included in the text’s corpus.

Writing good documentation for one’s software is almost more important than writing the software itself; don’t force the user to have to run around the internet; be comprehensive in the manual.


Why should good documentation not be bundled with the product?


Sure. Cmake has a brief man page and a big bulky HTML manual.


> not even as a reference

How are you supposed to write reference documentation without a section for describing the options which can be referred to by option name?

> The examples should have come first, in the synopsis.

Type with me: / E X A <return>. If anything, perhaps the first manual a man user should read is the manual for their default pager, usually LESS(1).

There are good and bad manpages, but I don't see how the format is truly deficient. Some very complex commands have separate sections for the most and least common options (or groups of related options, if there are subcommands or similar).


> The examples should have come first, in the synopsis.

That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an example. You're giving someone a false sense of confidence if you throw an example at them first thing. That's appropriate enough in some contexts, but not in official documentation for software tools.

> The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad.

The problems you go on to list have nothing to do with the structure, and everything to do with the content contained within that structure.

> No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial.

Since "documentation experts" write documentation this way, it's hard to imagine why you'd assert this.


I share your reactions, with the exception that examples first or last seems irrelevant when using a man page—Sometimes it’s better first because you simply need a reminder how to use the command, and other times you need to read more of the description to catch the warnings before you use the command for the first or infrequent time. But if you follow the General best practice to read the whole of some documentation before you use a command, then this too seems irrelevant.

That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.


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


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

https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-...

    $ man test -e

           STRING1 != STRING2
                  the strings are not equal

           INTEGER1 -eq INTEGER2
                  INTEGER1 is equal to INTEGER2

           INTEGER1 -ge INTEGER2
                  INTEGER1 is greater than or equal to INTEGER2
    --

           INTEGER1 -ne INTEGER2
                  INTEGER1 is not equal to INTEGER2

           FILE1 -ef FILE2
                  FILE1 and FILE2 have the same device and inode numbers

           FILE1 -nt FILE2
                  FILE1 is newer (modification date) than FILE2
    --

           -d FILE
                  FILE exists and is a directory

           -e FILE
                  FILE exists

           -f FILE
                  FILE exists and is a regular file


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.


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.


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


You can actually search for ' -l' (two spaces in front) and abuse the man layout engine to find the point at which the flag itself is defined. Makes the man pages a lot more useful in my opinion.


If your idea of what man is comes from using Linux, then you really haven't had a good exposure to what good documentation can be. Try Solaris or FreeBSD.


Indeed!


I agree with your point. There should be easier ways of doing some things in Unix. But since there are not (for some things, anyway, and I say this as a long-time Unix guy), sometimes, scripts can help. Here is one example by me:

m, a Unix shell utility to save cleaned-up man pages as text:

https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-s...

This tiny script lets you generate man pages as cleaned-up text, saves them in a ~/man directory, and you can from then on, open them in your favorite text editor or even pager (less/more/pg/etc.) and view them. Created it out of real-life personal need some years ago, on a Unix system, but is still useful on Linux and other Unix-like systems today.


  man test | grep -- ‘ -e’
UNIX already has that as you can see. You just need to learn the target substrate you’re using.


Even though I've fallen out of love with Matlab, its documentation is excellent. Brief description of the syntax for quick reference, a more detailed description, and finally detailed examples. Often there are references to the academic work behind the function and links to broader topics. Finally there's a bunch of related functions listed at the end which is great for discovering the vast array of Matlab's capabilities.

For example: https://uk.mathworks.com/help/symbolic/svd.html


I agree. An an author of several command line tools I would never document it's usage in the way the classical man pages are structured. They are in times of dire need, frankly, unhelpful.

I ALWAYS have to Google it, since the man page gave me nothing.


and maybe Examples at the end)

On a real UNIX like illumos and SmartOS, EXAMPLES are mandatory; I’ve no idea why people believe they may be optional, as they are one of the biggest reasons why someone would call up a manual page. It’s a manual.


I must admit I'm not a fan of this. I feel like the work could go towards submitting patches to the man pages. The MAN page layout [0] allows for an EXAMPLES section which serves this purpose. Great effort in creating this tool but I think it's replicating functionality already provided by the man pages. I've submitted patches for MAN pages for GNU tools in the past and the creators are very receptive to updates.

[0] - https://en.wikipedia.org/wiki/Man_page#Layout


Yup, and the examples section is usually last, with no possibility to jump directly to it


> and the examples section is usually last

A far better answer to this would have been a project to (1) improve man page examples, and then (2) create a small alternative man page client that displays only the examples (or puts them up top).

Having said that I do see the need for what tldr is doing, even though I would have preferred it added to existing tools. More often than not I only find man pages useful after I have needed to look up something. They're usually OK for wholistic understanding, but often too dense and assuming of far too much contextual knowledge to be useful in the heat of battle.


You can jump to it by typing /EXAMPLES<enter>

Or if that seems like a lot of keystrokes, /EX<enter> will probably jump to what you want most of the time too.


"probably"

   > man less

   /EX
   pattern not found

   /ex
   ends up somewhere in the middle of the text 
   on a word that contains ex


> with no possibility to jump directly to it

How about '/examples'? Maybe you should take some time to actually learn how 'man' works before you start bashing it online...


    $ cat ~/.bin/eg
    #!/bin/bash
    man $@ | awk '/^EXAMPLE/ { getline; while ($0 !~ /^[A-Z]+/) { print $0; getline; } }'


Usually Shift-G should transport you to the end of the document.


I've integrated TLDR content into online man pages if you'd like to see both in one place. For example: https://www.mankier.com/1/grep


Good idea. I just suggested something very similar before seeing your comment. Now all you need to do is write this up as a shell command ;)


just called them "manuals"

I'd be more specific: man vs tldr/bro is almost like an appliance's user manual vs service manual. The latter is super in depth but usually doesn't explain in an understandable way how to actually use the tool. While the former does that, but once you're stuck it offers no deeper explanation and you're lost.


Maintainer here.

> This TLDR tool definitely needs to exist, but in conjunction with man pages, not as a replacement.

tldr is _exactly_ that. We do not and will not aim to replace man pages. We have a hard limit of 8 examples at max for every command. Therefore, our scope is very limited and we try to mention the 8 most important and practical examples a beginner needs to know for a command.

If someone needs to go deeper, man pages are always there.


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.


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.


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


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.


On many Linux systems there are likely to be more non-GNU commands than GNU commands, so I'm not sure your argument fully works here.

GNU historically never made man pages: they used Texinfo for documentation, possibly combined with a tool to convert Texinfo to man pages. That shows in the result: an entire manual all joined together in a single unreadably long manual page. The bash man page is a nice example of that. I'm not sure if the use of Texinfo is still a requirement for GNU projects.

The verbosity of the generated man pages for GNU software probably did influence a lot of non-GNU Linux software.


At least in bash 4.4, the manpage and the info page are two different documents.

Many GNU manpages are generated with help2man, which causes the opposite problem, i.e. they are too terse. (Also, their typographical quality is often low.)


That's a good distinction. Yeah, GNU.


The man pages for Linux kernel internals and syscalls are pretty good stuff like, inotify, procfs etc all have really good detailed man pages. The userland stuff is a different story. I think it is because BSD doesn't distinguish userland from kernel they are all shipped in the same package so manual pages are probably kept more consistent. Linux uses stuff like GNU etc for a lot of userland tools so it is more of a mixed bag different community different developers etc.


Manpages are UNIX thing, and I can tell you that GNU ones are much better than what commercial UNIXes used to be like.


And as someone who, even nowadays, still points to the commercial manual pages for SCO Unix, HP/UX, AIX, Solaris, and suchlike, oftentimes for things that the GNU and BSD manual pages simply do not cover, I can tell you that you are quite wrong.

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

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

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

Here are the HP-UX, AIX, Solaris, Illumos, FreeBSD, and OpenBSD manual pages for the ls command:

* http://nixdoc.net/man-pages/HP-UX/man1/lsf.1.html

* https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i...

* https://docs.oracle.com/cd/E23824_01/html/821-1461/ls-1.html

* https://illumos.org/man/1/ls

* https://www.freebsd.org/cgi/man.cgi?query=ls

* http://man.openbsd.org/ls

And here is the GNU one from Debian Linux written (it says) by Richard Stallman:

* https://manpages.debian.org/stretch/coreutils/ls.1.en.html

As can be seen, the commercial manual pages are not worse, and are indeed in several aspects better than the GNU one. The same is pretty much true of the non-GNU free operating systems (FreeBSD, OpenBSD, and Illumos) as well.

Notice that ...

* ... only the HP-UX, AIX, Solaris, Illumos, and OpenBSD manual pages have examples (quite apposite considering the headline for this discussion)

* ... only the HP-UX, AIX, Solaris, and Illumos manual pages explain that output falls into three basic forms

* ... only the Solaris, Illumos, and FreeBSD manual pages actually explain in detail the configuration of the colour scheme (HP-UX, AIX, and OpenBSD not having a colour scheme mechanism, in fairness)

* ... only the HP-UX, AIX, Solaris, Illumos, OpenBSD, and FreeBSD manual pages explain what the characters output by the -F option actually signify

* ... only the HP-UX, AIX, Solaris, Illumos, and FreeBSD manual pages explain that the time format used in -l changes according to how long ago the timestamp was (an odd removal for OpenBSD, considering that OpenBSD ls does the same thing)

... and so on.


This, so much this. Having only transitioned into RHEL from Solaris in the latter 1/4 of my career, I still hark back to Solaris man pages and to this day, on Linux I will do -

man foo

/EXAMPLES

And frequently find what I find, if there are any at all, very lacking compared to Solaris.

I have often thought I and others who complain about this should get involved in working on these man pages and improve this situation.


Note that the GNU ls manpage is just `ls --help` in manpage format, with a "SEE ALSO" section at the bottom which tells you where the real documentation is.


Well, that was my memory going back to 2000. It has been a while since I bothered to look into them.

I remember having to go into the official documentation available on the HP, IBM and Sun web sites to find usable information, instead of just going through man pages.


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!


These community projects are great ways to test potential upstream changes before trying to make a bunch of upstream changes. The maintainer of the project doesn't have to field half-baked pull requests.

I think a bigger problem with man pages is not that they are badly written, it's that man itself is not user friendly:

1. I can't immediately jump to an entry for "-o", I have to use a search expression that might or might not work.

2. I can't reliably search for all references to "-o" from its definition.

3. I can't reliably jump to the definition of "-o" from any given reference.

4. I sure as hell can't search for "output" and easily find that "-o" is the option that controls the name of the output file.

5. There is no table of contents, and even if there were, there would be no way to link from an item in that table to its location in the manual.

HTML, for whatever it's deficiencies might be, is a far superior format for disseminating documentation. The Vim manual is pretty good too, due to the use of aggressive tagging and tight integration with those tags. Funny part is that manual pages can be written with semantic markup, but the semantic meaning is discarded once the manual pages rendered. It is totally backwards, and the world is in need of a better manual page renderer.


Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.


Why would you want a manpage that doesn't have the structure of a manpage? If every other manpage has one structure, you want yours to have another? What's special about yours?

The consistency is not an accident and my personal experience is that the format works well.


The point is exactly that people do not want something like a man page, so they make their own thing that's not like a man page, and the suggestion "go contribute to manpages instead" isn't a good one, because it would mean making bad man pages (or not fixing the issue people have). If aspects are useful for the man pages (e.g. to make better examples sections), they can still be pulled out and added there as well.


"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.


Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.


Many of these pages would make fine EXAMPLES sections for the corresponding man pages without compromising the overall structure.


It's more important that there is convention than that the convention is optimal.

If the problem is that manuals aren't user friendly enough to new users and should have more examples of common tasks then they belong in the EXAMPLES section.

There's nothing that says you need to stick to the conventional sections either. A TUTORIAL section wouldn't be out of place.


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


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


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)? That was always the go-to for more verbose descriptions and has much more of a howto vibe about it.


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


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


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


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


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


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


I pointed you directly at the correct sources of documentation: info pages (for most GNU software) and /usr/share/docs. These are the places where howtos belong, not man pages.

The issue isn't with man pages themselves. The issue is with the expectations sites, tutorials and users themselves set for man pages.


"People who complain about man pages tend not to understand man pages."

There could not be a more valid complaint. If the man pages aren't understandable, what program is supposed to explain them?


There isn't really a single program. Man pages have been built through convention by people who've taken the time to write them, at various points following guidelines from Ritchie et al. It's usually down to the OS to explain the purpose and function of man pages in their own documentation.

For some Operating Systems, man pages are exceptionally high quality (most notably the BSDs). For some, they're bilge, but such systems tend to have init managed through systemd.

Having said that, many OSes support info(1), which provides more detailed software manuals for many pieces of software.

Of course, there are actual physical locations for forms of documentation not in man format or structure. You can find out where such documentation lives on your system on most Unix-like OSes through man:

$ man hier


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

Good luck with getting those accepted, when there's an established man page and for 30+ years simple examples like in tldr where frowned upon in almost all of them.


https://tldr.ostera.io/tar

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

What they're covering is just the examples section of a traditional man page. What makes you think people wouldn't merge these?


It's a fundamentally different goal / structure.

`man` documents every last flag, and I generally use it for a command I know decently but need to dig into particulars. It goes to a scrollable page like `less` which is important bc it's total size spans several pages.

`tldr` is shows the 3-4 most common use cases for a command, and puts it right to stdout more like `cat` so you can refer to it as you type along. I'd generally use this for a command I do not know so well.


And why could that not go in the example section of the manual?


Discussion on this page at https://news.ycombinator.com/item?id=15779457 has already touched upon this.


You hit the nail on the head. If you want simple examples, send patches to your maintainers extending (or adding) the EXAMPLES section of the manual instead of looking to a project like tdlr pages.


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.


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


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

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.


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

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


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.


I think I remember reading that a goal of StackOverflow was to essentially build comprehensive documentation of software in a question-answer format. That’s a neat idea. Most mature software has decent documentation in the form of a textbook or a technical manual, but it’s great to have everything documented in the form of “here’s an answer to every question you might have about this software.”


What I like about this though is it's easy to forget the basic options of a command you haven't used in several months. Having the most common use cases at the top of the man page would save a lot of time than digging through some textbook.


a "manual" is not inherently restricted to being a reference. there's no reason a manpage shouldn't include a quick-start guide as well.


Yeah. It looks like some people argue against each other for no reason. I am pretty sure in many fields of work a manual actually explains how to do so me thing. The infamous IKEA manual is an how-to, the last car manuals all had how-tos include: how to change radio station, how to change oil,...

Is their ever a moment, that some picks up a manual and doesn't want to know how to do something?


Usually it’s just me trying to do some task and not caring to ever “learn the command” with any depth (because I don’t use it enough for that to be worthwhile). That’s why examples are great. I can probably usually just scan the examples and quickly recognize the one that does the thing I want to do.


Of course, sometimes this attitude of mine is a problem. The most obvious example for me is git, which I use nearly every day, but still have an embarrassingly shallow understanding of. Any time something “goes wrong” I’m googling for a magic command to fix it, or resorting to crude measures like copying the whole repo directory and resetting hard.


>The most obvious example for me is git, which I use nearly every day, but still have an embarrassingly shallow understanding of. Any time something “goes wrong” I’m googling for a magic command to fix it,

This is basically the reason I use Mercurial. It actually makes sense without getting a bloody degree in "how to use your DVCS", and the help is quite nice, and not a godawful clusterfuck like some popular DCVSes that were developed by developers of major FOSS kernels circa 2005.


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.


I've been using Linux for twenty years and have maybe spent two hours reading man pages. Man pages seem to be written by engineers that honestly wrote them like it was code. It's dense material and assumes you can decipher it.

Since the days of Alta Vista and webcrawler. And even with Google, I skip the first link (man pages) and find a better explanation


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.


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/

* FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html

* DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/

* TrueOS User Guide: https://www.trueos.org/handbook/trueos.html

* PC-BSD User Guide: 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/

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 , and a nosh Guide.

* 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/chain-loading-cheatshe...

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


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.


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 .


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.


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.


Or, more likely, somewhere in the entire operation of a computer there exists a task or two in which we don't care to specialize.


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


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.


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

* https://cr.yp.to/slashdoc.html


Of course, many man pages have an EXAMPLES section. You can search for it with `/EXAMPLES` when viewing the man page. On my Linux box:

    zgrep EXAMPLE /usr/share/man/man1/* | wc -l
Gives

   897


and:

  zgrep -L EXAMPLE /usr/share/man/man1/* | wc -l
Gives

  1629


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.


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


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.


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/


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.


There is also atool.

http://www.nongnu.org/atool/


Good to know, thanks! :)


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.


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.


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.


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.


That's just a classic middlebrow dismissal comment.

This solution exists. Yours doesn't. This solution is also far more reasonable than yours. Your solution is to somehow land a manpage patch into every project while this is a single project that can be fleshed out by a single sufficiently motivated person.


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.


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


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


Yep, I love bropages!


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


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


A manpage is a glorified README. An info page is a non-horrendous version of a html manual. So to see the appeal, don't compare `man cp` with `info cp`, try some more substantial manual like the emacs manual or python's documentation. Also, emacs is a much better info reader than the standalone program.

Info pages are at least an order of magnitude more efficient to navigate than the html documentation that has supplanted them. All the following are fast and a single keypress:

- regexp (s)earch (not just the current page, the whole document)

- hierarchical navigation ((u)p, (n)ext, (p)revious)

- jump to any (i)ndex topic

- jump between links/sections (by position: tab, shift-tab, by na(m)e)

The main shortcoming of info is no support for styling (or graphics) whatsoever, but if you're used to its efficiency using a mix of googling and clicking to navigate the html equivalent is profoundly frustrating.

The closest modern equivalent I know of is Dash.


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


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

How?


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.


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


info is a failed GNU experiment to replace man pages. I stated that strongly, but they've never caught on. It's too bad; GNU had a whole plan of improving Unix learnability with getopt, bash completion, info, etc. It's all sort of been useful but hasn't really changed the way people work.


I like using info pages, pretty helpful when you use it with Emacs. Sort of wish more projects would use it.


they are where GNU projects hide the man pages in an attempt to trick you into using emacs.


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

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


Maintainer here.

The node client already has autocompletion for OMZ users - 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.


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.


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


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.


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.


Sweet. Added this to my bashrc file.

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


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


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.


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


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


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.


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


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.


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


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


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


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


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


Maintainer here. You are free to use the C++ or Go or Rust client. Use a binary all you want.

Npm is just one client.


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.


"Description", yes, "Examples", not always; https://linux.die.net/man/1/sed 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.



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


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



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.


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


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)




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact

Search: