From 35973eceff091275d8692283ae3a1256a6317525 Mon Sep 17 00:00:00 2001
From: Alexander Ziaee <ziaee@FreeBSD.org>
Date: Sat, 12 Sep 2026 10:44:34 -0400
Subject: [PATCH] sh.1: Renew description of case

Update case synopsis, split description into paragraphs, improve markup,
light wordsmithing, and import exit status line from NetBSD.

While here, remove the '-' from the beginning of this document.

PR:	298329
Event:	EuroBSDcon 2026
Fixes:	c9afaa63894e ("Add case statement fallthrough")
Fixes:	f7a9b7fe3a8d ("Allow a left parenthesis before patterns in case blocks")
Fixes:	e00e16ad7f86 ("Allow empty case/esac statements")
MFC after:	3 days
Reviewed by:	bcr, jilles, Artem Bunichev <temcbun@gmail.com>
Differential Revision:	https://reviews.freebsd.org/D59518
---
 bin/sh/sh.1 | 54 ++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 37 insertions(+), 17 deletions(-)

diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
index 927ed666b440..cf81887247ca 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -1,4 +1,4 @@
-.\"-
+.\"
 .\" SPDX-License-Identifier: BSD-3-Clause
 .\"
 .\" Copyright (c) 1991, 1993
@@ -41,7 +41,7 @@
 .\" the referee document.  The original Standard can be obtained online at
 .\"     http://www.opengroup.org/unix/online.html.
 .\"
-.Dd July 19, 2026
+.Dd September 11, 2026
 .Dt SH 1
 .Os
 .Sh NAME
@@ -1077,12 +1077,15 @@ The syntax of the
 command is:
 .Bd -unfilled -offset indent -compact
 .Ic case Ar word Ic in
-.Ar pattern ) Ar list Li ;;
+.Oo Cm ( Oc Ar pattern Cm ) Oo Ar list Oc Cm ;&
+.Oo Cm ( Oc Ar pattern Cm ) Oo Ar list Oc Cm ;;
 .Ar ...
 .Ic esac
 .Ed
 .Pp
-The pattern can actually be one or more patterns
+The
+.Ar pattern
+can be one or more patterns
 (see
 .Sx Shell Patterns
 described later),
@@ -1090,23 +1093,40 @@ separated by
 .Ql \&|
 characters.
 Tilde expansion, parameter expansion, command substitution,
-arithmetic expansion and quote removal are applied to the word.
-Then, each pattern is expanded in turn using tilde expansion,
-parameter expansion, command substitution and arithmetic expansion and
-the expanded form of the word is checked against it.
-If a match is found, the corresponding list is executed.
-If the selected list is terminated by the control operator
-.Ql ;&
+arithmetic expansion and quote removal are applied to the
+.Ar word .
+Then, each
+.Ar pattern
+is expanded in turn using tilde expansion, parameter expansion,
+command substitution, and arithmetic expansion and
+the expanded form of the
+.Ar word
+is checked against it.
+.Pp
+If a match is found, the corresponding
+.Ar list ,
+if any, is executed.
+If the selected
+.Ar list
+is terminated by the control operator
+.Ql Cm ;&
 instead of
-.Ql ;; ,
-execution continues with the next list,
-continuing until a list terminated with
-.Ql ;;
+.Ql Cm ;; ,
+execution continues with the next
+.Ar list ,
+continuing until a
+.Ar list
+terminated with
+.Ql Cm ;;
 or the end of the
 .Ic case
 command.
-.Ic case
-fallthrough is specified by POSIX, but in practice is not entirely portable.
+The control operator
+.Ql Cm ;&
+is specified by POSIX, but in practice is not entirely portable.
+.Pp
+The exit status is that of the last command executed
+from the last list evaluated, if any, or zero otherwise.
 .Ss Grouping Commands Together
 Commands may be grouped by writing either
 .Sm off