
HVSC UPDATE SCRIPT
STRUCTURE DESCRIPTION

Version: 1.3 <the.mage (sid) gmx.net>, <LaLa (sid) C64.org>

[Ed: I guess you don't mind that I don't document the syntax using
anything as formal as (E)BNF. The complete thing is pretty complex
and there are some inconsistencies as well which have not been
removed since the creation of version 2.5 of the Update Tool.]


STRUCTURE OVERVIEW

Lines starting with a ``#'' or ``;'' character as the first non-space
character are treated as comments unless they belong to a block of
parameter lines. Comment lines can be everywhere except between
successive parameter lines.

Empty or blank lines are ignored, i.e. skipped.

Leading white-space characters of a line are skipped unless the line
belongs to a block of parameter lines which are meant to be copied
into the sidtune file directly (see description of TITLE, AUTHOR,
COPYRIGHT, CREDITS keywords).

Lines containing one of the following command keywords select the
current mode the Update Tool is in:

TITLE, AUTHOR, COPYRIGHT, CREDITS, SPEED, SONGS,
DELETE, MOVE, REPLACE, MKDIR,
FIXLOAD, MUSPLAYER, PLAYSID, VIDEO, SIDCHIP,
FREEPAGES, FLAGS

Keywords are case-insensitive. To improve readability of the script,
they should be upper-case-only.

Once the mode has been selected, one or more blocks of parameter
lines may (!) follow. A block of parameter lines specifies the
action to be performed. The number of lines in each parameter
block and their meaning depends on the current mode (more below):

TITLE:     2
AUTHOR:    2
COPYRIGHT: 2
CREDITS:   4
SPEED:     2
SONGS:     2
DELETE:    2
MOVE:      2
REPLACE:   2
MUSPLAYER: 2
PLAYSID:   2
VIDEO:     2
SIDCHIP:   2
FREEPAGES: 2
INITPLAY:  2
FLAGS:     5
MKDIR:     1
FIXLOAD:   1

Repeated statement of the same command keyword in front of
successive parameter blocks is not necessary.


VERSION CHECK

The first few lines of every update script must contain these
lines which reflect the update's dependency.

# Resulting Version: 3.1
#  Previous Version: 3.0

The update tool will fetch the version numbers from these lines.
The number of white-space between the words can be arbitrary.

The HVSC version is not fetched from any update script, but from
the main HVSC documentation file /DOCUMENTS/HVSC.txt. The first
few lines of that file must contain a line which contain nothing
else than the word "release" followed by a real value. White-space
is ignored. Example:

  release 3.0


HVSC-STYLE PATH NAMES

Any path names must be relative to the HVSC root directory and must
contain the slash (/) or back-slash (\) characters as file/directory
separators. In this document, all path names are HVSC-style path
names unless explicitly stated otherwise.

Destination directories must end with a / or \ character in order to
be recognized as a directory unless they exist already. To improve
readability of the script, it is recommended that all directories
end with a / or \ character.

File names, directory names, and path names are all case-insensitive.
The HVSC Update Tool examines each directory to determine the correct
case of a full path name. This is done to be file-system independent,
archiver independent, and to allow small type errors in the script.

These name all the same file:

/Galway_Martin/Wizball.sid
/GALWAY_Martin/Wizball.SID
/galway_martin/wizball.sid

The intended case of new files and directories is specified in
form of destination path names (or the files in the update
archive). See further below.


PARAMETER BLOCKS

Parameter lines are as follows. <dir> is a place-holder for
a HVSC-style path to a directory. <file> is a place-holder for
a HVSC-style path to a file. Any other text inside < and > is
a place-holder. Note that repeated statement of command keywords
in these examples is redundant.

The TITLE, AUTHOR, COPYRIGHT commands take a destination file name
and a credit line. A credit line must not be an empty or blank line
and is limited to 32 characters.
TITLE changes first line in PSID file, AUTHOR second line,
COPYRIGHT third line. ;-)

Example:

TITLE
<file>
<first_credit_line_in_psid_file>

# This is a comment.
/20CC/Amtrak.sid
Amtrak


The CREDITS command takes a path to a file and a block of three
successive lines as argument. A credit line containing an
asterisk (*) leaves the corresponding credit line in the sidtune
file untouched.

Update #10 has a parameter block which lacks the third credit line.
Since old versions of the update tool did not detect this and hence
did not cause an error, empty credit lines either must be allowed or
the update version must be checked and Update #10 treated differently.

CREDITS
<file>
<1st_credit_line_in_psid_file>
<2nd_credit_line_in_psid_file>
<3rd_credit_line_in_psid_file>

# Real example:

/20CC/Amtrak.sid
Amtrak
Edwin van Santen
1989 20th Century Composers

# Another one. Don't change author name.
# Next blank line will be skipped.

/20CC/Amtrak.sid
Amtrak
*
1989 20th Century Composers


