@DATABASE "RevUp Documentation"
@AUTHOR   "Boris Folgmann"
@(C)      "PROXITY SOFTWORKS"

##
## $Id: RevUp.guide,v 1.2 1994/09/04 21:06:07 folgmann Exp folgmann $
##

@$VER: RevUp.guide 1.2 (4.9.94)

###########################################################################
@NODE MAIN "RevUp"

                   @{b}RevUp@{ub} - Amiga Revision Update System

	           Freeware © 1994 by @{"PROXITY SOFTWORKS" LINK "PSI/PROXITY SOFTWORKS"}

	              Development by @{"Boris Folgmann" LINK "PSI/Boris Folgmann"}


	RevUp 1.2 (4.9.94)	User Manual

	@{" Copyrights          " LINK COPYRIGHTS}	Copyright information.
	@{" Disclaimer          " LINK PSI/DISCLAIMER}	Legal stuff.

	@{" Description         " LINK DESCRIPTION}	What is it for?

	@{" System requirements " LINK REQUIREMENTS}	What is needed?
	@{" Contents            " LINK CONTENTS}	Archive contents.
	@{" Installation        " LINK INSTALLATION}	How to install.

	@{" Usage               " LINK USAGE}	How is it used?
	@{" History             " LINK HISTORY}	What's new?

	@{" Support             " LINK PSI/SUPPORT}	How to contact us.
	@{" Update              " LINK PSI/UPDATE}	Where to get new releases.
	@{" Credits             " LINK PSI/CREDITS}	Thanks to some persons.
   
@ENDNODE

###########################################################################
@NODE COPYRIGHTS

                                COPYRIGHTS


                   Unless otherwise noted, all files are
                   Freeware © 1994 by @{"PROXITY SOFTWORKS" LINK "PSI/PROXITY SOFTWORKS"}
                           All Rights Reserved.

                     MagicWB © 1994 Martin Huttenloher

             Kickstart and Workbench are Copyright © 1985-1994
                           Commodore-Amiga, Inc.

@ENDNODE

###########################################################################
@NODE DESCRIPTION

                                DESCRIPTION

 o RevUp  generates  and  maintains  include and header files with revision
   information.

 o RevUp  is compatible to the CBM developer tool BumpRev, but offers a lot
   of new features.

 o Multiple dependency files are supported.

 o Beta count management for beta versions included.

@ENDNODE

###########################################################################
@NODE REQUIREMENTS

                            SYSTEM REQUIREMENTS


@{"Kickstart" LINK COPYRIGHTS} 2.04
@{"Workbench" LINK COPYRIGHTS} 2.0

@{"Workbench" LINK COPYRIGHTS} 2.1 for localized DOS error messages.

@ENDNODE

###########################################################################
@NODE CONTENTS

                                 CONTENTS


This software package consists of the following files:

@{FG HIGHLIGHT}RevUp@{FG TEXT}

	The executable shell command.

@{FG HIGHLIGHT}RevUp.guide@{FG TEXT}

	This AmigaGuide document for Multiview.

@{FG HIGHLIGHT}PSI@{FG TEXT}

	@{"Proxity Softworks" LINK "PSI/PROXITY SOFTWORKS"} information text.


All icons are part of @{"MagicWB" LINK COPYRIGHTS} and included with permission of the author.

@ENDNODE

###########################################################################
@NODE INSTALLATION

                               INSTALLATION


Simply copy RevUp to a directory in your path.

For example type:

	@{fg highlight}copy RevUp to C:@{fg text}

@ENDNODE

###########################################################################
@NODE USAGE

                                   USAGE


Usage:	RevUp <version> <projectname> {<dependency>} [REV <revision>]
				      [BETA] [NOC] [NOASM] [EXTRA] [TINY]

Template:

  @{" VERSION/N      " LINK VERSION} Version number.
  @{" PROJECTNAME/A  " LINK PROJECTNAME} Name of the project.
  @{" DEPENDENCIES/M " LINK DEPENDENCIES} Files to check the date.
  @{" REV/K/N        " LINK REVISION} Explicit revision number.
  @{" BETA/S         " LINK BETA} Generate beta information.
  @{" NOC/S          " LINK NOC} Don't generate C Headerfile.
  @{" NOASM/S        " LINK NOASM} Don't generate ASM Includefile.
  @{" EXTRA/S        " LINK EXTRA} Generate extra information.
  @{" TINY/S         " LINK TINY} Don't print credits.


