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.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.
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"
