--- a/docs/ccguide/scanf.refentry	Fri Nov 15 21:49:51 2002 +0000
+++ b/docs/ccguide/scanf.refentry	Fri Nov 15 21:49:51 2002 +0000
@@ -39,6 +39,134 @@
 <para>
 Placeholder
 </para>
+<para>
+Fscanf performs conversions from the file "fp", scanf from the
+standard input, and sscanf from the string pointed to by
+"string".
+</para>
+<para>
+Each function expects a control string containing conversion
+specifications, and zero or more pointers to objects into which
+the converted values are stored.
+</para>
+<para>
+The control string may contain three types of fields:
+<orderedlist numeration="loweralpha" spacing="compact">
+<listitem><para>
+Space, tab characters, or "\n" which match any of
+the three in the input.
+</para></listitem>
+<listitem><para>
+Characters not among the above and not "%" which must
+match characters in the input.
+</para></listitem>
+<listitem><para>
+A "%" followed by an optional "*" indicates
+suppression of assignment, an optional field width
+maximum and a conversion character indicating the
+type expected.
+</para></listitem>
+</orderedlist>
+</para>
+<para>
+A conversion character controls the conversion to be applied
+to the next field and indicates the type of the corresponding
+pointer argument. A field consists of consecutive non-space
+characters and ends at either a character inappropiate for the
+conversion or when a specified field is exhausted.
+When one field is finished, white-space characters are passed
+over until the next field is found.
+</para>
+<informaltable frame="none">
+<tgroup cols="2">
+<colspec colwidth="0.5in">
+<colspec colwidth="3.5in">
+<tbody>
+<row>
+<entry>d</entry>
+<entry>A decimal string is to be converted to an integer.</entry>
+</row>
+<row>
+<entry>o</entry>
+<entry>An octal string; the coresponding argument should
+point to an integer.</entry>
+</row>
+<row>
+<entry>x</entry>
+<entry>A hexadecimal string for conversion to an integer.</entry>
+</row>
+<row>
+<entry>s</entry>
+<entry>A string of non-space characters is expected and
+will be copied to the buffer pointed to by the
+corresponding argument and a null ("\0") appended.
+The user must ensure that the buffer is large
+enough. The input string is considered terminated
+by a space, tab of ("\n").</entry>
+</row>
+<row>
+<entry>c</entry>
+<entry>A character is expected and is copied into the byte
+pointed to by the argument. The white-space
+skipping is suppressed for this conversion. If a
+field width is given, the argument is assumed to
+point to a character array and the number of
+characters indicated is copied to it. NOTE to ensure
+that the next non-white-space character is read use
+"%1s" and that TWO bytes are pointed to by the
+argument.</entry>
+</row>
+<row>
+<entry>e,f</entry>
+<entry>A floating point representation is expected on the
+input and the argument must be a pointer to a float.
+Any of the usual ways of writing floating point
+numbers are recognized.</entry>
+</row>
+<row>
+<entry>[</entry>
+<entry>This denotes the start of a set of match characters;
+the inclusion or exclusion of which delimits the
+input field. The white-space skipping is
+suppressed. The corresponding argument should be a
+pointer to a character array. If the first
+character in the match string is not "^",
+characters are copied from the input as long as they
+can be found in the match string. If the first
+character is the "^", copying continues while characters
+cannot be found in the match string. The match
+string is delimited by a "]".</entry>
+</row>
+<row>
+<entry>D,O,X</entry>
+<entry>Similar to d,o,x above, but the corresponding
+argument is considered to point to a long integer.</entry>
+</row>
+<row>
+<entry>E,F</entry>
+<entry>Similar to e,f above, but the corresponding
+should point to a double.</entry>
+</row>
+<row>
+<entry>%</entry>
+<entry>A match for "%" is sought; no conversion takes place.</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+Each of the functions returns a count of the number of
+fields successfully matched and assigned.
+</para>
+</refsect1>
+
+<refsect1><title>Caveats</title>
+<para>
+The returned count of matches/assigments does not include
+character matches and assigments suppressed by "*". The
+arguments must ALL be pointers. It is a common error to call
+scanf with the value of an item rather than a pointer to it.
+</para>
 </refsect1>
 
 <refsect1><title>Diagnostics</title>
@@ -51,7 +179,7 @@
 
 <refsect1><title>See Also</title>
 <para>
-<link linkend="atof">atoi(), atof()</link>,
+<link linkend="atof">Atoi(), atof()</link>,
 <link linkend="getc">getc()</link>,
 <link linkend="printf">printf()</link>
 Kernighan and Ritchie pp 147-150