Document formal script syntax

docs/channel.md

@@ -52,7 +52,7 @@ process foo {
 
 workflow {
   result = foo(1)
-  result.view { txt -> "Result: ${txt}" }
+  result.view { file -> "Result: ${file}" }
 }
 ```
 

docs/developer/plugins.md

@@ -7,6 +7,8 @@ This page describes how to create, test, and publish third-party plugins.
 
 The best way to get started with your own plugin is to refer to the [nf-hello](https://github.com/nextflow-io/nf-hello) repository. This repository provides a minimal plugin implementation with several examples of different extension points and instructions for building, testing, and publishing.
 
+Plugins can be written in Java or Groovy.
+
 The minimal dependencies are as follows:
 
 ```groovy

docs/module.md

@@ -2,15 +2,15 @@
 
 # Modules
 
-In Nextflow, a **module** is a script that may contain functions, processes, and workflows (collectively referred to as *components*). A module can be included in other modules or pipeline scripts and even shared across workflows.
+Nextflow scripts can include **definitions** (workflows, processes, and functions) from other scripts. When a script is included in this way, it is referred to as a **module**. Modules can be included by other modules or pipeline scripts and can even be shared across workflows.
 
 :::{note}
 Modules were introduced in DSL2. If you are still using DSL1, see the {ref}`dsl1-page` page to learn how to migrate your Nextflow pipelines to DSL2.
 :::
 
 ## Module inclusion
 
-A component defined in a module script can be imported into another Nextflow script using the `include` keyword.
+Any definition in a module can be included into another Nextflow script using the `include` keyword.
 
 For example:
 
@@ -23,7 +23,7 @@ workflow {
 }
 ```
 
-The above snippet imports a process named `foo`, defined in the module script, into the main execution context. This way, `foo` can be invoked in the `workflow` scope.
+The above snippet imports a process named `foo`, defined in the module, into the main execution context. This way, `foo` can be invoked in the `workflow` scope.
 
 Nextflow implicitly looks for the script file `./some/module.nf`, resolving the path against the *including* script location.
 
@@ -57,7 +57,7 @@ Module directories allow the use of module scoped binaries scripts. See [Module
 
 ## Multiple inclusions
 
-A Nextflow script can include any number of modules, and an `include` statement can import any number of components from a module. Multiple components can be included from the same module by using the syntax shown below:
+A Nextflow script can include any number of modules, and an `include` statement can import any number of definitions from a module. Multiple definitions can be included from the same module by using the syntax shown below:
 
 ```groovy
 include { foo; bar } from './some/module'
@@ -73,7 +73,7 @@ workflow {
 
 ## Module aliases
 
-When including a module component, it's possible to specify an *alias* with the `as` keyword. Aliasing allows you to avoid module name clashes, by assigning them different names in the including context. For example:
+When including definition from a module, it's possible to specify an *alias* with the `as` keyword. Aliasing allows you to avoid module name clashes, by assigning them different names in the including context. For example:
 
 ```groovy
 include { foo } from './some/module'
@@ -85,7 +85,7 @@ workflow {
 }
 ```
 
-You can even include the same component multiple times under different names:
+You can even include the same definition multiple times under different names:
 
 ```groovy
 include { foo; foo as bar } from './some/module'
@@ -101,10 +101,10 @@ workflow {
 ## Module parameters
 
 :::{deprecated} 24.07.0-edge
-As a best practice, parameters should be used in the entry workflow and passed to functions / processes / workflows as explicit inputs.
+As a best practice, parameters should be used in the entry workflow and passed to workflows, processes, and functions as explicit inputs.
 :::
 
-A module script can define parameters using the same syntax as a Nextflow workflow script:
+A module can define parameters using the same syntax as a Nextflow workflow script:
 
 ```groovy
 params.foo = 'Hello'
@@ -184,9 +184,9 @@ Ciao world!
 
 ## Module templates
 
-The module script can be defined in an external {ref}`template <process-template>` file. The template file can be placed in the `templates` directory where the module script is located.
+Process script {ref}`templates <process-template>` can be included alongside a module in the `templates` directory.
 
-For example, suppose we have a project L with a module script that defines two processes, P1 and P2, both of which use templates. The template files can be made available in the local `templates` directory:
+For example, suppose we have a project L with a module that defines two processes, P1 and P2, both of which use templates. The template files can be made available in the local `templates` directory:
 
 ```
 Project L
@@ -210,15 +210,15 @@ Pipeline B
 └── main.nf
 ```
 
-With the possibility to keep the template files inside the project L, A and B can use the modules defined in L without any changes. A future project C would do the same, just cloning L (if not available on the system) and including its module script.
+With the possibility to keep the template files inside the project L, A and B can use the modules defined in L without any changes. A future project C would do the same, just cloning L (if not available on the system) and including its module.
 
 Beside promoting the sharing of modules across pipelines, there are several advantages to keeping the module template under the script path:
 
-1. module components are *self-contained*,
-2. module components can be tested independently from the pipeline(s) that import them,
-3. it is possible to create libraries of module components.
+1. modules are *self-contained*,
+2. modules can be tested independently from the pipeline(s) that import them,
+3. it is possible to create libraries of modules.
 
-Ultimately, having multiple template locations allows a more structured organization within the same project. If a project has several module components, and all of them use templates, the project could group module scripts and their templates as needed. For example:
+Ultimately, having multiple template locations allows a more structured organization within the same project. If a project has several modules, and all of them use templates, the project could group module scripts and their templates as needed. For example:
 
 ```
 baseDir

docs/process.md

@@ -234,7 +234,7 @@ In the above example, `$USER` is treated as a Bash variable, while `!{str}` is t
 
 ### Native execution
 
-Whereas the `script` block defines a script that is executed as a separate job, the `exec` block simply executes the code that it is given.
+Whereas the `script` block defines a script that is executed as a separate job, the `exec` block simply executes the code that it is given, without launching a job.
 
 For example:
 
@@ -876,7 +876,7 @@ process randomNum {
 
 workflow {
   numbers = randomNum()
-  numbers.view { v -> "Received: ${v.text}" }
+  numbers.view { file -> "Received: ${file.text}" }
 }
 ```
 

docs/reference/feature-flags.md

@@ -1,4 +1,4 @@
-(feature-flags)=
+(config-feature-flags)=
 
 # Feature flags
 

docs/reference/operator.md

@@ -256,7 +256,7 @@ Channel
     .collectFile( name: 'result.fa', sort: { v -> v.size() } ) {
         v -> v.sequence
     }
-    .view { v -> v.text }
+    .view { fa -> fa.text }
 ```
 
 :::{warning}
@@ -748,10 +748,10 @@ Available options:
 : The zero-based index of each item to use as the matching key. Can also be a list of indices, e.g. `by: [0, 2]` (default: `[0]`).
 
 `failOnDuplicate`
-: When `true`, an error is reported when the operator receives multiple items from the same channel with the same key (default: `false`). Value is set to `true` if {ref}`strict mode <feature-flags>` is enabled.
+: When `true`, an error is reported when the operator receives multiple items from the same channel with the same key (default: `false`). Value is set to `true` if {ref}`strict mode <config-feature-flags>` is enabled.
 
 `failOnMismatch`
-: When `true`, an error is reported when the operator receives an item from one channel for which there no matching item from the other channel (default: `false`). Value is set to `true` if {ref}`strict mode <feature-flags>` is enabled. This option cannot be used with `remainder`.
+: When `true`, an error is reported when the operator receives an item from one channel for which there no matching item from the other channel (default: `false`). Value is set to `true` if {ref}`strict mode <config-feature-flags>` is enabled. This option cannot be used with `remainder`.
 
 `remainder`
 : When `true`, unmatched items are emitted at the end, otherwise they are discarded (default: `false`). 

docs/reference/stdlib.md

@@ -56,9 +56,6 @@ The following constants are globally available in a Nextflow script:
 
 `params`
 : Map of workflow parameters specified in the config file or as command line options.
-: :::{note}
-  As a best practice, parameters should only be used in the entry workflow.
-  :::
 
 `projectDir`
 : Alias of `workflow.projectDir`.
@@ -330,18 +327,6 @@ The following methods are available for a `Duration` object:
 `getSeconds()`, `toSeconds()`
 : Get the duration value in seconds (rounded down).
 
-(stdlib-list)=
-
-## List
-
-TODO
-
-(stdlib-map)=
-
-## Map
-
-TODO
-
 (stdlib-types-memoryunit)=
 
 ## MemoryUnit
@@ -700,15 +685,3 @@ The following methods are available for splitting and counting the records in fi
 
 `splitText()`
 : Splits a text file into a list of lines. See the {ref}`operator-splittext` operator for available options.
-
-(stdlib-set)=
-
-## Set
-
-TODO
-
-(stdlib-string)=
-
-## String
-
-TODO

docs/reference/syntax.md

@@ -63,7 +63,7 @@ The first line of a script can be a [shebang](https://en.wikipedia.org/wiki/Sheb
 
 ### Feature flag
 
-A feature flag declaration is an assignment, where the target should be a valid {ref}`feature flag <feature-flags>` and the source should be a literal (e.g. number, string, boolean):
+A feature flag declaration is an assignment, where the target should be a valid {ref}`feature flag <config-feature-flags>` and the source should be a literal (e.g. number, string, boolean):
 
 ```groovy
 nextflow.preview.topic = true
@@ -629,8 +629,6 @@ Logic unconfined.
 
 Note that a slashy string cannot be empty because it would become a line comment.
 
-Refer to {ref}`stdlib-string` for the set of available string operations.
-
 ### Dynamic string
 
 Double-quoted strings can be interpolated using the `${}` placeholder, which can contain any expression:
@@ -669,8 +667,6 @@ A list literal consists of square brackets with a comma-separated list of zero o
 [1, 2, 3]
 ```
 
-Refer to {ref}`stdlib-list` for the set of available list operations.
-
 ### Map
 
 A map literal consists of square brackets with a comma-separated list of one or more key-value pairs, with the key and value separated by a colon:
@@ -693,8 +689,6 @@ def x = 'foo'
 // -> ['foo': 1]
 ```
 
-Refer to {ref}`stdlib-map` for the set of available map operations.
-
 ### Closure
 
 A closure, also known as an anonymous function, consists of a parameter list followed by zero or more statements, wrapped in curly braces: