FILE_ID.DIZ
Version v1.9 by Richard Holler [CIS 73567,1547] Last Revision 05/17/94

This HTML file was prepared at the request of the ASP (Association of 
Shareware Professionals), but the information contained in it may be of 
value to any shareware author.


FILE_ID.DIZ INFORMATION
-----------------------
Basically, the FILE_ID.DIZ file is a straight ASCII text file, distributed 
inside your distribution archive file along with your program files, which 
contains a description of your program. This file will be used by most BBS 
(Bulletin Board System) softwares for the online file description of your 
file. 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, the Author Direct FDN (File 
Distribution Network), and the majority of other electronic distribution 
services *REQUIRE* that a valid FILE_ID.DIZ file be contained in your 
submitted distribution archive. If your file doesn't contain a valid 
FILE_ID.DIZ file, then it simply won't be distributed by these services. 
Furthermore, most BBS sysops will not accept uploads of files which do not 
contain a valid FILE_ID.DIZ file, so you automatically lose out on that 
distribution as well.


DESCRIPTION:
------------
FILE_ID.DIZ was created by Clark Development for use with their PCBDescribe 
utility, as a means for shareware authors to provide descriptions for their 
products, and thus so that BBS callers can upload the file(s) without 
having to manually type in a file description. 

As long as an author creates and includes a FILE_ID.DIZ file in their 
distribution fileset, the text from that file will be used for the online 
description (in most cases) rather than anything typed in by the uploader. 
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 by the BBS industry more-or-less as the "standard" file 
description source. (The extension of "DIZ" actually stands for 
"Description In Zip").

NOTE: The FILE_ID.DIZ file *MUST* be named exactly that, and *NOT* 
something like .DIZ. It will *ONLY* be used if it is named 
FILE_ID.DIZ!

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 is 
used by most popular BBS software to describe your program, rather than 
using the description supplied by the person that uploaded your file. It 
should be placed *INSIDE* your distribution archive file. The FILE_ID.DIZ 
file is defined by its creators (Clark Development) as being created by the 
program author, and *NOT* the end user who is trying to upload the program.

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 make use of the 
FILE_ID.DIZ file have found it to be an excellent source for their manually 
added file descriptions.


STRUCTURE:
----------
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 "" 
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. Also try to include any hardware or 
software requirements that your product may have.

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.


EXAMPLE
-------
MY PROGRAM v1.23  - 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  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  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  Disk 2 of x").


ADDITIONAL INFO
---------------
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.

Fred Hill  has written a freeware utility which interactively creates 
a valid FILE_ID.DIZ file. The file is called DIZGEN.ZIP, and is included 
with this distribution archive.  I highly recommend that you use this 
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 distribution 
services, as well as other methods.

Two varieties of program files are defined here:

1) Program files which utilize an "install" utility and self-extracting 
program archives (later referred to as "Author-Installed Programs").

2) Programs files which do not use install utilities or self-extracting 
archives (later referred to as "User-Installed Programs").


AUTHOR-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 (SFX) 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, in order to allow
           them to be viewed/read by the various archive viewing utlities.
        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.TXT,
           SYSOP.TXT, etc.
        d. Any description or information file, such as DESCRIBE.TXT.
        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.


USER-INSTALLED PROGRAMS:
------------------------
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.TXT).


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 most BBS systems 
will convert your 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 doesn'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 for CompuServe uploading by simply removing the 2-digit version 
identifier, to make the file compatible with CompuServe libraries.

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
------------------------------
At one time, it was recommended that your final distribution archive not be 
larger than 350k, so that it would 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). This 
limitation is slowly falling by the wayside as more and more computer 
systems have 3.5" floppy disk drives as standard.

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). However, 
for CompuServe it is recommended that you simply create a single 
distibution file, and eliminate the multi-part file set.

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 distribution disk simply contain a ZIPd version 
of your product. However, If you choose to supply "unarchived" files on a 
distribution disk for Disk Vendor use, it is _VERY_ important that you 
specify in your documentation a suggested archive filename, so that BBS 
sysops can create archived files with the proper author-specified 
filenames. This information should be contained in your SYSOP.TXT (or 
VENDOR.TXT) 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, and nearly every other electronic 
distribution service *REQUIRE* that your files be submitted as an archived 
file, using the ZIP format. Also note that many BBS sysops will not go to 
the trouble of ZIPing your unarchived files for you. If you don't supply 
them with an archived distribution version of your product, it might not 
get distributed by BBSs.

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.


SUMMARY
-------
Your distribution disk should now be ready to submit to the various BBSs, 
distribution services, and Disk Vendors.

You may choose to create a separate distribution disk for use by BBSs and 
Disk Vendors. However, if you follow the above steps in preparing your 
distribution archive file, a separate "Disk 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.