Changes to files for the Watcom-port
====================================

I ported 'c2man' to the Watcom compiler (Watcom C32 version 11.0a) on MS
windows NT.
At the same time, I invented a "raw ASCII" output filter.

Usage on NT
===========

The file "win32.c2man.h" is necessary. It's included by Watcom's
preprocessor to provide #defines and typedefs that silence warnings and
errors because c2man doesn't know MS-keywords like "__declspec" and so
on, which are used in the system headers.
This file can be modified by the user as necessary.
It is not needed if you use c2man's option -P to change the
preprocessor.

So, place any suitable win32.c2man.h into the current directory or
elswhere into the #include-path (given by the environment variable
INCLUDE) and start c2man.exe with the usual command line arguments.

call "wmake -u -f makefile.watcom" to make.


Stuff found while testing
=========================

While I tested, I found the following errors/omissions/etc.. I've mailed
the list already, but I provide it here for the sake of completeness:

a)
"__declspec(blabla)" (an MS invention) doesn't work.
Frankly, it doesn't need to work, although the MS windows headers are
full of the stuff. But for documentation purposes it doesn't matter, you
can just have a
"#define __declspec(x)" and it's gone.
If you're interested, it's mainly used for exporting functions or
variables from shared libraries ("DLLs"). "__declspec(dllexport) int
foo(int);" means foo is exported.
This works much like the GNU '__attribute__' thing.

b)
A comment preceeding a preprocessor directive in the same line doesn't
work, like:
 /* !_M_IX86 */#line 15 "foo.h"
I've had a lot of them in the system headers until 15 minutes ago :-)
My preprocessor generated the lines whenever it found lines like
 #endif /* !_M_IX86 */
According to the Standard, a comment collapses to a whitespace before
the preprocessor sees it, so Watcom is in its right... although it looks
disgusting. I didn't know it would do that until today. It's really
awful.

c)
You had quite a lot of MS specific keywords already, but I've got more:
__stdcall, stdcall, __far, __near, __huge, and so on...
Basically, it's the current list plus "stdcall", and then all of them
with 2 leading underscores. Doesn't matter, they can be #defined to an
empty string.
They don't need to be in the manpages' prototypes.

d)
A nameless struct doesn't work, like in
  struct s;     /* this is a hidden datatype */

  struct s * create_an_s(size_t any_property_of_s);
     /* creates a struct s with the given property.
      * returns pointer to it.
      */
Your structs need contents, and they need a variable to be declared with
them, like:
  struct s { int dummy; } the_s;
dummy and the_s may not be omitted.

To me this is kind of heavy. I like to use "abstract datatypes" by
declaring a content-unknown struct in a header and implementing
access-functions.

e)
The same for unions, but that's not so interesting.

f)
c2man doesn't seem to like typedefs. The following:
  typedef enum tag_hello
    {
        h_1,    /* h1 */
        h_2     /* h2 */
    } retval;
gets described as
  SYNOPSIS
  extern enum tag_hello {} retval;
But that's a variable declaration instead of a type.

g)
64-bit-integers (longer than long) are not supported. Often they are
called '__int64'.
It's not necessary to support them. They are not standardized, so every
compiler handles them differently, and a "typedef __int64 long;" will
let c2man handle them well.

