remote TABs in doc/ and test/

[cc65] / doc / grc65.sgml

diff --git a/doc/grc65.sgml b/doc/grc65.sgml
index ae64cf40e22c2f91d73b4970a0922c089dc919ec..aec112f6bbbc237ab66960e34c77941978da90d8 100644 (file)
--- a/doc/grc65.sgml
+++ b/doc/grc65.sgml
@@ -1,15 +1,14 @@
 <!doctype linuxdoc system>
 <!doctype linuxdoc system>

-<article>
-
-<!-- Title information -->

 
 

+<article>

 <title>grc65 -- GEOS Resource Compiler
 <title>grc65 -- GEOS Resource Compiler

-<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
-<and><url name="Greg King" url="mailto:gngking@erols.com">
-<date>VII 2000; VI,VII 2002; 2005-8-3
+<author>
+<url url="mailto:ytm@elysium.pl" name="Maciej 'YTM/Elysium' Witkowiak">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
+

 <abstract>
 <abstract>

-This document describes a compiler that can create GEOS headers and menues for,
-and VLIR files from, cc65-compiled programs.
+This document describes a compiler that can create GEOS headers and menues for
+cc65-compiled programs.

 </abstract>
 
 <!-- Table of contents -->
 </abstract>
 
 <!-- Table of contents -->


@@ -26,51 +25,50 @@ files of an app.), dialog definitions, etc.  Without an application's header,
 GEOS is unable to load and start it.
 
 Currently, <bf/grc65/ supports only menues and the required header definition,
 GEOS is unable to load and start it.
 
 Currently, <bf/grc65/ supports only menues and the required header definition,

-along with support for building VLIR-structured files.
-
-<bf/grc65/ generates output in three formats: C header, <bf/ca65/ source (.s),
-and, for linking VLIR, <bf/ld65/ configuration script.  That is because
-application header data must be in assembly format, while menu definitions can
-be translated easily into C.  The purpose of the C file is to include it as a
-header in only one project file.  The assembly source should be processed by
-<bf/ca65/, and linked as the first object (read about <ref name="the building
-process" id="building-seq">).  The VLIR structure currently is supported for
-only projects that are written entirely in assembly code.
+along with support for building applications with VLIR-structured overlays.

 
 

-<bf/grc65/ can be used also as a handy VLIR linker -- used to build
-VLIR-structured <tt/.cvt/ files out of prepared binary chains.
+<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
+That is because the application header data must be in assembly format, while
+the menu definitions can be translated easily into C.  The purpose of the C
+file is to include it as a header in only one project file.  The assembly source
+should be processed by <bf/ca65/ and linked to the application (read about
+<ref name="the building process" id="building-seq">).

 
 
 
 <sect>Usage
 
 
 
 <sect>Usage

-<p>grc65 accepts the following options:<tscreen><verb>
--f         force the writing of the output files
--o name    name the .c output file
--s name    name the .s output file
--l name    name the ld65 output file
--h         show this help
-</verb></tscreen>
-When used as a VLIR linker, the correct syntax is:<tscreen><verb>
- grc65 -vlir output.cvt header.bin vlir0.bin vlir1.bin ...
+<p>grc65 accepts the following options:
+
+<tscreen><verb>
+---------------------------------------------------------------------------
+Usage: grc65 [options] file
+Short options:
+  -V                    Print the version number
+  -h                    Help (this text)
+  -o name               Name the C output file
+  -s name               Name the asm output file
+  -t sys                Set the target system
+
+Long options:
+  --help                Help (this text)
+  --target sys          Set the target system
+  --version             Print the version number
+---------------------------------------------------------------------------

 </verb></tscreen>
 Default output names are made from input names with extensions replaced by
 </verb></tscreen>
 Default output names are made from input names with extensions replaced by

-<tt/.h/ and <tt/.s/.  <bf/grc65/ will not overwrite existing files unless forced
-to do so.  That is done to avoid situations where you have <tt/test.c/ and
-<tt/test.grc/ files.  Both would put their output into <tt/test.s/.  For that
-reason, you should name your resource-files differently than sources, e.g.,
-<tt/resource.grc/ or <tt/apphead.grc/.
+<tt/.h/ and <tt/.s/.

 
 
 
 <sect>Resource file format
 <p>A resource file has the name extension <tt/.grc/.  That is not required, but
 it will make for an easier recognition of the file's purpose.  Also, <bf/cl65/
 
 
 
 <sect>Resource file format
 <p>A resource file has the name extension <tt/.grc/.  That is not required, but
 it will make for an easier recognition of the file's purpose.  Also, <bf/cl65/

-recognizes those files.  <bf/grc65/'s parser is very weak, at the moment; so,
+recognizes those files.  <bf/grc65/'s parser is very weak at the moment; so,

 read the comments carefully, and write resources exactly as they are written
 read the comments carefully, and write resources exactly as they are written

-here.  Look out for CAPS. and small letters.  Everything after a '<tt/;/',
-until the end of the line, is considered as a comment, and ignored.  See the
+here.  Look out for CAPS and small letters.  Everything after a '<tt/;/'
+until the end of the line is considered as a comment and ignored.  See the

 included <ref name="commented example .grc file" id="example-grc"> for a
 included <ref name="commented example .grc file" id="example-grc"> for a

-better view of the problem.
+better view of the situation.

 
 
 <sect1>Menu definition
 
 
 <sect1>Menu definition


@@ -80,7 +78,7 @@ MENU menuName leftx,topy <ORIENTATION> {
     ...
     "item name x" <MENU_TYPE> pointer
 }</verb></tscreen>
     ...
     "item name x" <MENU_TYPE> pointer
 }</verb></tscreen>

