0

I recently gave a workshop on Linux tools and have been telling students to consult the man pages of commands should they run into errors.

However, I noticed that the command itself never returns a message to see the man page with the man command.

Most commands advise to use the --help option, use the info page, a blurb on the usage or just print the error message.

I am wondering why does no command ask the user to consult the man page? Wouldn't that be the first place to go looking when it is being used incorrectly?

closed as primarily opinion-based by Thomas Dickey, jasonwryan, thrig, HalosGhost, Rui F Ribeiro Oct 31 '16 at 23:52

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 4
    --help is a terse prompt for the command, to refresh your memory. man is the detailed documentation. If you need to be told to read the man page, your problems extend beyond forgetting what the various options for a command are... – jasonwryan Oct 31 '16 at 23:10
  • @jasonwryan Right, but one would think the --help message would lead users to man. I looked up the --help messages of some commands but none lead to the man page. There is almost no way a novice user would even know of man unless someone explicitly tells them to do so. – mkc Oct 31 '16 at 23:16
  • @Ketan: But the user only needs to be told once, not by every single utility. (I'd get severely annoyed if my utilities contained some repeated red tape about reading the man or info pages.) I believe the user should be told about man, and man -k, even man -k topic | less, before letting them on the command line, actually. – Nominal Animal Oct 31 '16 at 23:21
4

There is an objective reason for this.

--help is a flag built in to the utility itself—built into the binary executable, or if it's a script then built into the script.

Man pages are stored separately on the filesystem from the executable itself.

Man pages can be missing and the executable itself still accessible.

As a utility developer, pointing users to a documentation resource which may or may not be present on their system makes less sense than inlining the information in the code itself.


Not only that, but the version of the executable and the version of the man page may or may not line up.

I have encountered this, for instance, when a version of Postgres was shipped with a certain package, and a different version of Postgres was also installed on the system. man psql would show information for one version, but it wasn't the version you actually got by running psql. If there were no --help flag, I would have had a big mystery why certain options didn't work according to the man page.

0

This is subject to opinion because there likely are no statistics on how advice in error messages is presented.

The predominant tie-in which I have seen is to print the usage message (which may be more than one line), perhaps because telling someone to read the manual page was unnecessary. Telling someone to read the --help message is redundant, and only a small fraction advise reading the info page.

All of the programs which I have developed provide a usage message (usually multiple lines).

Not the answer you're looking for? Browse other questions tagged or ask your own question.