git: 556e793d803e - main - sh: Improve function documentation

The branch main has been updated by des:

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

commit 556e793d803e12e9ad9361c6c53ed0433151f41e
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-16 20:23:18 +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
---
 bin/sh/sh.1 | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
index 4f860d89c654..e76ddc80187a 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -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.