gno/usr.orca.bin/describe/README
gdr-ftp 17aad04201 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.
1998-02-07 06:40:11 +00:00

242 lines
9.3 KiB
Plaintext

$Id: README,v 1.8 1998/02/07 06:39:53 gdr-ftp Exp $
This is the README file for the describe package. This package is
designated as version 1.0.6, 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.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.