-The definition starts with the keyword <tt/MENU/, then goes the menu's name,
+The definition starts with the keyword <tt/MENU/, then comes the menu's name,

 which will be represented in C as <tt/const void/.  Then are the co-ordinates
 of the top left corner of the menu box.  The position of the bottom right
 corner is estimated, based on the length of item names and the menu's
 which will be represented in C as <tt/const void/.  Then are the co-ordinates
 of the top left corner of the menu box.  The position of the bottom right
 corner is estimated, based on the length of item names and the menu's


@@ -92,7 +90,7 @@ be in quotes.  Next is a menu-type bit.  It can be <tt/MENU_ACTION/ or
 <tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit
 (see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of
 them).  You can use C logical operators in expressions, but you have to do it
 <tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit
 (see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of
 them).  You can use C logical operators in expressions, but you have to do it

-without spaces.  So, a dynamically created submenu will be something like:
+without spaces.  So a dynamically created submenu will be something like:

 <tscreen><verb>
 "dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
 The last part of the item definition is a pointer which can be any name that is
 <tscreen><verb>
 "dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
 The last part of the item definition is a pointer which can be any name that is


@@ -100,7 +98,7 @@ present in the C source code that includes the generated header.  It can point
 to a function or to another menu definition.
 
 If you are doing sub(sub)menu definitions, remember to place the lowest level
 to a function or to another menu definition.
 
 If you are doing sub(sub)menu definitions, remember to place the lowest level

-definition first, and the top-level menu as the last one.  That way, the C
+definition first, and the top-level menu as the last one.  That way the C

 compiler won't complain about unknown names.
 
 
 compiler won't complain about unknown names.
 
 


@@ -113,19 +111,18 @@ HEADER <GEOS_TYPE> "dosname" "classname" "version" {
     dostype   SEQ
     mode      any
     structure SEQ
     dostype   SEQ
     mode      any
     structure SEQ

+    icon      "sprite.raw"

 }</verb></tscreen>
 The header definition describes the GEOS header sector which is unique to
 }</verb></tscreen>
 The header definition describes the GEOS header sector which is unique to

-each file.  Currently, there's no way to change the default <bf/grc65/ icon
-(an empty frame).  It will be possible in the next version.  The definition
-starts with the keyword <tt/HEADER/, then goes the GEOS file-type.  You can use
-only <tt/APPLICATION/ here at the moment.  Then, there are (each one in quotes)
-the DOS file-name (up to 16 characters), the GEOS Class name (up to 12
-characters), and the version info (up to 4 characters).  The version should be
-written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the major, and <em/y/ is
-the minor, version number.  Those fields, along with both braces, are required.
-The lines between braces are optional, and will be replaced by default and
-current values.  The keyword <tt/author/ and its value in quotes name the
-programmer, and can be up to 63 bytes long.  <tt/info/ (in the same format) can
+each file.  The definition starts with the keyword <tt/HEADER/, then goes the
+GEOS file-type.  You can use only <tt/APPLICATION/ here at the moment.  Then,
+there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS
+Class name (up to 12 characters), and the version info (up to 4 characters).
+The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the
+major, and <em/y/ is the minor, version number.  Those fields, along with both
+braces, are required.  The lines between braces are optional, and will be replaced
+by default and current values.  The keyword <tt/author/ and its value in quotes name
+the programmer, and can be up to 63 bytes long.  <tt/info/ (in the same format) can

 have up to 95 characters.  If the <tt/date/ field is omitted, then the time of
 that compilation will be placed into the header.  Note that, if you do specify
 the date, you have to write all 5 numbers.  The <tt/dostype/ can be <tt/SEQ/,
 have up to 95 characters.  If the <tt/date/ field is omitted, then the time of
 that compilation will be placed into the header.  Note that, if you do specify
 the date, you have to write all 5 numbers.  The <tt/dostype/ can be <tt/SEQ/,


