Compose freshness for further how-to pages (#22980)

<!--Delete sections as needed -->

## Description

Freshness to:
 - Env variables and closes #22730
 - Build dependent images
 - Secrets
 - watch

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

Author: aevesdocker

content/manuals/compose/how-tos/dependent-images.md

@@ -8,7 +8,7 @@ weight: 50
 {{< summary-bar feature_name="Compose dependent images" >}}
 
 To reduce push/pull time and image weight, a common practice for Compose applications is to have services
-share base layers as much as possible. You will typically select the same operating system base image for
+share base layers as much as possible. You typically select the same operating system base image for
 all services. But you can also get one step further by sharing image layers when your images share the same
 system packages. The challenge to address is then to avoid repeating the exact same Dockerfile instruction 
 in all services.
@@ -162,3 +162,8 @@ Bake can also be selected as the default builder by editing your `$HOME/.docker/
   ...
 }
 ```
+
+## Additional resources
+
+- [Docker Compose build reference](/reference/cli/docker/compose/build.md)
+- [Learn about multi-stage Dockerfiles](/manuals/build/building/multi-stage.md)

content/manuals/compose/how-tos/environment-variables/_index.md

@@ -2,14 +2,13 @@
 title: Environment variables in Compose
 linkTitle: Use environment variables
 weight: 40
-description: Explainer on the ways to set, use and manage environment variables in
-  Compose
+description: Explains how to set, use, and manage environment variables in Docker Compose.
 keywords: compose, orchestration, environment, env file
 aliases:
 - /compose/environment-variables/
 ---
 
-By leveraging environment variables and interpolation in Docker Compose, you can create versatile and reusable configurations, making your Dockerized applications easier to manage and deploy across different environments. 
+Environment variables and interpolation in Docker Compose help you create reusable, flexible configurations. This makes Dockerized applications easier to manage and deploy across environments.
 
 > [!TIP]
 >

content/manuals/compose/how-tos/environment-variables/envvars-precedence.md

@@ -12,7 +12,7 @@ aliases:
 
 When the same environment variable is set in multiple sources, Docker Compose follows a precedence rule to determine the value for that variable in your container's environment.
 
-This page contains information on the level of precedence each method of setting environmental variables takes.
+This page explains how Docker Compose determines the final value of an environment variable when it's defined in multiple locations.
 
 The order of precedence (highest to lowest) is as follows:
 1. Set using [`docker compose run -e` in the CLI](set-environment-variables.md#set-environment-variables-with-docker-compose-run---env).
@@ -59,25 +59,25 @@ The columns `Host OS environment` and `.env` file is listed only for illustratio
 
 Each row represents a combination of contexts where `VALUE` is set, substituted, or both. The **Result** column indicates the final value for `VALUE` in each scenario.
 
-|  # |  `docker compose run`  |  `environment` attribute  |  `env_file` attribute  |  Image `ENV` |  `Host OS` environment  |  `.env` file      | |  Result  |
-|:--:|:----------------:|:-------------------------------:|:----------------------:|:------------:|:-----------------------:|:-----------------:|:---:|:----------:|
-|  1 |   -              |   -                             |   -                    |   -          |  `VALUE=1.4`            |  `VALUE=1.3`      || -               |
-|  2 |   -              |   -                             |  `VALUE=1.6`           |  `VALUE=1.5` |  `VALUE=1.4`            |   -               ||**`VALUE=1.6`**  |
-|  3 |   -              |  `VALUE=1.7`                    |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |   -               ||**`VALUE=1.7`**  |
-|  4 |   -              |   -                             |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.5`**  |
-|  5 |`--env VALUE=1.8` |   -                             |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.8`**  |
-|  6 |`--env VALUE`     |   -                             |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.4`**  |
-|  7 |`--env VALUE`     |   -                             |   -                    |  `VALUE=1.5` |   -                     |  `VALUE=1.3`      ||**`VALUE=1.3`**  |
-|  8 |   -              |   -                             |   `VALUE`              |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.4`**  |
-|  9 |   -              |   -                             |   `VALUE`              |  `VALUE=1.5` |   -                     |  `VALUE=1.3`      ||**`VALUE=1.3`**  |
-| 10 |   -              |  `VALUE`                        |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.4`**  |
-| 11 |   -              |  `VALUE`                        |   -                    |  `VALUE=1.5` |  -                      |  `VALUE=1.3`      ||**`VALUE=1.3`**  |
-| 12 |`--env VALUE`     |  `VALUE=1.7`                    |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.4`**  |
-| 13 |`--env VALUE=1.8` |  `VALUE=1.7`                    |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.8`**  |
-| 14 |`--env VALUE=1.8` |   -                             |  `VALUE=1.6`           |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.8`**  |
-| 15 |`--env VALUE=1.8` |  `VALUE=1.7`                    |  `VALUE=1.6`           |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      ||**`VALUE=1.8`**  |
-
-### Result explanation
+|  # |  `docker compose run`  |  `environment` attribute  |  `env_file` attribute  |  Image `ENV` |  `Host OS` environment  |  `.env` file      |   Result  |
+|:--:|:----------------:|:-------------------------------:|:----------------------:|:------------:|:-----------------------:|:-----------------:|:----------:|
+|  1 |   -              |   -                             |   -                    |   -          |  `VALUE=1.4`            |  `VALUE=1.3`      | -               |
+|  2 |   -              |   -                             |  `VALUE=1.6`           |  `VALUE=1.5` |  `VALUE=1.4`            |   -               |**`VALUE=1.6`**  |
+|  3 |   -              |  `VALUE=1.7`                    |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |   -               |**`VALUE=1.7`**  |
+|  4 |   -              |   -                             |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.5`**  |
+|  5 |`--env VALUE=1.8` |   -                             |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.8`**  |
+|  6 |`--env VALUE`     |   -                             |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.4`**  |
+|  7 |`--env VALUE`     |   -                             |   -                    |  `VALUE=1.5` |   -                     |  `VALUE=1.3`      |**`VALUE=1.3`**  |
+|  8 |   -              |   -                             |   `VALUE`              |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.4`**  |
+|  9 |   -              |   -                             |   `VALUE`              |  `VALUE=1.5` |   -                     |  `VALUE=1.3`      |**`VALUE=1.3`**  |
+| 10 |   -              |  `VALUE`                        |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.4`**  |
+| 11 |   -              |  `VALUE`                        |   -                    |  `VALUE=1.5` |  -                      |  `VALUE=1.3`      |**`VALUE=1.3`**  |
+| 12 |`--env VALUE`     |  `VALUE=1.7`                    |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.4`**  |
+| 13 |`--env VALUE=1.8` |  `VALUE=1.7`                    |   -                    |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.8`**  |
+| 14 |`--env VALUE=1.8` |   -                             |  `VALUE=1.6`           |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.8`**  |
+| 15 |`--env VALUE=1.8` |  `VALUE=1.7`                    |  `VALUE=1.6`           |  `VALUE=1.5` |  `VALUE=1.4`            |  `VALUE=1.3`      |**`VALUE=1.8`**  |
+
+### Understanding precedence results
 
 Result 1: The local environment takes precedence, but the Compose file is not set to replicate this inside the container, so no such variable is set.
 
@@ -87,7 +87,7 @@ Result 3: The `environment` attribute in the Compose file defines an explicit va
 
 Result 4: The image's `ENV` directive declares the variable `VALUE`, and since the Compose file is not set to override this value, this variable is defined by image
 
-Result 5: The `docker compose run` command has the `--env` flag set which an explicit value, and overrides the value set by the image. 
+Result 5: The `docker compose run` command has the `--env` flag set with an explicit value, and overrides the value set by the image. 
 
 Result 6: The `docker compose run` command has the `--env` flag set to replicate the value from the environment. Host OS value takes precedence and is replicated into the container's environment.
 
@@ -104,3 +104,8 @@ Result 11: The `environment` attribute in the Compose file is set to replicate `
 Result 12: The `--env` flag has higher precedence than the `environment` and `env_file` attributes and is to set to replicate `VALUE` from the local environment. Host OS value takes precedence and is replicated into the container's environment.
 
 Results 13 to 15: The `--env` flag has higher precedence than the `environment` and `env_file` attributes and so sets the value. 
+
+## Next steps
+
+- [Set environment variables in Compose](set-environment-variables.md)
+- [Use variable interpolation in Compose files](variable-interpolation.md)

content/manuals/compose/how-tos/environment-variables/envvars.md

@@ -1,17 +1,17 @@
 ---
 description: Compose pre-defined environment variables
-keywords: fig, composition, compose, docker, orchestration, cli, reference
-title: Set or change pre-defined environment variables in Docker Compose
+keywords: fig, composition, compose, docker, orchestration, cli, reference, compose environment configuration, docker env variables
+title: Configure pre-defined environment variables in Docker Compose
 linkTitle: Pre-defined environment variables
 weight: 30
 aliases:
 - /compose/reference/envvars/
 - /compose/environment-variables/envvars/
 ---
 
-Compose already comes with pre-defined environment variables. It also inherits common Docker CLI environment variables, such as `DOCKER_HOST` and `DOCKER_CONTEXT`. See [Docker CLI environment variable reference](/reference/cli/docker/#environment-variables) for details.
+Docker Compose includes several pre-defined environment variables. It also inherits common Docker CLI environment variables, such as `DOCKER_HOST` and `DOCKER_CONTEXT`. See [Docker CLI environment variable reference](/reference/cli/docker/#environment-variables) for details.
 
-This page contains information on how you can set or change the following pre-defined environment variables if you need to:
+This page explains how to set or change the following pre-defined environment variables:
 
 - `COMPOSE_PROJECT_NAME`
 - `COMPOSE_FILE`
@@ -30,16 +30,19 @@ This page contains information on how you can set or change the following pre-de
 
 ## Methods to override 
 
-You can set or change the pre-defined environment variables:
-- With an [`.env` file located in your working directory](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) 
-- From the command line
-- From your [shell](variable-interpolation.md#substitute-from-the-shell)
+| Method      | Description                                  |
+| ----------- | -------------------------------------------- |
+| [`.env` file](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) | Located in the working directory.            |
+| [Shell](variable-interpolation.md#substitute-from-the-shell)       | Defined in the host operating system shell.  |
+| CLI         | Passed with `--env` or `-e` flag at runtime. |
 
 When changing or setting any environment variables, be aware of [Environment variable precedence](envvars-precedence.md).
 
-## Configure
+## Configuration details
 
-### COMPOSE\_PROJECT\_NAME
+### Project and file configuration
+
+#### COMPOSE\_PROJECT\_NAME
 
 Sets the project name. This value is prepended along with the service name to
 the container's name on startup.
@@ -64,7 +67,7 @@ constraint, you must use one of the other mechanisms.
 
 See also the [command-line options overview](/reference/cli/docker/compose/_index.md#command-options-overview-and-help) and [using `-p` to specify a project name](/reference/cli/docker/compose/_index.md#use--p-to-specify-a-project-name).
 
-### COMPOSE\_FILE
+#### COMPOSE\_FILE
 
 Specifies the path to a Compose file. Specifying multiple Compose files is supported.
 
@@ -81,7 +84,7 @@ Specifies the path to a Compose file. Specifying multiple Compose files is suppo
 
 See also the [command-line options overview](/reference/cli/docker/compose/_index.md#command-options-overview-and-help) and [using `-f` to specify name and path of one or more Compose files](/reference/cli/docker/compose/_index.md#use--f-to-specify-the-name-and-path-of-one-or-more-compose-files).
 
-### COMPOSE\_PROFILES
+#### COMPOSE\_PROFILES
 
 Specifies one or more profiles to be enabled when `docker compose up` is run.
 
@@ -100,7 +103,29 @@ COMPOSE_PROFILES=frontend,debug
 
 See also [Using profiles with Compose](../profiles.md) and the [`--profile` command-line option](/reference/cli/docker/compose/_index.md#use-profiles-to-enable-optional-services).
 
-### COMPOSE\_CONVERT\_WINDOWS\_PATHS
+#### COMPOSE\_PATH\_SEPARATOR
+
+Specifies a different path separator for items listed in `COMPOSE_FILE`.
+
+- Defaults to:
+    - On macOS and Linux to `:`
+    - On Windows to`;`
+
+#### COMPOSE\_ENV\_FILES
+
+Specifies which environment files Compose should use if `--env-file` isn't used.
+
+When using multiple environment files, use a comma as a separator. For example: 
+
+```console
+COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2
+```
+
+If `COMPOSE_ENV_FILES` is not set, and you don't provide `--env-file` in the CLI, Docker Compose uses the default behavior, which is to look for an `.env` file in the project directory.
+
+### Environment handling and container lifecycle
+
+#### COMPOSE\_CONVERT\_WINDOWS\_PATHS
 
 When enabled, Compose performs path conversion from Windows-style to Unix-style in volume definitions.
 
@@ -109,15 +134,7 @@ When enabled, Compose performs path conversion from Windows-style to Unix-style
     - `false` or `0`, to disable
 - Defaults to: `0`
 
-### COMPOSE\_PATH\_SEPARATOR
-
-Specifies a different path separator for items listed in `COMPOSE_FILE`.
-
-- Defaults to:
-    - On macOS and Linux to `:`
-    - On Windows to`;`
-
-### COMPOSE\_IGNORE\_ORPHANS
+#### COMPOSE\_IGNORE\_ORPHANS
 
 When enabled, Compose doesn't try to detect orphaned containers for the project.
 
@@ -126,7 +143,7 @@ When enabled, Compose doesn't try to detect orphaned containers for the project.
    - `false` or `0`, to disable
 - Defaults to: `0`
 
-### COMPOSE\_REMOVE\_ORPHANS
+#### COMPOSE\_REMOVE\_ORPHANS
 
 When enabled, Compose automatically removes orphaned containers when updating a service or stack. Orphaned containers are those that were created by a previous configuration but are no longer defined in the current `compose.yaml` file.
 
@@ -135,11 +152,13 @@ When enabled, Compose automatically removes orphaned containers when updating a
    - `false` or `0`, to disable automatic removal. Compose displays a warning about orphaned containers instead.
 - Defaults to: `0`
 
-### COMPOSE\_PARALLEL\_LIMIT
+#### COMPOSE\_PARALLEL\_LIMIT
 
 Specifies the maximum level of parallelism for concurrent engine calls.
 
-### COMPOSE\_ANSI
+### Output 
+
+#### COMPOSE\_ANSI
 
 Specifies when to print ANSI control characters. 
 
@@ -149,7 +168,7 @@ Specifies when to print ANSI control characters.
    - `always` or `0`, use TTY mode
 - Defaults to: `auto`
 
-### COMPOSE\_STATUS\_STDOUT
+#### COMPOSE\_STATUS\_STDOUT
 
 When enabled, Compose writes its internal status and progress messages to `stdout` instead of `stderr`. 
 The default value is false to clearly separate the output streams between Compose messages and your container's logs.
@@ -159,19 +178,18 @@ The default value is false to clearly separate the output streams between Compos
    - `false` or `0`, to disable
 - Defaults to: `0`
 
-### COMPOSE\_ENV\_FILES
+#### COMPOSE\_PROGRESS
 
-Lets you specify which environment files Compose should use if `--env-file` isn't used.
+{{< summary-bar feature_name="Compose progress" >}}
 
-When using multiple environment files, use a comma as a separator. For example: 
+Defines the type of progress output, if `--progress` isn't used. 
 
-```console
-COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2
-```
+Supported values are `auto`, `tty`, `plain`, `json`, and `quiet`.
+Default is `auto`. 
 
-If `COMPOSE_ENV_FILES` is not set, and you don't provide `--env-file` in the CLI, Docker Compose uses the default behavior, which is to look for an `.env` file in the project directory.
+### User experience
 
-### COMPOSE\_MENU
+#### COMPOSE\_MENU
 
 {{< summary-bar feature_name="Compose menu" >}}
 
@@ -182,26 +200,17 @@ When enabled, Compose displays a navigation menu where you can choose to open th
    - `false` or `0`, to disable
 - Defaults to: `1` if you obtained Docker Compose through Docker Desktop, otherwise the default is `0`
 
-### COMPOSE\_EXPERIMENTAL
+#### COMPOSE\_EXPERIMENTAL
 
 {{< summary-bar feature_name="Compose experimental" >}}
 
-This is an opt-out variable. When turned off it deactivates the experimental features such as the navigation menu or [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md).
+This is an opt-out variable. When turned off it deactivates the experimental features.
 
 - Supported values:
    - `true` or `1`, to enable
    - `false` or `0`, to disable
 - Defaults to: `1`
 
-### COMPOSE\_PROGRESS
-
-{{< summary-bar feature_name="Compose progress" >}}
-
-Defines the type of progress output, if `--progress` isn't used. 
-
-Supported values are `auto`, `tty`, `plain`, `json`, and `quiet`.
-Default is `auto`. 
-
 ## Unsupported in Compose V2
 
 The following environment variables have no effect in Compose V2.
@@ -216,3 +225,4 @@ For more information, see [Migrate to Compose V2](/manuals/compose/releases/migr
 - `COMPOSE_INTERACTIVE_NO_CLI`
 - `COMPOSE_DOCKER_CLI_BUILD`
     Use `DOCKER_BUILDKIT` to select between BuildKit and the classic builder. If `DOCKER_BUILDKIT=0` then `docker compose build` uses the classic builder to build images.
+

content/manuals/compose/how-tos/environment-variables/variable-interpolation.md

@@ -149,6 +149,21 @@ The following syntax rules apply to environment files:
   - `VAR="some\tvalue"` -> `some  value`
   - `VAR='some\tvalue'` -> `some\tvalue`
   - `VAR=some\tvalue` -> `some\tvalue`
+- Single-quoted values can span multiple lines. Example:
+
+   ```yaml
+   KEY='SOME
+   VALUE'
+   ```
+
+   If you then run `docker compose config`, you'll see:
+  
+   ```yaml
+   environment:
+     KEY: |-
+       SOME
+       VALUE
+   ```
 
 ### Substitute with `--env-file`
 

content/manuals/compose/how-tos/file-watch.md

@@ -207,10 +207,6 @@ This setup demonstrates how to use the `sync+restart` action in Docker Compose t
 > or [local setup for Docker docs](https://github.com/docker/docs/blob/main/CONTRIBUTING.md)
 > for a demonstration of Compose `watch`.
 
-## Feedback
-
-We are actively looking for feedback on this feature. Give feedback or report any bugs you may find in the [Compose Specification repository](https://github.com/compose-spec/compose-spec/pull/253).
-
 ## Reference
 
 - [Compose Develop Specification](/reference/compose-file/develop.md)