Short Bytes: Software man pages and documentation can be thick and difficult enough for any beginner without the cryptic conventions laced with every kind of bracket and parenthesis. Here, we’ll try to tone down the complexity of Linux man pages and make it easier to understand.
NAME
First is the name heading, and that about sums it up. This section includes the name of the utility, as well as a brief description.
SYNOPSIS
There are varying degrees of readability from man page to man page, but one things is sure, the hardest part is typically deciphering a hairy synopsis. There are several conventions for indicating the required pieces of information for any given command. These conventions consist of different brackets and parentheses, as well as other forms of notation. All these different conventions can be extremely confusing for a beginner, and daunting still for someone that’s experienced but not versed in the art of manuals. Below we’ll break down the gibberish into digestible rules.
| emboldened | Type exactly as shown. |
| italic or underlined | Replace with appropriate argument. |
| [-abcxyz] | All flags within square brackets are optional. |
| -a | -b | Options separated by pipe cannot be used together. |
| <mandatory> | Mandatory argument, usually found in option descriptions. |
| {yes, no} | Limited options, only those specified will work. |
| … | Arguments followed by an ellipses can be repeated. |
These rules are fairly simple, but they get more difficult, and even intimidating, when they’re used in long function definitions, especially when they’re nested. So, we’ll take a look at some nesting below to build up what we’ve broken down.
tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ARG…]
The tar command has many options. We see the name of the tar command in bold because it should be typed as shown. Then we see the braces open with pipe-separated options indicating that we are limited to those and must chose only one. Next are the optional flags, we can use any number, though, they might not all work together, reading further into the man page will shed light on any potential conflicts of options. And, lastly, we have the repeatable argument, in the case of tar this for the file(s) you’re operating on.
su [options] [-] [user [argument…]]
Again, we see su bold because it’s the name of the command. Second, we see that no flags are actually specified, only that they are optional. Thirdly, there is a single flag that is specified, but it too is optional. Last, we see an optional argument that’s repeatable inside an optional argument. Now, what used to look very mysterious is making more sense.
whois [{-h|–host } HOST] [{-p|–port} PORT] [-abBcdGHKlLmMrRx] [-g SOURCE:FIRST-LAST] [-i ATTR[,ATTR]…] [-s SOURCE[,SOURCE]…]
[-T TYPE[,TYPE]…] [–verbose] OBJECT
This is a particularly dense one. Copy it into your favorite text editor and add some extra spaces in there if it helps you read it. After scanning over this, you should start to see a couple patterns. The host and port portions use the same formatting for the short and long form of the option followed by the argument for that option, while both being optional themselves. Then we see the string of optional flags. The next bit about sources from first to last is the syntax that is expected by whois that is explained later in the man page. Now we see this triplet of optional flags that take either a single argument or optional repeating arguments, this is the kind of compounding of the conventions that can be very difficult to fully grasp at first. Lastly there are verbose option and the object (the host/domain).
And that’s how to read a man page synopsis. There are a few other conventions, but they are much too obscure to cover in this article.
DESCRIPTION
This is generally where the intended use of the program or utility is outlined. Some manuals will be much more verbose under this heading than others.
OPTIONS
Remember all those flags and different arguments that could be optional or mandatory? This is where they all get explained. There is usually good information in here and it is often where you’ll find the <argument> convention, indicating that a given flag requires a corresponding argument. Sometimes you will find that the options will be in the description portion because there is no hard rule defining man pages, only conventions, and the will to comply with the standards.
EXAMPLES
This is one of the handiest parts that’s unfortunately not included in all manuals. You’ll also find that the amount of information and the number of examples varies significantly, and not all examples actually help with using the command.
Additionally, you’ll regularly find sections for the author, copyright information, bug reporting, and see also (apropos).
Beyond this, there are the formally defined sections of man pages as defined below.
| 1 | Executable programs or shell commands |
| 2 | System calls (functions provided by the kernel) |
| 3 | Library calls (functions within program libraries) |
| 4 | Special files (usually found in /dev) |
| 5 | File formats and conventions eg /etc/passwd |
| 6 | Games |
| 7 | Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7) |
| 8 | System administration commands (usually only for root) |
| 9 | Kernel routines (not normally found on Linux) |
Many commands do not have manuals in more than one section, but for the ones that do, or for some that might be ambiguously named, you can specify the section like the example below.
Commands aren’t the only things that have manuals as you can see from the available sections. Systems calls, configuration files, and special devices may just as likely have a corresponding man page. The amount of information on a typical Linux installation just in man pages is amazing, and the same applies to other open source UNIX-like operating systems.
If you find that the man page doesn’t suffice and you still don’t understand a command, always check online because many people offer more thorough explanations of certain tools, but also, many distributions have their own man pages for different software packages. Once you have found that you’re comfortable with a piece of software, but still feel the manual is lacking, you can always contribute by writing your own and submitting to the respective project. Documentation is often the most neglected part of software projects, so even if you can’t write code, you can write manuals, Wiki articles, and tutorials to help others.
Now that you know the anatomy of a man page, you have no excuse but to RTFM (and that’s read the free manual for those of you under 18) ?
Also Read: Linux Lexicon: Use Watch Command To Run A Command Every X Seconds
