Date: Thu, 15 Jun 2006 07:38:52 -0700 From: Rich Morin <rdm@cfcl.com> To: freebsd-doc@freebsd.org Subject: Re: checking man page includes and prototypes? Message-ID: <p062309e8c0b71c75ffc1@[192.168.254.205]> In-Reply-To: <p062309d5c0b5e6114077@[192.168.254.205]> References: <p062309d5c0b5e6114077@[192.168.254.205]>
next in thread | previous in thread | raw e-mail | index | archive | help
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@cfcl.com
http://www.cfcl.com/rdm/weblog +1 650-873-7841
Technical editing and writing, programming, and web development
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?p062309e8c0b71c75ffc1>