Module Name: src Committed By: uwe Date: Sat Jul 4 23:09:43 UTC 2020
Modified Files: src/share/man/man4: speaker.4 Log Message: Add more markup. Edit for clarity. To generate a diff of this commit: cvs rdiff -u -r1.24 -r1.25 src/share/man/man4/speaker.4 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/share/man/man4/speaker.4 diff -u src/share/man/man4/speaker.4:1.24 src/share/man/man4/speaker.4:1.25 --- src/share/man/man4/speaker.4:1.24 Sat Jul 4 19:25:24 2020 +++ src/share/man/man4/speaker.4 Sat Jul 4 23:09:43 2020 @@ -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 <nathanialsl...@yahoo.com.au> .\" All rights reserved. @@ -62,13 +62,18 @@ An attempt to 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 @@ definitions for the 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 @@ Accepts a pointer to the first of an arr 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