Justin,
> On Tue, May 30, 2006 at 12:26:45AM +0200, Michael Kerrisk wrote:
>> Justin,
>>
>> I feel this page could be improved further. Please:
>>
>> * read "man 3p getsubopt" and "info getsubopt".
> As noted in the manpage, I have done so.
(I think) I didn't mean that you hadn't read them -- mainly I was
worried about inconsistent terminology.
>> 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.)
> Attached.
Thanks.
>>> .TH GETSUBOPT 3 "2006-05-26" GNU
>>> .
>> What are these dots doing?
> Best-practice mentioned in roff.7:
>
> o Never include empty or blank lines in a roff document. Instead,
> use the empty request (a line consisting of a dot only) or a line
> comment .\" if a structuring element is needed.
Okay -- thanks for the pointer. Nevertheless, I'd prefer that you left
them out altogether. Please do so.
>>> .SH SYNOPSIS
>>> \fB#define _XOPEN_SOURCE 500
>> I prefer that you use the ".BI" style for
>> prototypes (see fcntl.2); please change this.
> You'll be happy to know that I recently started using them for argp.3.
>
> BTW, where are \f[RPBI] documented?
I don't know.
> I dislike .{nf,fi}, since it assumes a given terminal width.
The alternative is ugly, right justified prototypes. These are (IMO)
harder to read.
> By the
> way, why does nroff |less seem to assume 80 character width?
Because that's your terminal width?
> Re: your previous question ("Re: Fixes from the Debian diff...",
> [EMAIL PROTECTED])
>
> groff_diff.7:
> In GNU troff, as in UNIX troff, you should always follow a sentence
> with either a newline or two spaces.
Interesting. Of course many existing pages violate that. (This is not
an invitation for a patch.)
> Also:
>
> groff.7
> In text paragraphs, it is advantageous to start each sentence at a
> line of its own.
Interesting. I have different reasons for also preferring that.
(Diffs are likely to be at the sentence level.)
> roff.7
> o Start each sentence on a line of its own, for the spacing after a
> dot is handled differently depending on whether it terminates an
> abbreviation or a sentence. To distinguish both cases, do a line
> break after each sentence.
Thanks for the info.
>>> \fBNULL\fP-terminated list of accepted parameters.
>> Please don't format "NULL".
> Done; could you provide a quantitative distinction between things
> which should{,n't} be formatted?
In general, you can format constants, but NULL is so common that it
seems not worthwhile (and visually overpowering because it can be
frequent) to do so.
>>> 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"
> Is your objection to the order of the clauses, or to the preposition?
The preposition.
Cheers,
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]
