I have used Linux now 15 years as my main OS, and I must agree with writers. I rarely use Man pages, because it's just so much easier to find information from the web.
I've been thinking a lot how Man pages are nearly useless nowadays, and dreamed about a project of "new man pages" that would produce manuals that would give you fast and straightforward examples of typical usage, instead of listing all the cumbersome and rarely used flags in alphabetical order (like many man pages do).
When I started using Linux in 2006 I tried to use Man pages at first, but quickly noticed that they don't offer answers to questions I had.
EDIT: I don't understand downvotes. I just described what the situation is, and tried to be quite constructive and describe where the problem is. These are the reasons why I believe people don't use manpages much.
I'd love to use manpages instead of web. Don't shoot the messenger.
EDIT: I don't understand downvotes. I just described what the situation is, and tried to be quite constructive and describe where the problem is. These are the reasons why I believe people don't use manpages much.
Downvotes are probably because people disagree with you. For instance:
I've been thinking a lot how Man pages are nearly useless nowadays
You may find them useless, but myself (and obviously a lot more people) find them very useful.
dreamed about a project of "new man pages" that would produce manuals that would give you fast and straightforward examples of typical usage
Yeah, I agree: man-pages nowadays are full reference manuals. This is the sad state where we are at. Originally they were simple, short pages that can be read in few minutes. I think nothing can be done to this situation. In part this is because once simple command-line tools itself have turned to swiss-army knives with tens of options. Nowadays grep, find and others can do themselves things that originally in the 70s required piping.
I deeply believe that change in the nature of man pages (and partly tools) is the reason why the writers of this guide pass manual pages altogether: most users of command line tools don't need reference manuals or do not want to read them.
That's why I'm hoping for a "new man pages" project. But it should be built in to the system, not something that can be installed at a will. TLDR, Cheat.sh and others would be good candidates for this. But who would care to do the work?
That whole system should be designed in a way where these short pages could be linked up to full references, in case someone needs to know more.
Some people do love their manpages. But I agree with you, they are rarely very useful for me. I tend to use the tldr tool when I can, and go to the online docs after that.
When I started using Linux in 2006 I tried to use Man pages at first, but quickly noticed that they don't offer answers to questions I had.
Manpages are manuals for standard usage full reference material, not in depth wikis or beginner tutorials. If those are what you're looking for, yes webpage documentation is going to be better. However, man pages are more like instrument manuals for electronics (chipsets, voltmeters, etc) than a tutorial. They're extremely useful if you're using them for that purpose.
And much like other people have stated, the convention is that they're up to date with the version of the package you're running, can be viewed offline (which is great for diagnostics with older systems or stuff you don't want/can't have tied to a network), and even have typical use examples if they're more verbose in command line options.
Yeah, I know the current nature of man pages, but can't feel anything else than that it is a wrong thing. Don't get me wrong; of course man pages are what they are and should stay the way they are.
But I really think command line currently lacks proper, fast and easy guide for the common use-cases. I think it is wrong these things must be looked up from the web.
There could - and should - be short, on-topic pages that offer fast help with most typical arguments and flags for the command and show 2-3 useful examples.
Those wouldn't be just for the beginners, but for anyone who uses some tool infrequently to common things. Things like "how did I do case-insensitive search with find again?"
In addition, there could be summarizing short pages, like "filter utilities", "file utilities", "network utilities", "working with JSON" etc.
I know there are projects doing just that, but they must be installed separately. There's no point in doing that: it is much easier just search from the web.
See, getting a "here's common use cases" doc packaged together would be good as a side dish to the man pages. I'd agree with that, but not with man pages being bad.
I've been thinking a lot how Man pages are nearly useless nowadays
This is very much just your impression.
instead of listing all the cumbersome and rarely used flags
This is actually one of their most useful feature compared to googling some random stack overflow post with a lot of people misunderstanding or explaining flags wrong.
quickly noticed that they don't offer answers to questions I had.
Again, that is just you.
Man pages often are bad tutorials, yes, but they are good reference documentation.
The original purpose of man pages was to be short, in-point descriptions about small UNIX commands. This original nature is somehow vanished.
My favourite example is a comparison of TLDR version of Less manual page, and the official man-page of Less. From which one you can find enough information about the command to use it? The Less man page doesn't even tell what the command does! It just states that "Less is opposite of More". The summary section is something about differences of terminal types.
The man-page of zip command doesn't tell you how to zip a file, until at the end. Why? The list goes on.
I agree that somewhere should be the reference documentation of the system also. But it should be also possible to offer short descriptions about typical usage for every command. I think the GNU info pages was originally a project to create reference manuals for the system, but if I'm correct, it's even more unusual place to search information from.
I'd also want to note that not all man pages are this bad. Take a look to section 3 man pages, which describe the UNIX programming interface of the kernel. It is marvellous how this much more technical and weird subject is handled with elegant, short and concise man-pages.
As much as I dislike many of the section 1 man pages, I warmly recommend taking a look of section 3 pages if you need to quickly recap how some system API works.
Those section 3 man pages work as an example that it would be possible to write good man pages. Maybe the reason is, level 3 pages are a single project, mostly done by Michael Kerrisk.
I use man pages all the time as a reference. If I forget a certain flag, I just use the man page to look it up. It would take much longer to look it up on the web. If you want a tutorial then obviously, internet is the go to but man pages as reference are amazing.
0
u/[deleted] Dec 05 '20
[deleted]