Index of /geminiatari/FILES/UTILITY/WHATIS20

      Name                    Last modified       Size  Description


[DIR] Parent Directory        24-Sep-2006 15:31      -  
[   ] APROPOS.1Z              22-Oct-1993 11:36     1k  
[TXT] APROPOS.C               22-Oct-1993 11:36     8k  
[   ] APROPOS.MAN             22-Oct-1993 11:36     2k  
[TXT] APROPOS.TTP             22-Oct-1993 11:36    19k  
[TXT] COMMON.C                22-Oct-1993 11:36     5k  
[TXT] MAKEFILE                22-Oct-1993 11:36     3k  
[   ] MKWHATIS.8Z             22-Oct-1993 11:36     1k  
[TXT] MKWHATIS.C              22-Oct-1993 11:36     7k  
[TXT] MKWHATIS.MA8            22-Oct-1993 11:36     1k  
[TXT] MKWHATIS.TTP            22-Oct-1993 11:36    16k  
[   ] WHATIS.1Z               22-Oct-1993 11:36     1k  
[   ] WHATIS.5Z               22-Oct-1993 11:36     1k  
[TXT] WHATIS._1_              22-Oct-1993 11:36    14k  
[TXT] WHATIS._2_              22-Oct-1993 11:36     9k  

whatis, whatisin, apropos v2.0.1 92/9/13
----------------------------------------

Here is an implementation of whatis(1), whatisin(1), and apropos(1).
These were all built with gcc 1.40 with MiNT libs at PL 19. It has been
tested on TOS 1.2 running MiNT 0.94. It does not use any MiNT-specific
functions so it should run under TOS alone (untested).

This should just about complete an online documentation system consisting
of:

	nroff		text formatter (for manpages)
	man		manual "front end"
	manpager	file viewer
	apropos		given keyword, find appropriate documentation
	whatisin	find out what is in each section of the manual
	whatis		get summary of what a command, etc. is

Note that the nroff I just posted last week (~92/9/11) to atari.archive
supports the .tm macro and hence the .IX man macro is implemented. This
is useful for creating index entries. You could, in theory, write a macro
that would generate an whatis database entry each time a manpage was
formatted. .tm writes to stderr while nroff otherwise writes to stdout.


Manifest
--------

	apropos.1z	compressed, formatted manpage (manpager format)
	apropos.c	source
	apropos.man	nroff source for manpage
	apropos.ttp	executable
	common.c	common source code for all programs
	makefile	what u expect
	mkwhatis.8z	compressed, formatted manpage (manpager format)
	mkwhatis.c	source for tool to help build databases
	mkwhatis.ma8	nroff source for manpage
	mkwhatis.ttp	executable
	whatis.1z	compressed, formatted manpage (manpager format)
	whatis.5z	compressed, formatted manpage (manpager format)
	whatis._1_	example databases (manual section 1)
	whatis._2_	   "        "     (manual section 2)
	whatis._4_	   "        "     (manual section 4)
	whatis._5_	   "        "     (manual section 5)
	whatis._7_	   "        "     (manual section 7)
	whatis._8_	   "        "     (manual section 8)
	whatis.c	source
	whatis.h	common header file
	whatis.ma5	nroff source for manpage
	whatis.man	nroff source for manpage
	whatis.ttp	executable
	whatisin.1z	compressed, formatted manpage (manpager format)
	whatisin.___	data file for whatisin
	whatisin.c	source
	whatisin.man	nroff source for manpage
	whatisin.ttp	executable


Installation
------------

You will need to set an environment variable, MANPATH, to the directory
which will contain the databases. This is the same environment variable
used by man(1) (mine, at least). If you don't set it (and if you don't
override with the -P switch on these commands), the default directory is
d:\usr\man.

So put this in your shell's startup file:

	setenv MANPATH path

where path is the directory.

Then copy whatis._?_ and whatisin.___ files there.

Copy the executables to your bin directory. If you have one, you should
probably copy mkwhatis.ttp to your /etc directory instead. It is really
more of an administration command.


Building whatis Databases
-------------------------

I have included several of my own whatis databases here. They were all
built using the mkwhatis program (also included) though there was some
hand editing involved (i.e., to add keyword fields).

mkwhatis is given a list of file names which are manpage source files
(i.e., nroff -man). It will spew out a pretty good attempt at formatting
entries for the database. For details on the format of the database, see
the documentation in whatis(5), mkwhatis(8), and mkwhatis.c.

I decided to diverge from unix (BSD) practice and include a separate file
for each section of the manual. To see what the sections are, see the file
whatisin.___ (which is the data file for whatisin).

Typically, you should be able to move to the directory(ies) containing
your unformatted manpages and do:

	cd man1
	mkwhatis *.man > whatis._1_
	cd ../man2
	mkwhatis *.man > whatis._2_
	cd ../man3
	mkwhatis *.man > whatis._3_
	etc...

There is no command line option to rename the database file. If you want
to do that you will have to recompile.

whatis, apropos, and whatisin recognize sections from this list:

	0	general info
	1	commands
	2	system calls
	3	library functions
	4	devices, hardware, drivers, etc.
	5	file formats
	6	games
	7	misc
	8	sys admin commands
	9	unused
	l	local
	n	new
	o	old

To change this list, change SECTIONS macro in whatis.h and change whatisin.___
file. These sections are normal unix convention, but you can use them in any
other way you want.


Enjoy...

Bill Rosenkranz
rosenkra@convex.com