FILEID.TXT v1.7 by Richard Holler [CIS 73567,1547] Last Revision 03/11/93
This text file is prepared primarily for use by ASP (Association of Shareware Professionals) Author members, but the information contained in it may be of value to any shareware author.
Basically, the FILE_ID.DIZ file is a straight text file which contains a description of your program, and is used for online file descriptions on BBS systems. We recommend that the FILE_ID.DIZ file be used in all of your distribution archives.
This text file contains a description of the FILE_ID.DIZ file, as well as a description of the recommended distribution archive format.
WHY SHOULD YOU USE FILE_ID.DIZ?
The use of this file will insure that the online description of your program will be in your own words (and who better to describe your program than yourself?), and that it will remain the same no matter how many different people upload your file to various BBS systems.
As more and more BBS software makes use of this file, you can be assured that your own description will replace such online descriptions as "Cool Program" or "OK utility, but needs better …"
Please note that the ASP Hub Network *REQUIRES* that a valid FILE_ID.DIZ file be contained in your submitted distribution archive.
FILE_ID.DIZ was created by Clark Development for use with their PCBDescribe utility, as a means for BBS callers to upload a file without having to manually type in a file description. It also ensures that the online description is always the same regardless of the number of different BBS systems the file is posted on. It has since been accepted more-or-less as the "standard" archive file description. (The "DIZ" actually stands for Description In Zip).
The FILE_ID.DIZ file is nothing more than a straight ASCII text file which contains the full description of the archived file containing it. It can be used by certain popular BBS software to describe your program, rather than using the description supplied by the person that uploaded your file to the BBS. It should be placed *INSIDE* your distribution archive file.
The BBS software will "look" inside the archive file. If a FILE_ID.DIZ file is found, it will replace any existing online file description with the text contained in FILE_ID.DIZ. It is an excellent method for making sure that your program files are described the way that "you" want them described. Even sysops who's software can't automatically use the FILE_ID.DIZ file have found it to be an excellent source for manually adding their file descriptions.
The file consists of straight ASCII text, up to 10 lines of text, each line being no more than 45 characters long. It should NOT contain any blank lines, any form of centering or formatting, or any Hi-ASCII or ANSI characters. (i.e. it should ONLY contain alpha & numeric characters).
We recommended that it consist of 5 basic parts:
1. the proper name of your program 2. the version number 3. the "ASP" identifier (optional, for ASP members) 4. the description separator 4. the description
All of the above parts should be separated by a single "space".
PROGRAM NAME: To set it apart from the rest, it is recommended that you use ALL CAPS for the program name.
VERSION NUMBER: The version number should be in the form of "v12.34".
ASP IDENTIFIER: If you are an ASP author, we recommend that an "<ASP>" identifying mark be added after the version number, to identify your product as an ASP-authored product.
DESCRIPTION SEPARATOR: To separate the actual description text, insert a simple "-" (dash/minus) character after the ASP identifier (or version number, if not using the ASP identifier), and in front of the description text.
DESCRIPTION: You should attempt to FULLY describe your product, including its most important functions and features. Be sure to include anything which will separate your program from it's competition, and make the BBS user want to download your file.
You should try to use the first 2 lines of the text to give a basic description of your program. This is helpful for sysops who's BBS software limits them to less than 10 lines, 45 characters. Sysops who are limited to using shorter descriptions can simply use the 1st two lines and truncate the rest. Thus, you can basically still supply your own description for BBS software which does not actually utilize the FILE_ID.DIZ feature.
The remaining lines of text can be used to elaborate on the programs features, enhancements from the prior version, information concerning multi-file sets. Please note that older versions of some BBS software can only use 8 lines of text. It is advisable that you create your FILE_ID.DIZ file so that the file can be truncated to various line lengths without destroying it's usefulness.
MY PROGRAM v1.23 <ASP> - A program which will do anything for anybody. Will run in only 2k of memory. Can be run from the command line, or installed as a TSR. Completely menu- driven. Version 1.23 reduces the previous 4k memory requirements, and adds an enhanced graphical user interface. Also, MY PROGRAM now contains Windows and DESQview support. Coming soon - an OS/2 version. From Do-It-All Software, Inc. $15.00
MULTIPLE DISK INFO
Please note that if your distribution archive requires multiple archive files, you should create a separate, specific FILE_ID.DIZ file for each archive. This can be utilized to describe the various contents of each archive, and to identify each disk in the set. For example, the FILE_ID.DIZ file for disk #1 could contain:
"MY PROGRAM v1.23 <ASP> Program Executable Files - Disk 1 of 2" [followed by detailed description text]
while the FILE_ID.DIZ file for disk #2 could contain:
"MY PROGRAM v1.23 <ASP> Documentation Files - Disk 2 of 2" [followed by more detailed description text]
Optionally, you could also create a "complete" FILE_ID.DIZ file for the first disk, which would fully describe the program in detail, and identify it as Disk 1 of x. Then, for each remaining file in the set, simply include the Program Name, version number, ASP identifier, and the disk number (i.e. "MY PROGRAM v1.23 <ASP> Disk 2 of x").
Please don't be tempted to use fancy graphic or ANSI sequences in the FILE_ID.DIZ file, as most BBS software will not allow this, and will render your FILE_ID.DIZ file useless. Also, don't be tempted to simply copy your program description file to FILE_ID.DIZ. Attempting to "format" your FILE_ID.DIZ file (i.e line centering, right & left justification, etc) will also cause unexpected results, especially for BBS software which re-formats descriptions to other than 10line/45char.
(LATE-BREAKING NEWS - Fred Hill <ASP> has written a freeware utility which interactively creates a valid FILE_ID.DIZ file. The file is called DIZGEN.ZIP and can be found on CompuServe as well as on many fine BBS systems. I highly recommend that you download a copy of this wonderful utility for creating your FILE_ID.DIZ files.)
The following is a recommendation for the structure and contents of distribution archives prepared for use on BBS systems.
DISTRIBUTION DISK RECOMMENDATIONS
The following are recommendations for preparing your program files for distribution to Bulletin Board Systems (BBSs) via the ASP's Disk Mailing service, as well as other methods.
2 varieties of program files are defined here:
1) Program files which utilize an "install" utility and self-extracting program archives (later refereed to as "Author-Installed Programs").
2) Programs files which do not use install utilities or self-extracting archives (later refereed to as "User-Installed Programs").
These programs require a bit more work from the author, but will eliminate many user mistakes, especially in programs which require complicated setups.
Most "installation" utility programs will make use of program files which have been "archived" into Self-Extracting archives. We will attempt to define which files should be contained in the Self-Extracting archives, and which files should not.
1. Files which should be contained in the self-extracting program file archive:
a. All program-specific executable files. b. Any required configuration and/or data files required by the program. c. Program documentation files. Optionally, these may be left outside of the self-extracting archive, but they will not be installed to the destination directory with the program files. d. Any other program-specific files that are required for the operation of the program.
2. The files described above should be compiled into a self-extracting archive file, which will then be extracted by the install utility.
NOTE: the author is required to abide by any distribution requirements specified by the archive utility author, and to obtain any required distribution rights necessary. Please check to see if distribution rights are required for your archive utility choice.
3. Files which should NOT be contained in the self-extracting program file archive:
a. The install utility itself (obviously). b. The FILE_ID.DIZ file. (described in detail in the section preceding this one) c. Any distribution/information files, such as VENDOR.DOC, SYSOP.DOC, etc. d. Any description or information file, such as DESCRIBE.DOC. e. A user file (such as README.1ST), which should explain how to use the install utility, what the user should expect during the installation, and any preparation that the user should make prior to the installation. This file might also contain a brief description of your program, in case the user is able to read the documentation files in the distribution archive prior to downloading (many BBS systems offer this ability to the user).
4. The actual distribution archive file (described below) should then contain the install utility, the self-extracting program archive, and the files described in #3 above.
This type of distribution archive is much simpler than the Author-Installed variety. It should simply be an archive file, containing all of the files for the program described above.
Since this type of program requires the user to do all of the installation manually, it should contain very specific and detailed information regarding the installation requirements (such as INSTALL.DOC).
THE DISTRIBUTION ARCHIVE FILE:
The actual distribution archive file should merely be an archive file containing the files described above. For BBS distribution, this archive should be of the standard archive format, and -NOT- a self-extracting archive. Many sysops will not allow self-extracting archives, and most BBS software will not allow self-extracting archives to be uploaded.
There are many popular archive utilities available, such as PKZIP, LHA, LHARC, ARJ, etc. Most BBS systems are capable of handling archives in virtually any format. However, you should be aware that some BBS systems will convert your chosen archive format to the format of choice by the sysop. By following the methods described above, this conversion process should not affect your program, or any self-extracting files which are contained within your distribution archive file.
You should also retain the default archive file extension defined by the archive utility. For example, PKZIP uses a ".ZIP", LHARC uses "LZH", etc. Changing the file extension may cause the BBS software to delete your file because it won't recognize the format.
For the actual filename for your distribution archive, it is recommended that the program filename be limited to 6 characters to represent the program's name (i.e. MYPROG could represent "My Program"). This should be followed by 2 numeric digits which will represent the version number of your release. Even if this is your initial release it should include the version number in the filename (i.e. MYPROG10.ZIP would indicate the program called "My Program" version 1.0).
Please note that CompuServe limits filenames to only 6 characters. By limiting the file "name" to 6 characters, you will easily be able to rename the archive by removing the 2-digit version identifier, to make the file compatible with CompuServe libraries (which will only allow 6-character filenames).
By including the 2-digit version number in the archive filename, it will be very easy for both the user and the sysop (and yourself) to identify older versions of your program.
MULTIPLE DISTRIBUTION ARCHIVES
It is recommended that your final distribution archive not be larger than 350k, so that it will fit on a single 360k floppy disk and still leave room for any distribution files necessary for Disk Vendors. (i.e. Disk Vendors will often include their own GO.BAT file, or other various small files to help their customers install the software).
If your program is large enough to require more than one distribution archive, it is recommended that your filename be limited to 5 characters rather than 6 as described above. Following the 5-character name should be the same 2-digit version number. Then, append a single "letter" to identify the disk (i.e. MYPGM10A.ZIP, MYPGM10B.ZIP, etc.). For uploading to CompuServe, these filenames may then be shortened to 6 characters by removing the version identifiers (i.e. MYPGMA.ZIP, MYPGMB.ZIP).
If your program requires multiple distribution archives, -BE SURE- to create separate FILE_ID.DIZ files for each distribution archive. Also, each FILE_ID.DIZ file should contain disk number information pertaining to each individual archive (i.e. Disk 1 of 3, Disk 2 of 3, etc.).
THE DISTRIBUTION DISK
It is recommended that your final distribution archive file be under 350k in size, so that it will fit on a single 360k floppy disk. There is no need to include anything on the disk except the distribution archive.
However, you may want to include copies of your distribution text files (VENDOR.DOC, SYSOP.DOC, DISTRIB.DOC, etc.) so that the sysop (and/or disk vendor doesn't have to go inside the archive to gather information regarding your file.
If you choose to supply your files "unarchived" on the distribution disk, it is _VERY_ important that you specify what the archive filename should be, so that sysops can create archived files with the proper author-specified filenames. This information should be contained in your SYSOP.DOC (or VENDOR.DOC) file. If you don't supply a suggested archive file name, the sysops will be forced to create the name themselves, thus you may end up with thousands of versions of your products on BBS systems all over the world, but all with different filenames.
Please note that the ASP Hub Network *REQUIRES* that your files be submitted as an archived file, using the ZIP format.
If you supply your own disk labels, it is recommended that the ASP logo, or at least the initials "ASP" be included on the label, so that anyone can immediately identify your disk as an ASP member's software.
Your distribution disk should now be ready to submit for the ASP Author's Disk Mailing, as well as any separate mailings that you want to do yourself.
Since the ASP Disk Mailing Service allows separate distribution disks for BBSs and Vendors, you may optionally create a different distribution disk for use by Disk Vendors. However, if you follow the above steps in preparing your distribution archive file, a separate vendor disk is probably not necessary. The majority of disk vendors will be able to accept your distribution file/disk if it is prepared in the above described format.