Discovering the system
When faced with a challenge our first instinct might be to search google or stackoverflow. But unix systems come with high quality online documentation.
What are reasons to prefer the online documentation?
- It reflects the state of our actual system.
- It has a well defined, uniform format.
What is the format of the documentation?
There are three common forms of documentation from least informative to most:
Help
Most commands have a --help option.
This usually gives a short usage summary.
Just enough if you’ve forgotten the name of an option
but otherwise are familiar with the program.
Man pages
Man (short for manual) pages have a very compact, well structured format.
They are organized into sections by topic
and the pages themselves are also divided into sections.
To learn what these sections are run man man.
Man pages are opened by an outside application.
This application is called the pager
(and can be set through the Environment Variable PAGER).
On most systems by default this is less.
You can get a help screen by pressing h.
There are also graphical programs which can display man pages like yelp.
Info pages
Info pages are the most detailed kind of documentation out of the three. They are like miniature (or sometimes not even that miniature) books.
They have: - Multiple pages by topic - A Table of content - And a multilevel hierarchy
By default they are opened with the terminal program info.
There are also graphical programs to open them (like TkInfo).
Or there are programs to convert their source (called texinfo)
into HTML pages.
(like texi2html)
How to find topics
The apropos command can look for keywords in the short description of man pages.
This is equivalent to man -k.
For info pages there is an analogous option: info -k.
When faced with an unknown command (for example when reading a shell script)
we can use the whatis command to display a one line description of the given program.