From owner-svn-src-head@freebsd.org Wed Dec 20 03:20:33 2017 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 2056EE8F005; Wed, 20 Dec 2017 03:20:33 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail109.syd.optusnet.com.au (mail109.syd.optusnet.com.au [211.29.132.80]) by mx1.freebsd.org (Postfix) with ESMTP id DAC7A79852; Wed, 20 Dec 2017 03:20:32 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from [192.168.0.102] (c110-21-101-228.carlnfd1.nsw.optusnet.com.au [110.21.101.228]) by mail109.syd.optusnet.com.au (Postfix) with ESMTPS id 3DAE2D6A9C8; Wed, 20 Dec 2017 14:00:13 +1100 (AEDT) Date: Wed, 20 Dec 2017 14:00:12 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Alan Cox cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r326982 - head/share/man/man9 In-Reply-To: <201712191707.vBJH7onm015225@repo.freebsd.org> Message-ID: <20171220132345.S1291@besplex.bde.org> References: <201712191707.vBJH7onm015225@repo.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.2 cv=cK6QihWN c=1 sm=1 tr=0 a=PalzARQSbocsUSjMRkwAPg==:117 a=PalzARQSbocsUSjMRkwAPg==:17 a=kj9zAlcOel0A:10 a=sSRoe_nAf774Z2qvne8A:9 a=CjuIK1q_8ugA:10 X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.25 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 20 Dec 2017 03:20:33 -0000 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.9 Tue Dec 19 16:45:40 2017 (r326981) > +++ head/share/man/man9/atomic.9 Tue 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. Bruce