--- a/docs/ccguide/chap4.chapter	Sat Nov 23 10:39:11 2002 +0000
+++ b/docs/ccguide/chap4.chapter	Sat Nov 23 10:39:11 2002 +0000
@@ -11,6 +11,58 @@
 buffering of I/O channels improves the speed of file access because
 fewer system calls are necessary.
 </para>
+<para>
+The high-level I/O functions should not be confused with the
+low-level system calls with similar names. Nor shoul "file
+pointers" be confused with "path numbers". The standard library
+functions maintain a structure for each file open that holds status
+information and a pointer into the files buffer, A user program
+uses a pointer to this structure as the "identity" of the file
+(which is provided by "fopen()"), and passes it to the various
+I/O functions. The I/O functions will make the low-level system
+calls when necessary.
+</para>
+<para>
+<emphasis>Using a file pointer in a systen call, or a path number in a
+Standard Library call</emphasis>, is a common mistake among beginners to C and,
+if made, will be sure to <emphasis>crash your program.</emphasis>
+</para>
+<para>
+The convenience functions include facilities for copying,
+comparing, and concatening strings, converting numbers to strings,
+and doing the extra work in accessing systen information such as the
+time.
+</para>
+<para>
+In the page which follow, the functions available are
+described in terms of what they do and the parameters they expect.
+The "USAGE" section shows the name of the function and the type
+returned (if not int). The declaration of arguments are shown as
+they would be written in the function definition to indicate the
+types expected by the function. If it is necesary to include a
+file before the function can be used, it is shown in the "USAGE"
+section by "#include &lt;filename&gt;".
+</para>
+<para>
+Most of the header files that are required to be included, must
+reside in the "DEFS" directory on the default system drive. If the
+file is included in the source program using angle bracket
+delimiters instead of the usual double quotes, the compiler will
+append this path name to the file name. For example, "#include &lt;stdio.h&gt;"
+is equivalent to "#include &lt;/d0/defs/stdio.h&gt;", if "/d0" is
+the path name of the default system drive.
+</para>
+<para>
+<emphasis>Please note</emphasis> that if the type of the valye returned by a
+function is not INT, you should make a pre-declaration in your
+program before calling it. For example, if you wish to use
+"atof()", you should pre-declare by having "double atof();"
+somewhere in your program before a call to it. Some functions
+which have associated header files in the DEFS directory that
+should be included, will be pre-declared for you in the header. An
+example of this is "ftell()" which is pre-declared in "stdio.h". If
+you are in any doubt, read the header file.
+</para>
 
 &atofref;
 &fcloseref;

--- a/docs/ccguide/errors.appendix	Sat Nov 23 10:39:11 2002 +0000
+++ b/docs/ccguide/errors.appendix	Sat Nov 23 10:39:11 2002 +0000
@@ -1,9 +1,9 @@
 <appendix>
 <title>Compiler Generated Error Messages</title>
 <para>
-The error codes are shown in both hexadecimal (first column) and
-decimal (second column). Error codes other than those listed are
-generated by programming languages or user programs.
+Below is a list of the error messages that the C compiler generates,
+and, if applicable, probable causes and K &amp; R Appendix A section
+number (in parenthesis) to see for more specific information.
 </para>
 <variablelist>
 <varlistentry><term>already a local variable</term>
@@ -36,6 +36,8 @@
 <varlistentry><term>argument storage</term>
 <listitem>
 <para>
+Function arguments may only be declared as storage class
+register. (10.1)
 </para>
 </listitem>
 </varlistentry>
@@ -43,6 +45,8 @@
 <varlistentry><term>bad character</term>
 <listitem>
 <para>
+A character not in the C character set (probably a control
+char) was encountered in the source file. (2)
 </para>
 </listitem>
 </varlistentry>
@@ -50,6 +54,7 @@
 <varlistentry><term>both must be integral</term>
 <listitem>
 <para>
+&gt;&gt; and &lt;&lt; operands cannot be FLOAT or DOUBLE. (7.5)
 </para>
 </listitem>
 </varlistentry>
@@ -57,6 +62,8 @@
 <varlistentry><term>break error</term>
 <listitem>
 <para>
+The break statement is allowed only inside a while, do, for or
+switch block. (9.8)
 </para>
 </listitem>
 </varlistentry>
@@ -64,6 +71,8 @@
 <varlistentry><term>can't take address</term>
 <listitem>
 <para>
