MAN PAGES

While they're not all well-advertised, there are actually a variety of means of getting help under Unix. The most important and reliable of these are `man' pages.  Man pages correspond to online manuals for programs, file formats, functions, system calls, and so forth.  You might have asked a UNIX question on a newsgroup only to get back as a reply RTFMP ( Read The "Fantastic" Man Pages ).  If you've never read one before, the best way to start is by typing 'man man' at the command line.

Of course, while man pages are a vast improvement over the online documentation of most other OSes, they suffer from many failings:

That said, they're still better and more comprehensive than the alternatives. We'll try to address the first three failings in this document.

HOW TO READ MAN PAGES

Man pages are the standard documentation for every Unix; you're sure to come across a reference before too long of the form:

<command>(N)

Where N is a number from 1-9, possibly followed by a letter.  Here's an example we'll pick apart ( note: this example does not apply to all UNIX's but should be taken as general form )

% man mkdir

MKDIR(1)    USER COMMANDS       MKDIR(1)

NAME
   mkdir - make a directory

SYNOPSIS
   mkdir [ -p ] dirname...

DESCRIPTION
   mkdir creates directories. Standard entries,`.',for the
   directory itself, and `..' for its parent, are made automat-
   ically.

   The -p flag allows missing parent directories
   to be created as needed.

   With the exception of the set-gid bit, the
   current umask(2V) setting determines the mode in which
   directories are created. The new directory inherits the set-gid
   bit of the parent directory. Modes may be modified after
   creation by using chmod(1V).

   mkdir requires write permission in the parent directory.

SEE ALSO
   chmod(1V), rm(1), mkdir(2v), umask(2V)
  

Here's the breakdown of our example.

MKDIR(1)    USER COMMANDS        MKDIR(1) 

This means that the MKDIR command is documented under that name, in section (1) given within parentheses.

The section may be necessary in case there are multiple man pages for the same name. In the example above there are man pages called 'mkdir' in both sections (1) and (2v). If unspecified, man will give you the first manpage it finds. The -f option will show you all the available man pages for a given name.  The same effect can be achieved by using the command whatis instead of man

%whatis mkdir

AND

%man -f mkdir

are synonymous.  You should be able to get a description of each section (they vary from Unix to Unix) by doing

%man SECTION# intro

Continuing with the breakdown of the mkdir man page.

NAME
    mkdir - make a directory    

The name of the command and a brief description.

SYNOPSIS
       mkdir [ -p ] dirname...    

This discribes the various flags and the proper format the command requires.  The flag in this instance is -p and the syntax requires a directory name to follow. ( note: most flags are optional )  

DESCRIPTION
        mkdir creates directories. Standard entries,`.', for the
        directory itself, and `..' for its parent, are
        made automat-ically...    

A full fledged description of what the command will do including all of the flags.

SEE ALSO
     chmod(1V), rm(1), mkdir(2v), umask(2V)    

Suggestions of other commands that are somehow related.

FINDING MAN PAGES

apropos / man -k / man -kr

One invocation of man that you'll likely come to be very familiar with is the man -k (keyword) option. This function is also available by
running apropos (1), i.e. man -k and apropos are equivalent. It lets you search the database of man page summaries to look for a keyword
that might be mentionned in them.

Suppose we were looking for utilities to manipulate postscript documents.  We would either do

%man -k postscript

or

%apropos postscript

This produces a list, with summaries, of man pages which are likely to be related to your topic.  If you were looking for something less specific, say programs associated with databases, you would probably want to use less and/or grep to filter and view the output.

%man -k postscript | less

The output may produce many screens of data.

Note, these commands search the database which in most cases must be built by the system administrators, a task which is sometimes forgotten.  If you can't find what you are looking for and you believe it's there, try doing

%man -u man

under Linux followed by your search, or

%man -F

under Solaris.  SunOS has no such option.  Before trying this, make sure your MANPATH variable is set correctly.

MANPATH

There can be several hierarchies of man pages, depending on the system. On most of our systems, at least the following directories exist: /usr/man, /usr/local/man. In addition, there will be one for X programs (/usr/X11/man, /usr/local/X11/man, or /usr/openwin/man) and likely one for SOCS-specific man pages (/usr/socs/man).

man searches the environment variable MANPATH (a colon-seperated list of directories like the PATH variable) for man pages.  If you have hacked your script files or staff screwed up, the MANPATH could be wrong. The command whereis may be able to help here. whereis will locate the binary, source and manual page files for a command.  For example: ( note: this specific example should not be taken as generic under Unix but only as a illustration of possible results )

%whereis man
man: /usr/ucb/man /usr/local/man /usr/man/man1/man.1 /usr/man/man7/man.7

MANUAL SEARCH FOR MAN

Alternatively, you can just try the quick-and-dirty method of running grep (1) in the man directories you think might contain the command you are looking for; note that man pages are not stored in plain text format so the output may not be always readable. If you find the string you are looking for in a file located in MANDIR/man#, do

%man -M MANDIR # filename

to view the corresponding man page.

 

THERE'S NO MAN PAGE FOR X!

Ok, you have tried the suggestions given above to locate man pages, and still have not had any luck. It's quite possible there is no man page corresponding to what you're looking for - either because the tool or functionality you're searching for isn't installed on the system or because it has no man page installed (the latter is far more common under Linux than elsewhere).

Let's suppose that you're especially determined because you "know" that the command exists - it does something, just not quite what you want. Rather than get irate at the undocumented command, first make sure that it is actually a program that deserves a man page; here's an algorithmic approach to looking for a command's help file.

If you're running ksh or bash (you'll know if you are), first do