@@ -136,37 +133,37 @@ it describes system requirements.  <tt/any/ will work on both 64-GEOS and
 40-column mode only.  <tt/80only/ will work on only 128-GEOS in 80-column mode,
 and <tt/c64only/ will work on only 64-GEOS.  The default value for
 <tt/structure/ is <tt/SEQ/ (sequential).  You can put <tt/VLIR/ there, too; but
 40-column mode only.  <tt/80only/ will work on only 128-GEOS in 80-column mode,
 and <tt/c64only/ will work on only 64-GEOS.  The default value for
 <tt/structure/ is <tt/SEQ/ (sequential).  You can put <tt/VLIR/ there, too; but

-then, you also have to put in a third type of resource -- a VLIR-table
-description.
+then, you also have to put in a third type of resource -- a memory definition.
+The value of <tt/icon/ is a quoted file-name.  The first 63 bytes of this file
+are expected to represent a standard monochrome VIC sprite.  The file gets accessed
+when the generated assembly source is being processed by <bf/ca65/.  Examples for
+programs generating such files are <em/Sprite Painter/, <em/SpritePad/ and the
+<url name="sp65 sprite and bitmap utility" url="sp65.html">.  The default <tt/icon/
+is an empty frame internally represented in the generated assembly file.

 
 
 
 

-<sect1>VLIR table description
+<sect1>Memory definition

 <p><tscreen><verb>
 <p><tscreen><verb>

-VLIR headname address {
-    vlir0
-    blank
-    vlir2
-    blank
-    vlir4
+MEMORY {
+    stacksize   0x0800
+    overlaysize 0x2000
+    overlaynums 0 1 2 4 5

 }</verb></tscreen>
 }</verb></tscreen>

-The first element is the keyword <tt/VLIR/, then goes the name for the header
-binary file (read below), and the base address for all VLIR chains that are
-different from 0.  It can be either decimal (e.g., <tt/4096/) or hexadecimal
-with a <tt/0x/ prefix (e.g., <tt/0x1000/).  Then, between braces are the names
-of VLIR chain binaries or the keyword <tt/blank/ which denotes empty chains.
-In the example, chains #1 and #3 are missing.  The names between braces are
-the names of binaries that contain code for each VLIR part.  They matter only
-for the generated <bf/ld65/ configuration file, and will be the names of the
-resulting binary files after linking.  Each one will contain one VLIR chain;
-and, they will have to be put together, in the correct order, into a VLIR
-<tt/.cvt/ file, by <bf/grc65/ in its VLIR linker mode.
-
-The <tt/headname/ will be the name for the binary file which will contain only
-a GEOS <tt/.cvt/ header made out of compiling the <tt/.s/ header file that also
-was generated by <bf/grc65/.  At the end of the resulting <bf/ld65/ config. file
-(<tt/.cfg/), in comments, there will be information about what commands are
-required for putting the stuff together.  Read <ref name="this description"
-id="building-vlir"> for details.
+The memory definition is unique to each file and describes several attributes related
+to the memory layout.  It consists of the keyword <tt/MEMORY/ followed by braces which
+contain optional lines.  The value of <tt/stacksize/ can be either decimal (e.g.
+<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/).  The default value
+of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be
+either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied
+background screen buffer while the latter means that the program uses the memory of the
+background screen buffer for own purposes.  The default value of <tt/yes/ comes from the
+linker configuration file.  If the <tt/structure/ in the header definition is set to the
+value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the
+VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number
+0.  It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g.
+<tt/0x1000/).  <tt/overlaynums/ defines the VLIR record numbers used by the application.
+Skipped numbers denote empty records.  In the example, record number 3 is missing.  Read
+<ref name="this description" id="building-vlir"> for details.

 
 
 
 
 
 


