Subject: Re: bug#21845: sed docs bug: No documentation of which commands must be terminated by newlines

From: Jim Meyering <[email-masked]>
Date: Tue, 24 Jan 2017 20:34:37 -0800

On Tue, Jan 24, 2017 at 7:51 PM, Assaf Gordon <[email-masked]> wrote:
> Hello Ori,
>
> Sorry for the delayed response.
>
> On Fri, Nov 06, 2015 at 05:44:04PM +0200, Ori Avtalion wrote:
>>
>> Some commands, due to their syntax, cannot be followed by semicolons
>> [...]
>> I can find no mention of which commands this applies to.
>> This limitation should be mentioned next to each such command.
>
>
> Thank you for mentioning this. Indeed an important piece of information.
>
> I'm considering adding a new section about this.
> Draft attached, comments welcomed.

Thank you for that addition.
I did a quick once-over and suggest these changes:
diff --git a/doc/sed.texi b/doc/sed.texi
index 36953a3..ee3a44e 100644
--- a/doc/sed.texi
+++ b/doc/sed.texi
@@ -484,7 +484,7 @@ $ echo | sed 'Q42' ; echo $?
 * Other Commands::           Less frequently used commands
 * Programming Commands::     Commands for @command{sed} gurus
 * Extended Commands::        Commands specific of @value{SSED}
-* Multiple commands syntax:: Extnesion for easier scripting
+* Multiple commands syntax:: Extension for easier scripting
 @end menu

 @node sed script overview
@@ -1151,7 +1151,7 @@ hello
 @codequoteundirected off
 @codequotebacktick off

-Leading whitespaces after the @code{a} command are ignored.
+Leading whitespace after the @code{a} command is ignored.
 The text to add is read until the end of the line.

@@ -1240,7 +1240,7 @@ hello
 @codequoteundirected off
 @codequotebacktick off

-Leading whitespaces after the @code{i} command are ignored.
+Leading whitespace after the @code{i} command is ignored.
 The text to add is read until the end of the line.

 @item i\
@@ -1321,7 +1321,7 @@ hello
 @codequoteundirected off
 @codequotebacktick off

-Leading whitespaces after the @code{c} command are ignored.
+Leading whitespace after the @code{c} command is ignored.
 The text to add is read until the end of the line.

 @item c\
@@ -1721,11 +1721,12 @@ script in most multibyte locales (including UTF-8 locales).
 There are several methods to specify multiple commands in a @command{sed}
 program.

-Using newlines is most natural when running sed script from a file
-(using @option{-f} option).
+Using newlines is most natural when running a sed script from a file
+(using the @option{-f} option).

-On the command line, all @command{sed} commands can be separated by a
-newline, or with multiple @option{-e} parameters:
+On the command line, all @command{sed} commands may be separated by newlines.
+Alternatively, you may specify each command as an argument to an @option{-e}
+option:

 @codequoteundirected on
 @codequotebacktick on
@@ -1747,7 +1748,7 @@ $ seq 6 | sed -e 1d -e 3d -e 5d
 @codequoteundirected off
 @codequotebacktick off

-Most simple commands can be separated by a semicolon (@samp{;}):
+A semicolon (@samp{;}) may be used to separate most simple commands:

 @codequoteundirected on
 @codequotebacktick on
@@ -1783,9 +1784,9 @@ $ seq 6 | sed '@{1d;3d@};5d'
 @codequotebacktick off

 Labels used in @code{b},@code{t},@code{T},@code{:} commands are read
-until the semicolon. Leading and trailing whitespaces are ignored.  In
+until a semicolon.  Leading and trailing whitespace is ignored.  In
 the examples below the label is @samp{x}.  The first example works
-with @value{SSED}. The second is a portable equivalent.  For more
+with @value{SSED}.  The second is a portable equivalent.  For more
 information about branching and labels @pxref{Branching and flow
 control}.

@@ -1817,7 +1818,7 @@ require a newline:
 @item @code{a},@code{c},@code{i} (append/change/insert)

 All characters following @code{a},@code{c},@code{i} commands are taken
-as the text to append/change/insert. Using a semicolon leads to
+as the text to append/change/insert.  Using a semicolon leads to
 undesirable results:

 @codequoteundirected on
@@ -1852,7 +1853,7 @@ Hello
 @codequoteundirected off
 @codequotebacktick off

-Note that specifing the text to add (@samp{Hello}) immediately
+Note that specifying the text to add (@samp{Hello}) immediately
 after @code{a},@code{c},@code{i} is itself a @value{SSED} extension.
 A portable, POSIX-compliant alternative is:

@@ -1896,7 +1897,7 @@ $ seq 3 | sed '# this is a comment
 @item @code{r},@code{R},@code{w},@code{W} (reading and writing files)

 The @code{r},@code{R},@code{w},@code{W} commands parse the filename
-until end of the line. If whitespace or semicolons are found, they will
+until end of the line.  If whitespace or semicolons are found, they will
 be included in the filename, leading to unexpected results:

 @codequoteundirected on