Module Name: src Committed By: wiz Date: Sun May 28 18:23:22 UTC 2017
Modified Files: src/share/man/man4: speaker.4 Log Message: New sentence, new line. Punctuation fixes. Get rid of unnecessary \*[Lt], \*[Gt]. To generate a diff of this commit: cvs rdiff -u -r1.20 -r1.21 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.20 src/share/man/man4/speaker.4:1.21 --- src/share/man/man4/speaker.4:1.20 Sat May 27 12:15:34 2017 +++ src/share/man/man4/speaker.4 Sun May 28 18:23:22 2017 @@ -1,4 +1,4 @@ -.\" $NetBSD: speaker.4,v 1.20 2017/05/27 12:15:34 nat Exp $ +.\" $NetBSD: speaker.4,v 1.21 2017/05/28 18:23:22 wiz Exp $ .\" .\" Copyright (c) 2016 Nathanial Sloss <nathanialsl...@yahoo.com.au> .\" All rights reserved. @@ -55,12 +55,19 @@ The speaker device driver allows applica speaker on machines with a PC-like 8253 timer implementation or a synthesized speaker from an audio device/soundcard. .Pp -Only one process may have this device open at any given time; open() and -close() are used to lock and relinquish it. An attempt to open() when -another process has the device locked will return -1 with an +Only one process may have this device open at any given time; +.Xr open 2 +and +.Xr close 2 +are used to lock and relinquish it. +An attempt to +.Xr open 2 +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. An +error indication. +Writes to the device are interpreted as 'play strings' in a +simple ASCII melody notation. +An .Fn ioctl for tone generation at arbitrary frequencies is also supported. .Pp @@ -68,7 +75,8 @@ For the pcppi device sound-generation do .Em not monopolize the processor; in fact, the driver spends most of its time sleeping while the PC hardware is emitting -tones. Other processes may emit beeps while the driver is running. +tones. +Other processes may emit beeps while the driver is running. .Pp For the audio device speaker, the speaker uses one of the virtual audio channels. @@ -88,55 +96,70 @@ The tone_t structure used in these calls specifying a frequency (in hz) and a duration (in 1/100ths of a second). A frequency of zero is interpreted as a rest. .Pp -At present there are two such ioctls. SPKRTONE accepts a pointer to a -single tone structure as third argument and plays it. SPKRTUNE accepts a +At present there are two such ioctls. +SPKRTONE accepts a pointer to a +single tone structure as third argument and plays it. +SPKRTUNE accepts a pointer to the first of an array of tone structures and plays them in continuous sequence; this array must be terminated by a final member with a zero duration. .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 -environment and are omitted. The `octave-tracking' feature is also new. +IBM BASIC 2.0. +The MB, MF and X primitives of PLAY are not useful in a UNIX +environment and are omitted. +The `octave-tracking' feature is also new. .Pp There are 84 accessible notes numbered 1-83 in 7 octaves, each running from C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts -with middle C. By default, the play function emits half-second notes with the +with middle C. +By default, the play function emits half-second notes with the last 1/16th second being `rest time'. .Pp Play strings are interpreted left to right as a series of play command groups; -letter case is ignored. Play command groups are as follows: +letter case is ignored. +Play command groups are as follows: .Pp CDEFGAB -- letters A through G cause the corresponding note to be played in the -current octave. A note letter may optionally be followed by an +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 -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 +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 \*[Lt]n\*[Gt] -- if \*[Lt]n\*[Gt] is numeric, this sets the current octave. \*[Lt]n\*[Gt] may also be one +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). 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\*[Gt]c", and "olcb" as "olc\*[Lt]b". Octave -locking is disabled for one letter note following by \*[Gt], \*[Lt] and O[0123456]. +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 -\*[Gt] -- bump the current octave up one. +> -- bump the current octave up one. .Pp -\*[Lt] -- drop the current octave down one. +< -- drop the current octave down one. .Pp -N \*[Lt]n\*[Gt] -- play note n, n being 1 to 84 or 0 for a rest of current time value. +N <n> -- play note n, n being 1 to 84 or 0 for a rest of current time value. May be followed by sustain dots. .Pp -L \*[Lt]n\*[Gt] -- sets the current time value for notes. The default is 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.. +L <n> -- sets the current time value for notes. +The default is 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 -P \*[Lt]n\*[Gt] -- pause (rest), with \*[Lt]n\*[Gt] interpreted as for L. May be followed by -sustain dots. May also be written '~'. -.Pp -T \*[Lt]n\*[Gt] -- Sets the number of quarter notes per minute; default is 120. Musical -names for common tempi are: +T <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" .It very slow Ta Larghissimo Ta "" @@ -157,13 +180,17 @@ names for common tempi are: .It very fast Ta Prestissimo Ta "" .El .Pp -M[LNS] -- set articulation. MN (N 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 +M[LNS] -- set articulation. +MN (N 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. .Pp Notes (that is, CDEFGAB or 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; +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 @@ -181,7 +208,7 @@ This device was originally for the pcppi PC timer interface. Support was added for a synthesized device by Nathanial Sloss, first appearing in -.Nx 8.0 +.Nx 8.0 . .Sh AUTHORS .An Eric S. Raymond Aq Mt e...@snark.thyrsus.com .Sh BUGS