On 12/19/2017 21:00, Bruce Evans wrote:
> On Tue, 19 Dec 2017, Alan Cox wrote:
>
>> Log:
>> ...
>> Reorder and revise some of the existing text. For example, more
>> precisely describe when ordinary accesses are atomic.
>> ...
>> Modified: head/share/man/man9/atomic.9
>> ==
>>
>> --- head/share/man/man9/atomic.9Tue Dec 19 16:45:40 2017
>> (r326981)
>> +++ head/share/man/man9/atomic.9Tue Dec 19 17:07:50 2017
>> (r326982)
>> ...
>> @@ -147,8 +149,7 @@ unsigned 8-bit integer
>> unsigned 16-bit integer
>> .El
>> .Pp
>> -These must not be used in MI code because the instructions to
>> implement them
>> -efficiently might not be available.
>> +These types must not be used in machine-independent code.
>
> Example of normal use of "must". It is a requirement forthe caller.
>
>> .Pp
>> -When an atomic operation has acquire semantics, the effects of the
>> operation
>> -must have completed before any subsequent load or store (by program
>> order) is
>> +When an atomic operation has acquire semantics, the operation must have
>> +completed before any subsequent load or store (by program order) is
>
> Most other uses of "must" are requirements for the implementation. This
> commit seemed to introduce this misuse, but I just noticed that it was
> common and this commit only increased it a lot.
>
> POSIX uses "shall" a lot for requirements on the implementation. This is
> at best noise if it is copied to man pages, and we have the
> /usr/share/examples/mdoc/deshallify.sh script for removing the noise,
> e.g., by s/shall be/is/g (with complications or singular vs plural...).
> This is rarely used since the otherwise better wording in POSIX is rarely
> used in FreeBSD man pages, but the man pages are fairly shall-free, with
> most shalls being for requirements related to copyrights.
>
> s/must have competed/completes/g seems to be a correct demustification
> for
> the above. atomic.9 has to be more careful with tenses than most man
> pages
> since it is half about delicate ordering, so I wouldn't trust automatic
> translation of irregular verbs. It would be better to describe the
> ordering using symbols like <= than with words like "before" and
> complicated verbs.
Okay, I'll take a look at this.
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
