>From f6dde86126f8c4f9f2c6f555e9af0aa78deec914 Mon Sep 17 00:00:00 2001
From: Assaf Gordon <address@hidden>
Date: Thu, 12 Oct 2017 00:26:14 -0600
Subject: [PATCH] doc: fix incorrect line-wrapping example

Reported by Bamber Ward in https://bugs.gnu.org/28140 .

* doc/sed.texi (Line length adjustment): Fix sed script;
  Rewrite example to long script with inlined comments;
  Remove second example.
---
 doc/sed.texi | 90 +++++++++++++++++++++++++++++-------------------------------
 1 file changed, 43 insertions(+), 47 deletions(-)

diff --git a/doc/sed.texi b/doc/sed.texi
index cc47b66..c80bf1f 100644
--- a/doc/sed.texi
+++ b/doc/sed.texi
@@ -4698,7 +4698,7 @@ consecutive words spanning multiple lines, and the @code{b} command for
 branching.
 @xref{Multiline techniques} and @ref{Branching and flow control}.
 
-These (somewhat contrived) examples deal with formatting and wrapping
+This (somewhat contrived) example deal with formatting and wrapping
 lines of text of the following input file:
 
 @example
@@ -4715,70 +4715,66 @@ of foolishness,
 @end group
 @end example
 
-The following command will wrap lines at 40 characters:
address@hidden The following sed program wraps lines at 40 characters:
 @codequoteundirected on
 @codequotebacktick on
 @example
 @group
-$ sed -E ':x @{N ; s/\n/ /g ; s/(address@hidden,address@hidden)/\1\n/ ; /\n/!bx ; P ; address@hidden' \
-      two-cities-mix.txt
-It was the best of times, it was the wor
-st of times, it was the age of wisdom, i
-t was the age of foolishness,
+$ cat wrap40.sed
+# outer loop
+:x
+
+# Appead a newline followed by the next input line to the pattern buffer
+N
+
+# Remove all newlines from the pattern buffer
+s/\n/ /g
+
+
+# Inner loop
+:y
+
+# Add a newline after the first 40 characters
+s/(address@hidden,address@hidden)/\1\n/
+
+# If there is a newline in the pattern buffer
+# (i.e. the previous substitution added a newline)
+/\n/ @{
+    # There are newlines in the pattern buffer -
+    # print the content until the first newline.
+    P
+
+   # Remove the printed characters and the first newline
+   s/.*\n//
+
+   # branch to label 'y' - repeat inner loop
+   by
+ @}
+
+# No newlines in the pattern buffer - Branch to label 'x' (outer loop)
+# and read the next input line
+bx
 @end group
 @end example
 @codequoteundirected off
 @codequotebacktick off
 
-The following command will split lines by comma character:
+
+
address@hidden The wrapped output:
 @codequoteundirected on
 @codequotebacktick on
 @example
 @group
-$ sed -E ':x @{N ; s/\n/ /g ; s/,/,\n/ ; /\n/!bx ; s/^ *// ; P ; address@hidden' \
-      two-cities-mix.txt
-It was the best of times,
-it was the worst of times,
-it was the age of wisdom,
-it was the age of foolishness,
+$ sed -E -f wrap40.sed two-cities-mix.txt
+It was the best of times, it was the wor
+st of times, it was the age of wisdom, i
+t was the age of foolishness,
 @end group
 @end example
 @codequoteundirected off
 @codequotebacktick off
 
-Both examples use similar construct:
-
address@hidden @bullet
-
address@hidden
-The @samp{:x} is a label. It will be used later by the @command{b} command
-to jump to the beginning of the @command{sed} program without starting
-a new cycle.
-
address@hidden
-The @samp{N} command reads the next line from the input file, and appends
-it to the existing content of the pattern space (with a newline preceding it).
-
address@hidden
-The first @samp{s/\n/ /g} command replaces all newlines with spaces, discarding
-the line structure of the input file.
-
address@hidden
-The second @samp{s///} command adds newlines based on the desired pattern
-(after 40 characters in the first example, after comma character in the second
-example).
-
address@hidden
-The @samp{/\n/!bx} command searches for a newline in the pattern space
-(@samp{/n/}), and if it is @emph{not} found (@samp{!}), branches (=jumps)
-to the previously defined label @samp{x}. This will cause @command{sed}
-to read the next line without processing any further commands in this cycle.
-
address@hidden
-If a newline is found in the pattern space, @command{P} is used to print
-up to the newline (that is - the newly structured line) then @command{D}
-deletes the pattern space up to the newline, and starts a new cycle.
address@hidden itemize
 
 
 
-- 
2.7.4