Workflow output definition

docs/channel.md

@@ -398,7 +398,7 @@ The `interval` method emits an incrementing index (starting from zero) at a peri
 Channel.interval('1s').view()
 ```
 
-The above snippet will emit 0, 1, 2, and so on, every second, forever. You can use an operator such as {ref}`operator-take`, {ref}`operator-timeout`, or {ref}`operator-until` to close the channel based on a stopping condition.
+The above snippet will emit 0, 1, 2, and so on, every second, forever. You can use an operator such as {ref}`operator-take` or {ref}`operator-until` to close the channel based on a stopping condition.
 
 An optional closure can be used to transform the index. Additionally, returning `Channel.STOP` will close the channel. For example:
 
@@ -467,17 +467,9 @@ See also: [channel.fromList](#fromlist) factory method.
 This feature requires the `nextflow.preview.topic` feature flag to be enabled.
 :::
 
-A *topic* is a channel type introduced as of Nextflow 23.11.0-edge along with {ref}`channel-type-value` and
-{ref}`channel-type-queue`.
+A *topic channel*, similar to a *queue channel*, is a non-blocking unidirectional FIFO queue, with the ability to implicitly receive values from multiple sources based on a *topic name*.
 
-A *topic channel*, similarly to a *queue channel*, is non-blocking unidirectional FIFO queue, however it connects
-multiple *producer* processes with multiple *consumer* processes or operators.
-
-:::{tip}
-You can think about it as a channel that is shared across many different process using the same *topic name*.
-:::
-
-A process output can be assigned to a topic using the `topic` option on an output, for example:
+A process output can be sent to a topic using the `topic` option, for example:
 
 ```groovy
 process foo {
@@ -491,21 +483,38 @@ process bar {
 }
 ```
 
-The `channel.topic` method allows referencing the topic channel with the specified name, which can be used as a process
-input or operator composition as any other Nextflow channel:
+Additionally, the `topic:` section of a workflow definition can be used to send channels defined in a workflow to a topic:
+
+```groovy
+workflow foobar {
+    main:
+    foo()
+    bar()
+
+    topic:
+    foo.out >> 'my_topic'
+    bar.out >> 'my_topic'
+
+    emit:
+    bar.out
+}
+```
+
+Finally, the `Channel.topic()` factory can be used to consume the resulting channel for a given topic name, which can be used like any other channel:
 
 ```groovy
 channel.topic('my-topic').view()
 ```
 
-This approach is a convenient way to collect related items from many different sources without explicitly defining
-the logic connecting many different queue channels altogether, commonly using the `mix` operator.
+The same topic can be consumed using `Channel.topic()` any number of times, similar to referencing a channel multiple times.
+
+This approach is a convenient way to collect related items from many different sources without all of the logic that is required to connect them, e.g. using the `mix` operator.
 
 :::{warning}
-Any process that consumes a channel topic should not send any outputs to that topic, or else the pipeline will hang forever.
+Avoid creating a circular dependency within a topic (e.g. a process that consumes a channel topic and sends outputs to that same topic), as it will cause the pipeline to run forever.
 :::
 
-See also: {ref}`process-additional-options` for process outputs.
+See also: {ref}`process-additional-options` for process outputs and the {ref}`workflow topic section <workflow-topics>`.
 
 (channel-value)=
 

docs/cli.md

@@ -1109,6 +1109,8 @@ Checking nextflow-io/hello ...
 checkout-out at AnyObjectId[1c3e9e7404127514d69369cd87f8036830f5cf64] - revision: 1c3e9e7404 [v1.1]
 ```
 
+(cli-run)=
+
 ### run
 
 Execute a pipeline.

docs/operator.md

@@ -1466,6 +1466,8 @@ An optional {ref}`closure <script-closure>` can be used to transform each item b
 :language: console
 ```
 
+(operator-take)=
+
 ## take
 
 *Returns: queue channel*
@@ -1669,6 +1671,8 @@ The difference between `unique` and `distinct` is that `unique` removes *all* du
 
 See also: [distinct](#distinct)
 
+(operator-until)=
+
 ## until
 
 *Returns: queue channel*

docs/process.md

@@ -1008,7 +1008,7 @@ Some caveats on glob pattern behavior:
 Although the input files matching a glob output declaration are not included in the resulting output channel, these files may still be transferred from the task scratch directory to the original task work directory. Therefore, to avoid unnecessary file copies, avoid using loose wildcards when defining output files, e.g. `path '*'`. Instead, use a prefix or a suffix to restrict the set of matching files to only the expected ones, e.g. `path 'prefix_*.sorted.bam'`.
 :::
 
-Read more about glob syntax at the following link [What is a glob?][what is a glob?]
+Read more about glob syntax at the following link [What is a glob?][glob]
 
 ### Dynamic output file names
 
@@ -2163,6 +2163,10 @@ The following options are available:
 
 ### publishDir
 
+:::{deprecated} 24.04.0
+The `publishDir` directive has been deprecated in favor of the new {ref}`workflow output definition <workflow-output-dsl>`.
+:::
+
 The `publishDir` directive allows you to publish the process output files to a specified folder. For example:
 
 ```groovy
@@ -2668,4 +2672,3 @@ process foo {
 ```
 
 [glob]: http://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob
-[what is a glob?]: http://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob