git: ea13334abd9f - stable/15 - sh: Improve function documentation

The branch stable/15 has been updated by des:

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

commit ea13334abd9f4ed5456ba58970ee426a48c9c8e6
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:47 +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 4f860d89c654..a19aa7459896 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -41,7 +41,7 @@
 .\" the referee document.  The original Standard can be obtained online at
 .\"     http://www.opengroup.org/unix/online.html.
 .\"
-.Dd February 17, 2026
+.Dd June 16, 2026
 .Dt SH 1
 .Os
 .Sh NAME
@@ -487,7 +487,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
@@ -529,7 +529,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
@@ -1164,16 +1164,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
@@ -1185,7 +1189,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
@@ -2637,7 +2644,7 @@ by means of specifying their job IDs as arguments.
 See
 .Sx Job Control
 for a list of job ID forms.
-.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.