Skip to content

Department of Mathematics

College of Science

Main Navigation

Mathematics Department computing facilities

Last update(s): Tue Dec 12 14:29:04 MST 2017                Valid HTML 4.0!

Computer and Printing Support
help@math.utah.edu
problems@math.utah.edu
Nelson H. F. Beebe beebe@math.utah.edu 801-581-5254
Scott Patten patten@math.utah.edu 801-581-5252
Victor Gabrenas gabrenas@math.utah.edu 801-581-5257

Table of contents

The Info system

The bulk of our online software documentation is stored in the emacs info system, accessible inside emacs with the keystrokes C-h i (Control-h followed by the letter i), and on the Unix command line with the info and xinfo programs.

If you are unfamiliar with info, once inside, just type h for help and a tutorial. Barely a half-dozen one-letter commands suffice for most uses of info, and you can get a command summary at any time by typing a question mark (?). To quit, just type q.

In particular, documentation for almost all GNU software packages, locally-written packages, and mathematical libraries like EISPACK, LINPACK, and LAPACK, is provided in info form. Simple navigational and search commands and extensive use of hyperlinks make document access even easier than in Web browsers. From emacs, re-entry to the info system brings you back to the last node visited, making it easy to switch back and forth between documentation and the program that you are writing, and you don't need a window system to use info.

Unix manual pages

Traditional documentation in the Unix system takes the form of manual pages, which vendors normally also provided as a series of about ten fat printed volumes. Low-numbered volumes are used most frequently: volume 1 is user commands, volume 2 is system calls, volume 3 is C library functions, and so on. The higher volumes are numbered inconsistently across different Unix platforms.

The manual pages are intended to be brief summaries of software capabilities, not tutorials or detailed reference manuals. Nevertheless, some are large: the Unix shells (each of them a complex programming language) have manual pages of 30 or more pages.

The man command provides access to the manual pages. It takes an optional section number (-s n or n, depending on the Unix flavor), and the name of a command, file, system call, or library routine for which you need documentation. The section number is only rarely needed: it disambiguates names that appear in more than one section of the manual.

Here is an example: 

% man f90

User Commands                                              F95(1)

NAME
     f95, f90 - Fortran 95 compiler

SYNOPSIS
     May be invoked by either f95 or f90 commands; they are
     equivalent.

     f95 [ -a ] [ -aligncommon[=a] ] [ -ansi ] [ -arg=local ]
          [ -autopar ] [ -Bx ] [ -C ] [ -c ] [ -cg89 ] [ -cg92 ]
          [ -copyargs ] [ -Dnm[=def] ] [ -dalign ]
...
DESCRIPTION
...
OPTIONS
...
ENVIRONMENT
...
FILES
...
SEE ALSO
...
     asa(1),  cc(1),  dbx(1),  fpp(1),  fpr(1),  fsplit(1),
     gprof(1),  ild(1),  ld(1),  perror(3f),  prof(1),  tcov(1)
...

As illustrated, the manual page is organized into sections:

  • NAME (one-line summary),
  • SYNOPSIS (command and its [optional] arguments),
  • DESCRIPTION (explanatory prose),
  • OPTIONS (documentation of command-line options),
  • ENVIRONMENT (Unix environment variables that affect command behavior),
  • FILES (documentation of files that the command uses),
  • BUGS (caveats, misfeatures, and notes about potential problems), and
  • SEE ALSO (cross references to related commands).

The first four, and last, of those sections should always be present. The remaining sections, and others not listed here, may be present or absent, according to their author's intent.

The parenthesized section number is conventional in cross-references in manual-page documentation, as shown above in the fragment of the SEE ALSO section.

Here are examples of manual pages for a name that is both a user command 

% man -s 1 chown
User Commands                                            chown(1)

NAME
     chown - change file ownership

SYNOPSIS
     chown [ -fhR ]  owner  [  :  group  ]  file ...
...

and a system call: 

% man -s 2 chown
System Calls                                             chown(2)

NAME
     chown, lchown, fchown - change owner and group of a file

SYNOPSIS
     #include <unistd.h>
     #include <sys/types.h>

     int chown(const char *path, uid_t owner, gid_t group);
...

The man command is fine when you know exactly what documentation you need, but with 10,000+ manual pages available, more context is helpful. Manual pages are normally written in the -man style in the nroff and troff markup systems (although Sun Solaris often uses SGML markup instead), and to provide more information for subject searches, they contain a title header markup command that provides a one-line summary of their documentation. A database of those summaries is kept up-to-date nightly and can be accessed with the man -k (keyword) command, or equivalently, the apropos command: 

% apropos fortran
... same as next example ...

% man -k fortran
...
asa (1)      - convert FORTRAN carriage-control output to printable form
f77 (1)      - FORTRAN 77 compiler
f95, f90 (1) - Fortran 95 compiler
fdumpmod (1) - utility for displaying Fortran 95 module information
fpp (1)      - the Fortran language preprocessor for FORTRAN 77 and Fortran 95.
...

The output gives the manual page name, section (in parentheses), and a one-line summary.

Sometimes, even the one-line summaries are insufficient to find what you want: after all, they represent less than 0.3% of the more than three million lines of documentation in our collected vendor-provided and locally-added manual pages. We therefore provide full-text searching of the entire manual-page collection with the glimpseman command (named after the underlying search engine, glimpse): 

% glimpseman fortran | less
...
/opt/SUNWspro/prod/man/man1/fsplit.1: (This option has meaning for fortran-90 text only).
...
/usr/local/man/man1/phase.1:            A fortran routine that computes f(t,x,p).  This is created as
...
/usr/local/man/man1/ftnchek.1: ftp://netlib.org/fortran .
...

The output of this command can be voluminous, so we piped it into the less pager utility. The output shows filenames and contained lines whose text matches the command-line argument. The subdirectory man1 corresponds to section 1 of the manual, so you could later issue a man -s 1 ftnchek command to view the user-command manual pages for ftnchek(1).

Some manual pages can be converted to HTML with the man2html or rman utilities, and as a result, several thousand HTML files exist in the directory tree /usr/local/man/html for access via the File -> Open menu path in Web browsers.

Web-based documentation