sh: Improve function documentation

[des]

Summary

• 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

[des]

tweak

[ziaee]

LGTM from manpages modulo the suggestion to use the roff parenthesis escape instead of escaping the parenthesis. Thanks for doing this!

bin/sh/sh.1

1169–1171

[des]

bin/sh/sh.1

1169–1171

The mandoc_char(7) manual page explicitly warns against using \*(lp and \*)rp. Also, \& is not an escape, it is a zero-width space which prevents mandoc from interpreting the parentheses as punctuation and rendering them as ''( and '') instead of '(' and ')'.

[ziaee]

bin/sh/sh.1

1169–1171

The mandoc_char(7) manual page explicitly warns against using \*(lp and \*)rp

Oops, I missed that, thanks.

[jilles]

bin/sh/sh.1

1168–1173

OK. For that other review about extensions to POSIX, note that POSIX requires the command to be a compound command. For example, f() echo hi is not POSIX-compliant application code, does not work in bash but does work in most other shells (including our sh).

However, for this review there is no need to change anything.

[des]

bin/sh/sh.1

1168–1173

I have no idea what other review you are talking about. I only have this one.