RevUp  uses  a  revision  storage  file which contains the current revision
number.  Therefore  it's possible to increment the revision number on every
invocation of the program.

Look  at the example smakefile for SuperTool to get an impression how RevUp
is used.

@{fg highlight}SuperTool: SuperTool.c SCOPTIONS SMAKEFILE
	@RevUp 1 SuperTool SuperTool.c EXTRA BETA
	sc SuperTool.c@

RELEASE:
	@RevUp 1 SuperTool SuperTool.c EXTRA
	sc SuperTool.c NODEBUG OPT@{fg text}

Now have a look at the generated files @{"SuperTool_rev.h" LINK HEADERBETA} and @{"SuperTool_rev.i" LINK INCLUDEBETA}.

Call @{FG HIGHLIGHT}smake RELEASE @{FG TEXT} to get the files without beta information.
@{"SuperTool_rev.h" LINK HEADER}, @{"SuperTool_rev.i" LINK INCLUDE}.

Note that all definitions from TIME to HOST are only added if @{"EXTRA" LINK EXTRA} is
specified.

BASENAME  is the project name in capital letters, e.g. 'MYTOOL'. Useful for
ARexx  port or public screen naming. Note that language-sensitive functions
are used to convert to upper case.

USER and HOST are imported from the environment variables USERNAME and
HOSTNAME which are mentioned in the Amiga User Interface Style Guide.

To enable Commodore's VERSION command to display version information about
your program you have to put VERSTAG in your code.

Example for SuperTool:

@{FG HIGHLIGHT}#include	"SuperTool_rev.h"

const static char VersTag[] = VERSTAG;
@{FG TEXT}

@ENDNODE

###########################################################################
@NODE HEADER
/* C Headerfile generated by RevUp 1.2 */

#define VERSION		1
#define REVISION	1
#define DATE	"17.8.94"
#define VERS	"SuperTool 1.1"
#define VSTRING	"SuperTool 1.1 (17.8.94)\\r\\n"
#define VERSTAG	"\\0$VER: SuperTool 1.1 (17.8.94)"
#define TIME	"18:34:23"
#define PRGNAME	"SuperTool"
#define VSTR	"SuperTool 1.1 (17.8.94)"
#define BASENAME	"SUPERTOOL"
#define USER	"Boris Folgmann"
#define HOST	"prox"

@ENDNODE

###########################################################################
@NODE INCLUDE
;* ASM Includefile generated by RevUp 1.2 *

VERSION		EQU	1
REVISION	EQU	1
DATE	MACRO
		dc.b	'17.8.94'
	ENDM
VERS	MACRO
		dc.b	'SuperTool 1.1'
	ENDM
VSTRING	MACRO
		dc.b	'SuperTool 1.1 (17.8.94)',13,10,0
	ENDM
VERSTAG	MACRO
		dc.b	0,'$VER: SuperTool 1.1 (17.8.94)',0
	ENDM
TIME	MACRO
		dc.b	'18:34:23'
	ENDM
PRGNAME	MACRO
		dc.b	'SuperTool'
	ENDM
VSTR	MACRO
		dc.b	'SuperTool 1.1 (17.8.94)'
	ENDM
BASENAME	MACRO
		dc.b	'SUPERTOOL'
	ENDM
USER	MACRO
		dc.b	'Boris Folgmann'
	ENDM
HOST	MACRO
		dc.b	'prox'
	ENDM

@ENDNODE

###########################################################################
@NODE HEADERBETA
/* C Headerfile generated by RevUp 1.2 */

#define VERSION		1
#define REVISION	2
#define BETA		1
#define DATE	"3.9.94"
#define VERS	"SuperTool 1.2 BETA 1"
#define VSTRING	"SuperTool 1.2 BETA 1 (3.9.94)\\r\\n"
#define VERSTAG	"\\0$VER: SuperTool 1.2 BETA 1 (3.9.94)"
#define TIME	"21:56:02"
#define PRGNAME	"SuperTool"
#define VSTR	"SuperTool 1.2  BETA 1(3.9.94)"
#define BASENAME	"SUPERTOOL"
#define USER	"Boris Folgmann"
#define HOST	"prox"

@ENDNODE

###########################################################################
@NODE INCLUDEBETA
;* ASM Includefile generated by RevUp 1.2 *

VERSION		EQU	1
REVISION	EQU	2
BETA		EQU	1
DATE	MACRO
		dc.b	'3.9.94'
	ENDM