SPEED
<file>
<max_32-bit_hex_value>
# As documented on the SIDPLAY Home Page.
#
#
/Gray_Matt/Driller.sid
1


SONGS
<file>
<songs>,<startsong>

SONGS
/Brooke_Jason/Pi_r_Squared.sid
6,3


INITPLAY
<file>
<initAddress, 16 bit hex number>,<playAddress, 16 bit hex number>

INITPLAY
/VARIOUS/G-L/Hesford_Paul/Moon_Light_Demo_Note.sid
2000,0000


MUSPLAYER
<file>
<0 = built-in player | 1 = Compute's Sidplayer is required>

MUSPLAYER
/Hubbard_Rob/Commando.sid
0


PLAYSID
<file>
<0 = C64 compatible | 1 = PlaySID specific>

PLAYSID
/Tel_Jeroen/Hotrod.sid
1


VIDEO
<file>
<UNKNOWN | PAL | NTSC | ANY>

VIDEO
/GAMES/G-L/Into_the_Eagles_Nest_USA.sid
NTSC


SIDCHIP
<file>
<UNKNOWN | 6581 | 8580 | ANY>

SIDCHIP
/VARIOUS/A-F/Agemixer/Azmagutah_8580.sid
8580


FREEPAGES
<file>
<startpage, max 8 bits>,<pagelength, max 8 bits>

FREEPAGES
/Hubbard_Rob/Commando.sid
C0,10


FLAGS
<file>
<0 = built-in player | 1 = Compute's Sidplayer is required>
<0 = C64 compatible | 1 = PlaySID specific>
<UNKNOWN | PAL | NTSC | ANY>
<UNKNOWN | 6581 | 8580 | ANY>

# This is like the CREDITS directive: it makes it easier
# to modify multiple flags at the same time.
# A line containing an asterisk (*) leaves the corresponding
# flag in the sidtune file untouched.

FLAGS
/VARIOUS/A-F/Agemixer/Azmagutah_8580.sid
*
*
PAL
8580

FIXLOAD
<file>
# Increases load address of the C64 data inside a
# sidtune file by 2. Used to drop first two bytes
# of C64 data to get rid of a duplicate load address
# ($0FFE instead of $1000, for example).


MKDIR
<dir>
# Creates the last directory in the path. Almost obsolete
# since MOVE and REPLACE can create the last sub-dir in
# a path on the fly.

MKDIR
/VARIOUS/AMJ/Example/

MKDIR
# Causes an error if directory Blubb1 does not exist.
/VARIOUS/Zardax/Blubb1/Blubb2/


DELETE
# File must exist.
# Why, if we want to get rid of it anyway? :)
<file>

DELETE
# Only empty directories can be deleted.
<dir>


MOVE
<dir>
<dir>
#
# Non-recursive copy of directory contents, i.e. does not
# include sub-directories and their contents.
# Deletes source files.
# Creates destination directory if not available.

MOVE
<file>
<file>
#
# Gives an error if destination file already exists.
# Gives an error if destination directory does _not_ exist
# (this prevents creating unwanted dirs on the fly).
# Deletes source file when done.

MOVE
<file>
<dir>
#
# If destination directory does not exist, it will be created.
# Note that this will not create the full path, but just the
# last directory component like MKDIR.
# Deletes source file when done.


REPLACE
<dir>
<dir>
#
# Non-recursive merge of directory contents, i.e. does not
# include sub-directories and their contents.
# Creates last destination directory if not available
# (see MKDIR).
# Deletes any destination file that already exists.
# Deletes source files.

REPLACE
<file>
<file>
#
# Deletes destination file if it already exists.
# Deletes source file when done.
# Gives no error if destination file does _not_ exist.

REPLACE
<file>
<dir>
#
# Deletes any destination file that already exists.
# Deletes source file when done.
# If destination directory does not exist, it will be created.
# Note that this will not create the full path, but just the
# last directory component like MKDIR.

REPLACE
#
# Example to demonstrate case-insensitivity.
#
# The case of file names in the HVS script counts always.
# The old HVS Update Tool <= 2.4.x did not do this properly.
#
# REPLACE
# /update/DEMOS/eXaMpLe.SID
# /DEMOS/
#
# overwrites any file named ``example.sid'',
# disregarding case, and calls it ``eXaMpLe.SID'',
# disregarding the case of the actual file in the
# update archive.
#
#
# REPLACE
# /update/DEMOS/eXaMpLe.SID
# /DEMOS/Example.sid
#
# overwrites any file named ``example.sid'',
# disregarding case, and calls it ``Example.sid'',
# disregarding the case of the actual file in the
# update archive.

The precedence of file naming is this in decreasing order
of priority:

1.) Take case of destination file name (if specified).
2.) Take case of source file name (if specified).
3.) Take case of update archive file name.

And of course, the files *.hvs in the HVSC's DOCUMENTS dir serve
as good examples.