+&amp; operator not allowed in a register variable. Operand must
+otherwise be an lvalue. (7.2)
 </para>
 </listitem>
 </varlistentry>
@@ -71,13 +80,16 @@
 <varlistentry><term>cannot cast</term>
 <listitem>
 <para>
+Type result of cast cannot be FUNCTION or ARRAY. (7.2, 8.7)
 </para>
 </listitem>
 </varlistentry>
 
-<varlistentry><term>cannot evaluate data</term>
+<varlistentry><term>cannot evaluate size</term>
 <listitem>
 <para>
+Could not determine size from declaration or initializer.
+(8.6, 14.3)
 </para>
 </listitem>
 </varlistentry>
@@ -85,6 +97,8 @@
 <varlistentry><term>cannot initialize</term>
 <listitem>
 <para>
+Storage class or type does not allow variable to be
+initialized. (8.6)
 </para>
 </listitem>
 </varlistentry>
@@ -92,6 +106,9 @@
 <varlistentry><term>compiler trouble</term>
 <listitem>
 <para>
+Compiler detedted something it couldn't handle. Try compiling
+the program again. If this error still occurs, contact
+Microware.
 </para>
 </listitem>
 </varlistentry>
@@ -99,6 +116,8 @@
 <varlistentry><term>condition needed</term>
 <listitem>
 <para>
+While, do, for, switch and if statements require a condition
+expression. (9.3)
 </para>
 </listitem>
 </varlistentry>
@@ -106,6 +125,11 @@
 <varlistentry><term>constant expression required</term>
 <listitem>
 <para>
+Initializer expressions for statis or external variables cannot
+reference variables. They may, however, refer to the address
+of a previously declared variable. This installation allows no
+initializer expressions unless all operands are of type INT or
+CHAR (8.6)
 </para>
 </listitem>
 </varlistentry>
@@ -113,6 +137,8 @@
 <varlistentry><term>constant overflow</term>
 <listitem>
 <para>
+Input numeric constant was too large for the implied or
+explicit type. (2.6, [PDP-11])
 </para>
 </listitem>
 </varlistentry>
@@ -120,6 +146,8 @@
 <varlistentry><term>constant required</term>
 <listitem>
 <para>
+Variables are not allowed for array dimensions or cases. (8.3,
+8.7, 9.7)
 </para>
 </listitem>
 </varlistentry>
@@ -127,6 +155,8 @@
 <varlistentry><term>continue error</term>
 <listitem>
 <para>
+The continue statement is allowed only inside a while, do, or
+for block. (9.9)
 </para>
 </listitem>
 </varlistentry>
@@ -134,6 +164,12 @@
 <varlistentry><term>declaration mismatch</term>
 <listitem>
 <para>
+This declaration conflicts with a previous one. This is
+typically caused by declaring a function to return a non-integer
+type after a reference has been made to the function.
+Depending on the line structure of the declaration block, this
+error may be reported on the line following the erroneous
+declaration. (11, 11.1, 11.2)
 </para>
 </listitem>
 </varlistentry>
@@ -141,6 +177,7 @@
 <varlistentry><term>divide by zero</term>
 <listitem>
 <para>
+Divide by zero occurred when evaluating a constant expression.
 </para>
 </listitem>
 </varlistentry>
@@ -148,6 +185,8 @@
 <varlistentry><term>? expected</term>
 <listitem>
 <para>
+? is any character that was expected to appear here. Missing
+semicolons or braces cause this error.
 </para>
 </listitem>
 </varlistentry>
@@ -155,6 +194,7 @@
 <varlistentry><term>expression missing</term>
 <listitem>
 <para>
+An expression is required here.
 </para>
 </listitem>
 </varlistentry>
@@ -162,6 +202,8 @@
 <varlistentry><term>function header missing</term>
 <listitem>
 <para>
+Statement or expression encountered outside a function.
+Typically causes by mismatched braces. (10.1)
 </para>
 </listitem>
 </varlistentry>
@@ -169,6 +211,8 @@
 <varlistentry><term>function type error</term>
 <listitem>
 <para>
+A function cannot be declared as returning an array, function,
+struct, or union. (8.4, 10.1)
 </para>
 </listitem>
 </varlistentry>
@@ -176,6 +220,8 @@
 <varlistentry><term>function unfinished</term>
 <listitem>
 <para>
