docs: small adjustment for #1220

docs/docs/api_reference.md

@@ -128,7 +128,7 @@ There are some special variables that is available on the templating system:
 | `CHECKSUM`         | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`.                               |
 | `TIMESTAMP`        | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
 | `TASK_VERSION`     | The current version of task.                                                                                                                             |
-| `ITEM`             | The value of the current iteration when using the `for` property.                                                                                        |
+| `ITEM`             | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`.                                                                                        |
 
 ## ENV
 

docs/docs/usage.md

@@ -1043,7 +1043,9 @@ match that glob.
 
 Source paths will always be returned as paths relative to the task directory. If
 you need to convert this to an absolute path, you can use the built-in
-`joinPath` function:
+`joinPath` function.
+There are some [special variables](/api/#special-variables) that you may find
+useful for this.
 
 ```yaml
 version: '3'
@@ -1058,7 +1060,7 @@ tasks:
       - bar.txt
     cmds:
       - for: sources
-        cmd: cat {{ joinPath .MY_DIR .ITEM }}
+        cmd: cat {{joinPath .MY_DIR .ITEM}}
 ```
 
 ### Looping over variables
@@ -1073,11 +1075,10 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var: foo.txt bar.txt
+      MY_VAR: foo.txt bar.txt
     cmds:
-      - for:
-          var: my_var
-        cmd: cat {{ .ITEM }}
+      - for: { var: MY_VAR }
+        cmd: cat {{.ITEM}}
 ```
 
 If you need to split on a different character, you can do this by specifying the
@@ -1089,12 +1090,10 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var: foo.txt,bar.txt
+      MY_VAR: foo.txt,bar.txt
     cmds:
-      - for:
-          var: my_var
-          split: ','
-        cmd: cat {{ .ITEM }}
+      - for: { var: MY_VAR, split: ',' }
+        cmd: cat {{.ITEM}}
 ```
 
 All of this also works with dynamic variables!
@@ -1105,12 +1104,11 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var:
+      MY_VAR:
         sh: find -type f -name '*.txt'
     cmds:
-      - for:
-          var: my_var
-        cmd: cat {{ .ITEM }}
+      - for: { var: MY_VAR }
+        cmd: cat {{.ITEM}}
 ```
 
 ### Renaming variables
@@ -1124,12 +1122,10 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var: foo.txt bar.txt
+      MY_VAR: foo.txt bar.txt
     cmds:
-      - for:
-          var: my_var
-          as: FILE
-        cmd: cat {{ .FILE }}
+      - for: { var: MY_VAR, as: FILE }
+        cmd: cat {{.FILE}}
 ```
 
 ### Looping over tasks
@@ -1147,11 +1143,11 @@ tasks:
       - for: [foo, bar]
         task: my-task
         vars:
-          FILE: '{{ .ITEM }}'
+          FILE: '{{.ITEM}}'
 
   my-task:
     cmds:
-      - echo '{{ .FILE }}'
+      - echo '{{.FILE}}'
 ```
 
 Or if you want to run different tasks depending on the value of the loop:
@@ -1163,7 +1159,7 @@ tasks:
   default:
     cmds:
       - for: [foo, bar]
-        task: task-{{ .ITEM }}
+        task: task-{{.ITEM}}
 
   task-foo:
     cmds: