Hacker News Reader

Comment by Mahn | Hacker News Reader

I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them. For example, if I already understand how tar works and have a general idea of how to use it, man tar is great to drill down and find specific options and switches that I need or don't remember, but if I have no idea what tar files are or why would I want them, the man page really doesn't help much in explaining things.

I guess you could argue this is supposed to be so and man pages are doing their job, since they are documentation and not tutorials, but still.

View on HN

> I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them.

This is actually true. In some of the early Unix documentation or an interview (I can't remember which), one of the core Unix developers said pretty much this, i.e., that man pages were more like a collection of rough notes to help the developers of the Unix system itself not to forget how the commands should be invoked.

Info pages are better for that.

Info pages should be banished from the face of the earth.

https://xkcd.com/912/

I don't get it. The info pages usually have way more information available, and are proper software manuals with plenty of worked out examples, voluminous descriptive text, and hyperlinks to related resources. Try `info sed` and compare that with the bare breakdown of command line options and basic syntax of `man sed`.

I'm not sure what that comic has to do with anything.

Man pages are (in my experience) almost always viewed on a text console or terminal. Info pages work poorly there, and it's just frustrating to be looking for some information in a man page and have to start up some other program with a different UX to complete the task.

Man page standards have places for "See also" and "Examples" and that is good enough.

The options section is no doubt for people, who know the tool. But the huge section with examples is not.

Did you read the "Reader's guide" which is presented before the first option in the man page?

There was a time when many man pages had healthy EXAMPLES section. It seems less frequent now. And info pages are a disaster.

we have bropages for that alas they don't see much activity.

Can I ask to to run these and then comment?

LESS=+/EXAMPLE: man parallel

LESS=+/Reader.s man parallel

man parallel_tutorial

I'm sorry if you got the idea that EXAMPLE section is lacking in parallel manpage.

I wasn't checking that, I was ranting on the general state of man pages. I checked ls, curl, wget, mv - none of which had EXAMPLE sections, and that's where I wrote the comment. Didn't even have parallel on my system.

Reply on news.ycombinator.com