From c6d183c31b72dd710adaf35d4d6773165be077f1 Mon Sep 17 00:00:00 2001
From: Mariano Dominguez <mariano.dm@gmail.com>
Date: Mon, 16 Jan 2023 19:09:01 -0800
Subject: [PATCH] add documentation for _sound.

---
 doc/atari.sgml   |  1 +
 doc/funcref.sgml | 39 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/doc/atari.sgml b/doc/atari.sgml
index 2e2db0402..3057cd8a6 100644
--- a/doc/atari.sgml
+++ b/doc/atari.sgml
@@ -332,6 +332,7 @@ See the <url url="funcref.html" name="function reference"> for declaration and u
 <item>_scroll
 <item>_setcolor
 <item>_setcolor_low
+<item>_sound
 <item>waitvsync
 </itemize>
 
diff --git a/doc/funcref.sgml b/doc/funcref.sgml
index a8593ebb5..2df86289e 100644
--- a/doc/funcref.sgml
+++ b/doc/funcref.sgml
@@ -126,6 +126,7 @@ function.
 <!-- <item><ref id="_scroll" name="_scroll"> -->
 <!-- <item><ref id="_setcolor" name="_setcolor"> -->
 <!-- <item><ref id="_setcolor_low" name="_setcolor_low"> -->
+<item><ref id="_sound" name="_sound">
 <item><ref id="get_ostype" name="get_ostype">
 <!-- <item><ref id="get_tv" name="get_tv"> -->
 </itemize>
@@ -1108,6 +1109,43 @@ considered random to a certain degree.
 </descrip>
 </quote>
 
+<sect1>_sound<label id="_sound"><p>
+<quote>
+<descrip>
+<tag/Function/Use the speaker to produce sound in a specified voice. (Atari only)
+<tag/Header/<tt/<ref id="atari.h" name="atari.h">/
+<tag/Declaration/<tt/void _sound (unsigned char voice, unsigned char pitch, unsigned char distortion, unsigned char volume);/
+<tag/Description/The function produces a sound with the specified parameters. using any of the 4 availble oscillators (voices) controlled by POKEY chip. Sound is non cpu-blocking and it keeps oscillating until program sends 0 in all the other parameters.
+
+<tag/Notes/<itemize>
+<item>The function is specific to the Atari 8 bit.
+<item> Voice can be any of 0-3 different sound channels.
+<item> Pitch goes from 0-255 (about 125 Hz to 32 Khz).
+<item> Distortion (0-14) uses poly dividers to reshape wave in order to create a noise effect. Use 10 for a "pure" square-wave sound.
+<item>Volume (0-15) is the intensity for the wave.
+<item>Extra bits in those parameters will be ignored.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/Example/
+<verb>
+
+#include <stdio.h>
+int main(void)
+{
+    int i=0;
+    unsigned char j;
+    printf("playing sound \n");
+    for (j=0; j<144; j++) {
+      _sound(1,144-j,10,8);     //change the pitch for voice 1
+      for (i=0; i<50; i++);     //pause for sound duration
+    }
+    _sound(1,0,0,0);  //use zero in other parameters to stop the sound
+    return 0;
+}
+
+</verb>
+</descrip>
+</quote>
 
 <sect1>_stroserror<label id="_stroserror"><p>
 
@@ -6908,7 +6946,6 @@ switching the CPU into single clock mode.
 </descrip>
 </quote>
 
-
 <sect1>srand<label id="srand"><p>
 
 <quote>