Justin, I feel this page could be improved further. Please:
* read "man 3p getsubopt" and "info getsubopt". Make your terminology consistent with them (epsecially the 3p doc; e.g., use "token" and "value") * send me a test program that you've used to verify how getsubopt works. (Don't worry about including it in the man page -- I may do that later.) > .TH GETSUBOPT 3 "2006-05-26" GNU > . What are these dots doing? > .SH NAME > getsubopt \- parse comma-separated commandline parameters "commandline" is not correct; "command-line" > . > .SH SYNOPSIS > \fB#define _XOPEN_SOURCE 500 I prefer that you use the ".BI" style for prototypes (see fcntl.2); please change this. > \fB#include <stdlib.h> > > \fBint getsubopt(char **\fIoptionp\fP, char * const *\fPtokens\fP, char > **\fPvaluep\fP); > . > .SH DESCRIPTION > \fBgetsubopt\fP() parses \fPmount\fP(1)-style commandline arguments. I wouldn't describe things in terms of mount(1) -- that command is merely an example. Write it more generally, and then (maybe) cite mount(1) as an example. > An argument is defined as a list of comma-separated parameters with > optional values: > .sp > .RS > .B cat,bat=baz,rat,vat > .RE > > \fIoptionp\fP is a pointer to the input string; \fItokens\fP is a In fact I prefer the ".B/.I" approach generally; thus .I optionp Please change. > \fBNULL\fP-terminated list of accepted parameters. Please don't format "NULL". > The first equal sign in a parameter (if any) is interpreted as a > separator between the name and the value of that parameter. The value > extends to the next comma, or (for the last parameter) to the end of > the string. If the name of the parameter matches a known name from > \fItokens\fP, and a value string was found, \fBgetsubopt\fP() stores > to As noted for another of your pages, "stores to" isn't good grammer; Better: "store the address of that string in *valuep" > \fI*valuep\fP the address of that string. The first comma in > \fIoptionp\fP is overwritten with a null byte, so \fI*valuep\fP is > precisely the "value string" for that parameter. > > If the parameter is known, but no value string was found, > \fI*valuep\fP is set to \fBNULL\fP. No formatting of "NULL". > When \fBgetsubopt\fP() returns, \fIoptionp\fP points to the next .BR, .I > suboption, or the null character at the end of the string if the last > suboption was just processed. > . > .SH "RETURN VALUE" > If the first parameter in \fIoptionp\fP is known, \fBgetsubopt\fP() > returns the index into \fItokens\fP of that parameter. Otherwise, \-1 > is returned and \fI*valuep\fP is the entire > .IB name [= value ] > string. > > Since \fI*optionp\fP is changed, the first parameter before > \fBgetsubopt\fP() is not (necessarily) the same as the first parameter > after \fBgetsubopt\fP(). > . > .SH "CONFORMING TO" > \fBgetsubopt\fP() is specified by XPG4v2. > . > .SH NOTES > The tokens should be distinct, null-terminated strings containing at > least one character, with no embedded equal signs or commas. > > Since \fBgetsubopt\fP() overwrites any commas it finds in > \fI*optionp\fP, that variable must be writable; it cannot be a string > constant. > . > .SH SEE ALSO > .BR getopt (3), > .BR mount (1) Remove the "mount" reference. Thanks. Michael -- Michael Kerrisk maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 Want to help with man page maintenance? Grab the latest tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/, read the HOWTOHELP file and grep the source files for 'FIXME'. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
