From owner-freebsd-doc@FreeBSD.ORG Thu Jun 15 14:37:17 2006 Return-Path: X-Original-To: freebsd-doc@freebsd.org Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id E3AE816A479 for ; Thu, 15 Jun 2006 14:37:17 +0000 (UTC) (envelope-from rdm@cfcl.com) Received: from cfcl.com (cpe-24-221-172-174.ca.sprintbbd.net [24.221.172.174]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6A91143D49 for ; Thu, 15 Jun 2006 14:37:17 +0000 (GMT) (envelope-from rdm@cfcl.com) Received: from [192.168.254.205] ([192.168.254.205]) by cfcl.com (8.12.6/8.12.6) with ESMTP id k5FEgMvF017645 for ; Thu, 15 Jun 2006 07:42:23 -0700 (PDT) (envelope-from rdm@cfcl.com) Mime-Version: 1.0 Message-Id: In-Reply-To: References: Date: Thu, 15 Jun 2006 07:38:52 -0700 To: freebsd-doc@freebsd.org From: Rich Morin Content-Type: text/plain; charset="us-ascii" Subject: Re: checking man page includes and prototypes? X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 15 Jun 2006 14:37:18 -0000 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 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 /* 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 /* 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