
               The Manual Page Browser Utility Package
                             Version 2.1b
                             15-Jul-1994

                            maintained by
                   Wilf <G.Wilford@ee.surrey.ac.uk>

                     Documentation reorganized by
             Nils Magnus <n_magnus@informatik.uni-kl.de>


0. Intro:
---------

This is a replacement for Un*x man(1), apropos(1), whatis(1), and
manpath(1). It has all kinds of neat features that other versions of
man don't, including support for multiple man page directory trees,
preformatted man pages, and troff. It is provided without any warranty
whatever. I hope you find it useful.

This program is not a GNU product but it is distributed under the
terms of the GNU copyleft which is described in the file COPYING.

You will require Gnu Make version >= 3.70 to compile the package (older
versions may work) and either an ndbm or gdbm interface library.

./configure will determine which library you have and the package will use
the appropriate calls.

1. Contents of this package / Suggested Reading:
------------------------------------------------

README informs you about the general features and concepts that come
along with man_db-2.1. You are strongly encouraged to read this
completely before you do anything else.

After this, INSTALL gives you an in-depth guide on how to build the
binaries and manpages from the sources and also tells you how to
install them and create the necessary directories and databases.

Except for occasional references to manual pages supplied with this
package this is all you need to read, but the following files give 
some additional information:

As stated above, COPYING contains the GNU Public License, which tells
you your rights and duties about giving this package away.

CREDITS names some of the people involved in the making of this package.

HISTORY lists the changes of the several releases since version 1.0

Some routines for database management and regular expressions use
packages described in LIBRARIES. You may look over this file to ensure
that you have reasonably new and useful versions of them. It may also
provide some insight into the workings of the man package.

In TODO you'll find some ideas that will hopefully show up in subsequent 
releases and/or are currently being worked on. You are encouraged to add 
your own suggestions to this list; they may or may not be considered in 
future releases.


2. Features:
------------

Man_db 2.1 is a manual browser tool providing you with the visualization
of manual pages like the well known UN*X man program, but it also adds 
some enhanced functionality:

    - Support for multiple man page directory trees, and alternate
      systems.

    - Handling of user specific man trees.

    - Secure preformatting of man pages to cat pages.

    - Management of cat pages without nroff-sources, so called stray
      cats.

    - Management of complete cat-only systems without nroff.

    - Compression of catpages.

    - Replacement of file searching techniques with hashed database 
      lookup, thus providing greatly improved speed.

    - Support of several output formats like troff, postscript, dvi
      and others.

    - Enables viewing of local man page sources that have yet to be
      installed.

    - Optional complete FSSTND file placement compliance.

    - Easy to build and install because of completely rewritten
      configure script.


3. Programs that get installed and what they do:
------------------------------------------------

MAN - the browser itself and front-end for various operations.

MANDB - a new program. This is used to initialize the man database(s)
and is only really useful at the very start or after installing a lot
of new pages, say section 3. Once the database exists, man will keep
it up to date. BTW if you don't want the database, but just want the
FSSTND compliance, that's ok, just don't run mandb. If man doesn't
find the db, it'll slip into neutral and use the globbing routines to
find your file.

Mandb will also do some checks on your manfiles as it adds them to the
db. It'll find any duplicates you have (unless, of coarse, you are 
allowing duplicates for whatever reason), possible duplicates and
generally bogus ones (see mandb(1) for details).

STRAYCATS - another new program. This program will eek out any nroff
source-less formatted cat pages and will give some options as to how
to deal with them. Even if your entire system is nroff source-less, man
will still work for you. What you need to do is create a place-holder
in the source man tree for every stray cat which will then get
registered in the db. straycats will do this for you. It will also
find any non-relative stray cats (those which do have a source but is
in a different tree to where it is expected), see the man page for
more info.

MAKEWHATIS, WHATIS and APROPOS

These utils have now had a spring clean, although (as shell scripts)
their days are numbered.

GETWHATIS - this is driven by makewhatis to provide a whatis text
database. It should be used after running straycats and producing
place-holders. It will then grope around your straycats on a per file
basis if the source is not found.

MANPATH - this utility can be used to set your MANPATH environment
variable when you log in. This will make man a tiny bit quicker as
it does not have to decide your manpath every time it is run. BUT,
once it is set, it will stick until you login again or set it
manually.

Something like:
	
    export MANPATH=`/usr/bin/manpath -q` # for sh type shells
    setenv MANPATH `/usr/bin/manpath -q` # for csh type shells

in /etc/profile or .login or equivalent will do this.

