gno/usr.bin/man/README
gdr 73ce022151 Version 3.0 of the manpack archive. This moved on top of the
original makewhatis repository.  Earlier versions of man, apropos,
and whatis were by other authors (these are written from scratch).
Catman is new.
1996-01-28 00:41:22 +00:00

210 lines
6.4 KiB
Plaintext

--------------------------------------------
Name: manpack
Version: 3.0
Author: Devin Reade <gdr@myrias.com>
Computer: Apple IIgs
Requires: GNO v2.x
--------------------------------------------
===========
Description:
===========
Various programs for working with manual pages. This archive includes:
apropos v3.0 locate commands by keyword
catman v1.0 format cat pages from man pages
makewhatis v1.2 create the whatis database
man v3.0 display reference manual pages
whatis v3.0 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, catman, man, and whatis)
SBINDIR = /usr/sbin (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.
==========
Legalities:
==========
These utilities are copyright 1995 by Devin Reade <gdr@myrias.com>.
They are provided as freeware, and may be distributed by Internet
archive sites, online services such as GEnie, or BBSes provided that
the archive remains intact. Permission is granted for distribution
with GNO/ME 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.
=======
CHANGES:
=======
apropos, whatis
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
v1.0 (24 Jul 95)
Initial release. Written from scratch by Devin Reade.
makewhatis
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.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:
=====
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.