added note regarding the status of the tutorial and ebook

e.g.:
|40 @color-clear

and then use it as .color-clear

thanks tbsp!

src/introduction_to_uxn_programming_book.gmo

@@ -7,6 +7,10 @@ introduction to uxn programming is a beginner's, slow-paced and comprehensive gu
 
 originally available online as the {uxn tutorial}, this is a carefully revised version for you to have it offline and available anytime.
 
+IMPORTANT (12024-03-28)! keep in mind that the contents of the ebook are written from a somewhat outdated perspective and some of them might be wrong. the online {uxn tutorial} is more up-to-date. some things are done differently now, and the tutorial doesn't cover all the possibilities in the language that exist nowadays. in doubt, always refer to the official documentation. however, we hope it's still useful to you as an introduction to the uxn ecosystem!
+
+=> https://wiki.xxiivv.com/site/uxn.html XXIIVV — uxn official documentation
+
 # download
 
 => https://compudanzas.itch.io/introduction-to-uxn-programming get introduction to uxn programming

src/maintenance_practice.gmo

@@ -7,12 +7,17 @@ we have a twitch channel that we're using to stream our maintenance practice, fo
 
 # upcoming stream(s)
 
-* 12024-03-28, thursday, 19:00-21:00 UTC+1
+* no upcoming streams are scheduled for the moment. once we know about it we'll put it in the {log}
 
 # stream log
 
 in reverse chronological order:
 
+## 12024-03-28: uxn tutorial
+in this stream, we searched for the uses of macros in the whole tutorial and classified them according to how complex it would be to replace them with something more current. we replaced some macros (RTN) and listed the possible changes in the {roadmap}.
+
+we also went through the list of the pending tasks and realized that everything should be working alright except for the pong example that needs to be modified in how it clears the sprites.
+
 ## 12024-03-16: uxn tutorial day 2 (part 2.1)
 
 in this stream, we updated the example sprite for the 1bpp mode; it's now an arrow pointing downwards and to the left so that the flipping is more evident. we updated the corresponding code.

src/roadmap.gmo

@@ -13,6 +13,63 @@ the things that want to happen.
 * preparation of workshop for esLibre 2024 {propuesta taller computación somática}
 
 