+End-of-file encountered before the end of function definition.
+(10.1)
 </para>
 </listitem>
 </varlistentry>
@@ -183,6 +229,7 @@
 <varlistentry><term>identifier missing</term>
 <listitem>
 <para>
+Identifier name required here but none was found.
 </para>
 </listitem>
 </varlistentry>
@@ -190,6 +237,8 @@
 <varlistentry><term>illegal declaration</term>
 <listitem>
 <para>
+Declarations are allowed only at the beginning of a block.
+(9.2)
 </para>
 </listitem>
 </varlistentry>
@@ -197,6 +246,7 @@
 <varlistentry><term>label required</term>
 <listitem>
 <para>
+Label name required on goto statement. (9.11)
 </para>
 </listitem>
 </varlistentry>
@@ -204,6 +254,7 @@
 <varlistentry><term>label undefined</term>
 <listitem>
 <para>
+Goto to label not defined in the current function. (9.12)
 </para>
 </listitem>
 </varlistentry>
@@ -211,6 +262,8 @@
 <varlistentry><term>lvalue required</term>
 <listitem>
 <para>
+Left side of assigment must be able to be "stored into".
+Array names, functions, structs, etc. are no lvalues. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -218,6 +271,7 @@
 <varlistentry><term>multiple defaults</term>
 <listitem>
 <para>
+Only one default statement is allowed in a switch block. (9.7)
 </para>
 </listitem>
 </varlistentry>
@@ -225,6 +279,8 @@
 <varlistentry><term>multiple definition</term>
 <listitem>
 <para>
+Identifier name was declared more than once in the same block
+level (9.2, 11.1)
 </para>
 </listitem>
 </varlistentry>
@@ -232,6 +288,7 @@
 <varlistentry><term>must be integral</term>
 <listitem>
 <para>
+Type of object required here must be type int, char or pointer.
 </para>
 </listitem>
 </varlistentry>
@@ -239,6 +296,7 @@
 <varlistentry><term>name clash</term>
 <listitem>
 <para>
+Struct-union member and tag names must be mutually distinct.  (8.5)
 </para>
 </listitem>
 </varlistentry>
@@ -246,6 +304,7 @@
 <varlistentry><term>name in cast</term>
 <listitem>
 <para>
+Identifier name found in a cast. Only types are allowed. (7.2, 8.7)
 </para>
 </listitem>
 </varlistentry>
@@ -253,6 +312,7 @@
 <varlistentry><term>named twice</term>
 <listitem>
 <para>
+Names in a function parameter list may appear only once. (10.1)
 </para>
 </listitem>
 </varlistentry>
@@ -260,6 +320,8 @@
 <varlistentry><term>no 'if' for 'else'</term>
 <listitem>
 <para>
+Else statement found with no matching if. This is typically
+caused by extra or missing braces and/or semicolons. (9.3)
 </para>
 </listitem>
 </varlistentry>
@@ -267,6 +329,7 @@
 <varlistentry><term>no switch statement</term>
 <listitem>
 <para>
+Case statements can only appear within a switch block. (9.7)
 </para>
 </listitem>
 </varlistentry>
@@ -274,6 +337,9 @@
 <varlistentry><term>not a function</term>
 <listitem>
 <para>
+Primary in expression is not type "function returning...". If
+this is really a function call, the function name was declared
+differently elsewhere. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -281,6 +347,7 @@
 <varlistentry><term>not an argument</term>
 <listitem>
 <para>
+Name does not appear in the function parameter list. (10.1)
 </para>
 </listitem>
 </varlistentry>
@@ -288,6 +355,9 @@
 <varlistentry><term>operand expected</term>
 <listitem>
 <para>
+Unary operators require one operand, binary operators two.
+This is typically caused by misplaced parenthesis, casts or
+operators. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -317,6 +387,7 @@
 <varlistentry><term>pointer mismatch</term>
 <listitem>
 <para>
+Pointers refer to different types. Use a case if required. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -324,6 +395,8 @@
 <varlistentry><term>pointer or integer required</term>
 <listitem>
 <para>
+A pointer (of any type) or integer is required to the left of
+the '-&gt;' operator. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -331,6 +404,7 @@
 <varlistentry><term>pointer required</term>
 <listitem>
 <para>
+Pointer operand required with unary * operator. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -338,6 +412,7 @@
 <varlistentry><term>primary expected</term>
 <listitem>
 <para>
