Perkify - Manual
Written by Rich Morin.
Precis: introduction to using the Perkify manual
In the first two years of the history of Unix, no documentation existed. The Unix Programmer’s Manual was first published on November 3, 1971. The first actual man pages were written by Dennis Ritchie and Ken Thompson at the insistence of their manager Doug McIlroy in 1971.
Although they can be cryptic, man pages provide a wealth of information on commands, devices, files, library functions, system calls, and other aspects of the operating system. They are also supported by a variety of tools. So, learning how to use the man pages is basic knowledge for Perkify users.
Linux borrowed the idea of man pages from Unix, recapitulating most of the page content and supporting tools. Linux variants (e.g., Debian, Ubuntu, Perkify) carry on this tradition. Because most package developers also try to provide man pages, you can expect most of Perkify’s commands to have them.
The man pages are divided into a set of topical sections.
Often, the section number (or name) is appended to the page name,
giving a hint as to what it describes.
So, for example, the
man(1) page refers to the
documented in section 1.
In Linux systems, the principal manual sections are organized as follows:
Executable programs or shell commands
System calls (functions provided by the kernel)
Library calls (functions within program libraries)
Special files (usually found in
File formats and conventions (e.g.,
Game programs, etc.
Miscellany (e.g., macro packages, conventions)
System administration commands (may require
Kernel routines [Non standard]
In general, these sections are of interest to the following types of users:
end users - 1, 6
developers - 1, 2, 3, 4, 5, 7, 9
sysadmins - 1, 4, 5, 7, 8
For more information, visit the Ubuntu documentation.
Terminal-based usage of the
man(1) command is quite possible,
using a screen reader, so we describe it below.
However, it isn’t particularly convenient, let alone efficient.
For example, the FILES and SEE ALSO entries don’t act as links.
So, we’re working on providing web-based access. Stay tuned…
man(1) sends its output through
less(1), an interactive “pager”.
This pager has lots of options and interactive commands
(described, of course, in its man page), but here’s a “cheat sheet”:
- carriage return - show the next line
- b - go back one text “window”
- h - show a block of help text
- q - quit the
- space - skip to next “window”
Alternatively, users with screen readers may prefer to display all of the page’s text at once and then interact with it using familiar tools:
vagrant@perkify:~$ man less | cat LESS(1) General Commands Manual ... ...
In a few cases, multiple sections will have a page with the same name.
For example, each sections has an
So, you might not get the page you had in mind.
To work around this problem, just add the section name before the page name:
vagrant@perkify:~$ man 6 intro
Man pages have a reasonably standardized layout.
To explore this, let’s run the
man(1) command on itself:
vagrant@perkify:~$ man man MAN(1) Manual pager utils MAN(1) ...
After the banner line (shown above), the output will be divided into a dozen or so areas (aka page sections). Most of these have “traditional” titles, content, and format.
Note: The format of these pages was initially designed for use with teletypes, so it relies heavily on SHOUTING, indentation, etc. Web-based versions of this material should be far more accessible.
Each man page is divided into a series of labelled page sections. (e.g., NAME, SYNOPSIS, DESCRIPTION, FILES, SEE ALSO). Other areas may be added if the author(s) think them worthwhile. Here are some common page sections you may encounter:
BUGS - limitations, known defects or inconveniences, etc.
CONFORMING TO - relevant standards or conventions
DEFAULTS - discussion of the command’s default behavior
DESCRIPTION - paragraph-form notes on the command’s purpose, behavior, etc.
ENVIRONMENT - examples and terse descriptions of environment variable usage
EXAMPLES - examples and terse descriptions of typical command usage
EXIT STATUS - exit status values and terse descriptions for the command
FILES - locations and terse descriptions of relevant files and directories
HISTORY - summarizes the command’s development history
NAME - the name of the item (e.g.,
man), followed by a one-line description
OPTIONS - annotated list of command-line options
SEE ALSO - list of relevant man pages, sorted by name within section
SYNOPSIS - terse summaries of possible ways to use the command
Let’s assume that you don’t know the name of the command you want.
apropos command will perform a keyword-based search,
based on terse descriptions in the
vagrant@vagrant:~$ apropos music mpd (1) - A daemon for playing music mpd.conf (5) - Music Player Daemon configuration file ...
This tells us that
mpd(1) (the Music Player Daemon)
is available as a command and that it has a configuration file.
We can then use
man(1) to dig a bit deeper:
vagrant@vagrant:~$ man mpd Music Player Daemon(1) General Commands Manual NAME MPD - A daemon for playing music SYNOPSIS mpd [options] [CONF_FILE] DESCRIPTION MPD is a daemon for playing music. Music is played through the configured audio output(s) (which are generally local, but can be remote). The daemon stores info about all available music, and this info can be easily searched and retrieved. Player control, info retrieval, and playlist management can all be managed remotely. ...
To be continued…