+# uxn
+
+## tutorial
+
+contributions are welcome! some of these issues were managed or identified during our {maintenance practice}, but there's still some work to do!
+
+### critical
+
+* check blend mode 0 (in progress) --- this affects the pong example in {uxn tutorial day 6}
+=> https://lists.sr.ht/~rabbits/uxn/%3C692CA0D5-0200-408D-9357-BF0D8887D2BF%40noyu.me%3E Blend mode 0
+=> https://lists.sr.ht/~rabbits/uxn/%3CCAE2DaSQuj%3DC8e7ofV3+4H6MaTOhtD_wrFWihhYtCuYiEVtV6WQ%40mail.gmail.com%3E Massive tiny change coming to Varvara's Screen device 
+> the #00 blending will, from now on, only clear the pixels that are present in the sprite data at Screen/addr*.
+
+### pending
+* remove square brackets in devices
+* update images (to do: emulator needs a patch)
+
+### in order to remove macros
+this is an overview of how macros are used and what would be needed to replace them.
+
+* in {uxn tutorial day 1} they are deeply embedded as a learning block, so they need some rewriting
+* in {uxn tutorial day 2} they are used to increment coordinates and repeat the drawing of pixels or sprites. Replace with auto byte? (note that it's introduced until {uxn tutorial day 6})
+* in {uxn tutorial day 2} we also have them as example for HALF and HALF2.
+* in {uxn tutorial day 2} introduce the use of zero-page labels as constants.
+```
+|40 @color-clear
+
+( and then use it as .color-clear )
+```
+* in {uxn tutorial day 3} we talk about a ?ASCII-DIGIT macro
+* there are some macros from {uxn tutorial day 4} and onwards that are used as constants: replace them with zero-page labels!
+* in {uxn tutorial day 4} we introduce MOD, 8MOD, TO-SHORT
+* in {uxn tutorial day 5} we re-work MOD
+* in {uxn tutorial day 6} we use constants, and HALF, DOUBLE
+
+### further possible changes
+* make a folder of examples 
+* whenever we mention the theme loading, link to the suggested palette.
+
+* replace {uxn tutorial day 2} intro to colors with a table.
+* format and update {uxn running} notes
+
+* {uxn tutorial day 2}: divide into morning and evening?
+* {uxn tutorial day 2}: check sprite nibbles tables. include colors when colors are mentioned.
+* {uxn tutorial day 6} mention auto sprite flipping? maybe not needed
+=> https://lists.sr.ht/~rabbits/uxn/%3CCAE2DaSQQMb8XVfsn2NSsXQO+-0m2t4U2GD7nYD3GBUO4GPeTxQ%40mail.gmail.com%3E Whole auto sprite flipping 
+* new day: lambdas and more complex stuff (jumps, callings, etc)
+* include uxn5 in the web tutorial so that code can be run from there
+=> https://git.sr.ht/~rabbits/uxn5 uxn5
+
+## traducción:
+
+* sincroniza el {tutorial de uxn} con {uxn tutorial}
+* agrega las indicaciones sobre el uso de screen/auto en {uxn tutorial day 6}
+
+
+
 # dance
 
 continue developing, practicing and sharing the {qiudanz technique}
@@ -37,43 +94,6 @@ publish them in itch.io
 * explore more non-electronic computers examples from the {references}
 * develop a {computadora de papel} simulator?
 
-# uxn
-
-## tutorial
-
-### day 2 and onwards
-
-* check blend mode 0 (in progress)
-=> https://lists.sr.ht/~rabbits/uxn/%3C692CA0D5-0200-408D-9357-BF0D8887D2BF%40noyu.me%3E Blend mode 0
-=> https://lists.sr.ht/~rabbits/uxn/%3CCAE2DaSQuj%3DC8e7ofV3+4H6MaTOhtD_wrFWihhYtCuYiEVtV6WQ%40mail.gmail.com%3E Massive tiny change coming to Varvara's Screen device 
-> the #00 blending will, from now on, only clear the pixels that are present in the sprite data at Screen/addr*. 
-
-* {uxn tutorial day 6} auto sprite flipping
-=> https://lists.sr.ht/~rabbits/uxn/%3CCAE2DaSQQMb8XVfsn2NSsXQO+-0m2t4U2GD7nYD3GBUO4GPeTxQ%40mail.gmail.com%3E Whole auto sprite flipping 
-
-### pending
-* remove square brackets in devices
-* update images (to do: emulator needs a patch)
-* remove macros
-
-### further possible changes
-* make a folder of examples 
-* whenever we mention the theme loading, link to the suggested palette.
-
-* replace {uxn tutorial day 2} intro to colors with a table.
-* format and update {uxn running} notes
-
-* {uxn tutorial day 2}: divide into morning and evening?
-* {uxn tutorial day 2}: check sprite nibbles tables. include colors when colors are mentioned.
-* new day: lambdas and more complex stuff (jumps, callings, etc)
-* include uxn5 in the web tutorial so that code can be run from there
-=> https://git.sr.ht/~rabbits/uxn5 uxn5
-
-## traducción:
-
-* sincroniza el {tutorial de uxn} con {uxn tutorial}
-* agrega las indicaciones sobre el uso de screen/auto en {uxn tutorial day 6}
-
 # wiki
 
 ## generator

src/uxn_tutorial.gmo

@@ -2,10 +2,16 @@
 lang=en es->{tutorial de uxn}
 a beginner's, slow-paced and comprehensive guide for programming the varvara computer based on the {uxn} core.
 
-you can get an offline version of this guide as the {introduction to uxn programming book}!
-
 if you prefer video, you can watch a short {intro to uxn programming} workshop that we taught as an introduction.
 
+IMPORTANT (12024-03-28)! even though we updated to some extent the tutorial during our {maintenance practice}, and in principle everything that we say here works, keep in mind that it is written from a somewhat outdated perspective. some things are done differently now, and the tutorial doesn't cover all the possibilities in the language that exist nowadays. in doubt, always refer to the official documentation. however, we hope it's still useful to you as an introduction to the uxn ecosystem!
+
+=> https://wiki.xxiivv.com/site/uxn.html XXIIVV — uxn official documentation
+
+if you'd like to contribute improving the tutorial, check out our to-do list in the {roadmap} and {contact} us!
+
+there is an offline version of this guide as the {introduction to uxn programming book}, but it still needs to incorporate some of the changes we did here.
+
 # day 1
 
 in this first section of the tutorial we talk about the basics of the uxn computer called varvara, its programming paradigm in a language called uxntal, its architecture, and why you would want to learn to program it.

src/uxn_tutorial_day_1.gmo

@@ -4,6 +4,12 @@ hello! in this first section of the {uxn tutorial} we talk about the basics of t
 
 we also jump right in into our first simple programs to demonstrate fundamental concepts that we will develop further in the following days.
 
+IMPORTANT (12024-03-28)! even though we updated to some extent the tutorial during our {maintenance practice}, and in principle everything that we say here works, keep in mind that it is written from a somewhat outdated perspective. some things are done differently now, and the tutorial doesn't cover all the possibilities in the language that exist nowadays. in doubt, always refer to the official documentation. however, we hope it's still useful to you as an introduction to the uxn ecosystem!
+
+=> https://wiki.xxiivv.com/site/uxn.html XXIIVV — uxn official documentation
+
+if you'd like to contribute improving the tutorial, check out our to-do list in the {roadmap} and {contact} us!
+
 # why uxn?
 
 or first of all... what is uxn?

src/uxn_tutorial_day_3.gmo

@@ -425,7 +425,7 @@ we'll be using these instructions in many different ways during the following da
 
 the following are some examples based on snippets of code that we discussed already.
 
-keep in mind that using these instructions may contribute to a code that is hard to follow or read, so it will be always a good idea to use them within macros or to have comments in the code explaining what's happening :)
+keep in mind that using these instructions may contribute to a code that is hard to follow or read, so it will be always a good idea to have comments in the code explaining what's happening :)
 
 ### ascii digit: duplicate and swap
 
@@ -719,17 +719,7 @@ BRK
 @square ff81 8181 8181 81ff
 ```
 
-some possibilities for you to practice:
-
-* modify the code so that it will also respond to you pressing more than one arrow at the same time.
-* convert the increments and decrements of the coordinates to macros that take the address of the port as input, and perform an equivalent operation. both of these lines should work using the same macro:
-
-```
-.Screen/x INCREMENT
-.Screen/y INCREMENT
-```
-
-remember that .Screen/x is a literal address in the zero page, i.e. it pushes a byte corresponding to the address of the Screen/x sublabel :)
+as a possible exercise for you, modify the code so that it will also respond to you pressing more than one arrow at the same time.
 
 # practice possibilities
 

src/uxn_tutorial_day_5.gmo

@@ -397,17 +397,13 @@ additionally, as the addresses pushed by JSR are shorts, we need to activate the
 JMP2r ( jump to the absolute address at the top of the return stack )
 ```
 
-in many uxntal programs you will see this instruction written as a macro, RTN (return):
+at some point in time, this instruction was written as a macro, RTN, which stood for "return".
 
-```
-%RTN { JMP2r }
-```
-
-we can finish a subroutine using this macro in order to "return" to the position in the program after the corresponding JSR.
+we can finish a subroutine using this instruction in order to "return" to the position in the program after the corresponding JSR.
 
 ## complete example using subroutines
 
-this is the hello-pointer.tal program, but using draw-pointer as a subroutine that is "called" with JSR2 and that ends with RTN:
+this is the hello-pointer.tal program, but using draw-pointer as a subroutine that is "called" with JSR2 and that ends with JMP2r:
 
 ```
 ( hello-pointer.tal )
@@ -417,9 +413,6 @@ this is the hello-pointer.tal program, but using draw-pointer as a subroutine th
 |20 @Screen  [ &vector $2 &width $2 &height $2 &pad  $2 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1 ]
 |90 @Mouse   [ &vector $2 &x $2 &y $2 &state $1 &pad $3 &scrollx $2 &scrolly $2 ]
 
-( macros )
-%RTN { JMP2r }
-
 ( zero page )
 |0000
 @pointer [ &x $2 &y $2 ]
@@ -463,14 +456,14 @@ BRK
 
     ( draw sprite with color 2 in foreground )
     #4a .Screen/sprite DEO
-RTN
+JMP2r
 
 @pointer_icn [ 80c0 e0f0 f8e0 1000 ]
 ```
 
 note that the draw-pointer label is accompanied by the stack state notation ( -- ) to indicate that, in this case, it doesn't consume or produce contents from or to the working stack.
 
-also note how this subroutine ends with a RTN (JMP2r) that indicates that the flow of the program will return to the position after the subroutine was called.
+also note how this subroutine ends with a JMP2r that indicates that the flow of the program will return to the position after the subroutine was called.
 
 ## notes on subroutines as "functions"
 
@@ -553,7 +546,7 @@ a caret (^) after a value name indicates that it corresponds to a short.
         NEQ ( ws: length count flag / rs: )
         ,&loop JCN ( ws: length count / rs: )
      POP2 ( ws: / rs: )
-RTN
+JMP2r
 ```
 
 ### calling

src/uxn_tutorial_day_6.gmo

@@ -36,9 +36,6 @@ let's start with the following program as a template. it includes the data for a
 |20 @Screen  [ &vector $2 &width $2 &height $2 &auto $1 &pad $1 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1 ]
 |80 @Controller [ &vector $2 &button $1 &key $1 ]
 
-( macros )
-%RTN { JMP2r }
-
 ( main program )
 |0100
 @setup
@@ -180,9 +177,6 @@ the following shows our program in context, completely filling the first row of
 |20 @Screen  [ &vector $2 &width $2 &height $2 &auto $1 &pad $1 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1 ]
 |80 @Controller [ &vector $2 &button $1 &key $1 ]
 
-( macros )
-%RTN { JMP2r }
-
 ( main program )
 |0100
 @setup
@@ -309,7 +303,7 @@ now we can just wrap these nested loops inside a subroutine:
         GTH2k ( is the limit greater than y? aka is y less than the limit ? )
         ,&loop-y JCN ( jump if y is less than the limit )
     POP2 POP2 ( remove y and limit )
-RTN
+JMP2r
 ```
 
 that we can simply call from our initialization subroutine:
@@ -514,7 +508,7 @@ for this, we can configure it so that we draw two tiles in a row, automatically
     STHr
     ( draw three rows: )
     .Screen/sprite DEOk DEOk DEO
-RTN
+JMP2r
 ```
 
 that's it!
@@ -614,7 +608,6 @@ omitting the definition of the draw-background and draw-paddle subroutines, and
 |80 @Controller [ &vector $2 &button   $1 &key    $1 ]
 
 ( macros )
-%RTN { JMP2r }
 %HALF2 { #01 SFT2 } ( short -- short/2 )
 
 ( constants )
@@ -747,7 +740,7 @@ all of this can go inside its own subroutine for readability purposes:
 
     &end
         POP ( pop duplicate value of button )
-RTN
+JMP2r
 ```
 
 ### complete procedure
@@ -854,7 +847,7 @@ let's have the subroutine receive the color as an argument, so that we can clear
     .Screen/sprite
     ( draw two rows: )
     DEOk DEO
-RTN
+JMP2r
 ```
 
 notice how we are using a very similar approach to the draw-paddle subroutine!
@@ -1023,7 +1016,7 @@ based on what we just discussed, we can start our update-ball subroutine with th
     .ball/speed-y LDZ2 .ball/y LDZ2
     ADD2 ( add them together )
     .ball/y STZ2 ( store new y )
-RTN
+JMP2r
 ```
 
 if we complement our setup routine with the initial speeds, we'll be able to see the ball moving:
@@ -1156,7 +1149,7 @@ our update-ball subroutine looks like the following right now:
         &set-negative-speed
             BALL-NEGATIVE-SPEED .ball/speed-y STZ2
      &continue
-RTN
+JMP2r
 ```
 
 you can test it using different initial speed-y inside setup. the ball should be bouncing at the top and bottom now! :)
@@ -1291,7 +1284,7 @@ for the right paddle we will do the same as above, but changing the comparisons
               ,&finish JMP
 
  &finish
-RTN
+JMP2r
 ```
 
 that should be it! you can find the complete update-ball subroutine below!
@@ -1309,7 +1302,7 @@ here we'll just define a reset subroutine that returns the ball to the middle of
     HALF2 .ball/x STZ2
     .Screen/height DEI2 BALL-SIZE SUB2
     HALF2 .ball/y STZ2
-RTN
+JMP2r
 ```
 
 it would be interesting to have some mechanism to also change the speed: maybe based on the framecount, in the position of the paddles, or whatever else you choose.
@@ -1332,7 +1325,6 @@ here's all of the code we wrote today!
 |80 @Controller [ &vector $2 &button $1 &key $1 ]
 
 ( macros )
-%RTN { JMP2r }
 %HALF2 { #01 SFT2 } ( short -- short/2 )
 %DOUBLE2 { #10 SFT2 }
 
@@ -1425,7 +1417,7 @@ BRK
     HALF2 .ball/x STZ2
     .Screen/height DEI2 BALL-SIZE SUB2
     HALF2 .ball/y STZ2
-RTN
+JMP2r
 ```
 
 ## ball-related
@@ -1524,7 +1516,7 @@ RTN
                   ,&finish JMP
 
      &finish
-RTN
+JMP2r
 ```
 
 ### draw-ball
@@ -1547,7 +1539,7 @@ RTN
     .Screen/sprite
     ( draw two rows: )
     DEOk DEO
-RTN
+JMP2r
 ```
 
 ## paddle-related
@@ -1590,7 +1582,7 @@ RTN
 
     &end
         POP ( pop duplicate value of button )
-RTN
+JMP2r
 ```
 
 ## draw-paddle
@@ -1614,7 +1606,7 @@ RTN
     STHr .Screen/sprite
     ( draw three rows: )
     DEOk DEOk DEO
-RTN
+JMP2r
 ```
 
 ## draw-background
@@ -1642,7 +1634,7 @@ RTN
         GTH2k ( is the limit greater than y? aka is y less than the limit ? )
         ,&loop-y JCN ( jump if y is less than the limit )
     POP2 POP2 ( remove y and limit )
-RTN
+JMP2r
 ```
 
 ## data