@@ -178,9 +175,9 @@ general.
 
 GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
 the GEOS world.  It means that each file built with the cc65 package has to be
 
 GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
 the GEOS world.  It means that each file built with the cc65 package has to be

-deconverted, in GEOS, before it can be run.  You can read a step-by-step
-description of that in the GEOS section of the <url name="cc65 Compiler Intro"
-url="intro.html">.
+deconverted in GEOS, before it can be run.  You can read a step-by-step
+description of that in the <url name="GEOS section of the cc65 Compiler Intro"
+url="intro.html#ss6.5">.

 
 Each project consists of four parts, two are provided by cc65.  Those parts
 are:<enum>
 
 Each project consists of four parts, two are provided by cc65.  Those parts
 are:<enum>


@@ -189,132 +186,138 @@ are:<enum>
 <item>application objects
 <item>system library
 </enum>
 <item>application objects
 <item>system library
 </enum>

-<bf/2./ and <bf/4./ are with cc65; you have to write the application,
-yourself. ;-)
+<bf/2./ and <bf/4./ come with cc65; however you have to write the application
+yourself ;-)

 
 The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
 
 The application header is defined in the <tt/HEADER/ section of the <tt/.grc/

-file, and processed into an assembly <tt/.s/ file.  You must assemble it, with
+file and is processed into an assembly <tt/.s/ file.  You must assemble it, with

 <bf/ca65/, into the object <tt/.o/ format.
 
 <bf/ca65/, into the object <tt/.o/ format.
 

-
-<sect1>Building a GEOS application without cl65
-<p>Assume that there are three input files:  &dquot;<tt/test.c/&dquot; (a C
+Assume that there are three input files:  &dquot;<tt/test.c/&dquot; (a C

 source), &dquot;<tt/test.h/&dquot; (a header file), and
 source), &dquot;<tt/test.h/&dquot; (a header file), and

-&dquot;<tt/resource.grc/&dquot; (with menu and header definitions).  Note the
-fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;,
+&dquot;<tt/testres.grc/&dquot; (with menu and header definitions).  Note the
+fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;

 because you will have to be very careful with names (<bf/grc65/ will make
 &dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of
 because you will have to be very careful with names (<bf/grc65/ will make
 &dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of

-&dquot;<tt/test.grc/&dquot;, by default; and, you don't want that because
+&dquot;<tt/test.grc/&dquot; by default; and you don't want that because

 &dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
 &dquot;<tt/test.h/&dquot; is something completely different)!
 
 <bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
 <tscreen><verb>
 #include <geos.h>
 &dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
 &dquot;<tt/test.h/&dquot; is something completely different)!
 
 <bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
 <tscreen><verb>
 #include <geos.h>

-#include "resource.h"
+#include "testres.h"

 </verb></tscreen>
 There are no other includes.
 
 </verb></tscreen>
 There are no other includes.
 

+
+<sect1>Building the GEOS application using cl65
+<p>This is a simple one step process:
+<tscreen><verb>
+cl65 -t geos-cbm -O -o test.cvt testres.grc test.c
+</verb></tscreen>
+Always place the <tt/.grc/ file as first input file on the command-line in order
+to make sure that the generated <tt/.h/ file is available when it is needed for
+inclusion by a <tt/.c/ file.
+
+
+<sect1>Building the GEOS application without cl65

 <sect2>First step -- compiling the resources
 <sect2>First step -- compiling the resources

-<p><verb>
-$ grc65 resource.grc
-</verb>
-will produce two output files:  &dquot;<tt/resource.h/&dquot; and
-&dquot;<tt/resource.s/&dquot;.
+<p>
+<tscreen><verb>
+grc65 -t geos-cbm testres.grc
+</verb></tscreen>
+will produce two output files:  &dquot;<tt/testres.h/&dquot; and
+&dquot;<tt/testres.s/&dquot;.

 
 

-Note that &dquot;<tt/resource.h/&dquot; is included at the top of
+Note that &dquot;<tt/testres.h/&dquot; is included at the top of

 &dquot;<tt/test.c/&dquot;.  So, resource compiling <em/must be/ the first step.
 
 <sect2>Second step -- assembling the application header
 &dquot;<tt/test.c/&dquot;.  So, resource compiling <em/must be/ the first step.
 
 <sect2>Second step -- assembling the application header

-<p><verb>
-$ ca65 -t geos resource.s
-</verb>
-And, voil&aacute; -- &dquot;<tt/resource.o/&dquot; is ready.
+<p>
+<tscreen><verb>
+ca65 -t geos-cbm testres.s
+</verb></tscreen>
+And, voil&aacute; -- &dquot;<tt/testres.o/&dquot; is ready.

 
 <sect2>Third step -- compiling the code
 
 <sect2>Third step -- compiling the code

