MAN
===

Purpose
-------

MAN is a simple on-line help reader. It can be used to display UNIX-style
manual pages or other on-line manuals that can be organized in a similar
manner.

Usage
-----

MAN [chapter] topic

The optional chapter must a decimal digit. If missing, all chapters and
the "root" (see below) are searched.

How it works
------------

MAN uses the MANPATH environment variable or CONFIG.SYS line 0117 to locate
the on-line help texts it displays. From either source, it obtains a list
of folders that works much like the PATH variable most shells (and HERMES
programs too) use to locate executable files.

MAN considers each of the folders mentioned in the MANPATH the root folder
of a manual tree. The subfolders constitute the chapters, while the root
folder may be used to hold general information not suitable for inclusion
in any of the chapters. Chapters are identified by decimal digits, and the
corresponding folders are named MAN0 through MAN9.

If you omit the chapter from the command line, MAN searches each of the
root folders and all the subfolders from MAN0 to MAN9 of each root folder.

The manual page files must have the topic as their file name, while the
extension is ignored as long as it doesn't end with an 'F' or a 'Z' (see
below).

E g, when you enter "MAN topic" and the MANPATH is "f:\usr\man;g:\man",
MAN will look for the following files:

	f:\usr\man\topic.*
	f:\usr\man\man0\topic.* through f:\usr\man\man9\topic.*
	g:\man\topic.*
	g:\man\man0\topic.* through g:\man\man9\topic.*

If you enter "MAN 5 topic", it will look for

	f:\usr\man\man5\topic.*
	g:\man\man5\topic.*

and leave it at that.

All files matching the above search patterns are presented one after
another.

Files whose extension end in 'F' (or 'Z') are taken to be frozen (or
compressed). They will be copied to a temporary file with the extension
".F" (or ".Z"), and "freeze -d" (or "compress -d") will be run before
the file is displayed. If you don't mind waiting a moment and have many
long manual pages on-line, you will appreciate the disk space you save.

In TOS, there are no "hard links" (more than one name for a file). To
overcome that deficiency, MAN uses a special kind of "soft link" so that
different topics can share a manual page.

If the first line of a manual page is of the form "@btoa(1)", this page
is not displayed, but the pages with topic "btoa" in chapter 1 are. The
first line "@install" means all the maunal pages whose filename is
"install" are displayed rather than the one MAN is currently looking at.

MAN uses the TERM and TTYLVL environment variables to get the terminal
I/O right. (See HUSH(1), of all places.)