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.
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.
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.
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 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
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:
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.
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:
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.
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.
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.
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/
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.)
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)
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.
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.
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.
> 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.
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.
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.
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.
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:
>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.
`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.
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.)
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.
Interestingly, Stack Exchange answers are sometimes constructed by people using search engines to find phrase matches, sometimes with ridiculous results. (-:
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.
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.
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".
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.
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:
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.
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>`.
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.
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.
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 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)
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.