From c0f29993e06c1fbe81f7367e8445f51db05d5fc9 Mon Sep 17 00:00:00 2001
From: Greg King <gregdk@users.sf.net>
Date: Sat, 29 May 2021 08:53:13 -0400
Subject: [PATCH] Fixed the descriptions of the Creativision's functions.

Fixed bios_playsound()'s position in the alphabetical list of functions.
---
 doc/funcref.sgml | 112 ++++++++++++++++++++++++++---------------------
 1 file changed, 61 insertions(+), 51 deletions(-)

diff --git a/doc/funcref.sgml b/doc/funcref.sgml
index 792a51741..28faa068a 100644
--- a/doc/funcref.sgml
+++ b/doc/funcref.sgml
@@ -1669,41 +1669,6 @@ used in presence of a prototype.
 </quote>
 
 
-<sect1>bios_playsound<label id="bios_playsound"><p>
-
-<quote>
-<descrip>
-<tag/Function/Play sound sequence.
-<tag/Header/<tt/<ref id="creativision.h" name="creativision.h">/
-<tag/Declaration/<tt/void __fastcall__ bios_playsound(void *a, unsigned char b);/
-<tag/Description/The function may play chords based on a BASIC statement,
-note and duration are defined in the manual chapter 13 on page 102 resp. 103.
-<tag/Notes/<itemize>
-<item>BASIC has a fixed tempo of 18.
-<item>The function is only available as fastcall function, so it may only be
-used in presence of a prototype.
-</itemize>
-<tag/Availability/Creativision
-<tag/See also/
-<ref id="psg_delay" name="psg_delay">,
-<ref id="psg_outb" name="psg_outb">
-<tag/Example/
-<verb>
-static const unsigned char notes[] = {
-  0x77, 0x4F, 0x37,
-  0x4B, 0x05, 0xBB,
-  0x4F, 0x27, 0x83,
-  0x93, 0x9B, 0x93,
-  0x17, 0x4F, 0x96,
-  0xAB, 0x17, 0x4F,
-  0x0E
-};
-bios_playsound (notes, sizeof notes);
-</verb>
-</descrip>
-</quote>
-
-
 <sect1>bgcolor<label id="bgcolor"><p>
 
 <quote>
@@ -1729,6 +1694,44 @@ used in presence of a prototype.
 </quote>
 
 
+<sect1>bios_playsound<label id="bios_playsound"><p>
+
+<quote>
+<descrip>
+<tag/Function/Play a sequence of musical notes.
+<tag/Header/<tt/<ref id="creativision.h" name="creativision.h">/
+<tag/Declaration/<tt/void __fastcall__ bios_playsound (const void *a, unsigned char b);/
+<tag/Description/The function plays chords based on a BASIC statement. Notes and
+durations are defined in the BASIC manual, chapter 13 on pages 102 resp. 103.
+<tag/Notes/<itemize>
+<item>BASIC has a fixed tempo of 18.
+<item>The function is only available as fastcall function, so it may only be
+used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="psg_delay" name="psg_delay">,
+<ref id="psg_outb" name="psg_outb">
+<tag/Example/<verb>
+#include <creativision.h>
+void main (void)
+{
+  static const unsigned char notes[] = {
+    0x77, 0x4F, 0x37,
+    0x4B, 0x05, 0xBB,
+    0x4F, 0x27, 0x83,
+    0x93, 0x9B, 0x93,
+    0x17, 0x4F, 0x96,  // played backwards
+    0xAB, 0x17, 0x4F,  // three-note chords
+    0x0E               // tempo
+  };
+  bios_playsound (notes, sizeof notes);
+}
+</verb>
+</descrip>
+</quote>
+
+
 <sect1>bordercolor<label id="bordercolor"><p>
 
 <quote>
@@ -1823,7 +1826,7 @@ be used in presence of a prototype.
 <item>The function is specific to the C128.
 <item>The function will not return to the caller.
 </itemize>
-<tag/Availability/C128
+<tag/Availability/cc65
 <tag/Example/None.
 </descrip>
 </quote>
@@ -5820,14 +5823,14 @@ be used in presence of a prototype.
 <descrip>
 <tag/Function/Delay for a short period of time.
 <tag/Header/<tt/<ref id="creativision.h" name="creativision.h">/
-<tag/Declaration/<tt/void __fastcall__ psg_delay(unsigned char b);/
+<tag/Declaration/<tt/void __fastcall__ psg_delay (unsigned char b);/
 <tag/Description/The function specifies how long each note or pause between
 notes should last.
 <tag/Notes/<itemize>
 <item>The function is only available as fastcall function, so it may only be
 used in presence of a prototype.
 </itemize>
-<tag/Availability/Creativision
+<tag/Availability/cc65
 <tag/See also/
 <ref id="psg_outb" name="psg_outb">,
 <ref id="psg_silence" name="psg_silence">
@@ -5840,23 +5843,29 @@ used in presence of a prototype.
 
 <quote>
 <descrip>
-<tag/Function/Output a byte.
+<tag/Function/Output a byte to the PSG.
 <tag/Header/<tt/<ref id="creativision.h" name="creativision.h">/
-<tag/Declaration/<tt/void __fastcall__ psg_outb(unsigned char b);/
-<tag/Description/The function will send a PSG byte and wait for acknowledge.
+<tag/Declaration/<tt/void __fastcall__ psg_outb (unsigned char b);/
+<tag/Description/The function sends a byte to the Programmable Sound
+Generator, then waits for the PSG to acknowledge.
 <tag/Notes/<itemize>
 <item>The function is only available as fastcall function, so it may only be
 used in presence of a prototype.
 </itemize>
-<tag/Availability/Creativision
+<tag/Availability/cc65
 <tag/See also/
 <ref id="psg_delay" name="psg_delay">,
 <ref id="psg_silence" name="psg_silence">
-<tag/Example/
-<verb>
-psg_outb (0x80); // Latch frequency
-psg_outb (0x07); // Frequency byte 2 
-psg_outb (0x90); // Channel 0 full volume
+<tag/Example/<verb>
+#include <creativision.h>
+void main (void)
+{
+  psg_outb (0x80); // Latch frequency
+  psg_outb (0x07); // Frequency byte 2
+  psg_outb (0x90); // Channel 0 full volume
+  psg_delay (100);
+  psg_silence ();
+}
 </verb>
 </descrip>
 </quote>
@@ -5866,13 +5875,14 @@ psg_outb (0x90); // Channel 0 full volume
 
 <quote>
 <descrip>
-<tag/Function/Set volume off on each channel.
+<tag/Function/Set volume off on each PSG channel.
 <tag/Header/<tt/<ref id="creativision.h" name="creativision.h">/
-<tag/Declaration/<tt/void psg_silence(void);/
-<tag/Description/The function sends $9F, $BF, $DF, $FF to the PSG.
+<tag/Declaration/<tt/void psg_silence (void);/
+<tag/Description/The function resets the Programmable Sound Generator,
+then sends $9F, $BF, $DF, $FF to the PSG.
 <tag/Notes/<itemize>
 </itemize>
-<tag/Availability/Creativision
+<tag/Availability/cc65
 <tag/See also/
 <ref id="psg_delay" name="psg_delay">,
 <ref id="psg_outb" name="psg_outb">