MAN PAGE
Jimmy is a newbie in the tech industry and he is just learning how to use the Linux bash. Just like most other average joes that are new to tech, he begins to tinker with the bash terminal, trying out every trick he finds on google or YouTube or any website on the internet.
Life is great, until something happens. He mistakenly edits or deletes some important files in the PC. He doesn’t understand where the problem is coming from, and his PC is behaving in ways he can no longer decipher.
We have all been like Jimmy at some point in our lives, but who said it must be like that? Using the Linux bash can be overwhelming for a lot people, especially beginners. A lot of commands with many different options and parameters that can greatly modify or change your desired result.
Sometimes you may decide to ask someone for help, and they may say something like, “I don’t really know the exact way to do that, I think you should check out the man page for that command”.
Man page. What is that? Simply put, a man page is a formal piece of documentation provided for most command line programs. It helps users to understand how different Linux bash commands can be used. It is a documentation written to help users use their PCs in the safest and most productive ways possible.
The man page is used like this: man <program>, where program is the name of the command to view.
Man pages may have different layouts for different commands, but they generally consist of the following parts:
- A title: Name of the page.
This is the name of the command or function, followed by a short and simple description of what it does.
- synopsis of the command’s syntax.
A brief overview of how you can use the command. What parameters can it take, and in what order.
- A description of the command’s purpose.
A somewhat verbose description of what the command does.
- A listing and description of each of the command’s options.
Lets look at the example below:
In the image above, the green arrow points to the name of the command, the white arrow points to the brief description of the command, the red arrow points to the synopsis, and the blue arrow points to the description.
Let us take a quick look at the synopsis.
Get Anthony-Ikpe Godspower’s stories in your inbox
Join Medium for free to get updates from this writer.
The first word is usually the name of the command. In this case, it is mkdir. Then the next word is [OPTION], why the square bracket? These computer guys are so weird, jeez.
The square bracket indicates optional parameters, or flags. Most of them are very useful, as they help us modify the output of our result results in different, desirable ways, if and only if, you know how to use them.
The next word is the “DIRECTORY”. Notice that the directory is not in parenthesis. What this means is that the argument is required. You must provide the name of the new directory you want to create.
Now let’s go back to the image above. Notice the green arrow at the topmost part of the image. Notice the number beside it. It is important to note that the man page has different sections, so it can be used like this:
man <section> <program>.
Section Contents
1 User commands
2 Programming interfaces for kernel system calls
3 Programming interfaces to the C library
4 Special files such as device nodes and drivers
5 File formats
6 Games and amusements such as screen savers
7 Miscellaneous
8 System administration commands
different sections contain different information, sometimes we need to refer to specific sections of the manual to find what we are looking for.
As we may have noticed, man pages may be a bit technical, but they are concise and usually very accurate. It is highly encouraged that users have a good understanding of whatever command they choose to use in order to avoid a “jimmy” situation.
NB: be careful when using the linux bash, you can easily delete important system files and programs.
To learn more about the different kinds of brackets in man pages and what they could mean, you may want to check out this post from stackoverflow.
This textbook by William Shotts is very beginner friendly and you might want to check it out too.
Disclaimer: I am not affiliated with the author or publishers of the book in anyway. I am not gaining anything if you buy or use their products. I am only recommending them for educational purposes.
