minor corrections to drawing pixels section

src/roadmap.gmo

@@ -30,8 +30,7 @@ implement the following concepts as {coloring computers}:
 
 ### day 2 and onwards
 * remove square brackets in devices?
-* recap how to use learn-uxn for the programs there
-* check current color theme: Background/alpha, Selection, Foreground, Application
+* divide into morning and evening
 * update images if needed
 * check blend mode 0
 => https://lists.sr.ht/~rabbits/uxn/%3C692CA0D5-0200-408D-9357-BF0D8887D2BF%40noyu.me%3E Blend mode 0
@@ -42,6 +41,9 @@ implement the following concepts as {coloring computers}:
 => https://lists.sr.ht/~rabbits/uxn/%3CCAE2DaSQQMb8XVfsn2NSsXQO+-0m2t4U2GD7nYD3GBUO4GPeTxQ%40mail.gmail.com%3E Whole auto sprite flipping 
 
 * make a folder of examples 
+* whenever we mention the theme loading, link to the suggested palette.
+* replace intro to colors with a table.
+
 * include uxn5 in the web tutorial so that code can be run from there
 => https://git.sr.ht/~rabbits/uxn5 uxn5
 * format and update {uxn running}

src/tutorial_de_uxn_apéndice_a.gmo

@@ -30,9 +30,9 @@ comencemos con el siguiente programa como plantilla. incluye los datos para un s
 |0100
 @configuracion
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
 BRK
 
@@ -176,9 +176,9 @@ lo siguiente muestra nuestro programa en contexto, llenando completamente la pri
 |0100
 @configuracion
     ( establecer los colores del sistema )
-    #2ce9 .Sistema/r DEO2
-    #01c0 .Sistema/g DEO2
-    #2ce5 .Sistema/b DEO2
+    #2eef .Sistema/r DEO2
+    #1eb8 .Sistema/g DEO2
+    #1e2e .Sistema/b DEO2
 
     ;tile-fondo .Pantalla/direc DEO2 ( establecer la dirección del tile )
     #0000 ( x inicial )

src/tutorial_de_uxn_día_2.gmo

