Date: Fri, 22 Dec 2017 11:30:59 -0600 From: Alan Cox <alc@rice.edu> To: Bruce Evans <brde@optusnet.com.au>, 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: <de9a7cc7-5687-8a1c-0de9-6f763d3a0b10@rice.edu> In-Reply-To: <20171220132345.S1291@besplex.bde.org> References: <201712191707.vBJH7onm015225@repo.freebsd.org> <20171220132345.S1291@besplex.bde.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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 >> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D >> >> --- head/share/man/man9/atomic.9 Tue Dec 19 16:45:40 2017 =20 >> (r326981) >> +++ head/share/man/man9/atomic.9 Tue Dec 19 17:07:50 2017 =20 >> (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 ha= ve >> +completed before any subsequent load or store (by program order) is > > Most other uses of "must" are requirements for the implementation. Thi= s > 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 rare= ly > used in FreeBSD man pages, but the man pages are fairly shall-free, wit= h > 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 <=3D than with words like "before" and > complicated verbs.=20 Okay, I'll take a look at this.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?de9a7cc7-5687-8a1c-0de9-6f763d3a0b10>