mirror of https://github.com/GnoConsortium/gno.git
253 lines
9.8 KiB
Plaintext
253 lines
9.8 KiB
Plaintext
$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.
|