N.B. if your MANPATH environment variable is already set for you,
you will have to 'unset' it to force manpath to override it.

As of this version, it can also be used to supply catpath locations.

GETWHATIS - an interim C based makewhatis/catman clone. This is
*stunningly* faster than the shell script included with v2.0a2. To
actually create a whatis database, you'll need to run it using the
included makewhatis script. An example using my setup:

  sh = shell based makewhatis, mainly using awk. 
  C  = C based getwhatis, using new makewhatis shell script as wrapper.

Used on 910 manfiles + 100 straycats:
  sh: 10 mins 3 secs (no grogging of the straycats)  99% CPU
  C : 62 secs 83% CPU
Used on 875 manfiles:
  sh: 8 mins 51 secs 99% CPU
  C : 25 secs 71% CPU


4. General concepts:
--------------------

I originally set out to make the thing FSSTND compliant so that I
could have a read-only mounted /usr (which I now have), without having
to mess around with loads of symlinks.

That was fine, until I tried 'man -M . sliplogin' one day and I got a
seg fault. Damn. I had a couple of weeks spare and took the lid off of
the package, jumbled it all about, added a couple of programs and then
tidied it up a bit so that I could put it back on the net.

The theory: If you go to a library to take a book out, what do you do?

a) Go and look where it might be on a micro-fiche/terminal, take a look
where it is supposed to be on the shelf, and then go look at the new
arrivals if it's not where it's supposed to be?

OR

b) Start at one end of the ground floor, look along every bookshelf
until you've completed that floor, then go up a level and start again
until you've found what you're looking for?

Well, man 1.1B favoured (b), I've converted it to do mostly (a) -
there are a couple of options that invoke the old file globbing
routines, but I'm hoping they'll disappear soon.

Basically, this version of man_db will either give you the page you're
looking for, nearly instantly or tell you that it doesn't exist, again
nearly instantly.

"The Perl manual pager does that", I hear you cry, but it doesn't auto
update it's database, and last time I looked it couldn't deal with
stray cats. With this version of man_db, you shouldn't have to do any
maintenance, all new man pages are automatically registered as soon as
you try and find them.


5. Manpage organization:
------------------------

5.1: Global man tree:

I have resisted the temptation to handle all the bizarre ways various
vendors have of organizing man pages. This version of man_db assumes
that the global directory trees have the structure:

/usr/.../man
          /manSect
              /foo.Sect*
               ...
          /catSect
              /foo.Sect*
               ...

#ifdef FSSTND

/var/catman/.../
          /catSect
              /foo.Sect*
               ...

#endif FSSTND

where Sect is some number or string and should be listed in the set of
sections to be searched. It is not necessary to have both the cat*
and man* subdirectories, but you must have at least one.


5.2: User directories:

Man directory trees for users are also supported. They will not have a 
relative FSSTND cat tree as users man trees are not covered by the FSSTND.


5.3: Alternate systems:

----
From: Kim-Minh Kaplan <kkaplan@cdfhp3.in2p3.fr>
To: g.wilford@ee.surrey.ac.uk
Subject: patch to man-2.0a4 for alternate systems

* Alternate systems support.

