gno/usr.orca.bin/describe

$Id: README,v 1.9 1999/04/05 19:47:19 gdr-ftp Exp $

This is the README file for the describe package.  This package is
designated as version 1.0.7, 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

** NOTE **	The describe database itself is now shipped as a
		separate file.  You can find the most recent version
		of the database at the URLs mentioned in the installation
		section.

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@trenco.gno.org

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

After you have done this, type the command
	rehash
so that gsh will be able to locate the new utilities.

Next, you will need a current copy of the describe database.  As of 
version 1.0.5, the database is no longer included with the describe
sources.  Instead, you can get it from one of the following URLs:

	ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/desc.src.shk
	ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/desc.db.shk
	http://www.gno/org/~gno/describe
	http://www.arrowweb.com/sbehrens/describe.htm

The desc.src.shk file contains the describe database "source" file.
The desc.db.shk file contains a "precompiled" database.

If you downloaded the precompiled database archive, then you can extract
the contained file, "describe.db", and place it directly in /usr/lib.
If you select another location, you will have to set your DESC_DB 
environment variable.  See the describe(1) man page.  If you did
this step, then you can skip extraction and compilation of the database
source.

If you downloaded the database source archive (desc.src.shk), it will
extract to a file called "describe.source".  You can place this file
anywhere, but the recommended location is in /usr/lib.  Next, issue
the following command:
	/usr/sbin/descc /usr/lib/describe.source
This will create the file /usr/lib/describe.db.

You should periodically download a new copy of the database.  The 
date the database was updated is visible in the first few lines
of the describe.source file.

If you have submissions for the database, the web pages mentioned above
contain directions on how to do the submission.

KNOWN BUGS
==========

The describe.source file must be sorted (keyed on the "Name" field,
case insensitive) when being compiled by descc.  Failure to ensure
this will result describe failing to find certain entries, even if
they belong in the database.  Using the descu program to update the
database source ensures that the source is properly sorted.

CHANGES
=======

This details changes to the entire distribution.

v1.0.7  April 1999
	Make sure that if descu's rejects file already exists, that it
		is a regular file.  This prevents us from overwriting it.
	If the rejects file is empty at the end of the run, then delete it.
	Don't emit unchanged entries into the rejects file.  Changes are
		based on a whitespace-insensitive and case-insensitive
		on all fields.
	In descu, fix a bug that would sometimes eliminate blank lines
		between the "FTP:" header and the description.
	Removed some dead code in descu.

v1.0.6	February 1998
	There used to be a limit of 65k on the size of the describe
		database source when using descu.  This limit was imposed
		due to a bug in ORCA/C (it is no longer clear whether
		this was a bug in malloc(3) or in array indexing code).
		As of ORCA/C v2.1.x, this bug appears to be fixed, so
		the limit was lifted.
	A couple of calls to lseek(2) didn't have their return values
		checked for errors.  Fixed.
	Updated email address for Devin Reade.

v1.0.5  January 1998
	Increased the number of characters in the name field of the
		nameEntry struct from 34 to 36.  This gives an 8-byte
		alignment to the offset entry, which provides binary
		compatibility of the precompiled database file between
		the IIgs and little-endian 32-bit machines such as
		Linux boxes.

		*** THIS MEANS THAT THE PRECOMPILED DATABASE IS NO LONGER
		    BINARY COMPATIBLE WITH EARLIER VERSIONS.

	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).
	Fixed a bug in descu that caused the "header" to be slowly eaten,
		one character at a time.
	The describe database source file is no longer part of this
		archive.  It is available separately from the url, 
		above.
	Added a "Known Bugs" section and URLs on where to find the
		online database to this README.  Modified the installation
		instructions a bit.

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.6	Devin Reade	<gdr@trenco.gno.org>
	v1.0.5	Devin Reade
	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.