Perkify - Manual

Written by Rich Morin.

Contents: (hide) (show)

Path:  AreasContentHowTos

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.

https://en.wikipedia.org/wiki/Man_page

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.

Topical Sections

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 man command, documented in section 1. In Linux systems, the principal manual sections are organized as follows:

  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 (e.g., /etc/passwd)

  6. Game programs, etc.

  7. Miscellany (e.g., macro packages, conventions)

  8. System administration commands (may require sudo)

  9. Kernel routines [Non standard]

In general, these sections are of interest to the following types of users:

For more information, visit the Ubuntu documentation.

Usage Hints

Note: 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…

By default, 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”:

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 intro page. 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

Page Layout

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.

Page Sections

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:

Usage Example

Let’s assume that you don’t know the name of the command you want. The apropos command will perform a keyword-based search, based on terse descriptions in the whatis database:

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…