git: cee36a5e003c - stable/14 - sh: Improve function documentation

The branch stable/14 has been updated by des:

URL: https://cgit.FreeBSD.org/src/commit/?id=cee36a5e003c90659f274a2f20699543c73f2d34

commit cee36a5e003c90659f274a2f20699543c73f2d34
Author:     Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2026-06-16 20:23:18 +0000
Commit:     Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2026-06-20 19:02:53 +0000

    sh: Improve function documentation
    
    * Mention that the function body can be in parentheses.  It is already
      implied since the function body can be any valid statement, but it may
      not be obvious to a reader who has only ever seen functions that used
      curly brackets and assumes that they are part of the function syntax.
    
    * Remove the incorrect claim that a local statement may only occur at
      the top of a function.
    
    * Show that a value may be assigned to a variable in a local statement.
    
    * While here, replace unpaired double quotes with \(dq to avoid
      confusing syntax highlighters.
    
    PR:             296050
    MFC after:      1 week
    Reviewed by:    ziaee, jilles
    Differential Revision:  https://reviews.freebsd.org/D57596
    
    (cherry picked from commit 556e793d803e12e9ad9361c6c53ed0433151f41e)
    
    sh: Belatedly bump manual page date
    
    Fixes:          556e793d803e ("sh: Improve function documentation")
    (cherry picked from commit 09bb0b0d13968163c7394e9168491b16607fc2e7)
---
 bin/sh/sh.1 | 27 +++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
index eb517b6938ee..95847482a758 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -33,7 +33,7 @@
 .\"
 .\"	from: @(#)sh.1	8.6 (Berkeley) 5/4/95
 .\"
-.Dd November 17, 2025
+.Dd June 16, 2026
 .Dt SH 1
 .Os
 .Sh NAME
@@ -476,7 +476,7 @@ Vertical tab
 Literal backslash
 .It \e\&'
 Literal single-quote
-.It \e\&"
+.It \e\(dq
 Literal double-quote
 .It \e Ns Ar nnn
 The byte whose octal value is
@@ -518,7 +518,7 @@ It remains literal unless it precedes the following characters,
 which it serves to quote:
 .Pp
 .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
-.It Li $ Ta Li ` Ta Li \&" Ta Li \e Ta Li \en
+.It Li $ Ta Li ` Ta Li \(dq Ta Li \e Ta Li \en
 .El
 .It Backslash
 A backslash preserves the literal meaning of the following
@@ -1151,16 +1151,20 @@ is normally a list
 enclosed between
 .Ql {
 and
-.Ql } .
+.Ql }
+or
+.Ql \&(
+and
+.Ql \&) .
+In the latter case, the function will be executed in a subshell when
+invoked.
 .Pp
 Variables may be declared to be local to a function by
 using the
 .Ic local
-command.
-This should appear as the first statement of a function,
-and the syntax is:
+command:
 .Pp
-.D1 Ic local Oo Ar variable ... Oc Op Fl
+.D1 Ic local Oo Ar variable Ns Oo = Ns value Oc ... Oc Op Fl
 .Pp
 The
 .Ic local
@@ -1172,7 +1176,10 @@ When a variable is made local, it inherits the initial
 value and exported and readonly flags from the variable
 with the same name in the surrounding scope, if there is
 one.
-Otherwise, the variable is initially unset.
+Otherwise, the variable is initially unset unless assigned a value in
+the
+.Ic local
+statement.
 The shell
 uses dynamic scoping, so that if the variable
 .Va x
@@ -2417,7 +2424,7 @@ line.
 A built-in equivalent of
 .Xr kill 1
 that additionally supports sending signals to jobs.
-.It Ic local Oo Ar variable ... Oc Op Fl
+.It Ic local Oo Ar variable Ns Oo = Ns value Oc ... Oc Op Fl
 See the
 .Sx Functions
 subsection.