From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: =?utf-8?Q?Mattias_Engdeg=C3=A5rd?= Newsgroups: gmane.emacs.devel Subject: Re: Backslash-escaped brackets in string literals Date: Sun, 26 Jan 2020 12:24:11 +0100 Message-ID: References: <64ECD2AB-962B-4781-BFBA-6357277C9599@acm.org> <83a76cq8u7.fsf@gnu.org> <83pnf7pso7.fsf@gnu.org> <83k15fpidk.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.11\)) Content-Type: multipart/mixed; boundary="Apple-Mail=_31F98E4A-867C-40D3-AA66-7A4F516F9E0E" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="95656"; mail-complaints-to="usenet@ciao.gmane.io" Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jan 26 12:24:49 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ivg25-000Or1-8J for ged-emacs-devel@m.gmane-mx.org; Sun, 26 Jan 2020 12:24:49 +0100 Original-Received: from localhost ([::1]:32994 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ivg24-0001v9-Di for ged-emacs-devel@m.gmane-mx.org; Sun, 26 Jan 2020 06:24:48 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44059) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ivg1a-0001Vr-Ow for emacs-devel@gnu.org; Sun, 26 Jan 2020 06:24:19 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ivg1Z-0000LI-H4 for emacs-devel@gnu.org; Sun, 26 Jan 2020 06:24:18 -0500 Original-Received: from mail214c50.megamailservers.eu ([91.136.10.224]:53580 helo=mail193c50.megamailservers.eu) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1ivg1Y-0000GJ-Vq; Sun, 26 Jan 2020 06:24:17 -0500 X-Authenticated-User: mattiase@bredband.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1580037854; bh=kQPNUAHOq81fSMD7pxY28TJd5q+FWLbmoimitHHCA+M=; h=From:Subject:Date:In-Reply-To:Cc:To:References:From; b=c//5qLxgpT0CRPW4y3vZtXVN0NZLVakJw3706XScsuyv5WX4g9QtlugZG26LU++R1 fWR2HwmiS3/9UAcrTR5fXJEWjhURoBt4sRhaTl0oXrdH/KCjhT4thKJUp+QlYlgLdK REpZUSo30g2L0WVUiF81l9VgNoI8HE+BZPEUyy28= Feedback-ID: mattiase@acm.or Original-Received: from [192.168.0.4] (c188-150-171-71.bredband.comhem.se [188.150.171.71]) (authenticated bits=0) by mail193c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 00QBOBpQ031026; Sun, 26 Jan 2020 11:24:13 +0000 In-Reply-To: <83k15fpidk.fsf@gnu.org> X-Mailer: Apple Mail (2.3445.104.11) X-CTCH-RefID: str=0001.0A0B0212.5E2D76DE.0010, ss=1, re=0.000, recu=0.000, reip=0.000, cl=1, cld=1, fgs=0 X-CTCH-VOD: Unknown X-CTCH-Spam: Unknown X-CTCH-Score: 0.000 X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=SamJicZu c=1 sm=1 tr=0 a=SF+I6pRkHZhrawxbOkkvaA==:117 a=SF+I6pRkHZhrawxbOkkvaA==:17 a=jpOVt7BSZ2e4Z31A5e1TngXxSK0=:19 a=M51BFTxLslgA:10 a=mDV3o1hIAAAA:8 a=oPUUAJ0PDfmVtc53aPoA:9 a=CjuIK1q_8ugA:10 a=xkgen_3YrZ2_wr3SnRAA:9 a=B2y7HmGcmWMA:10 a=_FVE-zBwftR9WsbkzFJk:22 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x (no timestamps) [generic] X-Received-From: 91.136.10.224 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:244654 Archived-At: --Apple-Mail=_31F98E4A-867C-40D3-AA66-7A4F516F9E0E Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 25 jan. 2020 kl. 18.15 skrev Eli Zaretskii : > I thought I've just shown you that disregarding this issue entirely is > still premature. I'm okay with maybe making the text less mandatory > and more a recommendation, perhaps even mentioning older Emacs > versions. But removing it entirely? what's the rush? And I thought I just showed you that 'C-x 4 a' had actually been = fixed... Let's shake hands. It's perfectly normal to adjust the documentation to match the = implementation; no need for foot-dragging. Your point about being nice = to users of older versions is taken, though. Would this patch do? It = retains the recommendation while being clear about its purpose. --Apple-Mail=_31F98E4A-867C-40D3-AA66-7A4F516F9E0E Content-Disposition: attachment; filename=0001-Moderate-recommendation-to-escape-in-doc-strings.patch Content-Type: application/octet-stream; x-unix-mode=0644; name="0001-Moderate-recommendation-to-escape-in-doc-strings.patch" Content-Transfer-Encoding: quoted-printable =46rom=2053bceefe2922c2ae36513b1f17f13ab80cda9190=20Mon=20Sep=2017=20= 00:00:00=202001=0AFrom:=20=3D?UTF-8?q?Mattias=3D20Engdeg=3DC3=3DA5rd?=3D=20= =0ADate:=20Sat,=2025=20Jan=202020=2016:16:37=20+0100=0A= Subject:=20[PATCH]=20Moderate=20recommendation=20to=20escape=20'('=20in=20= doc=20strings=0A=0AThanks=20to=2057e2ca5c50=20and=20related=20changes,=20= opening=20brackets=20at=20the=0Aleftmost=20column=20inside=20doc=20= strings=20are=20no=20longer=20mistaken=20for=20the=0Astart=20of=20a=20= defun.=0A=0A*=20doc/lispref/tips.texi=20(Documentation=20Tips):=20= Clarify=20recommendation=0Aand=20move=20it=20down=20the=20list.=0A*=20= etc/NEWS:=20Announce.=0A---=0A=20doc/lispref/tips.texi=20|=2027=20= +++++++++++++++------------=0A=20etc/NEWS=20=20=20=20=20=20=20=20=20=20=20= =20=20=20|=20=204=20++++=0A=202=20files=20changed,=2019=20insertions(+),=20= 12=20deletions(-)=0A=0Adiff=20--git=20a/doc/lispref/tips.texi=20= b/doc/lispref/tips.texi=0Aindex=204395069fe2..0610f8029d=20100644=0A---=20= a/doc/lispref/tips.texi=0A+++=20b/doc/lispref/tips.texi=0A@@=20-802,18=20= +802,6=20@@=20Documentation=20Tips=0A=20starting=20the=20sentence=20with=20= lower-case=20``t'',=20which=20could=20be=20somewhat=0A=20distracting.=0A=20= =0A-@item=0A-If=20a=20line=20in=20a=20documentation=20string=20begins=20= with=20an=20open-parenthesis,=0A-write=20a=20backslash=20before=20the=20= open-parenthesis,=20like=20this:=0A-=0A-@example=0A-The=20argument=20FOO=20= can=20be=20either=20a=20number=0A-\(a=20buffer=20position)=20or=20a=20= string=20(a=20file=20name).=0A-@end=20example=0A-=0A-This=20prevents=20= the=20open-parenthesis=20from=20being=20treated=20as=20the=20start=20of=20= a=0A-defun=20(@pxref{Defuns,,=20Defuns,=20emacs,=20The=20GNU=20Emacs=20= Manual}).=0A-=0A=20@item=0A=20Write=20documentation=20strings=20in=20the=20= active=20voice,=20not=20the=20passive,=20and=20in=0A=20the=20present=20= tense,=20not=20the=20future.=20=20For=20instance,=20use=20``Return=20a=20= list=0A@@=20-849,6=20+837,21=20@@=20Documentation=20Tips=0A=20start=20= with=20words=20such=20as=20``Non-nil=20means'',=20to=20make=20it=20clear=20= that=0A=20all=20non-@code{nil}=20values=20are=20equivalent=20and=20= indicate=20explicitly=20what=0A=20@code{nil}=20and=20non-@code{nil}=20= mean.=0A+=0A+@item=0A+If=20a=20line=20in=20a=20documentation=20string=20= begins=20with=20an=20open-parenthesis,=0A+consider=20writing=20a=20= backslash=20before=20the=20open-parenthesis,=20like=20this:=0A+=0A= +@example=0A+The=20argument=20FOO=20can=20be=20either=20a=20number=0A= +\(a=20buffer=20position)=20or=20a=20string=20(a=20file=20name).=0A+@end=20= example=0A+=0A+This=20avoids=20a=20bug=20in=20Emacs=20versions=20older=20= than=2027.1,=20where=20the=0A+@samp{(}=20was=20treated=20as=20the=20= start=20of=20a=20defun=0A+(@pxref{Defuns,,=20Defuns,=20emacs,=20The=20= GNU=20Emacs=20Manual}).=0A+If=20you=20do=20not=20anticipate=20anyone=20= editing=20your=20code=20with=20older=20Emacs=0A+versions,=20there=20is=20= no=20need=20for=20this=20work-around.=0A=20@end=20itemize=0A=20=0A=20= @node=20Comment=20Tips=0Adiff=20--git=20a/etc/NEWS=20b/etc/NEWS=0Aindex=20= 792851e5af..433f1f76b8=20100644=0A---=20a/etc/NEWS=0A+++=20b/etc/NEWS=0A= @@=20-3338,6=20+3338,10=20@@=20versions.=0A=20'forward-comment',=20= 'scan-sexps',=20and=20'forward-sexp'=20when=20parsing=20backward.=0A=20= The=20new=20variable=20'comment-use-syntax-ppss'=20can=20be=20set=20to=20= nil=20to=20recover=0A=20the=20old=20behavior=20if=20needed.=0A+This=20= also=20means=20that=20there=20is=20no=20longer=20any=20need=20to=20= precede=20opening=0A+brackets=20at=20the=20start=20of=20a=20line=20= inside=20documentation=20strings=20with=20a=0A+backslash,=20although=20= there=20is=20no=20harm=20in=20doing=20so=20to=20make=20the=20code=0A= +easier=20to=20edit=20with=20an=20older=20Emacs=20version.=0A=20=0A=20= ---=0A=20**=20The=20'server-name'=20and=20'server-socket-dir'=20= variables=20are=20set=20when=20a=0A--=20=0A2.21.0=20(Apple=20Git-122.2)=0A= =0A= --Apple-Mail=_31F98E4A-867C-40D3-AA66-7A4F516F9E0E--