cvs commit: src/sys/ufs/ufs ufs_vnops.c

[Greg 'groggy' Lehey]

On Friday,  2 June 2006 at  2:50:47 +1000, Bruce Evans wrote:
> On Thu, 1 Jun 2006, John Baldwin wrote:
>
>> On Thursday 01 June 2006 06:01, Alexey Dokuchaev wrote:
>>> On Thu, Jun 01, 2006 at 10:49:50AM +0100, Ceri Davies wrote:
>>>> @@ -69,6 +69,10 @@
>>>> the file must be open for writing.
>>>> .Sh RETURN VALUES
>>>> .Rv -std
>>>> +If the file to be modified is not a directory or
>>>> +a regular file, the
>>>> +.Fn truncate
>>>> +call will return the value 0.
>>>
>>> Doesn't "value of 0" sound better?
>>
>> Not to me, though I can't explain why.  I think the phrase "X will return
>> the
>> value Y" is common in man pages though.
>
> "will return" sounds strange to be.

Yes, it will be better if you avoid the future tense.

> Normal is "Upon successful completion, the value 0 is returned...".

The passive is also to be avoided.

How about "upon successful completion,\n.Nm\nreturns the value 0."?

> This is part of what ".Rv -std" expands to.
>
> POSIX says "Upon successful completion, ftruncate( ) shall return 0...".

Yes, but this is prescriptive.  The man page should be descriptive.

> The POSIX wording is better.  "the value 0" says nothing more than
> "0",

It makes it clear that it's not a NULL pointer.

> and "returns" is clearer than "is returned".

Yes.

> Saying "the value 0" is apparently a hack to give the clause a
> subject (or is it an object? -- I think the value is the object
> convoluted to a subject or vice versa).

I don't think it makes any difference there.  0 is also a
subject/object.

Greg
--
See complete headers for address and phone numbers.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/cvs-src/attachments/20060602/b7ccd2cf/attachment.pgp