User:Rewood/UNIX Documentation

Learn about both printed and on-line documentation for UNIX concepts and programs.

Printed UNIX Documentation

There is a traditional set of basic documentation distributed with UNIX versions. Some vendors (Sun, HP, etc.) have tried to amplify upon these with additional beginner's guides and tutorial documents. But the basic material should always be there in some form. We have copies of the original 4.3 Berkeley UNIX documentation in Branner Library.

The Compaq Corporation web site has the complete documentation for Tru64 Unix version 4.0G (the operating system used on pangea). Although each volume of basic command documentation has a specific title, I tend to refer to the entire set as simply the "UNIX Programmer's Manual". The original Berkeley UNIX documentation is divided along two dimensions:

• Command reference versus tutorial (supplementary material).
• Intended audience (general users, programmers, and system managers)

"Command Reference" consists of 8 "sections", shown here divided into three groups according to primary intended audience.

• User Reference

1.User commands and utilities

6. Games

7. Macro packages, miscellaneous

• Programmer Reference

2. System (kernel) subroutine calls

3. Subroutine libraries for programmers

4. Special files and devices

5. Formats and conventions for standard files

• System Manager's Reference

8. System management commands and procedures

Although the on-line version of this documentation is not physically separated into volumes like the printed version, the section numbers are retained and may be important where the same name is used for both a general user command (section 1) and a programmer interface function (section 3). Tutorial style documents describing major components, such as the shells, mail, programming languages, system management, text-processing facilities, and some of the major utility programs, are printed in the "Supplementary" volumes. In the original Berkeley UNIX distribution, these documents were not on-line.

Some tutorial documents are on-line for the Tru64 UNIX operating system used by pangea at the web site given above. Many of the readings for the GP111 course are from the Supplementary Volumes. You should browse the table of contents occasionally to find helpful articles as your use of the computer grows.

Each section of the Reference manual contains individually numbered entries, organized alphabetically by the name of the command or routine to which they refer. The entries follow a standard format with several subsections in this order:

• NAME
• SYNOPSIS
• DESCRIPTION
• FILES
• SEE ALSO
• BUGS
• AUTHOR

There is also a permuted index at the front of section 1 in which each entry is indexed according to every keyword in its "NAME" line. The 4.3BSD manuals also have a master index that includes references to the tutorial documents - look there first!

On-line Documentation

All the printed manual reference entries are also available on-line using the man command from a simple command-line shell login, or the xman command from an X-window terminal. On-line entries are often more up-to-date than printed ones. Locally written or public domain software that is added to the system will not be documented in printed manuals from the vendor. The on-line manual entries are likely to be the only documentation for these programs.

On the command line, simply type "man commandname"

The man command will look through the sections in order from 1 to 8 to find the first entry under the name commandname, and then display it on your screen. If the entry has more lines than can fit on the screen (almost always), it displays one screenful, then prints a prompt on the bottom line and waits. Depending upon the system, this prompt will be something like one of these:

more (x%) stdin Press the SPACE bar to see another screenful, or type q to quit. 

Sometimes, there are entries in different sections of the reference manual with the same name. The man command only shows the first by default. To see the second entry, give the section number as the first argument to man, for example

man 8 restore 

The UNIX documentation includes a "permuted index", in which every entry is indexed by every significant word in its "name" line. This permuted index is also on-line and kept up to date to include new manual entries that may not be printed. It is accessible with the man command by adding the option -k and specifying a keyword, for example: man -k who (You can use the command apropos as an alias or synonym for man -k). All entries that contain the keyword in their "name" field are listed. You then use the man command with the command name for further information. Most "GNU" programs have a basic on-line manual page, but their primary and more substantial documentation is accessed through a program called info.