Date: Wed, 20 Dec 2017 14:00:12 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Alan Cox <alc@freebsd.org> Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r326982 - head/share/man/man9 Message-ID: <20171220132345.S1291@besplex.bde.org> In-Reply-To: <201712191707.vBJH7onm015225@repo.freebsd.org> References: <201712191707.vBJH7onm015225@repo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20171220132345.S1291>