%type -t CMD

For any other shell, do

%which CMD

This will tell you what kind of command you're dealing with.

If it says CMD is a 'builtin', then do 'help CMD' (bash only) or read your shell's manual page. ~(Note that tcsh - except under Linux - doesn't document all of its builtins since most are identical to csh's; I suggest looking in csh's man page first if you are somewhere other than Linux-land.)~

If you're told that CMD is an 'alias', then do

%alias CMD

and repeat this procedure from the beginning with the first word that alias returns. If you are told that CMD is a function ( not in csh ), do

%typeset -f CMD

to see its definition; from there you are on your own.

If you are given a path, then you may be justified in being irate. Or maybe the documentation is in another format; keep reading.

PRINTING MAN PAGES

You have a couple of options here, depending on whether you mind wasting a full page of paper for each page of text. We recommend printing man pages at least half-size, as you're unlikely to return to them a month later.

The simplest thing and most portable to do (though alternatives exist) is

%man -t MANPAGE > Manpage.ps

( Note: only works unaided under Linux )

This will produce a file called Manpage.ps in your current directory, which you can then use psnup (1) under SunOS to print 2- or 4- pages to a physical page.

Unfortunately, while the -t parameter is itself portable to virtually all man implementations, the output is not.  Under Linux, the above works fine. Under SunOS and Solaris, you have to do some preparation first: define the environment variable TCAT to be 'cat' and TROFF to be '/usr/local/bin/groff -man'. Furthermore, the GROFF_TYPESETTER variable must be set to 'ps'.

If you have trouble getting psnup to work or don't feel like fooling around with it, you can always work with text instead. This isn't ~quite~ text, as it still has bolding and underlining and so forth, but a2ps(1) understands it, as does less(1).

%man MANPAGE|a2ps -m >MANPAGE.ps

You don't have to produce the ps file if you don't like, of course - if you're confident that it'll work the first time, replace the '>MANPAGE.ps' with '|lpr -Pprinter-name'. Personally, I recommend previewing the output with ghostview (1) beforehand.
 

DO YOU REALLY WANT MAN?

Not all documentation is located in the manpages. The shells sometimes have online help, as do various other programs, especially graphical ones.

Other major online help systems include:

INFO


Info isn't really complex enough to deserve describing in detail. In brief, you can read info pages within emacs using 'C-h i' ('info') or from the command line using the command

% info

Online help and a tutorial on the info system are available from within both interfaces.  Don't discount info pages; although they are used mainly by GNU software, this includes such hugely useful info pages as gdb, gcc, emacs, gawk, and makePerl and bash also have info pages, though the information is available by other means as well in their cases.

/usr/doc

Only available under Linux, and often not terribly interesting, as a well-behaved package will provide documentation that can be integrated with the major help systems.   Still, there is a lot there, and should definitely be considered if you cannot find what you are looking for elsewhere.  Of particular interest are the docs for xv, debian, vim, wget, pqp, pine, libq++ and hsc.

Files contained here will generally be of three types: HTML, postscript, or plan text ( ASCII ).  We will make the assumption that you know how to deal with these formats.   Use the information in this document to find help and read up on lynx(1), ghostview(1), and less(1)

/use/local/pkgs, /usr/local/doc, /usr/share, /usr/local/share

These are more common to the servers, though they may exist on Linux machines as well.   Software packages are commonly installed into

/usr/local/pkgs/PKGNAME-VER#

and a link to that directory is created as

/usr/local/pkgs/PKGNAME

Sometimes there is documentation to be found there.  Documentation which is located in /usr/doc/PKGNAME on Linux will be in these directories on the servers, though they may get linked or copied into the other directories mentionned above ( /usr/local/doc, /usr/share, /usr/local/share )

Perldoc

Much Perl documentation is embedded with the source modules themselves.  To access it, you can usually do

%perldoc MODULENAME

and a man page will be generated for you.

Source code and Include files

While it should probably be a last resort, the source IS always the most current and sometimes the only documentation available for a particular package.   This is usually not installed on the system unless it cannot be compiled:  For example, Perl scripts and Lisp source are both interpreted, and so the program is the source. Whether or not the program you are trying to learn more about is written in a compiled or interpreted language./usr/include and /usr/local/include may have very useful files to help.