[src/trunk]: src/share/man/man4 Add more markup. Edit for clarity.

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7d6be1682808
branches:  trunk
changeset: 973590:7d6be1682808
user:      uwe <uwe%NetBSD.org@localhost>
date:      Sat Jul 04 23:09:43 2020 +0000

description:
Add more markup.  Edit for clarity.

diffstat:

 share/man/man4/speaker.4 |  220 +++++++++++++++++++++++++++++++---------------
 1 files changed, 147 insertions(+), 73 deletions(-)

diffs (288 lines):

diff -r f28e014e0008 -r 7d6be1682808 share/man/man4/speaker.4
--- a/share/man/man4/speaker.4  Sat Jul 04 22:17:09 2020 +0000
+++ b/share/man/man4/speaker.4  Sat Jul 04 23:09:43 2020 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: speaker.4,v 1.24 2020/07/04 19:25:24 uwe Exp $
+.\" $NetBSD: speaker.4,v 1.25 2020/07/04 23:09:43 uwe Exp $
 .\"
 .\" Copyright (c) 2016 Nathanial Sloss <nathanialsloss%yahoo.com.au@localhost>
 .\" All rights reserved.
@@ -62,13 +62,18 @@
 when another process has the device locked will return \-1 with an
 .Er EBUSY
 error indication.
-Writes to the device are interpreted as 'play strings' in a
-simple ASCII melody notation.
+Writes to the device are interpreted as
+.Dq play strings
+in a simple
+.Tn ASCII
+melody notation.
 An
 .Fn ioctl
 for tone generation at arbitrary frequencies is also supported.
 .Pp
-For the pcppi device sound-generation does
+For the
+.Xr pcppi 4
+device sound-generation does
 .Em not
 monopolize the processor; in fact, the driver
 spends most of its time sleeping while the PC hardware is emitting
@@ -89,19 +94,22 @@
 interface are in
 .In dev/spkrio.h .
 .Pp
-The tone_t structure is as follows:
-.Bd -literal
+The
+.Vt tone_t
+structure is as follows:
+.Bd -literal -offset indent
 typedef struct {
        int     frequency;      /* in hertz */
        int     duration;       /* in 1/100ths of a second */
 } tone_t;
 .Ed
+.Pp
 A frequency of zero is interpreted as a rest.
 .Pp
 At present there are four ioctls:
 .Bl -tag -width Dv
 .It Dv SPKRGETVOL