-<p><verb>
-$ cc65 -t geos -O test.c
-$ ca65 -t geos test.s
-</verb>
+<p>
+<tscreen><verb>
+cc65 -t geos-cbm -O test.c
+ca65 -t geos-cbm test.s
+</verb></tscreen>

 That way, you have a &dquot;<tt/test.o/&dquot; object file which
 contains all of the executable code.
 
 That way, you have a &dquot;<tt/test.o/&dquot; object file which
 contains all of the executable code.
 

-<sect2>Fourth and last step -- linking it together
-<p><verb>
-$ ld65 -o test.cvt -t geos resource.o geos.o test.o geos.lib
-</verb>
-&dquot;<tt/resource.o/&dquot; comes first because it contains the
-header.  The next one is &dquot;<tt/geos.o/&dquot;, a required starter-code
-file; then, the actual application code in &dquot;<tt/test.o/&dquot;, and the
-last is the GEOS system library.
+<sect2>Fourth and last step -- linking the application
+<p>
+<tscreen><verb>
+ld65 -t geos-cbm -o test.cvt testres.o test.o geos-cbm.lib
+</verb></tscreen>
+The last file is the GEOS system library.

 
 The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
 contained in the well-known GEOS <em/Convert/ format.  Note that its name
 
 The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
 contained in the well-known GEOS <em/Convert/ format.  Note that its name

