From a16a5ea81a50d3d73017cacc2891a86a27d1d7f5 Mon Sep 17 00:00:00 2001
From: Andrey Nering <andrey@nering.com.br>
Date: Mon, 24 Jul 2023 22:06:40 -0300
Subject: [PATCH] docs: small adjustment for #1220

---
 docs/docs/api_reference.md |  2 +-
 docs/docs/usage.md         | 42 +++++++++++++++++---------------------
 2 files changed, 20 insertions(+), 24 deletions(-)

diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md
index 06dd4e21..6595de0e 100644
--- a/docs/docs/api_reference.md
+++ b/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
 
diff --git a/docs/docs/usage.md b/docs/docs/usage.md
index 774be626..19ebc992 100644
--- a/docs/docs/usage.md
+++ b/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: