kern/60573: no wsconsctl definitions or examples so its hard to use

["nyashinsky%gmail.com@localhost via gnats" <gnats-admin%NetBSD.org@localhost>]

>Number:         60573
>Category:       kern
>Synopsis:       no wsconsctl definitions or examples so its hard to use
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Aug 10 20:15:01 +0000 2026
>Originator:     Neil Yashinsky
>Release:        src/HEAD (trunk), August 10 2026
>Organization:
ContextCore
>Environment:
all of them
>Description:
There is no reference to the pitch/period/volume parameters or usage examples in the wsbell(4) man page.

This patch:
1. Adds a compact parameter list to DESCRIPTION.
2. Adds an EXAMPLES section showing wsconsctl usage to inspect and adjust the bell.

This is the terse version closely matching my sense of the man-page style; I have another version with a plain-language intro and intentionally (hopefully thoughtfully wordier examples to make it easier to use) I'm happy to share, and/or to put it in the Guide/wiki.
>How-To-Repeat:
Read wsbell(4): it references pitch/period/volume and wsconsctl(8) without defining them or showing usage.
>Fix:
diff --git a/share/man/man4/wsbell.4 b/share/man/man4/wsbell.4
index 46f7f917..f772dedd 100644
--- a/share/man/man4/wsbell.4
+++ b/share/man/man4/wsbell.4
@@ -24,7 +24,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 13, 2017
+.Dd August 10, 2026
 .Dt WSBELL 4
 .Os
 .Sh NAME
@@ -46,10 +46,26 @@ screen,
 .Nm
 sounds the bell.
 .Pp
-The
+The sound of the bell is controlled by three parameters, each with a
+.Em current
+value, used for the next bell, and a
+.Em default
+value, restored on reset:
+.Bl -tag -width period -compact
+.It Va pitch
+Tone frequency, in Hz.
+.It Va period
+Tone duration, in milliseconds.
+.It Va volume
+Loudness, as a percentage of the maximum.
+.El
+.Pp
+These are accessed with
 .Xr wsconsctl 8
-utility gives access to several configurable parameters that affect the sound
-of the system bell.
+.Pq see Sx EXAMPLES
+or the
+.Xr ioctl 2
+calls below.
 .Ss Ioctls
 The following
 .Xr ioctl 2
@@ -98,6 +114,27 @@ struct wskbd_bell_data {
 .It
 .Pa /usr/include/dev/wscons/wsconsio.h .
 .El
+.Sh EXAMPLES
+The bell parameters are exposed as
+.Xr wsconsctl 8
+variables.
+Show the current settings:
+.Dl # wsconsctl -a | grep bell
+.Pp
+Set a lower-pitched, softer, slightly longer bell than the default:
+.Bd -literal -offset indent
+# wsconsctl -w bell.pitch=600
+# wsconsctl -w bell.period=150
+# wsconsctl -w bell.volume=30
+.Ed
+.Pp
+The
+.Va bell.pitch.default ,
+.Va bell.period.default ,
+and
+.Va bell.volume.default
+variables set the values restored on reset:
+.Dl # wsconsctl -w bell.volume.default=30
 .Sh SEE ALSO
 .Xr speaker 4 ,
 .Xr wscons 4 ,