- version.doc --------------------------------------------------------------

Version Command
===============

There  has been some confusion about what the format of version strings are.
The  exact  format  is  detailled in the Amiga User Interface Style Guide on
page 110.  The format is:

 $VER: <name> <version>.<revision> (dd.mm.yy)

example: $VER: FooBar 1.1 (23.5.92)

The  string  starts  with  $VER:   followed  by a space, followed by <name>.
<name>  is the name of the program.  <name> can NOT contain any spaces.  You
can use underscores to achieve a similar effect.

After  <name> comes a single space, followed by <version>.  <version> is the
major version number for the program.  There should be no leading zeros.

After  <version>  comes  a  dot,  followed by <revision>.  <revision> is the
minor version number for the program.  There should be no leading zeros.

Following the revision number comes a space, and then the date.  The date is
specified  in  numeric  form  only,  with  no  leading  zeros  on any of the
components.   First comes the day of the month, then the month, then the two
digits  year.   In  the  future,  a  four  digit  year  format  will also be
supported, but not yet.

After  <date>  may  be  comes  a single space, optional followed by a little
comment.   since  OS  39,  this  part of text will be printed by using a new
line.

The  versionstring  self  terminates by a linefeed or NULL and should not be
larger than 80 chars.

Embedding  a version string in the exact format described above will let the
C/Version  command  find the version string.  In the future, there will be a
system  call  to  enable applications, and other system tools, to obtain the
version information from files easily.

****************************************************************************

    Note  that  as  always,  specifying  incorrectly  formatted version
    strings will cause the VERSION and REVISION command line options of
    the  Version  command  not  to  work as expected.  Basically, using
    these  keywords,  will result in output like "2.1 < 2.04", which is
    not what is usually expected.

    The  incorrect  version  string  formats  are  not supported by the
    Installer.   It  will  behave  much  like  the VERSION and REVISION
    cmd-line options of the Version command.

****************************************************************************

ROM  Tags.   The  version  command  not  only  looks  for the $VER:  version
strings,  it  also  search executable files for standard ROM tags.  ROM tags
only  contain  a  version number, they have no revision or date fields.  The
recommended  approach  is  to  store  a  pointer  to a version string in the
RT_IDSTRING  field of the ROM tag.  This string should be in the same format
as the normal version string, except without the "$VER:  " prefix.

An  executable  file  containing  a  ROM  tag  with  a  properly initialized
RT_IDSTRING field does not need any other version information in it, such as
a separate $VER-style string.

Leading  Zeros.   Leading zeros are not supported as part of the version and
revision  numbers.  So "2.04" is not a valid version/revision pair as far as
the  version  command is concerned.  The reason this is so is because of the
VERSION  and  REVISION  command-line  options of the Version command.  These
allow the version and revision of a file to be checked by a script such as:

   Version asl.library VERSION 38 REVISION 4

The  above command will return 0 if asl.library is greater or equal to 38.4,
and 5 if it is not.  Specifying:

   Version asl.library VERSION 38 REVISION 04

Does  the  same  thing.   This means that from the standpoint of the Version
command,  2.04  is the same as 2.4, and thus 2.04 evaluates as being greater
than  2.1,  which  is  not the desired effect.  So, the version and revision
numbers  must not be treated as a floating-point number, but as two separate
and distinct integers.

This  brings  up the concept of user versions and internal versions.  V37 is
known  to  the  public  as  Release  2.04, and V39 is known as 3.0.  All the
version  strings  in  the  system software use version strings starting with
V39.  The recommended approach is as follows:

   o Assign your products user-space numbers of the form 2.04 and the like.

   o Assign the various components of your distribution the same version
     numbers as for your product.  For example, "2".

   o Assign each individual components of your distribution their own
     unique, monotonically increasing revision numbers.  These numbers have
     nothing to do with the user-space number of your product as a whole.

An  example is in order.  Assume a word processor called "SliceAndDiceWord",
which  is  at  version 4.03.  All the files composing the distribution would
have a version number of "4", and a file-specific revision number:

   Package number : SliceAndDiceWord 4.03
   Main executable: SADW 4.1423
   Support library: SADW.library 4.4129
   README file    : SADW.README 4.6

When  SliceAndDiceWord  5.0  comes out, all the version numbers of the files
included  with  the  distribution  get bumped to 5, and the revision numbers
start at 0 again.

- eof version.doc ----------------------------------------------------------