1 files changed, 58 insertions, 4 deletions
diff --git a/doc/user/bas_verb b/doc/user/bas_verb
index d7f2904..6165878 100644
--- a/doc/user/bas_verb
+++ b/doc/user/bas_verb
@@ -1,12 +1,15 @@
 @Section
-   @Title { Verbatim text }
+   @Title { Verbatim and piped text }
    @Tag { verbatim }
 @Begin
 @PP
 The @Code "@Verbatim" symbol
-@FootNote { Prior to Version 3.13 the @Code "@Verbatim" symbol was
-implemented in a way that restricted its availability to Unix
-systems only.  This restriction no longer applies. }
+@FootNote {
+Prior to Version 3.13 the @Code "@Verbatim" symbol was restricted to Unix
+systems only.  This restriction no longer applies to @Code "@Verbatim" and
+{@Code "@RawVerbatim"}, but it does apply to {@Code "@Pipe"},
+{@Code "@PipeVerbatim"}, and {@Code "@PipeRawVerbatim"}.
+}
 prints the following object exactly as
 verbatim.sym @Index @Code "@Verbatim"
 it appears in the input file.  All special meanings for characters,
@@ -47,4 +50,55 @@ all white spaces preceding the closing brace.  However, the alternative
 raw.verbatim.sym @Index @Code "@RawVerbatim"
 as soon as a newline character is reached; in other words, it will
 preserve all white spaces following the first newline.
+@PP
+The @Code "@Pipe" symbol (available on Unix-style systems only) may be
+pipe.sym @Index @Code "@Pipe"
+used to pipe some text through a Unix command.  For example,
+@ID @Code lines @Break @Verbatim {
+@ID lines @Break "sort" @Pipe {
+Gaskell, Elizabeth
+Lawrence, D. H.
+Austen, Jane
+Dickens, Charles
+}
+}
+will cause the object between braces following @Code "@Pipe" to be
+piped without interpretation through the Unix @Code "sort" command; its
+output is the result of the @Code "@Pipe" command, here made into a
+display preserving the line breaks in the output.  The final result will
+be the four authors, one per line, in alphabetical order.  We can't show
+this result to you because that would make this manual not compilable on
+non-Unix systems.
+@PP
+The double quotes around @Code sort are not necessary in this example,
+but may be in more complex ones.  For example, one can see just the
+first few lines of the sorted result using
+@ID @Code @Verbatim { "sort | head" @Pipe ... }
+and here the quotes are necessary because @Code "|" is one of the special
+characters that need quoting, according to Section {@NumberOf characters}.
+The quotes also serve to group the command into a single Lout object.
+@PP
+Some Unix commands don't need any input, and then the object following
+@Code "@Pipe" may be empty.  For example,
+@ID @Code @Verbatim { "ls" @Pipe {} }
+will list the files of the current directory.
+@PP
+Any Lout symbols in the result of the @Code "@Pipe" symbol, such as
+{@Code "@PP"}, {@Code "@Box"}, and so on, will be interpreted in the
+usual way.  This is convenient because it allows you to write your
+own Unix commands that include Lout symbols in their output.  However,
+sometimes it is preferable if the output is treated verbatim.  For
+example,
+@ID @Code @Verbatim { "pwd" @Pipe {} }
+attempts to print the current working directory, but this will not
+come out well because the output contains {@Code "/"} symbols, which
+Lout will then attempt to interpret as Lout symbols.  To avoid this
+problem, use @Code "@PipeVerbatim" instead of {@Code "@Pipe"}:
+pipeverbatim.sym @Index @Code "@PipeVerbatim"
+piperawverbatim.sym @Index @Code "@PipeRawVerbatim"
+@ID @Code @Verbatim { "pwd" @PipeVerbatim {} }
+This causes the output of the command to be enclosed in
+@Code "@Verbatim @Begin" and {@Code "@End @Verbatim"}.  There is
+also a @Code "@PipeRawVerbatim" symbol which encloses the output in
+@Code "@RawVerbatim" rather than the ordinary {@Code "@Verbatim"}.
 @End @Section