Documentation Update

[Michael van Acken <acken@vanacken.do.uunet.de>]

Here is a small documentation diff describing the changes that were
made to oo2c for the Win32 target.  Anything dropped from the docs is
no longer known to the compiler.  I will send the changes over to Eric
for inclusion into the next release of OOCref, with additional
material describing oocn.  That's the plan, anyway.

As an aside, I intend to unbundle X11 support from the oo2c
distribution starting with the next release.  The X11 files, including
OakXYplane.Mod, will be available as a separate file (at Tim's site)
that will install just like VO (i.e., "./configure; make install"
should do the trick).

-- mva

------------------------------------------------------------------------

-The ``calling convention'' string specifies how procedures declared in this
-module are to be activated by the compiler.  At the moment, the only calling
-convention supported by @code{oo2c} is @code{"C"}.
+The ``calling convention'' string specifies how procedures declared in
+this module are to be activated by the compiler.  At the moment, the
+only calling convention supported for all target operating systems is
+@code{"C"}.  If the target operating system is @samp{Win32}, then
+additionally the calling convention @code{"Pascal"} is available.  The
+default calling convention used is @code{"Pascal"} for @samp{Win32}, and
+@code{"C"} for all other targets.
 
 The implementation of a module can be taken from a number of sources: an
 uncompiled C file, an object file, a library, or an arbitrary mix of these
@@ -1762,11 +1676,6 @@
 The @samp{INIT_FCT} flag signals that module @file{Foo.Mod} links in a
 function @code{void Foo__init(void)}, which will be called during
 program startup as part of the normal module initialization.
-
-@item GCC_ATTRIB_STDCALL
-When used in an @samp{INTERFACE} module, this flag sets the corresponding
-type flag for all procedure types of the module.  This includes both
-procedure declarations and definitions of procedure types.
 @end table
 
 
@@ -1801,26 +1710,27 @@
 flag is automatically set if the pointer or the base type is marked with
 @samp{NO_DESCRIPTOR}, @samp{NO_LENGTH_INFO}, or @samp{STATIC_POINTER}.
 
-@item GCC_ATTRIB_STDCALL
-When translating this procedure type to C, insert the string
-@samp{__attribute__ ((stdcall))} before the name of the function
-declaration.  This special declaration convention is used to access
-functions of the MS-Windows API with @code{gcc}.
-
-@item NOALIGN
-Record flag, not implemented yet...
-
-@item ALIGN2
-Record flag, not implemented yet...
-
-@item ALIGN4
-Record flag, not implemented yet...
-
-@item ALIGN8
-Record flag, not implemented yet...
-
-@item UNTAGGED
-Record and array flag, not implemented yet...
+@item ALIGN1, ALIGN2, ALIGN4, ALIGN8
+Determines the alignment of record fields.  By default record fields of
+scalar type are aligned at addresses that are a multiple of the type's
+size in bytes@footnote{At the moment this is even done if the target
+system uses less alignment for some basic types.  This only leads to
+problems, e.g. on ix86 systems, if the record declaration contains a
+field of type @code{double} that must be aligned at 4 bytes.}.
+Specifying @samp{ALIGNn} forces the alignment to be at most @samp{n}
+bytes, i.e., all fields that would be aligned with more than @samp{n}
+bytes are instead aligned at @samp{n} byte boundaries.  @samp{ALIGN1}
+effectively disables all padding between record fields.
+
+@item CSTRING
+Setting this flag for a pointer type whose base type is a character
+array enables C-style array assignment semantics for variables derived
+from this type.  Assigning a character array or string constant to such
+a pointer variable is legal, and assigns the @emph{address} (but not the
+@emph{contents}) of the array or string to the variable.  With this
+feature external C functions with string parameters can be called
+without reverting to the cumbersome @code{SYSTEM.VAL(P,SYSTEM.ADR(a))}
+construction.
 @end table
 
 Procedure types and procedure declarations inherit the calling convention
@@ -1837,10 +1747,12 @@
 rules for matching parameter lists: two corresponding parameters are
 required to share the same system flags in order to match.
 
-@code{oo2c} uses the C calling convention for standard Oberon-2 procedures.
-This means that any matching C function can be assigned to an Oberon-2
-procedure variable.  This does not work with compilers that use different
-calling conventions for native procedures and Oberon-2 procedures.
+@code{oo2c} uses the default calling convention of the target operating
+system for standard Oberon-2 procedures.  This means that any matching C
+function can be assigned to an Oberon-2 procedure variable unless the
+function's calling convention has been overidden.  The compiler will
+prevent an assignment, if the calling convention of the procedure
+variable differs from that of the procedure.