-(<tt/test/) isn't important; the real name, after deconverting, is the DOS name
+(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name

 that was given in the header definition.
 
 that was given in the header definition.
 

-At each step, a <tt/-t geos/ was present on the command-line.  That switch is
-required for the correct process of GEOS sequential app. building.
+At each step, a <tt/-t geos-cbm/ was present on the command-line.  That switch is
+required for the correct process of GEOS sequential application building.

 
 
 
 
 
 

-<sect>Building a GEOS VLIR application<label id="building-vlir">
-<p>Currently, you can build VLIR applications only if your code is written in
-assembly -- no C code allowed.
+<sect>Building a GEOS VLIR overlay application<label id="building-vlir">
+<p>Large GEOS applications typically don't fit in one piece in their designated
+memory area.  They are therefore split into overlays which are loaded into memory
+on demand.  The individual overlays are stored as records of a VLIR (Variable
+Length Index Record) file.  When GEOS starts a VLIR overlay appliation it loads
+record number 0 which is supposed to contain the main program.  The record numbers
+starting with 1 are to be used for the actual overlays.

 
 

-In your sources, only the command <tt/.segment &dquot;/<em/NAME/<tt/&dquot;/
-will decide which code/data goes where.  File-names don't matter.  Segments
-<tt/CODE/, <tt/RODATA/, <tt/DATA/, and <tt/BSS/ go into VLIR part #0.  Segment
-<tt/VLIR1/ goes into VLIR part #1, <tt/VLIR2/ goes into VLIR part #2, and so
-on.
+In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting
+of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/".

 
 

-The GEOS resource file's contents are similar to <ref
-name="the sequential-file example" id="building-seq">, but there also is a
-<tt/VLIR/ section and a <tt/structure VLIR/ tag.  Here is that part:<tscreen>
-<verb>
-VLIR vlir-head.bin 0x3000 {
-  vlir-0.bin    ; CODE, RODATA, DATA, BSS
-  vlir-1.bin    ; VLIR1
-  vlir-2.bin    ; VLIR2
-}</verb></tscreen>
-(Source files are only <tt/.s/.)
-
-OK, we have &dquot;<tt/cvthead.grc/&dquot;, so let's allow <bf/grc65/ to compile
-it:<verb>
-$ grc65 cvthead.grc
-</verb>
-Now, there are two new files:  &dquot;<tt/cvthead.cfg/&dquot; and
-&dquot;<tt/cvthead.s/&dquot; -- the first one is a config. file for <bf/ld65/,
-and the second one contains the GEOS <tt/.cvt/ header.  It can be assembled:
-<verb>
-$ ca65 -t geos cvthead.s
-</verb>
-Now, we have &dquot;<tt/cvthead.o/&dquot;.  The rest of the assembly
-sources can be assembled:<verb>
-$ ca65 -t geos vlir0.s
-$ ca65 -t geos vlir1.s
-$ ca65 -t geos vlir2.s
-</verb>
-Note that the file-names here, although similar to those from the
-<tt/VLIR/ section of the <tt/.grc/ file, are not significant.  The only thing
-that matters is which code will go into which segment.
-
-Now, we can generate binaries.  This time, the order of the arguments on the
-command-line is not important.<verb>
-$ ld65 -C cvthead.cfg vlir1.o cvthead.o vlir0.o vlir2.o
-</verb>
-As defined in the <tt/.grc/ file, we now have the binary parts of the
-VLIR file:  &dquot;<tt/vlir-head.bin/&dquot;, &dquot;<tt/vlir-0.bin/&dquot;,
-&dquot;<tt/vlir-1.bin/&dquot;, and &dquot;<tt/vlir-2.bin/&dquot;.
-
-The last step is to put them together in the right order -- the order of the
-arguments <em/is important/ this time!  As suggested in the comments at the end
-of &dquot;<tt/cvthead.cfg/&dquot;, we do:<verb>
-$ grc65 -vlir output.cvt vlir-head.bin vlir-0.bin vlir-1.bin vlir-2.bin
-</verb>
-That is the end.  The file &dquot;<tt/output.cvt/&dquot; can be
-deconverted under GEOS.  Note that <tt/-C cvthead.cfg/ was used on the
-<bf/ld65/ command-line instead of the switch <tt/-t geos/.
+
+<sect1>Building the GEOS overlay application using cl65
+<p>This is a simple one step process:
+<tscreen><verb>
+cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c
+</verb></tscreen>
+Always place the <tt/.grc/ file as first input file on the command-line in order
+to make sure that the generated <tt/.h/ file is available when it is needed for
+inclusion by a <tt/.c/ file.
+
+You will almost certainly want to generate a map file that shows (beside a lot of
+other infos) how large your individual overlays are.  This info is necessary to tune
+the distribution of code into the overlays and to optimize the memory area reserved
+for the overlays.
+
+
+<sect1>Building the GEOS overlay application without cl65
+<sect2>First step -- compiling the overlay resources
+<p>
+<tscreen><verb>
+grc65 -t geos-cbm overlay-demores.grc
+</verb></tscreen>
+
+<sect2>Second step -- assembling the overlay application header
+<p>
+<tscreen><verb>
+ca65 -t geos-cbm overlay-demores.s
+</verb></tscreen>
+
+<sect2>Third step -- compiling the overlay code
+<p>
+<tscreen><verb>
+cc65 -t geos-cbm -O overlay-demo.c
+ca65 -t geos-cbm overlay-demo.s
+</verb></tscreen>
+
+<sect2>Fourth and last step -- linking the overlay application
+<p>
+<tscreen><verb>
+ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos-cbm.lib
+</verb></tscreen>

 
 
 
 
 
 


@@ -339,7 +342,7 @@ for addresses.
 
 
 
 
 
 

-<appendix>
+<!-- <appendix> -->

 <sect>Appendix A -- example.grc<label id="example-grc">
 <p><tscreen><verb>
 ; Note that MENU can define both menues and submenues.
 <sect>Appendix A -- example.grc<label id="example-grc">
 <p><tscreen><verb>
 ; Note that MENU can define both menues and submenues.


@@ -378,11 +381,11 @@ HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
 ; file named MyFirstApp with the Class-string "Class Name V1.0"
 {
 ; Not all fields are required, default and current values will be used.
 ; file named MyFirstApp with the Class-string "Class Name V1.0"
 {
 ; Not all fields are required, default and current values will be used.

-    author "Maciej Witkowiak"  ; always in quotes!
-    info "Information text"    ; always in quotes!
-;    date yy mm dd hh ss       ; always 5 fields!
-;    dostype seq               ; can be:  PRG, SEQ, USR (only all UPPER- or lower-case)
-;    structure seq             ; can be:  SEQ, VLIR (only UPPER- or lower-case)
-    mode c64only               ; can be:  any, 40only, 80only, c64only
+    author "Maciej Witkowiak"   ; always in quotes!
+    info "Information text"     ; always in quotes!
+;    date yy mm dd hh ss        ; always 5 fields!
+;    dostype seq                ; can be:  PRG, SEQ, USR (only all UPPER- or lower-case)
+;    structure seq              ; can be:  SEQ, VLIR (only UPPER- or lower-case)
+    mode c64only                ; can be:  any, 40only, 80only, c64only

 }</verb></tscreen>
 </article>
 }</verb></tscreen>
 </article>