$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 " where 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 . The descu utility was written by Devin Reade. The following people have performed updates as listed: v1.0.6 Devin Reade v1.0.5 Devin Reade v1.0.4 Devin Reade v1.03 Soenke Behrens 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.