gno/usr.orca.bin/describe

$Id: README,v 1.6 1997/12/22 00:34:51 gdr Exp $

This is the README file for the describe package.  This package is
designated as version 1.0.5, and consists of the following utilities:

	describe - show database entries describing the current
                   status of programs

	descc    - the describe source compiler

	descu    - the describe source updater

ABOUT DESCRIBE AND DESCC
========================

  This is yet another project I've been sitting on for a while, but have
finally decided to release.  The basic idea of the 'describe' package
(the descc "compiler" and describe itself) is to provide a quick, easy
way of accessing information related to the utilities which so many
different people are releasing these days.  The reason it sat around on
my harddrive so long is I was having qualms about its designated role in
life.  I wasn't sure exactly what I wanted it to do.  Well, I've decided
to KISS for now: descc simply compiles the utility list, which I maintain,
into a (very) simple "database" located in /usr/local/lib.
[As of v1.0.4, this database is now in /usr/lib.  gdr]  [Alternatively,
the full path given in the environment variable DESCDB will be
used, if it is set. sb].  The companion utility 'describe' is used to
fetch information about a particular utility from this "database".

   descc is fairly limited, as is the "database" format itself.  Part of the
KISS (or it wouldn't be out now) design philosophy ;).  Usage is simple:
when you get a new listing (I'll provide monthly updates), simply "descc
<filename>" where <filename> is the name of the newly released update.
descc will simply write over the old database and replace it with the
new.  (Note:  No appendages are allowed by descc.  See descu.)

   As always, coments are appreciated.  And, moreso than on other projects,
I'd appreciate some comments about the direction I'm going in, suggestions
as to where to take this, etc.  I have a feeling that some fields in the
format (eg, FTP:) are rather useless, and I'd like to know what you guys
out there think.

James Brookes
jamesb@ecst.csuchico.edu

ABOUT DESCU
===========

I think describe and descc were really good ideas; they sure beat the
text file list of GNO utilities that James used to keep.  The one major
shortfall I found was having to manually update the describe database
source every time I wanted to include a new entry.

I therefore wrote descu, the describe updater, which is also rather
limited due to following the KISS principle.

For completeness, I have also added the man pages describe.1, descc.8,
and descu.8.  I briefly pondered having a describe.5, but alas I was too
lazy; you can find the file formats as part of descc.8.

Devin Reade
gdr@myrias.ab.ca

INSTALLATION
============

You can either type "dmake install", or do the following:

	cp ./describe /usr/bin
	cp ./descc    /usr/sbin
	cp ./descu    /usr/sbin
	cp ./describe.1 /usr/man/man1
	cp ./descc.8 ./descu.8 /usr/man/man8
	rm /usr/local/lib/describe
	rm /usr/local/bin/descc
	rm /usr/local/bin/describe

You will also want to do the following, which is NOT done by dmake's
install target:

	rehash
	/usr/sbin/descc ./describe.src

Note that the describe database source file (describe.src) included in
this archive is almost certainly out-of-date.  The most recent version
of this file can be obtained online at:

	http://www.arrowweb.com/sbehrens/describe.htm

If the above url is unreachable, check the GNO FAQ for a new location.

CHANGES
=======

This details changes to the entire distribution.

v1.0.5  December 1997
	Updated descu so that the "Last Updated" line in the describe
	source "header" is updated to reflect the current date and
	time (GMT, if supported).

v1.0.4  September 1997
	This package is now part of the base GNO distribution.
	Version numbers are now in lockstep.
	Some bugs were fixed in descu that cropped up when the
		describe database source file didn't already exist.
	Location of the system database has been changed to
		/usr/lib/describe.db from /usr/local/lib/describe.
	Descc will now set the file type of the database to BIN vice TXT.

v1.03   January 1996
        descu now sorts entries correctly (longer entries
        ended up before shorter ones with 1.0.2, i.e. "calls"
        came before "cal")

v1.02	October 1995
	descc now circumvents a bug in ORCA/C's ftell() function.
	describe can now find entries that are not all lower-case.
	describe will now print the name of entries in the case
		they were entered into the database.
	descu now sorts the describe source file case-insensitive.
	describe and descc can now find the database in a path given
		by the environment variable DESCDB. If DESCDB is not set,
		/usr/local/lib/describe is used, as before.
	A new "Shell:" field has been added to the format of the database.

v1.01	May 1995
	Initial release for descu.
	Added -h and -v flags to describe and descc.
	Common defines and typedefs were extracted to desc.h.
	Descc now exits -1 on failure (vice 0).
	In descc, some more error checking and flushing were added.  Also,
		mygets wasn't dereferencing one of its arguments properly.
	Allocated stack size was increased from 512 to 768 bytes.
	Describe and descc were modified not to be dependant on the size
		of integers.
	Ran source files through indent(1).
	
v1.0	Feb 1994
	Initial release for describe and descc.

AUTHORS
=======

The original describe and descc utilities and the describe format were
written by James Brookes <jamesb@ecst.csuchico.edu>.

The descu utility was written by Devin Reade.

The following people have performed updates as listed:
	v1.0.5	Devin Reade	<gdr@myrias.com>
	v1.0.4	Devin Reade
	v1.03	Soenke Behrens	<sbehrens@bigfoot.com>
	v1.02	Soenke Behrens
	v1.01	Devin Reade

LEGALESE
========

The describe and descc utilities are copyright (c) 1994-1997 by James
Brookes.  The descu utility is copyright (c) 1995-1997 by Devin Reade.

These programs may be freely copied provided that the archive, including
source files and this README, remain intact.  Modified versions of these
programs may not be distributed without the permission of the respective
authors.

Contact the respective authors for permission to include these programs on
any commercial software collections.  Permission is granted to Usenet sites
and GEnie Information Services for inclusion in software archives.

The Apple IIGS executable files distributed with this archive contain
material from the ORCA/C Run-Time Libraries, copyright 1987-1997 by
Byte Works, Inc.  Used with permission.