home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / information / product-infos < prev    next >
Text File  |  1994-02-27  |  34KB  |  788 lines
  1. Future material in the library will be indexed by means of information
  2. contained in "Product-Info" files.  Below is the current draft of the
  3. specification for these files.  If you submit material to the library
  4. please create and submit a Product-Info file at the same time.  If you
  5. have material that was included in the past, please create and send
  6. in a Product-Info file for it.  Thanks.
  7.  
  8. -Fred
  9.  
  10. ---------------------------------------------------------------------------
  11.  
  12.              FishROM Database
  13.              ~~~~~~~~~~~~~~~~
  14.             (Draft #6: 940225)
  15.  
  16. ---------------------------------------------------------------------------
  17.  
  18. Synopsis of Changes in this Draft:
  19.  
  20.     1. If .Product-Info is not found, Product-Info is also considered a
  21.        valid product information file.  See (6) below.
  22.     2. A NEW FIELD (.fullname) is now available.  It is optional but
  23.        should be used by applications that derive their common name
  24.        from and abbreviation of their full (complete) name.  As an
  25.        example, AIBB would have a .fullname of "Amiga Intuition Based
  26.        Benchmarks"  See the field descriptions, below.
  27.     3. A NEW FIELD (.stored-in) is now available.  It describes where
  28.        and how the application is stored.  The generation of this field
  29.        requires some care because it may reference EITHER a directory
  30.        OR an (archive) file.  See the field descriptions, below.
  31.     4. A NEW FIELD (.submittal) is now available.  It describes who
  32.        submitted the program or how it came to be placed into the
  33.        collection.  See the field descriptions, below.
  34.     5. A NEW FIELD (.described-by) is now available.  It specifies who
  35.        created the Produc-Info file (all those fields) for the program.
  36.     6. New .type keywords have been added according to a list that Fred
  37.        posted.  This list is open-ended but extensions should be made
  38.        with care.  Unrestrained expansion could neutralize the use of
  39.        this field.
  40.     7. The description for the .version field has been altered to
  41.        indicate that the MAJOR.MINOR format is a suggestion, not a
  42.        rule.  What any program does with the information is anyhow
  43.        largely unspecified.  The specs laid down by this draft aim to
  44.        create law and order (... must be maintained at all times, Ja?)
  45.        but are NOT meant to impose needless and senseless restrictions.
  46.        NOTE: nothing hinders you from storing 20 lines of descriptive
  47.        text in the .version field or leave the .description field
  48.        entirely blank.  While KingFisher itself will give a hoot, the
  49.        user will be needlessly confused.  Stick as closely as POSSIBLE
  50.        to these guidelines to make the overall functionality more and
  51.        more reliable.
  52.  
  53. ---------------------------------------------------------------------------
  54.  
  55. NOTE: This document contains some specific information on the KingFisher
  56.       Database, as well as features and design choices of the KingFisher
  57.       2.0 Server.
  58.  
  59.       The KingFisher 2.0 Server is a program to which client applications
  60.       attach and from which clients may retrieve information.  This allows
  61.       multiple clients nearly unrestrained access to multiple databases.
  62.       Clients may have ARexx, CLI, and/or GUI interfaces, and may have a
  63.       very specific or quite general purpose.
  64.  
  65.  
  66. 1. A KingFisher 2.0 database is described by a text file whose name ends in
  67.    .kfdb (KingFisher DataBase.)  This file describes everything that the
  68.    KingFisher Server needs to know about the database, especially the names
  69.    of one or more database sections and what range of record numbers each
  70.    contains, the names of primary and secondary index files, as well as
  71.    some other, less vital, information.
  72.  
  73. 2. A database consists of zero or more records spread over one or more
  74.    files and indexed by a single (primary) index file.
  75.  
  76. 3. Each record is an extended ASCII (text) file which may contain standard
  77.    characters of the ISO Latin 1 character set (0x20..0xff) as is the
  78.    standard Amiga symbol set, as well as the ASCII formatting character
  79.    0x1a (newline.)  All other symbols in the range 0x00..0x1f are illegal
  80.    for a record and may or may not produce erratic behavior.
  81.  
  82.    Expressly forbidden are the NUL (0x00) and the ^N (0x0e) as they have
  83.    special meaning.
  84.  
  85.    Furthermore, a dot (.) is not permitted as the first character on a line
  86.    unless it preceeds the name of a FIELD (see below.)  A dot leading text
  87.    on a line (rather unusual) may be avoided without loss by placing a \
  88.    (backslash) symbol immediately before it.  KingFisher's formatting
  89.    functions will recognize and adjust for such occurrences, as well as
  90.    other special formatting sequences that begin with a backslash.
  91.  
  92.    And last, but not least, a record begins with the character string
  93.    ".name" (sans quotes) so that the start of the NEXT record can be easily
  94.    determined by the appearance of this special key string.  No other field
  95.    is special to KingFisher.
  96.  
  97.    Field name identifiers are not case sensitive.
  98.  
  99. 4. KingFisher places between some records a special marker (^N (0x0e)) line
  100.    to indicate breaks between disks.  This allows reindexing algorithms to
  101.    properly recover information about disk references.  While the new
  102.    .reference field makes this less necessary, it does help in carrying
  103.    over older KingFisher Release 1 databases.
  104.  
  105.    Suggestion:    You could "misuse" this disk number scheme with a database
  106.         of your own design by assigning it the concept of pages.
  107.         Thus you could store text and filenames in a database and
  108.         use the disk markers as new-page markers, all under the
  109.         control of the KingFisher server, of course.
  110.  
  111. 5. New records (fish) are added to the database at the end.  KingFisher
  112.    maintains a database with variable size records and removal of records
  113.    always truncates the database at that point.  Unlike the original
  114.    KingFisher Release 1, however, the records so truncated will be removed
  115.    from the database.  The interface to the server, however, would allow a
  116.    client application to make prior backup arrangements of the records that
  117.    it wants to delete, in order to undo the truncate operation again.
  118.  
  119. 6. Information in the form of KingFisher Database Records (see (3) above)
  120.    is to accompany an application in the form of a .Product-Info file.
  121.    Unless client applications decide to use a different filename (STRONGLY
  122.    discouraged!) the .Product-Info file is herewith a standard.
  123.  
  124.    As of draft #5, the leading period on the name .Product-Info is optional
  125.    and may be omitted.  Programs parsing the directory tree should check
  126.    for the presence of the .Product-Info file first, and if not found, try
  127.    to load the Product-Info (no leading period) file.
  128.  
  129. 7. When KingFisher Database Records are transported via electronic mail or
  130.    otherwise embedded within unrelated text (i.e. with news headers and
  131.    personal signatures following) the records MUST BE enclosed in special
  132.    DATA TRANSPORT MARKERS that tell the parsing software what information
  133.    is part of the records and what is not.  Multiple such records may be
  134.    enclosed by only a single pair of markers, or multiple records may be
  135.    enclosed each by a pair of markers with unrelated text before, after,
  136.    and between the markers.
  137.  
  138.    If a file is being parsed which begins with a line less than or equal to
  139.    30 characters in length, and does not have a special DATABASE HEADER,
  140.    then KingFisher assumes this file to be a KingFisher Release 1 database.
  141.    This assumption can be false, so it remains the user's responsibility to
  142.    assure that no garbage is fed to the parser.
  143.  
  144.    Note that the DATA TRANSPORT MARKERS are not meant for use in the
  145.    .Product-Info files, although they will be ignored if found.  They would
  146.    simply be wasted, there.
  147.  
  148.    The following examples are to be read as complete files between the
  149.    lines that look like this: ---------------
  150.  
  151.    Example 1:  A file containing text in addition to the database record.
  152.  
  153.     ----------------------------------------
  154.     Hello, Joe.  Here is the description of that weird game
  155.         I was telling you about.  See if you can figure out how
  156.         to win this.  Good luck!
  157.  
  158.     .BEGIN-FISH-DESCRIPTION
  159.     .name
  160.     MonkeyCommand
  161.     .author
  162.     KingKong Industries