checking man page includes and prototypes?

[Rich Morin]

In case anyone is interested, here is the outline of a way
to check man page includes and prototypes against the code:

  For each man page:
    Save #include information.
    For each prototype:
      Construct two C test files.
      Compile the test files.
      Look for nastygrams, etc.


For example, the sysconf(3) SYNOPSIS contains the lines:

  #include <unistd.h>

  long
  sysconf(int name);


Here's the first test file:

  % cat test1.c
  /*
  || test1.c - test to see if prototype matches what's included.
  ||
  || Usage:  cc -c test1.c  # Silence gives consent.
  */

  #include <unistd.h>       /* man page include(s) */

  long sysconf(int name);   /* man page prototype  */


Here's the second test file:

  % cat test2.c
  /*
  || test2.c - test to see if include(s) supply a prototype
  ||
  || Usage:  cc -c test2.c  # Silence means error.
  ||
  || Output should be of the form:
  ||
  ||   test2.c:9: error: conflicting types for 'sysconf'
  ||   /usr/include/unistd.h:462: error:
  ||     previous declaration of 'sysconf' was here
  */

  #include <unistd.h>        /* man page include(s)   */

  void sysconf(void, void);  /* known false prototype */


The testing process will be somewhat iterative, because of
oddball cases.  Roughly:

  Generate and test files, reporting only the exceptions.
  If parsing problems are encountered, either:
    Tweak the man page to make parsing easier,
    upgrade the parsing script to handle the issue,
    or add a "hint" to a control (e.g., YAML) file.
  If actual inconsistencies are found, either:
    Fix the man page to match the code, or vice versa.
  Rinse, repeat until the test script comes up clean.


This test suite could (and I believe should) be put into
the release cycle, as a sanity check.  If anyone wants to
pursue the matter, please contact me for details.

-r
-- 
http://www.cfcl.com/rdm            Rich Morin
http://www.cfcl.com/rdm/resume     rdm at cfcl.com
http://www.cfcl.com/rdm/weblog     +1 650-873-7841

Technical editing and writing, programming, and web development