Merge pull request #2733 from Russell-S-Harper/update-docn-with-cscanf

Updated documentation with cscanf

doc/funcref.sgml

@@ -302,6 +302,7 @@ function.
 <item><ref id="cputcxy" name="cputcxy">
 <item><ref id="cputs" name="cputs">
 <item><ref id="cputsxy" name="cputsxy">
+<item><ref id="cscanf" name="cscanf">
 <item><ref id="cursor" name="cursor">
 <item><ref id="cvline" name="cvline">
 <item><ref id="cvlinexy" name="cvlinexy">
@@ -2720,7 +2721,7 @@ see anything that you type.  (See the description of <tt/cbm_k_scnkey()/.)
 
 <quote>
 <descrip>
-<tag/Function/Input a string directly to the console.
+<tag/Function/Input a string directly from the console.
 <tag/Header/<tt/<ref id="conio.h" name="conio.h">/
 <tag/Declaration/<tt/char* __fastcall__ cgets (const char* buffer, int size);/
 <tag/Description/The function inputs a string of at most <tt/size - 1/
@@ -2735,11 +2736,12 @@ be used in the presence of a prototype.
 </itemize>
 <tag/Availability/cc65
 <tag/See also/
-<ref id="cgetc" name="cgetc">
+<ref id="cgetc" name="cgetc">,
+<ref id="cscanf" name="cscanf">
 <tag/Example/<verb>
 #include &lt;conio.h&gt;
 
-int main ()
+int main (void)
 {
     char buffer[200], *p;
 
@@ -3353,6 +3355,47 @@ be used in presence of a prototype.
 </quote>
 
 
+<sect1>cscanf<label id="cscanf"><p>
+
+<quote>
+<descrip>
+<tag/Function/Read formatted input from the console
+<tag/Header/<tt/<ref id="conio.h" name="conio.h">/
+<tag/Declaration/<tt/int cscanf (const char* format, ...);/
+<tag/Description/The <tt/cscanf()/ function scans input from the console under
+control of the argument <tt/format/. Following the format string is a list of
+addresses to receive values. The format string is identical to that of the
+<tt/scanf()/ function.
+<tag/Notes/<itemize>
+<item>A direct call to <tt/cursor()/ may be required to show the cursor.
+<item>Some control characters like backspaces are not recognized.
+<item>A better user experience can sometimes be provided by using <tt/cgets()/
+to retrieve the input, and then using <tt/sscanf()/ to parse it.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cgets" name="cgets">,
+<ref id="cursor" name="cursor">
+<tag/Example/<verb>
+#include &lt;conio.h&gt;
+
+int main (void)
+{
+    int a, b, c;
+
+    cputs ("Type three integers that add to 100: ");
+    if (cscanf ("%d %d %d", &amp;a, &amp;b, &amp;c) == 3 && a + b + c == 100)
+        cputs ("\r\nYou passed!\r\n");
+    else
+        cputs ("\r\nYou failed!\r\n");
+
+    return 0;
+}
+</verb>
+</descrip>
+</quote>
+
+
 <sect1>cursor<label id="cursor"><p>
 
 <quote>