mjhjmtu

For example,

[fakename]$ type echo
echo is a shell builtin

But man echo gives me the GNU coreutils version of echo. What's the easiest way to tell if the man page I'm looking at is the correct one, i.e the one for the utility I'd get if I directly invoked it?

You don't, really. Not without knowledge external to the man page.

In the case of echo (and printf, and test, ...), it's often a shell builtin, so you'll need to know that and read the shell's documentation.
_{(And echo is notoriously different in different implementations, use printf instead.)}

In most, if not all shells, you can find if something is a builtin with type command, e.g. type echo will print echo is a shell builtin. (type is specified by POSIX but e.g. fish supports it too, as non-POSIXy as it is.) In Bash, you'd then read man bash, the online documentation, or use the builtin command help (which is specific to Bash, and which you need to know exists).

Even if the command is not a builtin, it's possible that there are several commands with the same name, rename being a famous example (see Why is the rename utility on Debian/Ubuntu different than the one on other distributions, like CentOS?). Now, your OS should have the correct man page for the actually installed utility, and e.g. in Debian, the "alternatives" system updates the corresponding man pages also when the command alternatives are changed. But if you read an online man page, you'll need to be aware of it.

Many utilities have a command line option like --version which might tell you what implementation that command is. (But not nearly all utilities have it. I think it's a GNUism originally, so GNU utilities have it, as well as those that happened to copy the custom.) In the case of rename, it happens to work in telling two different implementations apart:

debian$ rename --version
/usr/bin/rename using File::Rename version 0.20
centos$ rename --version
rename (util-linux-ng 2.17.2)

Besides that, your system might have an alias or a function with the same name of a utility, usually to modify the behaviour of the utility. In that case, the defaults presented in a man page might not apply. Aliases for ls are common, as are aliases adding -i to rm or mv. But type foo would also tell you if foo is an alias or function.

If you want the manual for a built-in command, then you need to look at the manual of your shell. The command will be documented therein, along with all other built-in commands (or there will at least be a reference to where the documentation for builtins is to be found).

• 
  bash: man bash or help echo from an interactive bash shell.


• 
  zsh: man zsh (and after a bit of reading, man zshbuiltin)


• 
  fish: man fish (and after a bit of reading, help echo)

The manual that you get for man echo documents /bin/echo, i.e. the external echo command. This command is not what you would use when you use echo without an explicit path.

It should be possible to invoke the non-shell-internal version by giving the full path (which you could get with which echo). There are not separate manpages for shell internals; for documentation on those you'll want to look for the manpage for your shell. The "type" command you mention above is the best way to figure out which you'll get.

Since the command you want to get information on is a shell built-in, typing help <command name> in the same shell will give you the correct help entry:

$ help echo
echo: echo [-neE] [arg ...]
 Write arguments to the standard output.
 ...

Alternatively, you can type man bash(or whatever shell you are using) and find the builtin you were looking for.

Unfortunately, there is no easy way to verify that a man page fully matches the command you want to run. Getting the "right" page is trickier than it seems, as that will depend on many factors such as the command's full path, environment variables and aliases, and it's technically impossible for man do account for all such factors. However, after a short while you should develop general understanding of where to look for help.

If I were to describe a general algorithm of getting the right documentation on most modern *nices, it would look something like this:

• Do you need help with a built-in (type <command> says it's built-in)?
  
  
  • Use help <command> or man <shellname> if help is unavailable in your shell.
  
  


• Do you want your help succinct and technical?
  
  
  • Use man <command> (or man <section> <command> if there are multiple entries in different sections, see man man for the list of sections)
  
  


• Do you want your help in the form of a lengthier interactive tutorial/manual (if available)?
  
  
  • use info <command>
    
  
  


• If the above steps fail:
  
  
  • Check /usr/share/doc/<package name> for additional documentation on the package, such as HTML pages.
  
  
  • Run the command with the -h or --help options, assuming the command is to be trusted. That will oftentimes give a brief summary of what it does and tell you where you can find more information.
  
  
  • Google.
  
  

but I must reiterate, this all will become "natural" as one spends some time with the OS.

man is split in section:

1. General Section


2. System Calls


3. Library Functions


4. File Formats


5. Games and screensavers


6. Miscellaneous


7. System administration

Depending on what you are looking for you can invoke man like that to avoid confusion: man section command.

For more information you can actually use man man

If your OS distro does not have man pages for those programs that mention the differences, you should make bug report.

In fact, this is the task of the distro creators, but if you type:

type cmdname

you will get output whether cmdname is a shell builtin. If you know what shell you are using, you could run:

man shellname

replacing shellname with the name ouf your shell. The man page of your shell should contain information about builtin commands.

Let me give an example on how a user friendly UNIX should document this: http://schillix.sourceforge.net/man/man1/test.1.html