VERS	MACRO
		dc.b	'SuperTool 1.2 BETA 1'
	ENDM
VSTRING	MACRO
		dc.b	'SuperTool 1.2 BETA 1 (3.9.94)',13,10,0
	ENDM
VERSTAG	MACRO
		dc.b	0,'$VER: SuperTool 1.2 BETA 1 (3.9.94)',0
	ENDM
TIME	MACRO
		dc.b	'21:56:02'
	ENDM
PRGNAME	MACRO
		dc.b	'SuperTool'
	ENDM
VSTR	MACRO
		dc.b	'SuperTool 1.2 BETA 1(3.9.94)'
	ENDM
BASENAME	MACRO
		dc.b	'SUPERTOOL'
	ENDM
USER	MACRO
		dc.b	'Boris Folgmann'
	ENDM
HOST	MACRO
		dc.b	'prox'
	ENDM

@ENDNODE

###########################################################################
@NODE VERSION

                                 VERSION/N


This  needed  argument  specifies the version number (the number before the
dot).

Use @{fg highlight}0@{fg text} for beta versions and @{fg highlight}1@{fg text} for the first release version.

You  should  increase  the  version  number  only  when  major  changes and
improvements are done.

@ENDNODE
@NODE PROJECTNAME

                               PROJECTNAME/A


This  needed  argument  should be the name of your project. It will be used
for  the naming of the RevUp revision storage file ('projectname_rev.rev'),
the  C  header  file  ('projectname_rev.h')  and  the assembly include file
('projectname_rev.i').

Is   is   also   used  for  building  the  version  strings  found  in  the
header/include files, so keep care of the right capitalisation.

@ENDNODE

@NODE DEPENDENCIES

                              DEPENDENCIES/M


RevUp checks the dates of the dependency files against the revision storage
file. Therefore it's possible to update the revision number only if certain
parts of the project are changed.

@ENDNODE

@NODE REVISION

                                  REV/K/N


Explicitly  set  the  revision to a specific value. Normally RevUp gets the
old revision from projectname_rev.rev and increments it by 1.

@ENDNODE

@NODE BETA

                                  BETA/S


Enables  the  beta  version  count.  If  BETA  is  given the first time the
revision  is  incremented  as  on  a  normal call. Additonally a beta count
storage file is created. The beta count starts at 1 as the revision does.

Assume  that  version  is  1  and  revision  is  1, with BETA specified the
header/include file will look like this:

@{"SuperTool_rev.h" LINK HEADERBETA}, @{"SuperTool_rev.i" LINK INCLUDEBETA}

On every following call with BETA, only the beta count will be incremented,
the revision will stay at 2.

If  the  beta stage of the program is finished call RevUp without BETA. The
beta count storage file will be deleted and VERS will now look like this:

@{FG HIGHLIGHT}#define	VERS "SuperTool 1.2"@{FG TEXT}

That means all beta information removed.


                                   NOTE

You  should  not  publicly  distribute  versions of your program containg a
VERSTAG  with  beta information because this string does not follow the CBM
version  string  standard.  Although  all your beta testers will be able to
correctly  display the version information with the current version command
(40.1).


                                   HINT

Using the beta switch avoids to increment the revision on each compilation,
therefore   giving  shorter  revision  numbers  for  your  programs  public
releases.

BETA is only defined in the header file if specified in the commandline. So
you could easyly include additional debugging code like that:

@{FG HIGHLIGHT}#ifdef BETA
	kprintf("Variable x contains: %ld", x);
#endif@{FG TEXT}

@ENDNODE

@NODE NOC

                                   NOC/S


Prevents  RevUp  from  generating  a  header file for C language. Useful if
version information is only used in assembly source codes.

@ENDNODE

@NODE NOASM

                                  NOASM/S


Prevents  RevUp  from generating an include file for 68k assembly language.
Useful if version information is only used in C source codes.

@ENDNODE
@NODE EXTRA

                                  EXTRA/S


Adds  some  extra  information  to  the  header/include files which are not
generated by CBMs BumpRev!

@ENDNODE

@NODE TINY

                                  TINY/S


Supresses printing of the copyright message, therefore giving less output.

@ENDNODE

###########################################################################
@NODE HISTORY

                                  HISTORY


1.1 (18.8.94) Release 

First public release.

1.2 (4.9.94) Release

NEW: @{"BETA" LINK BETA} switch enables beta version count.

@ENDNODE