docs: Update config page (#6642) [ci fast]

Co-authored-by: Ben Sherman <bentshermann@gmail.com>

Author: christopher-hakkaart

docs/config.md

@@ -2,50 +2,48 @@
 
 # Configuration
 
-## Configuration file
+## Configuration files
 
-When a pipeline script is launched, Nextflow looks for configuration files in multiple locations. Since each configuration file may contain conflicting settings, they are applied in the following order (from lowest to highest priority):
+When you launch a pipeline script, Nextflow detects configuration files from multiple sources and applies them in the following order (from lowest to highest priority):
 
-1. The config file `$HOME/.nextflow/config` (or `$NXF_HOME/config` when {ref}`NXF_HOME <nxf-env-vars>` is set).
-2. The config file `nextflow.config` in the project directory
-3. The config file `nextflow.config` in the launch directory
-4. Config files specified using the `-c <config-files>` option
+1. `$NXF_HOME/config` (defaults to `$HOME/.nextflow/config`)
+2. `nextflow.config` in the project directory
+3. `nextflow.config` in the launch directory
+4. Config files specified with `-c <config-files>`
 
 :::{tip}
-You can alternatively use the `-C <config-file>` option to specify a fixed set of configuration files and ignore all other files.
+You can use the `-C <config-file>` option to specify a fixed set of configuration files and ignore all other files.
 :::
 
 (config-syntax)=
 
 ## Syntax
 
-The Nextflow configuration syntax is based on the Nextflow script syntax. It is designed for setting configuration options in a declarative manner while also allowing for dynamic expressions where appropriate.
+Nextflow configuration uses a similar syntax as Nextflow scripts. Configuration options must be set declaratively, but the value of a config option can be an arbitrary expression.
 
-A Nextflow config file may consist of any number of *assignments*, *blocks*, and *includes*. Config files may also contain comments in the same manner as scripts.
-
-See {ref}`syntax-page` for more information about the Nextflow script syntax.
+A config file may contain any number of [assignments](#assignments), [blocks](#blocks), and [includes](#includes). You can add comments just like in scripts.
 
 ### Assignments
 
-A config assignment consists of a config option and an expression separated by an equals sign:
+A config assignment sets a config option to a value:
 
 ```groovy
 workDir = 'work'
 docker.enabled = true
 process.maxErrors = 10
 ```
 
-A config option consists of an *option name* prefixed by any number of *scopes* separated by dots. Config scopes are used to group related config options. See {ref}`config-options` for the full set of config options.
+The config option consists of an *option name* prefixed by any number of *scopes*. Scopes group related config options. See {ref}`config-options` for the full set of config options.
 
-The expression is typically a literal value such as a number, boolean, or string. However, any expression can be used:
+The value is typically a literal value, such as a number, boolean, or string. However, you can use any {ref}`expression <syntax-expressions>`:
 
 ```groovy
 params.helper_file = "${projectDir}/assets/helper.txt"
 ```
 
 ### Blocks
 
-A config scope can also be specified as a block, which may contain multiple configuration options. For example:
+You can specify config options in the same scope as a block:
 
 ```groovy
 // dot syntax
@@ -59,7 +57,7 @@ docker {
 }
 ```
 
-As a result, deeply nested config options can be assigned in various ways. For example, the following three assignments are equivalent:
+As a result, deeply nested config options can be assigned in multiple ways. The following three assignments are equivalent:
 
 ```groovy
 executor.retry.maxAttempt = 5
@@ -77,7 +75,7 @@ executor {
 
 ### Includes
 
-A configuration file can include any number of other configuration files using the `includeConfig` keyword:
+You can include configuration files in other configuration files with the `includeConfig` keyword:
 
 ```groovy
 process.executor = 'sge'
@@ -90,12 +88,10 @@ includeConfig 'path/extra.config'
 Relative paths are resolved against the location of the including file.
 
 :::{note}
-Config includes can also be specified within config blocks. However, config files should only be included at the top level or in a [profile](#config-profiles) so that the included config file is valid on its own and in the context in which it is included.
+Config files should only be included at the top level or in a [profile](#config-profiles). This ensures the included config file is valid on its own and in the context in which it is included.
 :::
 
-(config-constants)=
-
-## Constants
+## Constants and functions
 
 The following constants are globally available in a Nextflow configuration file:
 
@@ -113,20 +109,18 @@ The following constants are globally available in a Nextflow configuration file:
 `secrets: Map<String,String>`
 : Map of pipeline secrets. See {ref}`secrets-page` for more information.
 
-## Functions
-
 The following functions are globally available in a Nextflow configuration file:
 
 `env( name: String ) -> String`
-: :::{versionadded} 24.11.0-edge
+: :::{versionadded} 25.04.0
   :::
 : Get the value of the environment variable with the specified name in the Nextflow launch environment.
 
 (config-params)=
 
 ## Parameters
 
-Pipeline parameters can be defined in the config file using the `params` scope:
+You can define pipeline parameters in config files using the `params` scope:
 
 ```groovy
 // dot syntax
@@ -141,10 +135,10 @@ params {
 ```
 
 :::{note}
-When including a config file, the included config is evaluated with the parameters that are defined before the include. Parameters defined after the include are not visible to the included config.
+When including a config file, the included config is evaluated with the parameters defined before the include. The included config cannot see parameters defined after the include.
 :::
 
-As a best practice, declare parameters in the config file only if they are used by other config options. If a parameter is used within the script, declare it there and override it in config profiles as needed. For example:
+You should declare parameters in the config file only when other config options use them. When you use a parameter in the script, you should declare it there and override it in config profiles as needed:
 
 ```nextflow
 // main.nf
@@ -166,13 +160,13 @@ profiles {
 }
 ```
 
-See {ref}`cli-params` for information about how pipeline parameters are resolved at runtime.
+See {ref}`cli-params` for information about how Nextflow resolves pipeline parameters at runtime.
 
 (config-process)=
 
 ## Process configuration
 
-The `process` scope allows you to specify {ref}`process directives <process-reference>` separately from the pipeline code.
+You can use the `process` scope to specify {ref}`process directives <process-reference>` separately from the pipeline code.
 
 For example:
 
@@ -184,13 +178,13 @@ process {
 }
 ```
 
-By using this configuration, all processes in your pipeline will be executed through the SGE cluster, with the specified settings.
+This configuration executes all processes using the SGE executor with the given settings.
 
 (config-process-selectors)=
 
 ### Process selectors
 
-The `withLabel` selectors allow the configuration of all processes annotated with a {ref}`process-label` directive as shown below:
+You can use the `withLabel` selector to configure all processes annotated with a {ref}`process-label` directive:
 
 ```groovy
 process {
@@ -202,9 +196,9 @@ process {
 }
 ```
 
-The above configuration example assigns 16 cpus, 64 Gb of memory and the `long` queue to all processes annotated with the `big_mem` label.
+This configuration assigns 16 CPUs, 64 GB of memory, and the `long` queue to all processes with the `big_mem` label.
 
-In the same manner, the `withName` selector allows the configuration of a specific process in your pipeline by its name. For example:
+You can use the `withName` selector to configure a specific process by its name:
 
 ```groovy
 process {
@@ -216,19 +210,22 @@ process {
 }
 ```
 
-The `withName` selector applies both to processes defined with the same name and processes included under the same alias. For example, `withName: hello` will apply to any process originally defined as `hello`, as well as any process included under the alias `hello`.
+The `withName` selector matches both:
 
-Furthermore, selectors for the alias of an included process take priority over selectors for the original name of the process. For example, given a process defined as `hello` and included as `sayHello`, the selectors `withName: hello` and `withName: sayHello` will both be applied to the process, with the second selector taking priority over the first.
+- Processes defined with that name
+- Processes included under that alias
+
+When you include a process with an alias, selectors for the alias take priority over selectors for the original name. For example, if you define a process as `hello` and include it as `sayHello`, both `withName: hello` and `withName: sayHello` apply, with `withName: sayHello` taking priority.
 
 :::{tip}
-Label and process names do not need to be enclosed with quotes, provided the name does not include special characters (`-`, `!`, etc) and is not a keyword or a built-in type identifier. When in doubt, you can enclose the label name or process name with single or double quotes.
+You don't need to enclose label and process names in quotes unless they contain special characters (`-`, `!`, etc.) or are keywords or built-in type identifiers.
 :::
 
 (config-selector-expressions)=
 
 ### Selector expressions
 
-Both label and process name selectors allow the use of a regular expression in order to apply the same configuration to all processes matching the specified pattern condition. For example:
+You can use regular expressions in process selectors to apply the same configuration to all processes matching the pattern:
 
 ```groovy
 process {
@@ -239,9 +236,9 @@ process {
 }
 ```
 
-The above configuration snippet requests 2 cpus and 4 GB of memory for processes labeled as `hello` or `bye`.
+This configuration requests 2 CPUs and 4 GB of memory for processes labeled as `hello` or `bye`.
 
-A process selector can be negated prefixing it with the special character `!`. For example:
+You can negate a selector expression by prefixing it with the special character `!`:
 
 ```groovy
 process {
@@ -251,13 +248,13 @@ process {
 }
 ```
 
-The above configuration snippet sets 2 cpus for every process labeled as `hello` and 4 cpus to every process *not* labeled as `hello`. It also specifies the `long` queue for every process whose name does *not* start with `align`.
+This configuration sets 2 CPUs for processes labeled as `hello` and 4 CPUs for all processes *not* labeled as `hello`. It also specifies the `long` queue for processes whose name does *not* start with `align`.
 
 (config-selector-priority)=
 
 ### Selector priority
 
-Process configuration settings are applied to a process in the following order (from lowest to highest priority):
+Nextflow applies process configuration settings in the following order (from lowest to highest priority):
 
 1. Process configuration settings (without a selector)
 2. Process directives in the process definition
@@ -277,17 +274,18 @@ process {
 }
 ```
 
-With the above configuration:
-- All processes will use 4 cpus (unless otherwise specified in their process definition).
-- Processes annotated with the `hello` label will use 8 cpus.
-- Any process named `bye` (or imported as `bye`) will use 16 cpus.
-- Any process named `bye` (or imported as `bye`) invoked by a workflow named `aloha` will use 32 cpus.
+This configuration:
+
+- Sets 4 CPUs for all processes (unless otherwise specified in their process definition)
+- Sets 8 CPUs for processes annotated with the `hello` label
+- Sets 16 CPUs for any process named `bye` (or imported as `bye`)
+- Sets 32 CPUs for any process named `bye` (or imported as `bye`) invoked by a workflow named `aloha`
 
 (config-profiles)=
 
 ## Config profiles
 
-Configuration files can define one or more *profiles*. A profile is a set of configuration settings that can be selected during pipeline execution using the `-profile` command line option.
+Configuration files can define one or more *profiles*. A profile is a set of configuration settings that can be selected at runtime using the `-profile` command line option.
 
 Configuration profiles are defined in the `profiles` scope. For example:
 
@@ -311,44 +309,18 @@ profiles {
 }
 ```
 
-The above configuration defines three profiles: `standard`, `cluster`, and `cloud`. Each profile provides a different configuration for a given execution environment. The `standard` profile is used by default when no profile is specified.
+This configuration defines three profiles: `standard`, `cluster`, and `cloud`. Each profile provides a different configuration for a given execution environment. When you do not specify a profile, Nextflow uses the `standard` profile by default.
 
-Configuration profiles can be specified at runtime as a comma-separated list:
+You can enable configuration profiles at runtime as a comma-separated list:
 
 ```bash
-nextflow run <your script> -profile standard,cloud
-```
-
-Config profiles are applied in the order in which they were defined in the config file, regardless of the order they are specified on the command line.
-
-:::{versionadded} 25.02.0-edge
-When using the {ref}`strict config syntax <updating-config-syntax>`, profiles are applied in the order in which they are specified on the command line.
-:::
-
-:::{danger}
-When defining a profile in the config file, avoid using both the dot and block syntax for the same scope. For example:
-
-```groovy
-profiles {
-    cluster {
-        process.memory = '2 GB'
-        process {
-            cpus = 2
-        }
-    }
-}
+nextflow run main.nf -profile standard,cloud
 ```
 
-Due to a limitation of the legacy config parser, the first setting will be overwritten by the second:
-
-```console
-$ nextflow config -profile cluster
-process {
-   cpus = 2
-}
-```
+Nextflow applies config profiles in the order in which they were defined in the config, regardless of the order you specify them on the command line.
 
-This limitation can be avoided by using the {ref}`strict config syntax <updating-config-syntax>`.
+:::{versionadded} 25.04.0
+When using the {ref}`strict syntax <strict-syntax-page>`, Nextflow applies profiles in the order you specify them on the command line.
 :::
 
 (config-workflow-handlers)=
@@ -363,7 +335,6 @@ You can define workflow event handlers in the config file:
 
 ```groovy
 workflow.onComplete = {
-    // any workflow property can be used here
     println "Pipeline complete"
     println "Command line: $workflow.commandLine"
 }

docs/reference/stdlib-types.md

@@ -731,7 +731,7 @@ The following methods are available for listing and traversing directories:
 : Returns the first-level elements (files and directories) in a directory.
 
 `listFiles() -> Iterable<Path>`
-: :::{deprecated}
+: :::{deprecated} 26.04.0
   Use `listDirectory()` instead.
   :::
 : Returns the first-level elements (files and directories) in a directory.

docs/reference/syntax.md

@@ -602,6 +602,8 @@ catch( IOException e ) {
 
 The try block will be executed, and if an error is raised and matches the expected error type of a catch clause, the code in that catch clause will be executed. If no catch clause is matched, the error will be raised to the next enclosing try/catch statement, or to the Nextflow runtime.
 
+(syntax-expressions)=
+
 ## Expressions
 
 An expression represents a value. A *literal* value is an expression whose value is known at compile-time, such as a number, string, or boolean. All other expressions must be evaluated at run-time.
@@ -1010,4 +1012,3 @@ The following legacy features were excluded from this page because they are depr
 - The `addParams` and `params` clauses of include declarations. See {ref}`module-params` for more information.
 - The `when:` section of a process definition. See {ref}`process-when` for more information.
 - The `shell:` section of a process definition. See {ref}`process-shell` for more information.
-- The implicit `it` closure parameter. See {ref}`script-closure` for more information.