@@ -185,9 +185,9 @@ podemos escribirlo de la siguiente manera:
 ( programa principal )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 ```
 
 ¿cómo podríamos leer lo que significan esos cortos literales?
@@ -325,9 +325,9 @@ el programa completo se vería de la siguiente manera:
 ( programa principal )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( dibujar un píxel en la pantalla )
       #0008 .Pantalla/x DEO2
@@ -452,9 +452,9 @@ usando estas macros que definimos arriba, nuestro código puede terminar viéndo
 
 ( programa princpal )
 |0100
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( establecer las coordenadas iniciales x,y )
       #0008 .Pantalla/x DEO2
@@ -677,9 +677,9 @@ el siguiente programa dibujará nuestro sprite una vez:
 ( programa principal )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( establecer coordenadas x,y )
       #0008 .Pantalla/x DEO2
@@ -719,9 +719,9 @@ el siguiente código dibujará nuestro sprite cuadrado con las 16 combinaciones
 ( programa principal )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( establecer coordenadas iniciales x,y )
       INIT-X INIT-Y
@@ -954,9 +954,9 @@ el siguiente código mostrará nuestro sprite en las 16 diferentes combinaciones
 ( programa principal )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( establecer coordenadas iniciales x,y )
       INIT-X INIT-Y

src/tutorial_de_uxn_día_3.gmo

@@ -99,9 +99,9 @@ este utiliza el procedimiento de dibujo de sprites que probamos el día anterior
 ( programa principal )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( asignar vector del controlador )
       ;en-controlador .Controlador/vector DEO2
@@ -659,9 +659,9 @@ observa el uso de las máscaras AND, los saltos condicionales y algunas operacio
 ( programa principal )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( asignar vector del controlador )
       ;en-controlador .Controlador/vector DEO2

src/tutorial_de_uxn_día_4.gmo

@@ -40,9 +40,9 @@ el siguiente programa demuestra un uso básico pero potente del vector pantalla:
 ( init )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( establecer coordenadas iniciales x,y )
       #0008 .Pantalla/x DEO2
@@ -238,9 +238,9 @@ en este caso el programa es más largo, pero puede ser visto como una buena plan
 ( init )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( establecer coordenadas iniciales x,y )
       #0008 .píxel/x STZ2
@@ -410,9 +410,9 @@ el siguiente programa ilustra los puntos anteriores, haciendo que nuestro cuadra
 ( init )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( fijar la Pantalla/y a la mitad de la pantalla, menos 4 )
       .Pantalla/alto DEI2 MITAD2 #0004 SUB2 .Pantalla/y DEO2
@@ -509,9 +509,9 @@ el siguiente programa nos permite controlar la posición horizontal de nuestro c
 ( init )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( fijar la Pantalla/y a la mitad de la pantalla, menos 4 )
       .Pantalla/alto DEI2 MITAD2 #0004 SUB2 .Pantalla/y DEO2
@@ -833,9 +833,9 @@ la sección "borrar el sprite" no es realmente necesaria en este caso debido a l
 ( init )
 |0100
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
       ( fijar Pantalla/x e `y` a la mitad de la pantalla, menos 4 )
       .Pantalla/ancho DEI2 MITAD2 #0004 SUB2 .Pantalla/x DEO2

src/tutorial_de_uxn_día_5.gmo

@@ -94,9 +94,9 @@ dibuja nuestro cuadrado en la posición del ratón, cambiando su color cuando se
 ( init )
 |0100
      ( establecer los colores del sistema )
-     #2ce9 .Sistema/r DEO2
-     #01c0 .Sistema/g DEO2
-     #2ce5 .Sistema/b DEO2
+     #2eef .Sistema/r DEO2
+     #1eb8 .Sistema/g DEO2
+     #1e2e .Sistema/b DEO2
 
      ( establecer vector del ratón )
      ;en-ratón .Ratón/vector DEO2
@@ -166,9 +166,9 @@ este es un programa que logra dibujar el puntero en la pantalla
 ( init )
 |0100
     ( establecer los colores del sistema )
-    #2ce9 .Sistema/r DEO2
-    #01c0 .Sistema/g DEO2
-    #2ce5 .Sistema/b DEO2
+    #2eef .Sistema/r DEO2
+    #1eb8 .Sistema/g DEO2
+    #1e2e .Sistema/b DEO2
 
     ( establecer el vector del ratón )
     ;en-ratón .Ratón/vector DEO2
@@ -427,9 +427,9 @@ este es el programa hola-puntero.tal, pero utilizando dibuja-puntero como subrut
 ( init )
 |0100
     ( establecer los colores del sistema )
-    #2ce9 .Sistema/r DEO2
-    #01c0 .Sistema/g DEO2
-    #2ce5 .Sistema/b DEO2
+    #2eef .Sistema/r DEO2
+    #1eb8 .Sistema/g DEO2
+    #1e2e .Sistema/b DEO2
 
     ( establecer el vector del ratón )
     ;en-ratón .Ratón/vector DEO2

src/tutorial_de_uxn_día_6.gmo

@@ -43,9 +43,9 @@ empecemos con el siguiente programa como plantilla. incluye los datos para un sp
 |0100
 @configuración
       ( establecer los colores del sistema )
-      #2ce9 .Sistema/r DEO2
-      #01c0 .Sistema/g DEO2
-      #2ce5 .Sistema/b DEO2
+      #2eef .Sistema/r DEO2
+      #1eb8 .Sistema/g DEO2
+      #1e2e .Sistema/b DEO2
 
 BRK
 
@@ -187,9 +187,9 @@ lo siguiente muestra nuestro programa en contexto, llenando completamente la pri
 |0100
 @configuración
     ( establecer los colores del sistema )
-    #2ce9 .Sistema/r DEO2
-    #01c0 .Sistema/g DEO2
-    #2ce5 .Sistema/b DEO2
+    #2eef .Sistema/r DEO2
+    #1eb8 .Sistema/g DEO2
+    #1e2e .Sistema/b DEO2
 
     ( dibujar fondo )
     ;tile-fondo .Pantalla/direc DEO2 ( establecer la dirección del tile )
@@ -634,9 +634,9 @@ omitiendo la definición de las subrutinas dibuja-fondo y dibuja-pala y como for
 |0100
 @configuración
     ( establecer los colores del sistema )
-    #2ce9 .Sistema/r DEO2
-    #01c0 .Sistema/g DEO2
-    #2ce5 .Sistema/b DEO2
+    #2eef .Sistema/r DEO2
+    #1eb8 .Sistema/g DEO2
+    #1e2e .Sistema/b DEO2
 
     ( establecer vector de pantalla )
     ;en-cuadro .Pantalla/vector DEO2
@@ -1361,9 +1361,9 @@ aquí está todo el código que hemos escrito hoy:
 |0100
 @configuración ( -> )
     ( establecer los colores del sistema )
-    #2ce9 .Sistema/r DEO2
-    #01c0 .Sistema/g DEO2
-    #2ce5 .Sistema/b DEO2
+    #2eef .Sistema/r DEO2
+    #1eb8 .Sistema/g DEO2
+    #1e2e .Sistema/b DEO2
 
     ( establecer el vector de la pantalla )
     ;en-cuadro .Pantalla/vector DEO2

src/uxn_tutorial_appendix_a.gmo

@@ -30,9 +30,9 @@ let's start with the following program as a template. it includes the data for a
 |0100
 @setup
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
 BRK
 
@@ -176,9 +176,9 @@ the following shows our program in context, completely filling the first row of
 |0100
 @setup
     ( set system colors )
-    #2ce9 .System/r DEO2
-    #01c0 .System/g DEO2
-    #2ce5 .System/b DEO2
+    #2eef .System/r DEO2
+    #1eb8 .System/g DEO2
+    #1e2e .System/b DEO2
 
     ;tile-background .Screen/addr DEO2 ( set tile address )
     #0000 ( initial x )

src/uxn_tutorial_day_1.gmo

@@ -276,7 +276,7 @@ we're talking about a device address, 18, but what does it mean?
 
 looking at the devices table from the varvara reference, we can see that the device with address 1 in the high nibble is the console (standard input and output), and that the column with address 8 in the low nibble corresponds to the "write" port.
 
-=> https://wiki.xxiivv.com/site/varvara.html#console varvara: console device
+=> https://wiki.xxiivv.com/site/varvara.html#console XXIIVV — varvara console device
 
 so, device address 18 corresponds to "console write", or standard output.
 

src/uxn_tutorial_day_2.gmo

@@ -20,7 +20,7 @@ when we use 8 bits, we can represent 256 different values (2 to the power of 8).
 
 in the previous section, we talked about a case where this amount is not enough in uxn: the number of bytes that the main memory holds, 65536.
 
-that number corresponds to the values that can be represented using two bytes, or 16 bits, or a "short": 2 to the power of 16. that quantity is also known as 64KB, where 1KB corresponds to 1024 or 2 to the power of 10.
+that number corresponds to the values that can be represented using two bytes, or 16 bits, or a "short": 2 to the power of 16. that quantity is also known as 64KiB, where 1KiB corresponds to 1024 or 2 to the power of 10.
 
 besides expressing addresses in main memory, today we will see another case where 256 values is not always enough: the x and y coordinates for the pixels in our screen.
 
@@ -32,10 +32,13 @@ how do we deal with them?
 
 counting from right to left, the 6th bit of a byte that encodes an instruction for the uxn computer is a binary flag that indicates if the short mode is set or not.
 
-whenever the short mode is enabled, i.e. when that bit is 1 instead of 0, the uxn cpu will perform the instruction given by the first 5 bits (the opcode) but using pairs of bytes instead of single bytes.
+whenever the short mode is enabled, i.e. when that bit is 1 instead of 0, the uxn cpu will perform the instruction indicated by the first 5 bits (the opcode) but using pairs of bytes instead of single bytes.
 
 the byte that is deeper inside the stack will be the "high" byte of the short, and the byte that is closer to the top of the stack will be the "low" byte of the short.
 
+you can see this illustrated in the notes shared by Rostiger:
+=> https://nchrs.xyz/uxn_notes.html nchrs: uxn notes
+
 in uxntal, we indicate that we want to set this flag adding the digit '2' to the end of an instruction mnemonic.
 
 let's see some examples!
@@ -56,7 +59,7 @@ this would be the final state of the stack:
 32 <- top
 ```
 
