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.
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.
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.
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.
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.
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.
> 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/
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.
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.
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.
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)
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.
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.
>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.
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.
TFA uses a “NodeJS” “client” and its members nerd out on “Gitter”. I’m not sure what the hell any of that hipster bullshit means, but to people of that ilk, if it’s not on GitHub it does not exist.
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.)
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.
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.
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.
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".
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.
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.
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.
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'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.
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>`
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)
- 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.
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`.
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.
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.
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.
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.
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.
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.
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.
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.
Are you looking for hacker? Contact for any hacking such as Facebook Hacking, Whatsapp Hacking, Instagram, Mobile Hacking, Increase credit score, removal of name from criminal record, removal of links from website. Recover Your email passwords, Hack into Bank/Company web site, etc,if you have any hacking contact: incfidelibus@gmail.com
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.
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.
11 replies →
> 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.
1 reply →
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
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? )
9 replies →
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
6 replies →
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/
1 reply →
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.
1 reply →
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://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.
3 replies →
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.
1 reply →
"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.
3 replies →
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.
8 replies →
"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?
1 reply →
>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?
2 replies →
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.
TFA uses a “NodeJS” “client” and its members nerd out on “Gitter”. I’m not sure what the hell any of that hipster bullshit means, but to people of that ilk, if it’s not on GitHub it does not exist.
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.
3 replies →
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.
1 reply →
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://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.
3 replies →
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:
Gives
and:
Gives
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:
To extract:
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.
4 replies →
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.
1 reply →
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.
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!
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.
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?
2 replies →
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.
If you have Pandoc and w3m:
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:
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.
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 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.
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.
Only looking at GNU manual pages gives you a wildly incorrect impression of things.
* http://man.openbsd.org/sed#EXAMPLES
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.
Are you looking for hacker? Contact for any hacking such as Facebook Hacking, Whatsapp Hacking, Instagram, Mobile Hacking, Increase credit score, removal of name from criminal record, removal of links from website. Recover Your email passwords, Hack into Bank/Company web site, etc,if you have any hacking contact: incfidelibus@gmail.com
Duplicates https://news.ycombinator.com/item?id=15769046
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.
1 reply →