-Returns an integer, which is the current bell volume as a percentage (0-100).
+Returns an integer, which is the current bell volume as a percentage (0\(en100).
 .It Dv SPKRSETVOL
 Accepts an integer, which is the desired volume as a percentage.
 .It Dv SPKRTONE
@@ -111,98 +119,164 @@
 them in continuous sequence; this array must be terminated by a final member
 with a zero duration.
 .El
-.Pp
-The play-string language is modelled on the PLAY statement conventions of
-IBM BASIC 2.0.
-The MB, MF and X primitives of PLAY are not useful in a UNIX
+.\"
+.Ss Play string language
+.\"
+The play string language is modelled on the
+.Ic PLAY
+statement conventions of
+.Tn IBM BASIC No 2.0 .
+The
+.Ic MB ,
+.Ic MF
+and
+.Ic X
+primitives of
+.Ic PLAY
+are not useful in a
+.Tn UNIX
 environment and are omitted.
-The `octave-tracking' feature is also new.
+The
+.Dq octave-tracking
+feature is also new.
 .Pp
-There are 84 accessible notes numbered 1-84 in 7 octaves, each running from
-C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts
+There are 84 accessible notes numbered 1\(en84 in 7 octaves, each running from
+C to B, numbered 0\(en6; the scale is equal-tempered A440 and octave\~3 starts
 with middle C.
 By default, the play function emits half-second notes with the
-last 1/16th second being `rest time'.
+last 1/16th second being
+.Dq rest time .
 .Pp
-Play strings are interpreted left to right as a series of play command groups;
-letter case is ignored.
+Play strings are interpreted left to right as a series of play command groups.
+Letter case is ignored.
+Whitespace is ignored and may be used to separate melody sections.
 Play command groups are as follows:
-.Pp
-CDEFGAB -- letters A through G cause the corresponding note to be played in the
-current octave.
+.Bl -tag -width Ic
+.It Ic C , D , E , F , G , A , B
+Letters
+.Sq Ic A
+through
+.Sq Ic G
+cause the corresponding note to be played in the current octave.
 A note letter may optionally be followed by an
 .Em accidental sign ,
-one of # + or -; the first two of these cause it to be sharped one
+one of
+.Sq Ic \&# ,
+.Sq Ic \&+ ,
+or
+.Sq Ic \&- ;
+the first two of these cause it to be sharped one
 half-tone, the last causes it to be flatted one half-tone.
 It may also be
 followed by a time value number and by sustain dots (see below).
-Time values
-are interpreted as for the L command below;.
-.Pp
-O <n> -- if <n> is numeric, this sets the current octave.
-<n> may also be one
-of 'L' or 'N' to enable or disable octave-tracking (it is disabled by default).
+Time values are interpreted as for the
+.Sq Ic L
+command below;.
+.\"
+.It Ic O Ns Ar n , Ic OL , Ic ON
+If
+.Ar n
+is numeric, this sets the current octave.
+.Sq Ic OL
+enables, and
+.Sq Ic ON
+disables
+.Em octave-tracking
+(it is disabled by default).
 When octave-tracking is on, interpretation of a pair of letter notes will
 change octaves if necessary in order to make the smallest possible jump between
 notes.
-Thus "olbc" will be played as "olb>c", and "olcb" as "olc<b".
-Octave
-locking is disabled for one letter note following by >, < and O[0123456].
-.Pp
-> -- bump the current octave up one.
-.Pp
-< -- drop the current octave down one.
-.Pp
-N <n> -- play note n, n being 1 to 84 or 0 for a rest of current time value.
+Thus
+.Dq Li olbc
+will be played as
+.Dq Li olb>c ,
+and
+.Dq Li olcb
+as
+.Dq Li olc<b .
+Octave tracking is temporarily disabled for one letter note that follows
+.Sq Ic \&> ,
+.Sq Ic \&<
+or
+.Sq Ic O Ns Ar n .
+.\"
+.It Ic \&>
+Bump the current octave up one.
+.\"
+.It Ic \&<
+Drop the current octave down one.
+.\"
+.It Ic N Ns Ar n
+Play note
+.Ar n ,
+.Ar n
+being 1 to 84 or 0 for a rest of current time value.
 May be followed by sustain dots.
-.Pp
-L <n> -- sets the current time value for notes.
-The default is L4, quarter notes.
+.\"
+.It Ic L Ns Ar n
+Sets the current time value for notes.
+The default is
+.Dq Li L4 ,
+quarter notes.
 The lowest possible value is 1; values up to 64 are accepted.
-L1 sets whole notes, L2 sets half notes, L4 sets quarter notes, etc..
-.Pp
-P <n> -- pause (rest), with <n> interpreted as for L.
-May be followed by
-sustain dots.
-May also be written '~'.
-.Pp
-T <n> -- Sets the number of quarter notes per minute; default is 120.
+.Dq Li L1
+sets whole notes,
+.Dq Li L2
+sets half notes,
+.Dq Li L4
+sets quarter notes, etc...
+.\"
+.It Ic P Ns Ar n , Ic \&~ Ns Ar n
+Pause (rest), with
+.Ar n
+interpreted as for
+.Sq Ic L .
+May be followed by sustain dots.
+.\"
+.It Ic T Ns Ar n
+Sets the number of quarter notes per minute; default is 120.
 Musical names for common tempi are:
-.Bl -column Description Prestissimo "Beats per Minute" -offset indent
-.It Ta Sy Tempo Ta Sy "Beats per Minute"
+.Bl -column "very slow" "Larghissimo" "999\(en999" -offset indent
+.It           Ta Sy "Tempo"  Ta Sy "BPM"
 .It very slow Ta Larghissimo Ta ""
-.It           Ta Largo Ta 40-60
-.It           Ta Larghetto Ta 60-66
-.It           Ta Grave Ta ""
-.It           Ta Lento Ta ""
-.It           Ta Adagio Ta 66-76
-.It slow Ta Adagietto Ta ""
-.It      Ta Andante Ta 76-108
-.It medium Ta Andantino Ta ""
-.It        Ta Moderato Ta 108-120
-.It fast Ta Allegretto Ta ""
-.It      Ta Allegro Ta 120-168
-.It      Ta Vivace Ta ""
-.It      Ta Veloce Ta ""
-.It      Ta Presto Ta 168-208
+.It           Ta Largo       Ta 40\(en60
+.It           Ta Larghetto   Ta 60\(en66
+.It           Ta Grave       Ta ""
+.It           Ta Lento       Ta ""
+.It           Ta Adagio      Ta 66\(en76
+.It slow      Ta Adagietto   Ta ""
+.It           Ta Andante     Ta 76\(en108
+.It medium    Ta Andantino   Ta ""
+.It           Ta Moderato    Ta 108\(en120
+.It fast      Ta Allegretto  Ta ""
+.It           Ta Allegro     Ta 120\(en168
+.It           Ta Vivace      Ta ""
+.It           Ta Veloce      Ta ""
+.It           Ta Presto      Ta 168\(en208
 .It very fast Ta Prestissimo Ta ""
 .El
-.Pp
-M[LNS] -- set articulation.
-MN (N for normal) is the default; the last 1/8th of
+.\"
+.It Ic ML , Ic MN , Ic MS
+Set articulation.
+.Sq Ic MN
+(for normal) is the default; the last 1/8th of
 the note's value is rest time.
-You can set ML for legato (no rest space) or
-MS (staccato) 1/4 rest space.
+You can set
+.Sq Ic ML
+for legato (no rest time) or
+.Sq Ic MS
+for staccato (1/4 rest time).
+.El
 .Pp
-Notes (that is, CDEFGAB or N command character groups) may be followed by
-sustain dots.
+Notes, that is,
+.Ic C , D , E , F , G , A , B ,
+or
+.Ic N
+command character groups, may be followed by sustain dots.
 Each dot causes the note's value to be lengthened by one-half
 for each one.
 Thus, a note dotted once is held for 3/2 of its undotted value;
 dotted twice, it is held 9/4, and three times would give 27/8.
-.Pp
-Whitespace in play strings is simply skipped and may be used to separate
-melody sections.
 .Sh FILES
 .Bl -tag -width Pa -compact
 .It Pa /dev/speaker