http://www.wam.umd.edu/~walrus/Product-Info.html (Amiga Plus Extra No. 5/97, 05/1997)
Main text of the Product-Info Specification
Fields defined by the Product-Info Specification
Starter file for a .Product-Info file of your own
Common errors when creating a Product-Info file
The Product-Info Specification was designed by me (Udo Schuermann) with much feedback from Fred Fish. Fred has repeatedly said that I'm too modest to take the credit for this work. Maybe I am, but without his initiative to get me going and his feedback to help polish it, the Product-Info Specification would not have come to be what it is, either. So, I guess it is a bit of a joint effort.
---------------------------------------------------------------------------
Product-Info Specification
Version 8
March 23, 1996
---------------------------------------------------------------------------
By providing a well-written 'Product-Info' with your product, you assure yourself of maximum potential exposure to customers who are looking to fill a need that your product might fill.
---------------------------------------- Hello, Joe. Here is the description of that weird game I was telling you about. See if you can figure out how to win this. Good luck! .BEGIN-FISH-DESCRIPTION .name MonkeyCommand .author KingKong Industries .description Lure the love struck monster ape back to his island. Tools include Fay Wray's torn nightgown, a Fokker airplane (you get to pilot it), a compass and a map. \.png image support lets you paint your own airplane decals. .END-FISH-DESCRIPTION ----------------------------------------
---------------------------------------- .name MonkeyCommand .author KingKong Industries .description Lure the love struck monster ape back to his island. Tools include Fay Wray's torn nightgown, a Fokker airplane (you get to pilot it), a compass and a map. \.png image support lets you paint your own airplane decals. .name MonkeyCommand II .author KingKong Industries .description Keep the captured ape from assaulting the defenses of the prison that was erected at the conclusion of MonkeyCommand I. The game consists of coordinating the actions of four native tribal leaders and their vassals in repairing the damage done by the enraged monster ape as it tries to escape and revenge itself on whoever won the original MonkeyCommand. ----------------------------------------
---------------------------------------- Hi Tom, Remember that monkey game you told my about? .BEGIN-FISH-DESCRIPTION .name MonkeyCommand .author KingKong Industries .description Lure the love struck monster ape back to his island. Tools include Fay Wray's torn nightgown, a Fokker airplane (you get to pilot it), a compass and a map. \.png image support lets you paint your own airplane decals. .END-FISH-DESCRIPTION Well, seems that one wasn't enough and they released another one. We'll have to figure out how to finally beat the first one, it seems, before they let us play the next. Maybe we can look through the binary to find that code phrase. Here's the text: .BEGIN-FISH-DESCRIPTION .name MonkeyCommand II .author KingKong Industries .description Keep the captured ape from assaulting the defenses of the prison that was erected at the conclusion of MonkeyCommand I. The game consists of coordinating the actions of four native tribal leaders and their vassals in repairing the damage done by the enraged monster ape as it tries to escape and revenge itself on whoever won the original MonkeyCommand. .restriction You need the secret code from the first MonkeyCommand which you can only get if you won that game. .END-FISH-DESCRIPTION (=:Joe:=) ----------------------------------------
===========================================================================
.name (absolutely required; must also be the first field)
Purpose: The program's popular name. This is sometimes an
abbreviated version of the "fullname"
Format: 1 line only
Example: KingFisher
Example: HomeBase VI
Example: BLAZEMONGER
Example: AIBB
Example: gcc
.fullname (optional)
Purpose: The full (or complete) name of the program if it
differs from the "name"; omit this field if you
would merely duplicate "name"
Format: 1 line only
Example: Amiga Intuition Based Benchmarks
Example: GNU C Compiler
.short (optional, but recommended)
Purpose: A one-line description, preferably not exceeding
40 characters in length, à la Aminet. A single-
glance to the program's purpose.
Format: 1 line, best not to exceed 40 characters
Example: Software catalog/search/maintenance tool
Example: Full featured C/C++ package; CLI only
Example: 230db sound, mind-reading, killer game
.type
Purpose: Categorize the package; multiple keywords permitted,
but adhere as closely as possible to the list given
at the end of this document. Wild variations will
reduce the value of this field.
Format: One or more lines, but best not to exceed a single
word or two.
Example: database
Example: animation player
Example: animation tool
Example: spreadsheet
Example: communications
Example: display commodity
Example: mouse commodity
.description
Purpose: A full-text description of your package, containing
anything that is NOT ALREADY available through the
other fields (above and below.) The reader should
gain a good understanding what your program can and
cannot do. If you mention other (similar) software,
please add these also to the "reference" field.
Please note that this field FLOWS text and
is not designed for fixed-pitch ASCII graphics or
other flash. If you need to insert a newline, do so
with the "\n" sequence (backslash followed by a
lowercase "n"); newline characters are treated as
blanks. See the section on FORMATTING below!
Format: Free form: Any number of lines, treated as a single
stream of text and formatted according to embedded
formatting symbols (see FORMATTING below.)
Notes: The text should be readable regardless of the font
that is used in its display, and regardless of the
line width available (resizable window vs. printer)
.version
Purpose: The program's version number; please note that this
should follow the standard guidelines for versions,
as obeyed by most (but sadly not all, not even all
system software):
37.1 < 37.17 < 37.39 < 37.100 < 37.170
The following are all vastly different versions:
37.1 37.10 37.100 37.1000
Format: One line only: MAJOR.MINOR
Example: 37.100
Notes: Nothing requires you to maintain your versions this
way, but you should be aware that some software may
make use of this field by searching for a release
that has reached, for example, at least version 2
(perhaps as a requirement that said software has
been maintained by its author beyond some initial
release 1); if your program's version is "v940205"
then this would simply count as version 0 and could
be missed.
.date
Purpose: The program's official release date. NOT the date
when it made it into the database.
Format: year.month.day
Example: 1993.09.27
Example: 1996.01.01
Notes: The format was chosen to make it easily sortable.
Note the use of leading zeros in month and day, and
the complete year (with century.)
.author
Purpose: Any and all authors who have a part in the program.
Format: Any number of lines, each name should be placed on
its own line.
Example: Joe R. User
Tea Rexx
Example: J. Jones
Random Hacker
Bone Head
Notes: Addresses matching these authors should be placed
into the .address field, one after the other, and
in the correct order to produce a 1-to-1 relation.
.address (optional)
Purpose: Describe a full postal address of the author(s),
to be used when it becomes necessary or desirable
to contact the author by snailmail. Do not specify
the author's name, as this already appears in the
"author" field.
Format: Multiple lines. Formatting symbols are not used, as
physical newlines are respected.
Example: 7022 Hanover Parkway, Apt. C2
Greenbelt, MD 20770-2049
USA
.email (optional)
Purpose: Full electronic mail address
Format: Multiple lines, each having a 1-to-1 relation with
the "author" field; more than one email address may
appear on a line, separated by blank space (the
preferred way) or by commas.
Example: walrus@wam.umd.edu
Example: walrus@wam.umd.edu walrus@sprintmail.com
.url (optional)
Purpose: Universal Resource Locator, usually for ftp sites
or World Wide Web support/home pages.
Format: One or more lines, each on a 1-to-1 relation with
the "author" field. More than one URL (Universal
Resource Locator) may appear on a single line.
Example: http://www.wam.umd.edu/~walrus/KingFisher.html
Example: ftp://nowhere.com/Bogus.png
.keywords (optional)
Purpose: List as few or as many keywords as necessary to sum
up the major features of this package. It is
recommended to keep this entry to 10 keywords or
less, but no definitive limit will be enforced. The
idea with this field is to help construct a memory-
resident quick index for systems that can afford to
maintain a large amount of data in RAM.
Format: One or more lines; keywords or keyphrases separated
by white space (space, tab, or newline.)
Example: fish disks
library maintenance
search expressions
product-info
.restrictions (optional)
Purpose: If your software has any restrictions placed upon
it, list them here, in detail. You should indicate
if your package has been made dysfunctional (such
as would be the case with a demo package.) If the
program will not run on anything less than a 68020
CPU, you should list this here, to.
Format: Free form (see "description")
Example: Demo version has SAVE and PRINT disabled.
Example: Documentation available only in German.
Example: Disables video DMA while playing samples.
Notes: List actual restrictions here, not minimum system
requirements.
.requirements (optional)
Purpose: List minimum requirements for your program. These
should give the reader enough information to
determine if the software is likely to run on his/
her system. Be sure to specify operating system,
(hard)disk requirements, non-standard libraries
(such as MUI) and whether or not some or all of
these required libraries are included in the
distribution.
Format: Free form (see "description")
Example: 68020, 68030, or 68040 CPU; 3M free RAM; 18M disk
space; at least 640×480 display capabilities and
16 colors or better.
Example: Requires WB2.1 (V38)
Example: Requires 1024×768 (or larger) displays.
Example: Works only with 4096-channel, 230db BLAZETHUNDER
audio board.
Example: Requires MUI (Magic User Interface) version 10.
.reference (optional)
Purpose: List the full path to software in some way related
to this package. This may include previous versions
of your package or similar packages. The path is a
volume:path/ or volume:path/archive
Format: 2 lines per reference: the first is the path with
trailing slash (if you do not give the slash then
the name of an archive is assumed); the second line
is the version number.
Example: FishROM-0002:Productivity/Databases/HomeBase VI/
417.0
FishROM-0001:Productivity/Databases/HomeBase VI/
415.12
.distribution (optional)
Purpose: Describe the distribution and ownership status of
this software. Please see below for a list of the
most common (and recommended) terms.
Format: 1 line
Example: shareware
Example: commercial demo
.price (optional)
Purpose: If your package is available for a fee, describe
this price here. it is strongly recommended that
the first currency is expressed in US dollars to
provide a common base unit for prices. If your
package is freely available and has no price
attached, then omit this field.
Format: Free form but best adhere to examples.
Example: $50(US), DM75
.installsize (optional)
Purpose: The minimum and maximum sizes of the package as it
is installed. The minimum size should give an
indication of how much disk space is required for
an absolute minimal installation. If the reader has
less diskspace than that, the program is likely not
to be able to function at all. The maximum is the
absolute highest amount of diskspace that the
package is likely to consume when all portions are
installed (including optional tutorials, demo files,
etc.)
Format: One or more lines; only the first line has a fixed
format, the rest are free-form.
Example: 220K - 2400K
Most of the database files can be kept on floppy
disks, so valuable hard disk space is not wasted.
Example: 18K
Example: 38K - 500K
Lots of documentation and example scripts make up
the bulk of this installation.
Notes: It is recommended that sizes are scaled to kilo-
bytes to maintain a uniform scale, rather than
expressing them in bytes or megabytes. Always add
a size quantifier (K=kilobyte=1024bytes, M=megabyte,
T=terabyte, etc.)
.exectype (optional)
Purpose: Describe the type of executable(s) that make up
your program. Most packages are probably compiled
C, but some may be shell or ARexx scripts, BASIC,
AMOS, or otherwise interpreted. The reason for this
is that some packages are known to cause problems
on some systems, or the customer is looking for
something "better" than interpreted BASIC and would
like to know this before "wasting" time locating,
downloading, and installing the package.
Format: Free form (see "description")
Example: Compiled C
Example: AmigaBASIC
.source (optional)
Purpose: Describe what source code is available as part of
your package. If source is not available, then omit
this field. How large is the source? What compiler,
translator, or interpreter is required? It might be
good to give an idea of the version of the compiler
that is required.
Format: Free form (see "description")
Example: SAS/C 6.56, Manx, DICE source (750K) available for
$15(US); some old SAS/C 5.10b sources (30K) included
free.
Example: Limited C source examples (15K) included
Example: All source plus custom libraries: 12M
.construction
Purpose: Describe the types of languages used to create this
program and the methods used to build the final
executable. If possible, include the compiler
versions and possibly important options, such as
optimization for various CPUs (it is possible to
optimize somewhat for a 68040 without sacrificing
68000 compatibility.)
Format: Free form (see "description")
Example: SAS/C++ 6.56 with speed optimizations weighed for
the 68040 CPU (68040 not required, however.)
Example: AdaEd
Example: Handcrafted assembly
Example: Fortran with self-made compiler.
Example: AMOS
.tested (optional)
Purpose: Give an indication of which configurations have
served as test environments. If the software
operates without problems with non-standard system
enhancements, this would be a good place to mention
them.
Format: Free form (see "description")
Example: A500(512K Chip, 0K Fast, 1 Floppy), A2000(1M Chip,
2M Fast, 40M HD, 1 Floppy); not tested on 68020+
CPUs.
Example: A1000, A500, A600, A2000, A2000/30, A3000, A1200,
A4000/30, A4000/40 with various amounts of Chip
and Fast RAM, with and without MMU or FPU. Found
to be free of Enforcer hits and able to work with
virtual memory products; compatible with Retina,
EGS/Spectrum, and Picasso software. Also tested
under V33 through V40 system software.
Example: CPU: 68000, 68020, 68030, 68040 (68060 unknown);
Kickstart V37, V38, V39, V40; Video/Graphics: PAL,
NTSC, Picasso II (Village Tronic and CyberGraphX),
GVP EGS Spectrum (others unknown); Tested with
system enhancements such as GigaMem 3.12, VMM 3.2,
Enforcer 37.62, Executive 1.30, IPrefs2Fast 0.9b,
OpaqueMove 1.0, KingCON 1.3.
.run (optional)
Purpose: Specifies how to start the program.
Format: visible=type,command
where 'visible' would be what the user would see
and select; 'type' is either 'CLI' or 'WB' (the
system interface) and 'command' is the program to
execute. The 'CLI' version may include parameters,
including I/O redirection, as this string is passed
directly to the System() call.
Example: HomeBase VI=WB,HomeBase VI
HomeBase VI=CLI,ExecuteMe.HB6
HomeBase VI Fixer=CLI,ExecuteMe.HB6Fixer
KingFisher=CLI,KingFisher
Example: FishTub=WB,ExecuteMe
Notes: As this item may be dangerous to the unsuspecting
user, it has not been implemented by KingFisher and
is not likely to be implemented.
.execute (optional)
Purpose: An 'execute' script. This entry has been added by
Fred Fish; the script views the documentation,
installs the software, or merely runs the program.
Format: A shell script, line by line.
Notes: It is not recommended that this entry be supplied
by you, as Fred Fish may simply replace it with a
version of his own.
.docs (optional)
Purpose: List all documentation files associated with your
package. Do not specify the files if they are not
available as-is; if they are only located within an
archive, omit them.
Format: 1 line per file, do not include the path as this
is provided by the "stored-in" field.
Example: HomeBase.guide
HomeBase.dvi
HomeBase.doc
.described-by (optional)
Purpose: Who created the description ('Product-Info' file)
for this project.
Format: Free form (should include an electronic mail
address too, if available.)
Example: Fred Fish <fnf@amigalib.com>
Example: Udo Schuermann <walrus@wam.umd.edu>
.submittal (optional)
Purpose: Who submitted to package to Fred (or else how the
package came to be on the reference disk.)
Format: Free form (usually one line)
Example: Submitted on disk directly by the author.
Example: Downloaded from wuarchive.wustl.edu in pub/aminet/util/misc
.stored-in
Purpose: Specifies where and especially HOW the package is
stored. This field should specify EITHER the name
of a directory (ending with a ':' or a '/') OR the
name of a file. In the case of an archive, the name
should reflect that with the appropriate extension
(.lha .zip .gz .Z etc.)
Format: One or more lines
Example: FF1000:d501-1000/Disk950/Enforcer/
FF1000:d501-1000/Disk950/Enforcer/Enforcer
FF1000:BBS/d501-1000/Disk950/Enforcer/Enforcer.lha
Notes: This field is usually generated by the disk creator
software, not by the submitter of the package, as
the final location on the disk may not be controlled
by the submitter of the Product-Info.
.path (obsolete)
.aminet-dir (optional)
Purpose: The path (WITHOUT trailing '/') where this package
is available on the global Aminet.
Format: One line; must NOT end with a '/'
Example: biz/dbase
Example: gfx/edit
Notes: Together with aminet-file, this entry can be used
to construct the complete path to this package on
Aminet or Aminet CD-ROMs.
.aminet-file (optional)
Purpose: The name of the package (archive) as stored on
Aminet.
Example: KingFisher220.lha
Example: VanGogh.lha
Notes: Together with aminet-dir, this entry can be used
to construct the complete path to this package on
Aminet.
===========================================================================
Ship the resulting file with your product!
Acceptable names for the file (in increasing order of desirability) are:
.Product-Info Product-Info myproject.pi
Suggested keywords for the TYPE field:
Action Game Animation Animation Player Animation Tool Archiver CLI Tool Communications Compiler Compression Database Disk Tool Display Commodity Drawing Image Conversion Image Processing Library Mouse Commodity Music Composition OS Utility Painting Picture Printing Sound Analysis Sound Editing Sound Playing Spreadsheet Strategy Game Text Text Editing Text Viewer Thinking Game Word Processing Workbench Tool
Keywords for the DISTRIBUTION field:
Commercial Commercial software is owned and distributed through licenses. It costs money to individual end-users and is not freely distributable. SUCH PIECES SHOULD NOT APPEAR ON DISKS THAT ARE MEANT FOR FREELY DISTRIBUTABLE SOFTWARE! Commercial Demo Represents a demonstration of a commercial package. As such, commercial demos are freely distributable and may have limitations as described in the .limitations field. Shareware Such software is owned and copyrights are held by the author(s). The software may be distributed freely, but not sold for profit, of course. Shareware often specifies a limit of some time after which you are requested or required to register the software (i.e. pay for it.) This provides you with the means to evaluate the software thoroughly before paying for it. Freeware Such software is owned and copyrights are held by the author(s). The software may be distributed freely, but not sold for profit, which would mean the software is no longer FREEware. No payments are required for such software. Public Domain Software labeled PD (Public Domain) belongs to the public, i.e. ANYONE. Some people release their software into the public domain with the mistaken idea that they can continue to own and control the program. Not so. Software that is labeled Public Domain (or said by the author to be released into the public domain) truly belongs to anyone and everyone. It is quite legal for someone to take such a program and sell it for profit as is. Likewise, it it perfectly acceptable to modify public domain software to build a better product (or whatever) out of it and then sell it for profit. GNU Public License The terms and conditions of this license are long and not easily reproduced here. Suffice to say that software released under the GNU Public License cannot be sold for profit and must be distributed with source code. They are not public domain, however.
Unless specifically stated in the Field Definitions, a field's contents flow without regard for your newline characters, unless you specify a newline as a \n symbol where you want KingFisher to begin a new line. In fact, newlines, tabs, and spaces are all treated as blank characters, and multiple such blanks are treated as no more than a single blank!
If you require a portion of a field's data to be treated exactly as you specify it, you must force verbatim mode on with the \# symbol. Do not forget to turn back to flow mode with another \#. Verbatim mode overrides the flow mode feature of filling text within the margins, although word wrapping will still be performed. If the display window is too narrw for your verbatim text, the result will be a mess. Likewise, if you format your text for a fixed pitch font, you will likely produce a mess in anyone's window who is using a proportional font! Tabs and indents may help in that case, but overriding flow mode with \# is recommended only as a last resort.
To proof-read the appearance of your Product-Info files, use the "VIEW/Product-Info file" menu command. Resize KingFisher's window when you view your file to assure that your creation does not rely on a specific font and window width!