+Primary expression required here. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -345,6 +420,9 @@
 <varlistentry><term>should be NULL</term>
 <listitem>
 <para>
+Second and third expression of ?: conditional operator cannot
+be pointers to different types. If both are pointers, they
+must be of the same type or one of the two must be null. (7.13)
 </para>
 </listitem>
 </varlistentry>
@@ -352,6 +430,8 @@
 <varlistentry><term>**** STACK OVERFLOW ****</term>
 <listitem>
 <para>
+Compiler stack has overflowed. Most likely cause is very deep
+lock-level nesting or hundreds of switch cases.
 </para>
 </listitem>
 </varlistentry>
@@ -359,6 +439,8 @@
 <varlistentry><term>storage error</term>
 <listitem>
 <para>
+Reg and auto storage classes mey only be used within functions.
+(8.1)
 </para>
 </listitem>
 </varlistentry>
@@ -366,6 +448,8 @@
 <varlistentry><term>struct member mismatch</term>
 <listitem>
 <para>
+Identical member names in two different structures must have
+the same type and offset in both. (8.5)
 </para>
 </listitem>
 </varlistentry>
@@ -373,6 +457,8 @@
 <varlistentry><term>struct member required</term>
 <listitem>
 <para>
+Identifier used with . and -&gt; operators must be a structure
+member name. (7.1)
 </para>
 </listitem>
 </varlistentry>
@@ -380,6 +466,7 @@
 <varlistentry><term>struct syntax</term>
 <listitem>
 <para>
+Brace, comma, etc. is missing in a struct declaration. (8.5)
 </para>
 </listitem>
 </varlistentry>
@@ -387,6 +474,7 @@
 <varlistentry><term>struct or union inappropiate</term>
 <listitem>
 <para>
+Struct or union cannot be used in the context.
 </para>
 </listitem>
 </varlistentry>
@@ -394,6 +482,7 @@
 <varlistentry><term>syntax error</term>
 <listitem>
 <para>
+Expression, declaration or statement is incorrectly formed.
 </para>
 </listitem>
 </varlistentry>
@@ -401,6 +490,9 @@
 <varlistentry><term>third expression missing</term>
 <listitem>
 <para>
+? must be followed by a : with expression. This error may be
+causes by unmatched parenthesis or other errors in the
+expression. (7.13)
 </para>
 </listitem>
 </varlistentry>
@@ -408,6 +500,8 @@
 <varlistentry><term>too long</term>
 <listitem>
 <para>
+Too many characters provided in a string initializing a
+character array. (8.6)
 </para>
 </listitem>
 </varlistentry>
@@ -415,6 +509,8 @@
 <varlistentry><term>too many brackets</term>
 <listitem>
 <para>
+Unmatched or unexpected brackets encountered processiong an
+initializer. (8.6)
 </para>
 </listitem>
 </varlistentry>
@@ -422,6 +518,8 @@
 <varlistentry><term>too many elements</term>
 <listitem>
 <para>
+More data items supplied for aggregate level in initializer
+than members of the aggregate. (8.6)
 </para>
 </listitem>
 </varlistentry>
@@ -429,6 +527,7 @@
 <varlistentry><term>type error</term>
 <listitem>
 <para>
+Compiler type matching error. Should never happen.
 </para>
 </listitem>
 </varlistentry>
@@ -436,6 +535,7 @@
 <varlistentry><term>type mismatch</term>
 <listitem>
 <para>
+Types and/or operators in expression do not correspond. (6)
 </para>
 </listitem>
 </varlistentry>
@@ -443,6 +543,7 @@
 <varlistentry><term>typedef - not a variable</term>
 <listitem>
 <para>
+Typedef type name cannot be used in this manner. (8.8)
 </para>
 </listitem>
 </varlistentry>
@@ -450,6 +551,7 @@
 <varlistentry><term>undeclared variable</term>
 <listitem>
 <para>
+no declaration exists at any block level for this identifier.
 </para>
 </listitem>
 </varlistentry>
@@ -457,6 +559,8 @@
 <varlistentry><term>undefined structure</term>
 <listitem>
 <para>
+Union or struct declaration refers to an undefined structure
+name. (8.5)
 </para>
 </listitem>
 </varlistentry>
@@ -464,6 +568,7 @@
 <varlistentry><term>unions not allowed</term>
 <listitem>
 <para>
+Cannot initialize union members. (8.6)
 </para>
 </listitem>
 </varlistentry>