Frequently Asked Questions about c2man
--------------------------------------
By Graham Stoney (greyham@research.canon.com.au)
Last-modified: $Date: 2000/02/25 01:07:24 $

Q. Where can I get an up-to-date already patched copy of c2man?

A. The latest complete version is available via ftp from:
	ftp://ftp.research.canon.com.au/pub/misc/c2man/c2man.tar.gz

   If you wish to upgrade an existing version rather than fetching the entire
   package, you can fetch the patches from:
	ftp://ftp.research.canon.com.au/pub/misc/c2man/patches/

   It should also be available in your local comp.sources.misc archive.  The
   versions in the alt.sources and comp.sources.reviewed archives are
   obsolete.


Q. How do I remove myself from the c2man discussion list?

A. You should have received instructions on how to do this when you joined the
   list.  It's always wise to save a copy of the instructions you receive when
   you join a mailing list, so that you can refer to them in future when you
   wish to leave.

   To remove yourself from the c2man discussion list, send E-mail to:
        majordomo@research.canon.com.au

   With the message:
	Subject:
	unsubscribe c2man

   You should also be able to unsubscribe by running Configure again, and
   asking it to unsubscribe you when it asks if you wish to subscribe to, or
   unsubscribe from the mailing list.

   Note that the discussion list and the automatic patch notification/update
   list are completely independent.


Q. Can c2man handle C++?  Is anyone working on a version that can?

A. No, it can't handle C++, although there are other tools that do a similar
   job for C++.  A few people have expressed interest, but I don't know of
   anyone who is actively working on it.  If you look in the file C++autodoc in
   the distribution, you'll get all the gory details.  This file is always kept
   up-to-date with the current state of play.


Q. How do I apply the official patches to c2man?

A. You need the patch program, by Larry Wall.  Chances are that it's already
   installed on your system; if not, you could ask your system administrator
   about getting it, or search for it using archie if you know how.  Once
   you've got it, follow the instructions in each of the patch headers.  For
   example, patch 10 says:

    Fix:    From rn, say "| patch -p -N -d DIR", where DIR is your c2man source
	    directory.  Outside of rn, say "cd DIR; patch -p -N <thisarticle".
	    If you don't have the patch program, apply the following by hand,
	    or get patch (version 2.0, latest patchlevel).
    
   In other words, 'cd' to your c2man directory and type:
	    patch -p -N < patch10

   That should feed the patch into the patch program, which will apply it.  You
   also need to take care to follow the "After Patching" instructions in each
   patch, and repeat this procedure for each patch.  In general, you can apply
   all the patches without having to re-run Configure after every patch set,
   although you must run Configure after patch30, because it renames a few
   files.  You can apply patches 10 through 30 without having to run Configure
   though.  The "After patching" instructions assume that you apply patches as
   they are issued; you don't generally have to do them multiple times if
   you're applying a whole group of patch sets.


Q. Can c2man document structure fields automatically, like it does for enums?

A. In short, No.

   This is a very logical extension; so much so in fact that I'd say it's
   absence in the current version is a real deficiency.  I'm not sure if you
   always want the structure contents listed in the manual page for the
   functions that use the type though, since some interfaces use "opaque"
   types, where the structure contents is deliberately hidden from the user;
   eg: the stdio FILE type.  My thoughts were to generate a separate manual
   page for each struct or type definition, with perhaps an option to include
   the info in all the functional manual pages using that type, as now happens
   with enum types now.
   
   Adding struct support to the current grammar should be fairly easy; mainly
   by copying what it does with enum's; and it would certainly be very
   worthwhile.  I'd encourage anyone who'd like to see greater functionality in
   c2man to feel free to add it in, and send me the diffs.

   Sorry, this doesn't work at present.  It's probably the most serious
   omission from the program; lots of people have asked about this.  At
   present, I don't know when it's likely to be fixed.  I might suddenly get
   really keen one day and do it -- otherwise, someone else will have to
   implement it and send me the diffs.  It shouldn't be too hard, but it's a
   matter of making it a priority and getting around to actually doing it...


Q. Why do my functions using ``FILE *'' get documented with this weird
   ``struct _iobuf'' type?

A. Unfortunately, many systems use a #define for ``FILE'' in stdio.h to rename
   it to ``struct _iobuf'', rather than using a typedef.  Since c2man sees the
   output of the pre-processor, ``FILE'' is long gone before it reads the
   code, and so the documentation that it generates is misleading.

   Some stdio.h's perform this #define conditionally, so it may be possible to
   pass certain -D flags to c2man which will cause stdio.h to use a typedef
   instead, although this will be very system-dependent.

   I don't know of a really good solution to this problem, but I'd be
   interested to hear if anyone has one.


Q. How can I get c2man recognise and document #defines?

A. c2man doesn't recognise #defines at all, but you can rewrite it as an enum.
   You do need to be able to change the type passed to an enum though, to get
   c2man to recognise that it's what's being passed.  C is very loose with its
   enums, so it's still just as flexible as the #define case, and the types
   look more self-documenting in the code too:

	enum Bits
	{
		BIT0 = 1,       /* The first bit */
		BIT1 = 2,       /* The next bit */
		BIT2 = 4        /* The last bit */
	};
	
	/* set the bits! */
	void set_bits( enum Bits bits );
	
   Gives you:
	
	set_bits(3)         UNIX Programmer's Manual          set_bits(3)
	
	NAME
		set_bits - set the bits!
	
	SYNOPSIS
		#include <set_bits.h>
	
		void set_bits(enum Bits bits);
	
	PARAMETERS
		enum Bits bits
		    Possible values for an enum Bits are as follows:
		    BIT0  The first bit.
		    BIT1  The next bit.
		    BIT2  The last bit.
	
	DESCRIPTION
		Set the bits!.


Q. But what if my function returns an errno-like code which can take many
   values, but I'd like the documentation to list only those that the function
   in question can actually generate?

A. c2man makes a crude attempt at identifying token/value lists in the RETURNS
   section from the comment describing the function.  If the first thing on a
   line in the RETURNS section is a single token followed a ':' or TAB
   character, c2man interprets it as a token list and attempts to format it
   accordingly.  Have a look at the file "eg/reterrno.h" for an example.