-in the previous day we mentioned that the literal hex rune (#) is a shorthand for the LIT instruction. therefore we could have written our code as follows:
+in the previous day, we mentioned that the literal hex rune (#) is a shorthand for the LIT instruction. therefore we could have written our code as follows:
 
 ```
 LIT 02 LIT 30 ADD ( assembled code: 80 02 80 30 18 )
@@ -86,7 +89,7 @@ what would be the state of the stack after executing this code?
 #0004 #0008 ADD
 ```
 
-that's right! the stack will have the following values, because we are pushing 4 bytes down onto the stack, ADDing the two of them closest to the top, and pushing the result down onto the stack
+that's right! because we are pushing 4 bytes down onto the stack, ADDing the two of them closest to the top (00 and 08), and pushing the result down onto the stack, the stack will end with the following values:
 
 ```
 00 04 08 <- top
@@ -114,7 +117,7 @@ the stack ends up looking as follows:
 00 0c <- top
 ```
 
-we might not need to think too much about the per-byte manipulations of arithmetic operations, because normally we can think that they are doing the same operation as before, but using pairs of bytes instead of single bytes. their order not really changes.
+we might not need to think too much about the bytewise manipulations of arithmetic operations, because normally we can think that they are doing the same operation as before, but using pairs of bytes instead of single bytes. their order doesn't really change.
 
 in any case, it's useful to keep in mind how they work for some behaviors we might need later :)
 
@@ -138,17 +141,17 @@ DEI ( address -- value )
 
 what do you think that DEO2 and DEI2 would do?
 
-in the case of the short mode of DEO and DEI, the short aspect applies to the value to output or input, and not to the address.
+in the case of the short mode of DEO and DEI, the short aspect applies to the value to output or input only, and not to the address.
 
 remember that the 256 i/o addresses are covered using one byte only already, so using one short for them would be redundant: the high byte would be always 00.
 
 considering this, the following are the behaviors that we can expect:
 
-the DEO2 instruction needs a value (1 short) to output, and an i/o address (1 byte) in the stack, in order to output that value to that address. therefore it needs a total of 3 bytes in the stack to operate.
+the DEO2 instruction needs in the stack a value (1 short) to output, and an i/o address (1 byte), in order to output that value to that address. therefore it needs a total of 3 bytes in the stack to operate.
 
-on the other hand, the DEI2 instruction needs an i/o address (1 byte) in the stack, and it will push down onto the stack the value (1 short) that corresponds to that input.
+on the other hand, the DEI2 instruction needs in the stack an i/o address (1 byte), and it will push down onto the stack the value (1 short) that corresponds to that read input.
 
-in the following section we will see some examples where we'll be able to use these instructions.
+in the following section, we will see some examples where we'll be able to use these instructions.
 
 the 'write' port of the console device that we used last time has a size of 1 byte, so we can't really use these new instructions in a meaningful way with it.
 
@@ -159,16 +162,18 @@ the system device is the varvara device with an address of 00. its output ports
 in uxntal examples we can see its labels defined as follows:
 
 ```
-|00 @System  [ &vector $2 &pad $6 &r $2 &g $2 &b $2 ]
+|00 @System &vector $2 &pad $6 &r $2 &g $2 &b $2
 ```
 
+=> https://wiki.xxiivv.com/site/varvara.html#system XXIIVV — varvara system device
+
 we will ignore the first elements for the moment, and focus on the color components.
 
 ## system colors
 
 the varvara screen device can only show a maximum of four colors at a time.
 
-these four colors are called color 0, color 1, color 2 and color 3.
+these four colors are called color0, color1, color2 and color3.
 
 each color has a total depth of 12 bits: 4 bits for the red component, 4 bits for the green component, and 4 bits for the blue component.
 
@@ -180,32 +185,32 @@ we could write that as follows:
 ( hello-screen.tal )
 
 ( devices )
-|00 @System  [ &vector $2 &pad $6 &r $2 &g $2 &b $2 ]
+|00 @System &vector $2 &pad $6 &r $2 &g $2 &b $2
 
 ( main program )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 ```
 
 how would we read what those literal shorts mean?
 
-we can read each of the colors vertically, from left to right:
+we can read each of the colors vertically, from left to right. therefore:
 
-* color 0 would be red: 2, green: 0, blue: 2 ( #220022 in hex color notation, dark purple )
-* color 1 would be red: c, green: 1, blue: c ( #cc11cc in hex color notation, magenta )
-* color 2 would be red: e, green: c, blue: e ( #eeccee in hex color notation, light pink )
-* color 3 would be red: 9, green: 0, blue: 5 ( #990055 in hex color notation, dark red )
+* color0 would have: red: 2, green: 1, blue: 1 (#221111 in hex color notation, brown)
+* color1 would be red: e, green: e, blue: e (#eeeeee in hex color notation, white)
+* color2 would be red: e, green: b, blue: 2 (#eebb22 in hex color notation, amber)
+* color3 would be red: f, green: 8, blue: e (#ff88ee in hex color notation, pink)
 
-if we run the program now we'll see a dark purple screen, instead of black as what we had before.
+if we run the program now we'll see a brown screen, instead of black as what we had before.
 
-try changing the values of color 0, i.e. the first column, and see what happens :)
+try changing the values of color0, i.e. the first column, and see what happens :)
 
 # the screen device
 
-as a recap: we mentioned that the screen device can only show four different colors at a given time, and that these colors are numbered from 0 to 3. we set these colors using the corresponding ports in the system device.
+the screen device can only show four different colors at a given time, and these colors are numbered from 0 to 3. we set these colors using the corresponding ports in the system device.
 
 now let's discuss the screen device and start using it!
 
@@ -214,15 +219,17 @@ now let's discuss the screen device and start using it!
 in uxntal programs for the varvara computer you will be able to find the labels corresponding to this device ports as follows:
 
 ```
-|20 @Screen  [ &vector $2 &width $2 &height $2 &auto $1 &pad $1 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1 ]
+|20 @Screen &vector $2 &width $2 &height $2 &auto $1 &pad $1 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1
 ```
 
+=> https://wiki.xxiivv.com/site/varvara.html#screen XXIIVV — varvara screen device
+
 these are the ports in list format:
 
 * vector (2 bytes)
 * width of the screen (2 bytes)
 * height of the screen (2 bytes)
-* auto (1 byte)
+* auto byte (1 byte)
 * x coordinate (2 bytes)
 * y coordinate (2 bytes)
 * memory address (2 bytes)
@@ -235,24 +242,24 @@ we will cover the rest of the ports today!
 
 ## foreground and background
 
-the screen device has two overlayed layers of the same size, the foreground and the background.
+the screen device has two overlaid layers of the same size, the foreground and the background.
 
-whatever is drawn over the foreground layer will cover anything that is drawn in the same position in the background layer.
+whatever is drawn in the foreground layer will cover anything that is drawn in the same position in the background layer.
 
-in the beginning the foreground layer is completey transparent: a process of alpha blending makes sure that we can see the background layer.
+in the beginning, the foreground layer is completey transparent: a process of alpha blending makes sure that we can see the background layer.
 
-# drawing a pixel
+# drawing pixels
 
 the first and simpler way to draw into the screen is drawing a single pixel.
 
-in order to do this we need to set a pair of x,y coordinates where we want the pixel to be drawn, and we need to set the 'pixel' byte to a specific value to actually perform the drawing.
+in order to do this, we need to set a pair of x,y coordinates where we want the pixel to be drawn, and we need to set the 'pixel' byte to a specific value to actually perform the drawing.
 
 ## setting the coordinates
 
 the x,y coordinates follow conventions that are common to other computer graphics software:
 
-* x starts in 0 at the left, and increases towards the right of the screen
-* y starts in 0 at the top, and increases towards the bottom of the screen
+* x starts at 0 from the left, and increases towards the right of the screen.
+* y starts at 0 from the top, and increases towards the bottom of the screen.
 
 if we wanted to draw a pixel in coordinates ( 8, 8 ), we'd set its coordinates in this way:
 
@@ -283,15 +290,15 @@ the low nibble of the byte, i.e. the hexadecimal digit at the right, will determ
 the 8 possible combinations of the 'pixel' byte that we have for drawing a pixel are:
 
 + <table>
-+ <tr><th>pixel</th><th>color</th><th>layer</th></tr>
-+ <tr><td class="num">00</td><td class="num">0</td><td>bg</td></tr>
-+ <tr><td class="num">01</td><td class="num">1</td><td></td></tr>
-+ <tr><td class="num">02</td><td class="num">2</td><td></td></tr>
-+ <tr><td class="num">03</td><td class="num">3</td><td></td></tr>
-+ <tr><td class="num">40</td><td class="num">0</td><td>fg</td></tr>
-+ <tr><td class="num">41</td><td class="num">1</td><td></td></tr>
-+ <tr><td class="num">42</td><td class="num">2</td><td></td></tr>
-+ <tr><td class="num">43</td><td class="num">3</td><td></td></tr>
++ <tr><th>pixel</th><th>layer</th><th>color</th></tr>
++ <tr><td class="num">00</td><td>bg</td><td class="num">0</td></tr>
++ <tr><td class="num">01</td><td></td><td class="num">1</td></tr>
++ <tr><td class="num">02</td><td></td><td class="num">2</td></tr>
++ <tr><td class="num">03</td><td></td><td class="num">3</td></tr>
++ <tr><td class="num">40</td><td>fg</td><td class="num">0</td></tr>
++ <tr><td class="num">41</td><td></td><td class="num">1</td></tr>
++ <tr><td class="num">42</td><td></td><td class="num">2</td></tr>
++ <tr><td class="num">43</td><td></td><td class="num">3</td></tr>
 + </table>
 & background layer:
 & * 00: draw pixel with color 0
@@ -307,7 +314,7 @@ the 8 possible combinations of the 'pixel' byte that we have for drawing a pixel
 
 ## hello pixel
 
-let's try it all together! the following code will draw a pixel with color 1 in the foreground layer, at coordinates (8,8)
+let's try it all together! the following code will draw a pixel using color1 in the foreground layer, at coordinates ( 8, 8 )
 
 ```
 #0008 .Screen/x DEO2
@@ -321,26 +328,24 @@ the complete program would look as follows:
 ( hello-pixel.tal )
 
 ( devices )
-|00 @System  [ &vector $2 &pad $6 &r $2 &g $2 &b $2 ]
-|20 @Screen  [ &vector $2 &width $2 &height $2 &pad $2 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1 ]
+|00 @System  &vector $2 &pad $6 &r $2 &g $2 &b $2
+|20 @Screen  &vector $2 &width $2 &height $2 &pad $2 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1
 
 ( main program )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( draw a pixel in the screen )
       #0008 .Screen/x DEO2
       #0008 .Screen/y DEO2
-      #41 .Screen/pixel DEO ( fg layer, color 1 )
+      #41 .Screen/pixel DEO ( fg layer, color1 )
 ```
 
 woohoo!
 
-remember you can use F1 to switch between zoom levels, and F3 to take screenshots of your sketches :)
-
 ## hello pixels
 
 the values we set to the x and y coordinates stay there until we overwrite them.
@@ -371,17 +376,19 @@ for example, we can draw multiple pixels in an horizontal line, setting the y co
 #41 .Screen/pixel DEO
 ```
 
-note that we have to set the color for each pixel we draw; that operation signals the drawing and has to be repeated.
+note that we have to set the color for each pixel we draw. remember that the operation of writing to the pixel byte signals the drawing and therefore has to be repeated.
 
-we can define a macro to make this process easier to write:
+we can define a macro to make the process of drawing a pixel easier to write:
 
 ```
 %DRAW-PIXEL { #41 .Screen/pixel DEO } ( -- )
 ```
 
+in this way, whenever we write DRAW-PIXEL, the assemblers that support macros will replace it with the corresponding uxntal code.
+
 ## reading and manipulating coordinates
 
-we will not cover repetitive structures yet, but this is a good opportunity to start aligning our code towards that.
+we will not cover control flow yet, but this is a good opportunity to start aligning our code towards eventually creating loops and repetive structures.
 
 even though the x and y coordinates of the screen device are intended as outputs, we can also read them as inputs.
 
@@ -437,6 +444,8 @@ our macro for incrementing the x coordinate could be then written as follows:
 %INC-X { .Screen/x DEI2 INC2 .Screen/x DEO2 } ( -- )
 ```
 
+this change saves a couple of bytes and for performance-intensive applications can make our programs run slightly faster.
+
 ## hello pixels using macros
 
 using these macros we defined above, our code could end up looking as following:
@@ -445,8 +454,8 @@ using these macros we defined above, our code could end up looking as following:
 ( hello-pixels.tal )
 
 ( devices )
-|00 @System  [ &vector $2 &pad $6 &r $2 &g $2 &b $2 ]
-|20 @Screen  [ &vector $2 &width $2 &height $2 &pad $2 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1 ]
+|00 @System  &vector $2 &pad $6 &r $2 &g $2 &b $2
+|20 @Screen  &vector $2 &width $2 &height $2 &pad $2 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1
 
 ( macros )
 %DRAW-PIXEL { #41 .Screen/pixel DEO } ( -- )
@@ -454,9 +463,9 @@ using these macros we defined above, our code could end up looking as following:
 
 ( main program )
 |0100
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set initial x,y coordinates )
       #0008 .Screen/x DEO2
@@ -679,9 +688,9 @@ the following program will draw our sprite once:
 ( main program )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set x,y coordinates )
       #0008 .Screen/x DEO2
@@ -721,9 +730,9 @@ the following code will draw our square sprite with all 16 combinations of color
 ( main program )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set  initial x,y coordinates )
       INIT-X INIT-Y
@@ -958,9 +967,9 @@ the following code will show our sprite in the 16 different combinations of colo
 ( main program )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set  initial x,y coordinates )
       INIT-X INIT-Y

src/uxn_tutorial_day_3.gmo

@@ -99,9 +99,9 @@ it uses the sprite drawing procedure we tried in the previous day, but has it ha
 ( main program )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( assign controller vector )
       ;on-controller .Controller/vector DEO2
@@ -659,9 +659,9 @@ note the use of AND masks, conditional jumps, and some stack operations!
 ( main program )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( assign controller vector )
       ;on-controller .Controller/vector DEO2

src/uxn_tutorial_day_4.gmo

@@ -40,9 +40,9 @@ the following program demonstrates a basic but powerful use of the screen vector
 ( init )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set initial x,y coordinates )
       #0008 .Screen/x DEO2
@@ -238,9 +238,9 @@ in this case the program is longer, but it could be seen as a nice template for
 ( init )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set initial x,y coordinates )
       #0008 .pixel/x STZ2
@@ -410,9 +410,9 @@ it combines several things that we have covered in the past few days!
 ( init )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set screen/y to half of screen minus 4 )
       .Screen/height DEI2 HALF2 #0004 SUB2 .Screen/y DEO2
@@ -509,9 +509,9 @@ note the similarities between the previous program, and what we covered on {uxn
 ( init )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set screen/y to half of screen minus 4 )
       .Screen/height DEI2 HALF2 #0004 SUB2 .Screen/y DEO2
@@ -834,9 +834,9 @@ the clear sprite section is not actually needed in this case because of the colo
 ( init )
 |0100
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
       ( set screen/x and y to half of screen minus 4 )
       .Screen/width DEI2 HALF2 #0004 SUB2 .Screen/x DEO2

src/uxn_tutorial_day_5.gmo

@@ -94,9 +94,9 @@ it draws our square in the position of the mouse, changing its color when any mo
 ( init )
 |0100
      ( set system colors )
-     #2ce9 .System/r DEO2
-     #01c0 .System/g DEO2
-     #2ce5 .System/b DEO2
+     #2eef .System/r DEO2
+     #1eb8 .System/g DEO2
+     #1e2e .System/b DEO2
 
      ( set mouse vector )
      ;on-mouse .Mouse/vector DEO2
@@ -166,9 +166,9 @@ this is a program that accomplishes drawing the pointer on the screen!
 ( init )
 |0100
     ( set system colors )
-    #2ce9 .System/r DEO2
-    #01c0 .System/g DEO2
-    #2ce5 .System/b DEO2
+    #2eef .System/r DEO2
+    #1eb8 .System/g DEO2
+    #1e2e .System/b DEO2
 
     ( set mouse vector )
     ;on-mouse .Mouse/vector DEO2
@@ -427,9 +427,9 @@ this is the hello-pointer.tal program, but using draw-pointer as a subroutine th
 ( init )
 |0100
     ( set system colors )
-    #2ce9 .System/r DEO2
-    #01c0 .System/g DEO2
-    #2ce5 .System/b DEO2
+    #2eef .System/r DEO2
+    #1eb8 .System/g DEO2
+    #1e2e .System/b DEO2
 
     ( set mouse vector )
     ;on-mouse .Mouse/vector DEO2

src/uxn_tutorial_day_6.gmo

@@ -43,9 +43,9 @@ let's start with the following program as a template. it includes the data for a
 |0100
 @setup
       ( set system colors )
-      #2ce9 .System/r DEO2
-      #01c0 .System/g DEO2
-      #2ce5 .System/b DEO2
+      #2eef .System/r DEO2
+      #1eb8 .System/g DEO2
+      #1e2e .System/b DEO2
 
 BRK
 
@@ -187,9 +187,9 @@ the following shows our program in context, completely filling the first row of
 |0100
 @setup
     ( set system colors )
-    #2ce9 .System/r DEO2
-    #01c0 .System/g DEO2
-    #2ce5 .System/b DEO2
+    #2eef .System/r DEO2
+    #1eb8 .System/g DEO2
+    #1e2e .System/b DEO2
 
     ( draw background )
     ;tile-background .Screen/addr DEO2 ( set tile address )
@@ -633,9 +633,9 @@ omitting the definition of the draw-background and draw-paddle subroutines, and
 |0100
 @setup
     ( set system colors )
-    #2ce9 .System/r DEO2
-    #01c0 .System/g DEO2
-    #2ce5 .System/b DEO2
+    #2eef .System/r DEO2
+    #1eb8 .System/g DEO2
+    #1e2e .System/b DEO2
 
     ( set screen vector )
     ;on-frame .Screen/vector DEO2
@@ -1359,9 +1359,9 @@ here's all of the code we wrote today!
 |0100
 @setup ( -> )
     ( set system colors )
-    #2ce9 .System/r DEO2
-    #01c0 .System/g DEO2
-    #2ce5 .System/b DEO2
+    #2eef .System/r DEO2
+    #1eb8 .System/g DEO2
+    #1e2e .System/b DEO2
 
     ( set screen vector )
     ;on-frame .Screen/vector DEO2