Here are my patches for alternate systems support. I made all
executables (but _not_ the shell scripts, see later) accept the `-m
SYSTEM' option. SYSTEM should be a non-empty list of systems separated
by commas or semi-colons, without spaces! If this option is not
present, then the environment variable SYSTEM is looked for instead,
and if set, it serves the same purpose. At most _one_ of the two is
used (priority to the option); none may be used (if neither is
present) in which case the behavior is the same as if this patch had
not been applied.

For the remaining of the description I'll assume that either the
option or the environment variable SYSTEM is used and I'll call it
SYSTEM whichever is used. Remember that this _does not_ apply to shell
scripts.

Each system (component) from SYSTEM is added to each path from the
manpath. An example:

SYSTEM='i386,sun,hpux'
MANPATH='/usr/man:/usr/share/man' (or the MANPATHS from manpath.config)

and the following directories exist:
/usr/man
/usr/man/i386
/usr/share/man
/usr/share/man/sun
/usr/share/man/hpux

then it is as if MANPATH was:
/usr/man/i386:/usr/man:/usr/share/man/sun:/usr/share/man/hpux:/usr/share/man

* Shell scripts

As it is not easy to parse options in shell scripts (I think that
getopt is bash dependent, is it?), there are no options for alternate
systems. But using the environment SYSTEM, you can get the same
result.
----

When using the system support it is necessary to run mandb with all of the
available systems as the -m argument otherwise those systems' man pages
will not be registered in the lookup database. It is not necessary to 
explicitly specify the path to the alternate systems' man pages in the 
manpath.config file.

6. How retrieval of manpages and creation of catpages is performed:
-------------------------------------------------------------------

If man_db is FSSTND compliant, man will look in both the old cat 
locations in the /usr tree and the new /var/catman hierarchy, in that 
order.

The default FSSTND behaviour is to only produce new cat pages under
/var/catman. Ie. although man will look under /usr it will never try
to put newly formatted pages there.

You should refer to the FSSTND in deciding where you would like to
keep the majority of your catpages and why there are two valid
locations where they may reside.

Personally, I have decided to store my straycats (of which I have a
few), under /usr until such time as I replace them with nroff
source. Any cat pages that man produces will be stored under
/var/catman (as per the FSSTND) and so that way, I can expire any cat
pages I find under /var/catman without worrying whether they are
straycats. The straycats are safely out of the way in the /usr
hierarchies.


7. Compression:
---------------

I've been approached to support catfiles with various extensions such
as .Z, .z and .gz all at the same time.

For this to be sensible, the cat files would have to be straycats,
with no source man page and no likelihood of there ever being
one. This is neither a good idea nor is it possible to guarantee.

The reason:

We have a formatted cat page: foo.1.z, a source man page: foo.1 and
the default compression extension is .gz. As long as the cat page is
newer, all is fine - every time you ask for the page, foo.1.z will be
found, decompressed and displayed. If, however, you install a newer
version of the software, including new man pages, foo.1.z will be 'out
of date' and so the new foo.1 will be formatted into foo.1.gz and also
displayed. Now you have foo.1 foo.1.z and foo.1.gz. This is
unfortunate and would take more effort than it was worth to discover
and put right by man.

Thus I suggest that you make sure that all of your cat files have a
single type of extension, of your choice, and compile that in as the
default for man.


8. Output formats:
------------------

If you compile with support for preformatted man pages, man(1) will
try to update the preformatted page if the man page source is newer.

If you compile with support for troff, you can say things like

    man -t foo | lpr -Pps 
or
    man -t -T dvi bar > bar.dvi

to print your man pages on a postscript printer, or produce a dvi
version of the page. Other devices that are available with your
version of troff (groff), can also be used.


9. What has changed from the last public release, man-2.0a2?
------------------------------------------------------------

Generally improved security, speed and features (no more becoming
daemon just by shell escaping from the pager).

Eliminated a vast amount of trivial and non-trivial-bugs.

Completely rewritten configure script. There is no more need to
specify a dozen paths.

Added new options to man:

  -T allows choice of device used with troff;
  -l causes man to format and display local nroff man files rather
     than man pages.

$MANPATH is now sanity checked, no more barfs with a daft environment
variable.

Added support for alternate systems.

Straycats will now cope with both compressed and uncompressed cat
files. Hopefully no more seg faults.

C based Makewhatis replaces sh version.

Greatly enhanced portability. Compiles 'out-of-the-box' on Ultrix.

10. Some utilities only used at compile time:
---------------------------------------------

ACCESSDB

To make, type make accessdb.

A simple program that outputs all of the key/content pairs stored in a
man database, in human readable form. The database read will default
to the global db, but is command line selectable.

GDBMVER 

To make, type make gdbmver.

This will give you the GNU dbm version you have installed, libc-4.5.26
contains version 1.5. The current version is 1.7.3 (as at 19th May
1994). The GDBM_FAST flag that both mandb and man can use was
introduced at version 1.6.

GETMANDBVER

To make, type make getmandbver.

To protect from mistakes, a version ID is incorporated into the db when
it is created. The program will just access the ID and show it to
you. Newer versions of man_db may/will store the db information in a
different way to version 2.0. The ID is to protect from inconsistencies 
between versions.

MKCATDIRS 

A shellscript that prepares the creation of the cat page directory
hierarchy. It examines the existing filesystem, guesses where man
trees can be found and produces another script with instructions to
build equivalent cat trees and assign reasonable permissions to
them. You can look over this file, change it to suit your system, if
necessary, and then run it.


11. Reporting Bugs, contacting the maintainer:
----------------------------------------------

If you find any bugs, think I've completely wasted my time, or have a
really bright idea (apart from changing the shell script utils or
implementing a different db storage algorithm), give me an
email. (Check TODO first, It'll contain last minute ideas).

I can be contacted at G.Wilford@ee.surrey.ac.uk or eep2gw@surrey.ac.uk
My snail mail address changes much more often so I'll leave it out.

Enjoy.
Wilf.
