Inconsistency in docs: variable names and substitution rules

Description

The documentation is unclear on a few points about how ARG build arguments and ENV environment variables are treated differently in terms of variable substitution (interpolation).

The Dockerfile reference documentation says:

Environment replacement
... Environment variables are supported by the following list of instructions in the Dockerfile:
[list of instructions that does not include RUN]

First, this is unclear about whether it's only talking about ENV environment variables (as it seems to) or if it also applies to ARG build arguments.

Second, it also says:

Using ARG variables
You can use an ARG or an ENV instruction to specify variables that are available to the RUN instruction.

This seems to directly contradict the absence of RUN in the "Environment replacement" list. Perhaps it is meant that variable expansion of ENV variables will be performed by the shell under which the RUN instruction command executes, rather than by Docker itself. But it is not guaranteed that the shell performs such expansion.

The documentation also gives an example in which an ARG is used in a RUN instruction, suggesting that its absence from the "Environment replacement" list above is indeed an omission or something else.

FROM busybox
ARG SETTINGS
RUN ./run/setup $SETTINGS

Similarly, the "Environment replacement" list says FROM supports expansion of environment variables, but there is a section specifically talking about its behavior with build arguments.

There are some weird edge cases with ARG and ENV like how ENV declarations shadow prior ARG, and how ARG has to be repeated after a FROM, but before raising these issues the documentation should be much clearer on how to use them in the first place.

Output of docker version:

docker version
Client:
 Cloud integration: 1.0.17
 Version:           20.10.8
 API version:       1.41
 Go version:        go1.16.6
 Git commit:        3967b7d
 Built:             Fri Jul 30 19:55:20 2021
 OS/Arch:           darwin/amd64
 Context:           default
 Experimental:      true

Server: Docker Engine - Community
 Engine:
  Version:          20.10.8
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.16.6
  Git commit:       75249d8
  Built:            Fri Jul 30 19:52:10 2021
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.4.9
  GitCommit:        e25210fe30a0a703442421b0f60afac609f950a3
 runc:
  Version:          1.0.1
  GitCommit:        v1.0.1-0-g4144b63
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Output of docker info:

Client:
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Build with BuildKit (Docker Inc., v0.6.1-docker)
  compose: Docker Compose (Docker Inc., v2.0.0-rc.3)
  scan: Docker Scan (Docker Inc., v0.8.0)

Server:
 Containers: 2
  Running: 2
  Paused: 0
  Stopped: 0
 Images: 20
 Server Version: 20.10.8
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 1
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: e25210fe30a0a703442421b0f60afac609f950a3
 runc version: v1.0.1-0-g4144b63
 init version: de40ad0
 Security Options:
  seccomp
   Profile: default
 Kernel Version: 5.10.47-linuxkit
 Operating System: Docker Desktop
 OSType: linux
 Architecture: x86_64
 CPUs: 4
 Total Memory: 1.939GiB
 Name: docker-desktop
 ID: XBSX:EJU6:QSRV:CFL4:MYOE:F77V:GBOU:4F63:XLBZ:ZQUR:RS4N:LDLP
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 HTTP Proxy: http.docker.internal:3128
 HTTPS Proxy: http.docker.internal:3128
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
 Live Restore Enabled: false

Start with the Dockerfile reference sections “Environment replacement” and “Using ARG variables,” including their linked examples. Compare the documented behavior of ARG and ENV in RUN and FROM instructions, then revise the documentation so substitution rules and shell expansion are unambiguous, including the noted shadowing and repeated-ARG cases.