From d6717106567e82574bad7613f60a59332f614a69 Mon Sep 17 00:00:00 2001
From: Fabian Boehm <FHomborg@gmail.com>
Date: Sat, 1 Apr 2023 16:00:42 +0200
Subject: [PATCH] docs: Chapter on combining redirections

Fixes #5319
---
 doc_src/language.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc_src/language.rst b/doc_src/language.rst
index 4167a4b5c..0ba6f833c 100644
--- a/doc_src/language.rst
+++ b/doc_src/language.rst
@@ -238,6 +238,37 @@ As a convenience, the pipe ``&|`` redirects both stdout and stderr to the same p
 
 .. [#] A "pager" here is a program that takes output and "paginates" it. ``less`` doesn't just do pages, it allows arbitrary scrolling (even back!).
 
+
+Combining pipes and redirections
+--------------------------------
+
+It is possible to use multiple redirections and a pipe at the same time. In that case, they are read in this order:
+
+1. First the pipe is set up.
+2. Then the redirections are evaluated from left-to-right.
+
+This is important when any redirections reference other file descriptors with the ``&N`` syntax. When you say ``>&2``, that will redirect stdout to where stderr is pointing to *at that time*.
+
+Consider this helper function::
+
+  # Just make a function that prints something to stdout and stderr
+  function print
+      echo out
+      echo err >&2
+  end
+
+Now let's see a few cases::
+
+  # Redirect both stderr and stdout to less
+  # (can also be spelt as `&|`)
+  print 2>&1 | less
+
+  # Show the "out" on stderr, silence the "err"
+  print >&2 2>/dev/null
+  
+  # Silence both
+  print >/dev/null 2>&1
+
 .. _syntax-job-control:
 
 Job control