From ff13b46cc3464cf3f4a45546cd935997a5b4b864 Mon Sep 17 00:00:00 2001
From: Mitsuru Kariya <mitsuru.kariya@nttdata.com>
Date: Thu, 11 Jul 2024 00:27:05 +0900
Subject: [PATCH] docs: update environment replacement

Signed-off-by: Mitsuru Kariya <mitsuru.kariya@nttdata.com>
---
 frontend/dockerfile/docs/reference.md | 64 ++++++++++++++++++++-------
 1 file changed, 48 insertions(+), 16 deletions(-)

diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md
index a5a0a049fa2e..32e6b1c0ec60 100644
--- a/frontend/dockerfile/docs/reference.md
+++ b/frontend/dockerfile/docs/reference.md
@@ -309,10 +309,10 @@ PS E:\myproject>
 
 ## Environment replacement
 
-Environment variables (declared with [the `ENV` statement](#env)) can also be
-used in certain instructions as variables to be interpreted by the
-Dockerfile. Escapes are also handled for including variable-like syntax
-into a statement literally.
+Environment variables (declared with [the `ENV` statement](#env) and [the `ARG`
+statement](#arg)) can also be used in certain instructions as variables to be
+interpreted by the Dockerfile. Escapes are also handled for including
+variable-like syntax into a statement literally.
 
 Environment variables are notated in the Dockerfile either with
 `$variable_name` or `${variable_name}`. They are treated equivalently and the
@@ -322,22 +322,43 @@ whitespace, like `${foo}_bar`.
 The `${variable_name}` syntax also supports a few of the standard `bash`
 modifiers as specified below:
 
-- `${variable:-word}` indicates that if `variable` is set then the result
-  will be that value. If `variable` is not set then `word` will be the result.
-- `${variable:+word}` indicates that if `variable` is set then `word` will be
+- `${variable:-word}` indicates that if `variable` is set and not an empty
+  string then the result will be that value, otherwise the result is `word`.
+
+- `${variable-word}` indicates that if `variable` is set then the result
+  will be that value, otherwise the result is `word`.
+
+  This syntax can be used with `docker/dockerfile:1.6.0` or later.
+
+- `${variable:+word}` indicates that if `variable` is set and not an empty
+  string then `word` will be the result, otherwise the result is the empty
+  string.
+
+- `${variable+word}` indicates that if `variable` is set then `word` will be
   the result, otherwise the result is the empty string.
 
-The following variable replacements are supported in a pre-release version of
-Dockerfile syntax, when using the `# syntax=docker/dockerfile-upstream:master` syntax
-directive in your Dockerfile:
+  This syntax can be used with `docker/dockerfile:1.6.0` or later.
+
+- `${variable:?word}` indicates that if `variable` is set and not an empty
+  string then the result will be that value, otherwise display `word` as an
+  error message.
+
+  This syntax can be used with `docker/dockerfile/1.1.6` or later.
+
+- `${variable?word}` indicates that if `variable is set then the result will be
+  that value, otherwise display `word` as an error message.
+
+  This syntax can be used with `docker/dockerfile:1.1.6` or later.
 
 - `${variable#pattern}` removes the shortest match of `pattern` from `variable`,
   seeking from the start of the string.
-  
+
   ```bash
   str=foobarbaz echo ${str#f*b}     # arbaz
   ```
-  
+
+  This syntax can be used with `docker/dockerfile:1.7.0` or later.
+
 - `${variable##pattern}` removes the longest match of `pattern` from `variable`,
   seeking from the start of the string.
 
@@ -345,6 +366,8 @@ directive in your Dockerfile:
   str=foobarbaz echo ${str##f*b}    # az
   ```
 
+  This syntax can be used with `docker/dockerfile:1.7.0` or later.
+
 - `${variable%pattern}` removes the shortest match of `pattern` from `variable`,
   seeking backwards from the end of the string.
 
@@ -352,6 +375,8 @@ directive in your Dockerfile:
   string=foobarbaz echo ${string%b*}    # foobar
   ```
 
+  This syntax can be used with `docker/dockerfile:1.7.0` or later.
+
 - `${variable%%pattern}` removes the longest match of `pattern` from `variable`,
   seeking backwards from the end of the string.
 
@@ -359,22 +384,28 @@ directive in your Dockerfile:
   string=foobarbaz echo ${string%%b*}   # foo
   ```
 
+  This syntax can be used with `docker/dockerfile:1.7.0` or later.
+
 - `${variable/pattern/replacement}` replace the first occurrence of `pattern`
-  in `variable` with `replacement`
+  in `variable` with `replacement`.
 
   ```bash
   string=foobarbaz echo ${string/ba/fo}  # fooforbaz
   ```
 
+  This syntax can be used with `docker/dockerfile:1.7.0` or later.
+
 - `${variable//pattern/replacement}` replaces all occurrences of `pattern`
-  in `variable` with `replacement`
+  in `variable` with `replacement`.
 
   ```bash
   string=foobarbaz echo ${string//ba/fo}  # fooforfoz
   ```
 
-In all cases, `word` can be any string, including additional environment
-variables.
+  This syntax can be used with `docker/dockerfile:1.7.0` or later.
+
+In all cases, `word`, `pattern` and `replacement` can be any string, including
+additional environment variables.
 
 `pattern` is a glob pattern where `?` matches any single character
 and `*` any number of characters (including zero). To match literal `?` and `*`,
@@ -397,6 +428,7 @@ Environment variables are supported by the following list of instructions in
 the Dockerfile:
 
 - `ADD`
+- `ARG`
 - `COPY`
 - `ENV`
 - `EXPOSE`