There is a lot of on-system documentation available in a typical GNU/Linux (or similar) system. These range from the built-in help in tools, to manual pages, texinfo pages, examples and other packaged documentation in various forms. Knowing how to navigate these troves of information will help you immensely when you are looking for help on a particular part of your system.
Built in help
Most tools will have built in help which will, at least, give you an idea of
the commandline syntax for using them. The standard way for tools to offer
this to you these days is with a
-h commandline argument.
$ who --help Usage: who [OPTION]... [ FILE | ARG1 ARG2 ] Print information about users who are currently logged in. -a, --all same as -b -d --login -p -r -t -T -u -b, --boot time of last system boot ...
Commands which have been grandfathered in from a time before GNU long options
were common may require the
-h option form:
$ reset --help reset: invalid option -- '-' Usage: tset [options] [terminal] ...
Often this is good enough to get you the help, but sometimes it'll really be
confusing. Some commands don't support
--help (or they end up
mapping them to real arguments) and so you need to do something outlandish to
get them to give up their hoarded secrets:
$ ssh-keygen -\? ssh-keygen: illegal option -- ? usage: ssh-keygen [options] Options: -A Generate non-existent host keys for all key types. -a trials Number of trials for screening DH-GEX moduli. ...
Every now and again, a command has sub-commands (for example
morph) and for those there may be a
help subcommand to help you along. For
$ svn help ls list (ls): List directory entries in the repository. usage: list [TARGET[@REV]...] List each TARGET file and the contents of each TARGET directory as they exist in the repository. If TARGET is a working copy path, the ...
Give it a go, explore what commands can tell you about their usage and see what you can learn in only a few minutes.
Most commandline applications, and indeed many non-commandline apps have manual pages. Manual pages are an old concept and as such they are often well provided for. Unfortunately they are also often written in a special language known as Mannish which can take a while to get used to.
man command is your primary gateway to the manual pages on your computer.
There is also
man -k which can be used to search for appropriate
pages to display. Manual pages are usually rendered for your terminal width at
the point you invoke the
man tool and will be displayed in the pager for you
to scroll up and down at will.
$ man ls ... the manual page for ls is displayed ...
$ apropos revision darcs (1) - an advanced revision control system git-blame (1) - Show what revision and author last modified each line of a file gitrevisions (7) - specifying revisions and ranges for git uupdate (1) - upgrade a source code package from an upstream revision
Whenever manual pages (or indices) refer to other manual pages, they will tend to state not only the name but the section where that page can be found. That is the number in parentheses following the manual page names in the listing above. Traditionally the manual sections have specific meanings...
- 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
- 5: File formats and conventions eg
- 6: Games
- 7: Miscellaneous (including macro packages and conventions), e.g.
- 8: System administration commands (usually only for root)
- 9: Kernel routines
You will also find unusual manual sections such as 3pm for Perl modules.
If you find that a given name for a manual page is available in multiple
sections then you can select which section simply by running
page. For example, the
passwd program has a manpage, as does the
$ man passwd ... passwd(1) is shown... $ man 5 passwd ... passwd(5) is shown...
GNU introduced a mechanism of offering documentation which was more powerful,
hyperlinked and theoretically easier for the author to produce than manual
pages. This is the
info system. Documentation in this form is
often referred to as a Texinfo manual and the
info program gives you access
Sometimes manual pages will refer you to a Texinfo manual for further information about the topic you are investigating. For example:
$ man ls ... The full documentation for ls is maintained as a Texinfo manual. If the info and ls programs are properly installed at your site, the command info coreutils 'ls invocation' should give you access to the complete manual.
The example given (
info coreutils 'ls invocation') shows how you can use the
info tool to jump to a particular node (
ls invocation) in the manual for
Navigating in the
info tool is pretty simple. You can use the arrow keys to
move around the document. Anything with a double colon (
::) after it is a
link and you can press ENTER when your cursor is over such a link to traverse
it. There are also a number of single keypress navigation options:
- SPACE: Page down
- b: Go up a page
- n: Go to the next node
- p: Go to the previous node
- q: Quit the viewer
But perhaps the most important keypress to learn is h which will show you
the help for the
Packaged help and examples
This is the least well structured of the options available on a typical system. There is no standard way for examples etc to be provided. I shall limit myself to where you can look on Debian and derived systems such as Ubuntu or Linux Mint.
On these systems, each package which is installed places additional
documentation in two common places. The first is simply a second package
whateverpackage-doc. For example, there is
and its associated
libvdk2-doc packages. To get these
packages onto your system, simply install them as you would any other.
Whatever package you are interested in, be it a
-doc package or not, you can
dpkg for the list of files in it with
dpkg -L packagename and if you
pipe that through
grep doc then you'll get a good idea of where documentation
can be found.
$ dpkg -L subversion | grep doc /usr/share/doc /usr/share/doc/subversion /usr/share/doc/subversion/NEWS.Debian.gz /usr/share/doc/subversion/copyright /usr/share/doc/subversion/HACKING /usr/share/doc/subversion/changelog.gz ...
As you can see, each package will also install a
directory into which various documentation may be placed. This is a common
place to find examples.
$ dpkg -L gnupg | grep example /usr/share/doc/gnupg/examples /usr/share/doc/gnupg/examples/convert-from-106
There's clearly many other places where documentation might lurk. Some of it
might show in things like the GNOME documentation index displayed if you run
gnome-help. Simply examine the contents of packages to see where they might
be hiding documentation and you'll rapidly find it.
There is a significant amount of documentation available on your typical GNU/Linux (or similar) system. There's often no need to go to Google to find what you need to know. Just learn how to navigate what you already have.