From owner-svn-src-head@freebsd.org Fri Dec 22 17:31:03 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 23146EA605D; Fri, 22 Dec 2017 17:31:03 +0000 (UTC) (envelope-from alc@rice.edu) Received: from mx0b-0010f301.pphosted.com (mx0b-0010f301.pphosted.com [148.163.153.244]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "*.pphosted.com", Issuer "thawte SHA256 SSL CA" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id BF8CA7FC41; Fri, 22 Dec 2017 17:31:02 +0000 (UTC) (envelope-from alc@rice.edu) Received: from pps.filterd (m0102859.ppops.net [127.0.0.1]) by mx0b-0010f301.pphosted.com (8.16.0.21/8.16.0.21) with SMTP id vBMHQUaE015630; Fri, 22 Dec 2017 11:31:00 -0600 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=rice.edu; h=subject : to : cc : references : from : message-id : date : mime-version : in-reply-to : content-type : content-transfer-encoding; s=ricemail; bh=lNOxlsPQ78flGiKNbLRZCXG5fhAyW7VqF0kuQeR5W7A=; b=V2Gn3XzazaxI3pwvLt1xU50Q7RHrkWsRky0f7BFsLrH38FdSJaSkwhsy+DpefmUqafLC OhmOAve3PbkL+V8SJQCaFRGzElKek6PAAutWfuWCGOCH60RwR/m5yB/tJCcsA/z150av wnNFSetyMymEDK78jUhu2EvMTx5wEriclFOm7kSh5SvWG6n8ScCFk7qQ/jx9PrcNcy9o vh+jKlbf4V5Rl9ghQDrpy0pLvgRZjryE5ghWklKaUbrFov2I1mPkCvoWVe1aA9iPkK2T DWYaN8sdcCNUbUYeSoTrjsWFsK2EOwWCMI2wBwJycvSsoo8scsXa3ANWSWoD7iiUi16Z 1w== Received: from mh11.mail.rice.edu (mh11.mail.rice.edu [128.42.199.30]) by mx0b-0010f301.pphosted.com with ESMTP id 2eyanu43xf-1; Fri, 22 Dec 2017 11:31:00 -0600 Received-X: from mh11.mail.rice.edu (localhost.localdomain [127.0.0.1]) by mh11.mail.rice.edu (Postfix) with ESMTP id 065564C07BE; Fri, 22 Dec 2017 11:31:00 -0600 (CST) Received-X: from mh11.mail.rice.edu (localhost.localdomain [127.0.0.1]) by mh11.mail.rice.edu (Postfix) with ESMTP id 0473E4C07AC; Fri, 22 Dec 2017 11:31:00 -0600 (CST) X-Virus-Scanned: by amavis-2.7.0 at mh11.mail.rice.edu, auth channel Received-X: from mh11.mail.rice.edu ([127.0.0.1]) by mh11.mail.rice.edu (mh11.mail.rice.edu [127.0.0.1]) (amavis, port 10026) with ESMTP id zy4n5eQChmWT; Fri, 22 Dec 2017 11:30:59 -0600 (CST) Received: from 108-254-203-201.lightspeed.hstntx.sbcglobal.net (108-254-203-201.lightspeed.hstntx.sbcglobal.net [108.254.203.201]) (using TLSv1 with cipher RC4-MD5 (128/128 bits)) (No client certificate requested) (Authenticated sender: alc) by mh11.mail.rice.edu (Postfix) with ESMTPSA id 927124C06CA; Fri, 22 Dec 2017 11:30:59 -0600 (CST) Subject: Re: svn commit: r326982 - head/share/man/man9 To: Bruce Evans , Alan Cox Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org References: <201712191707.vBJH7onm015225@repo.freebsd.org> <20171220132345.S1291@besplex.bde.org> From: Alan Cox Message-ID: Date: Fri, 22 Dec 2017 11:30:59 -0600 User-Agent: Mozilla/5.0 (X11; FreeBSD i386; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 MIME-Version: 1.0 In-Reply-To: <20171220132345.S1291@besplex.bde.org> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Content-Language: en-US X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2017-12-22_06:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=13 phishscore=0 bulkscore=0 spamscore=0 clxscore=1011 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=357 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1712220246 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: Fri, 22 Dec 2017 17:31:03 -0000 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.