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

1 files 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.