gno/usr.bin/man/README

--------------------------------------------
Name:     manpack
Version:  3.1
Author:   Devin Reade <gdr@trenco.gno.org>
Computer: Apple IIgs
Requires: GNO v2.x
--------------------------------------------

===========
Description:
===========

Various programs for working with manual pages.  This archive includes
the following utilities.  All utilities have their versions lockstepped:

        apropos		locate commands by keyword
	catman		format cat pages from man pages
	makewhatis	create the whatis database
	man		display reference manual pages
	whatis		locate commands by name

============
Installation:
============

Type at the command line `dmake install`.  You may wish to first
verify the destination directories in "Makefile.mk".  By default
these are:

	BINDIR  = /usr/bin	(apropos, man, and whatis)
	SBINDIR = /usr/sbin	(catman, and makewhatis)
	MANDIR  = /usr/man	(all manual pages)

Ensure that all older versions of these programs are deleted.
They may or may not be in the above directories.

If you're building a GNO release in the base builds, then use the
command `dmake release`.

==========
Legalities:
==========

These utilities are copyright 1995-1998 by Devin Reade <gdr@trenco.gno.org>.

They are provided as freeware, and may be distributed by Internet
archive sites, online services such as Delphi, or BBSes provided that
the archive remains intact.  Permission is granted for distribution
with GNO and ORCA provided credit for this work is given along
with any other attributions.

Inclusion of these utilities in collections on disk, CD-ROM, or
other portable media is permitted provided that only a nominal
fee (not much more than the media cost) is charged.  Contact the
author regarding other commercial distributions.

Updates to these utilities may be distributed provided that the source
and this README file are included.  Please follow the coding style
already in use and document your changes in this file.  Better yet,
email me with your suggested changes and I'll consider incorporating
them into the base distribution.

=======
CHANGES:
=======

apropos, whatis
	v3.1 (28 Mar 98)
		Incorporated all utilities into the GNO base build.  All
		versions are now lockstepped.

		Searches are no longer case sensitive.

	v3.0 (24 Jul 95)
		Complete rewrite from scratch by Devin Reade.

		This version makes use of MANPATH in the same way
		as man(1) v3.0.  Similarily, it will also search
		the 17/syscmnd ORCA database.

		In the previous version, the behavior of apropos was
		identical to that of whatis.  This version has been
		fixed so that whatis is case sensitive and searches
		only the manual page names.  The apropos search is
		case insensitive and searches the entire database
		entry.

	v2.1 (1 Jul 92 ?)
		This version is by Mike Horwath and shipped with GNO v1.1.
		Although no version flags or resource forks where provided
		with this release, this release is designated as v2.1
		because it shipped with man(1) v2.1.
                         
catman
	v3.1 (28 Mar 98)
		Incorporated all utilities into the GNO base build.  All
		versions are now lockstepped.

	v1.0 (24 Jul 95)
		Initial release.  Written from scratch by Devin Reade.

makewhatis
	v3.1 (28 Mar 98)
		Incorporated all utilities into the GNO base build.  All
		versions are now lockstepped.

		Don't use binary mode to read the files; this doesn't
		give the right results with the GNO v2.0.6 stdio package
		since we're doing calls to fgets() at times.

	v1.2 (24 Jul 95)
		Fixed bug where pages in "manl" ending in ".l" (that's
		"ell" in both cases) would be ignored.

		Added recognition of files compressed with gzip.

		File compression suffixes are now case sensitive.

		If none of MANPATH, USRMAN, or MANDIR are defined,
		"/usr/man" will now be used.

		Fixed a bug where the word SYNOPSIS appearing in the
		description would mangle the database entry.

		Added a verbose-level-three flag (-v3), which is basically
		the old -v2 flag.  The new -v2 is somewhat less verbose
		than it was.

	v1.1 (29 May 94)
		Makewhatis will now ignore any man page starting with
		".so", in order to eliminate multiple files.  The resultant
		blank lines in the whatis database have therefore been
		eliminated.

   		Changed -v flag to {-v1|-v2} for differing stages of verbosity.
		Only error output will be logged with the -l flag.

		Manual page was updated, to include a correction to the -o
		flag usage and the modification to the -v flag.  Descriptions
		of bugs unlikely to be fixed were added.  Date and version
		were changed.

		Fixed bug where input buffer wasn't properly terminated, and
		added checks for buffer overflows.

		Makewhatis will now display all commands about which the
		manual page is written.  For example, if foo.1 described
		both foo(1) and bar(1), and bar.1 was an .so (or .l) link
		to foo.1, then the database entry will have changed from

		    foo (1)		- extract and add thingys
		    foo, bar (1)	- extract and add thingys

		Makewhatis used to pick up the first NAME string in the file
		as a reference point.  Now, any NAME is ignored in any line
		starting with .\" or .TH

		Filename chapter numbers will now be correctly extracted
		regardless of the existence of .Z, .z, .F, or .f suffixes,
		or of the existence of '.' within the base file name.

		Makewhatis is now linked with Soenke's gnulib for the
		getopt() function, rather than using the libc version.

		Stack usage was reduced to 1k.  Be aware, though, that a
		fair amount of global storage is used, including three 1k
		buffers.

	v1.0 (15 May 94)
		Initial release.  Written from scratch by Devin Reade.

man
	v3.1 (28 Mar 98)
		Incorporated all utilities into the GNO base build.  All
		versions are now lockstepped.

		Searches are no longer case sensitive.

	v3.0 (24 Jul 95)
		Complete rewrite from scratch by Devin Reade.

                The -k, -t, -, -f, -M, and -T flags were added.

		Man now supports the MANPATH environment variable which
		can be a list of paths delimited by either colons or
		spaces.

		Added sections 3f, l, n, o, and p to searched subdirectories.

		Added gzip(1) to compress(1) and freeze(1) as allowable
		source compressors.

		Fixed bug with the .so source command;  .so references
		should now (properly) appear as ".so man<section>/<filename>"
		instead of using the full pathname.

		Updates to apropos v3.0 apply to man when invoked with
		the -k flag.

		Preprocessing by eqn(1), refer(1), tbl(1), and vgrind(1)
		is not yet supported.

	v2.1 (1 Jul 92 ?)
		Recognised environment variable USRMAN as well as MANDIR.
		
		This version was also by Mike Horwath.

	v2.0 (Date Unknown)
		This version is by Mike Horwath and shipped with GNO v1.1.

		It made use of the environment variable MANDIR which had
		to be a single directory.
		

=====
TO DO:
=====

Here's a possible optimization option:
	Create a database in the user's home directory that contains a
	list of all man pages and their locations, based on MANPATH.
	Keep a magic number (a checksum or hash?) in the file to see if
	MANPATH has changed.  *maybe* check the date of the file against
	the modification date of the respective directories and generate a
	warning if the db is out-of-date.

Makewhatis is not very well integrated with the rest of the package;
there is still duplication of definitions and functions in some files.

Man, catman, and makewhatis need to support preformatting for eqn(1),
vgrind(1), et al.

Makewhatis' "verbose" output could be cleaner.

Performance analysis has not been done.  No doubt some things could
improve, including some string matching in util.c

If the stock getenv(3) function is used (as is done here), then the
return value should be duplicated (via strdup) rather than just used.
If the getenv function from the lenviron library is used, this is not
a concern.

Perhaps an "X" version should be done for the Second Sight card.  This
will have to wait a while.