man, apropos and whatis

[debtboy]

Thought I'd try my hand at a simple tutorial...

One of the most important features of any Linux System is the Manual, otherwise known as the Man Pages.
The Linux man pages is a project that documents the Linux Kernel and C Library interfaces employed by user programs.

It's broken down into the following sections:

1 General commands
2 System calls
3 C library functions
4 Special files (usually devices, those found in /dev) and drivers
5 File formats and conventions
6 Games and screensavers
7 Misc.
8 System Administration commands and daemons


All individual man pages follow a common layout:

NAME
The name of the command or function, with a one-line description of what it does.

SYNOPSIS
In the case of a command, you get a formal description of how to run it and what command line options it takes. For program functions, a list of the parameters the function takes and which header file contains its definition. For experienced users, this may be all the documentation they need.

DESCRIPTION
A textual description of the functioning of the command.

EXAMPLES
Some examples of common usage.

SEE ALSO
A list of related commands or functions.

Other sections may be present, but these are not well standardized across man pages. Common examples include: OPTIONS, EXIT STATUS, ENVIRONMENT, KNOWN BUGS, FILES, AUTHOR, REPORTING BUGS, HISTORY and COPYRIGHT.


When you run man, at the command line, the return is sent to standard out using "less" as the default browser. This is why it only displays a page worth of data and allows you to navigate through the rest of the output with the following:
<enter key> - increment line by line through output
<spacebar> - increment page by page
<q> - quit

In addition you will notice a number in parenthesis after the NAME like man(1), this number refers to the section mentioned above.

To use man, at the command prompt type:
man <command name>

<command name> being the exact name of the command/function, for example...

man man





(If I could only give one command to a Linux newbie, it would be: man man)



apropos (which is the same as man with the -k option (man -k)) searches through the man pages NAME and DESCRIPTION areas for occurrences of the keyword (pattern). This is especially useful when you can't remember the exact command name, but you know the partial name (NAME) or what it does (DESCRIPTION).

The apropos output is sent directly to standard output without the benefit of a default browser such as less or more, so if the output is more then one screen you might want to pipe the output into less or more for convenient browsing.

To use apropos, at the command prompt type:
apropos <keyword>

<keyword> being the name, partial name or partial description, for example...

apropos manual
or
apropos manual | less



The apropos command returns information from the whatis database, which is basically a database containing a command name and a one-line description which matches the NAME section of the Man Pages. This database is also used below with the whatis command.

whatis is another piece in this documentation puzzle. Most descriptions say it searches the whatis database for a matching complete keyword. Basically, I think of it as a man page summary.

whatis <keyword>

<keyword> being the exact command name/function, for example...

whatis man
(the most perfect thing ever made, Ha! Ha! Ha! --sorry )



These 3 commands (man, apropos and whatis) can help a new, as well as experienced, Linux user through most any command line problems that arise.
In addition to these 3 commands, there is an alternate help system for the Linux user called... info, but that system is beyond the scope of this tutorial.

Experiment with man, apropos and whatis as they are useful tools when navigating the command line.



References:
Man page - Wikipedia, the free encyclopedia
Linux man-pages home
apropos - Linux
makewhatis(8): Create whatis database - Linux man page
Linux MAN Pages - Linux Documentation with Search
The GNU info Command

[marwex89]

Good to see you're writing tutorials - this one is great! Well explained and thorough, that's a +rep for sure

[Jordan]

Very good tutorial! Man is a great and useful resource. Now, if we can only get people to start using it... +rep!

[marwex89]

I remember laughing hard after trying "whatis penis".... lol

Nothing appropriate

[debtboy]

To finish up this tutorial, I'm adding a very brief description of the info command/documentation system mentioned above.

The info command/function displays documentation saved in the info format which is typically created from a
texinfo source (texinfo is a language) using the makeinfo command. texinfo was created to use a single document
for online as well as printed documentation.

The info command structure is as follows:

info <filename>

<filename> being the name of the info file (typically the name of a command)

info man





A wealth of information on the texinfo language and format is easily obtained via...

info texinfo



info, just like man, apropos and whatis are all great tools, let's make use of them.


References:
Using the Linux Info Command - To Get Info on a Linux Command | DataStronghold.com
info - Linux Command - Unix Command

[debtboy]

I remember laughing hard after trying "whatis penis".... lol

Nothing appropriate

Ha! Ha! Ha!
when I run that under my login I get this...

when used properly... inheritance is divided

just kidding

[WingedPanther]

Very nice. +rep

[Jordan]

Ha! Ha! Ha!
when I run that under my login I get this...

when used properly... inheritance is divided

just kidding

LOL, now that is funny!