update glue documentation

res/attract.conf

@@ -1 +1 @@
-#
# Mega-Attract-Mode configuration file
#
# Mega-Attract-Mode is split into modules. Each module can be a
# short slideshow or a self-running demo (like a game's built-in
# 'attract mode'). Modules are run in the order listed here, one
# after the next, until interrupted by user input. The last-run
# module is tracked in the master prefs file.
#
# Format:
# key=value
#
# value must be one of
#   1 for HGR slideshow (key is a file containing a list of HGR graphics)
#   2 for DHGR slideshow (key is a file containing a list of DHGR graphics)
#   3 for self-running demo (key is an executable binary file)
#
# Blank lines and lines beginning with '#' are ignored (like this one!)
# A line beginning with '[' terminates the parsing
#

#SPY.HUNTER=3
SHORT.CONF=1
LODE.RUNNER=3
SHORT.CONF=1
BURGERTIME=3
SHORT.CONF=1
PITFALL.II=3
SHORT.CONF=1
SPARE.CHANGE=3
SHORT.CONF=1
SNEAKERS=3
SHORT.CONF=1
WAVY.NAVY=3
DHGR.CONF=2
FAVORITES.CONF=1
EFG.CONF=1
ACTIVISION.CONF=1
CD.CONF=1
BRODERBUND.CONF=1
T.CONF=1
ATARI.CONF=1
SIERRA.CONF=1
PQR.CONF=1
DATAMOST.CONF=1
MNO.CONF=1
DATASOFT.CONF=1
S.CONF=1
MICROFUN.CONF=1
AB.CONF=1
PICCADILLY.CONF=1
HIJKL.CONF=1
SIRIUS.CONF=1

[eof]
+#
# Mega-Attract-Mode configuration file
#
# Mega-Attract-Mode is split into modules. Each module can be a
# short slideshow or a self-running demo (like a game's built-in
# 'attract mode'). Modules are run in the order listed here, one
# after the next, until interrupted by user input. The last-run
# module is tracked in the master prefs file.
#
# Format:
# key=value
#
# value must be one of
#   1 for HGR slideshow (key is a file containing a list of HGR graphics)
#   2 for DHGR slideshow (key is a file containing a list of DHGR graphics)
#   3 for self-running demo (key is an executable binary file)
#
# Blank lines and lines beginning with '#' are ignored (like this one!)
# A line beginning with '[' terminates the parsing
#

SHORT.CONF=1
LODE.RUNNER=3
BURGERTIME=3
PITFALL.II=3
SPARE.CHANGE=3
SNEAKERS=3
WAVY.NAVY=3
#SPY.HUNTER=3
DHGR.CONF=2
FAVORITES.CONF=1
EFG.CONF=1
ACTIVISION.CONF=1
CD.CONF=1
BRODERBUND.CONF=1
T.CONF=1
ATARI.CONF=1
SIERRA.CONF=1
PQR.CONF=1
DATAMOST.CONF=1
MNO.CONF=1
DATASOFT.CONF=1
S.CONF=1
MICROFUN.CONF=1
AB.CONF=1
PICCADILLY.CONF=1
HIJKL.CONF=1
SIRIUS.CONF=1

[eof]

src/glue.prorwts2.a

@@ -11,22 +11,23 @@
 ; A general note about paths:
 ;
 ; LoadFile, LoadDHRFile, and SaveSmallFile support files in subdirectories.
-; Paths are delimited by '/' like ProDOS. HOWEVER, you should never include a
+; Directories are delimited by '/' like ProDOS. At program startup, we get the
-; disk volume name. At program startup, we get the current directory and save
+; current directory and save it; that is the PROGRAM ROOT DIRECTORY. All
-; it; that is the PROGRAM ROOT DIRECTORY. The first '/' always points to the
+; pathnames are relative to the PROGRAM ROOT DIRECTORY. There is no concept of
-; PROGRAM ROOT DIRECTORY. All pathnames are relative to the PROGRAM ROOT
+; setting or changing the 'current' directory.
-; DIRECTORY.
 ;
 ; The PROGRAM ROOT DIRECTORY is not guaranteed to be the root directory of the
-; underlying ProDOS disk (although it can be). These functions provide no
+; underlying ProDOS disk (although it can be). But it doesn't matter, because
-; access to any directory above the PROGRAM ROOT DIRECTORY, i.e. you can't use
+; these functions provide no access to any directory above the PROGRAM ROOT
-; '..' to access the parent directory.
+; DIRECTORY. You can't use '..' to access the parent directory, and you can't
+; start a pathname with '/' to access the root directory of the underlying
+; ProDOS disk.
 ;
 ; Examples:
-; '/PREFS.CONF' points to a file named 'PREFS.CONF' in the PROGRAM ROOT
+; 'PREFS.CONF' points to a file named 'PREFS.CONF' in the PROGRAM ROOT
 ; DIRECTORY.
 ;
-; '/FX/RIPPLE' points to a file named 'RIPPLE' in a directory named 'FX' in the
+; 'FX/RIPPLE' points to a file named 'RIPPLE' in a directory named 'FX' in the
 ; PROGRAM ROOT DIRECTORY.
 
 gRootDirectory
@@ -36,9 +37,13 @@ gPrefix
 
 ;------------------------------------------------------------------------------
 ; LoadFile
-; load a file into memory all at once, using ProRWTS2
+; Load a file into memory all at once, using ProRWTS2, at the load address
+; specified by the file's ProDOS metadata. Hey, do you have a text file that
+; doesn't have a load address? This routine will happily load it at $0000, and
+; your program will likely crash as a result. So give it a load address as if
+; it were a binary file.
+;
 ; supports paths, see note
-; uses file's load address
 ;
 ; in:    stack contains 2 bytes of parameters:
 ;        +1 address of filename
@@ -68,6 +73,7 @@ LoadFile
 ; all at once, using ProRWTS2
 ; first $2000 bytes of file are loaded into auxiliary memory $2000..$3FFF
 ; second $2000 bytes of file are loaded into main memory $2000..$3FFF
+;
 ; supports paths, see note
 ;
 ; in:    stack contains 2 bytes of parameters:
@@ -103,6 +109,7 @@ LoadDHRFile
 ; Save a file into memory all at once, using ProRWTS2.
 ; /!\ Only first block (512 bytes) is written. Keep those files small. /!\
 ; /!\ All 512 bytes are written to disk. Clear buffer before calling. /!\
+;
 ; supports paths, see note
 ;
 ; in:    stack contains 4 bytes of parameters: