From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] master b533552 2/5: Documentation fixes re quotes Date: Tue, 1 Sep 2015 18:05:15 -0700 Organization: UCLA Computer Science Department Message-ID: <55E64B4B.3030006@cs.ucla.edu> References: <20150831061236.27796.57762@vcs.savannah.gnu.org> <55E3F3AD.2010602@yandex.ru> <55E3F6B6.20205@cs.ucla.edu> <55E3F88A.50003@yandex.ru> <55E3F9D7.6040601@cs.ucla.edu> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1441155938 1846 80.91.229.3 (2 Sep 2015 01:05:38 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 2 Sep 2015 01:05:38 +0000 (UTC) Cc: emacs-devel@gnu.org To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Sep 02 03:05:26 2015 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1ZWwUP-0002UQ-Be for ged-emacs-devel@m.gmane.org; Wed, 02 Sep 2015 03:05:25 +0200 Original-Received: from localhost ([::1]:59997 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZWwUO-0006ns-UM for ged-emacs-devel@m.gmane.org; Tue, 01 Sep 2015 21:05:24 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34375) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZWwUL-0006nc-BT for emacs-devel@gnu.org; Tue, 01 Sep 2015 21:05:22 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZWwUI-000093-6X for emacs-devel@gnu.org; Tue, 01 Sep 2015 21:05:21 -0400 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:38153) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZWwUH-00008x-U4; Tue, 01 Sep 2015 21:05:18 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 84C96160828; Tue, 1 Sep 2015 18:05:16 -0700 (PDT) Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id bboGhGHt1iWp; Tue, 1 Sep 2015 18:05:15 -0700 (PDT) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id B46FD160F8C; Tue, 1 Sep 2015 18:05:15 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id orz6PW0ntCpb; Tue, 1 Sep 2015 18:05:15 -0700 (PDT) Original-Received: from [192.168.1.9] (pool-100-32-155-148.lsanca.fios.verizon.net [100.32.155.148]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 953DF160828; Tue, 1 Sep 2015 18:05:15 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.2.0 In-Reply-To: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 131.179.128.68 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:189440 Archived-At: Richard Stallman wrote: > Doc strings should be written > with straight quotes, so the example should show straight quotes. That example came very early in the tutorial, where it's inappropriate to be burdening the novice reader with low-priority detail like quoting, so I rewrote it to use neither curved nor grave quotes, thus sidestepping the issue in that example. I also reverted the changes that curved the quotes in the the bulk of the examples, which were taken from Emacs 22, so they now quote `like this' as before. > However, the text should > explain (without the full detail) the difference in quotes. I added text to do that as well. All the above is in master commit afe1cf00713847c1d8f3a9d95d4980d705ec39f1. More generally, though, I did not remove every single curved quote from the tutorial. That is because it's fine if some programmers want to use curved quotes in docstrings and diagnostics. These quotes have worked for many years, and they now work even a bit better than they did before, in the sense that they're now markup that is automatically converted to grave quotes for old-fashioned users who prefer the grave style. Using curved quotes in the source has technical advantages, as the programmer sees the same quotes that typical users will see in the next version of Emacs, which is a clear win. Of course it also has technical disadvantages, for developers who have trouble dealing with non-ASCII characters or who want to have code that generates diagnostics or help buffers that quote `like this' in older Emacs versions, but overall in many cases the benefits exceed the costs and it is a win, and it's OK for the Emacs documentation to cover this alternative. As far as the Emacs source code goes, because the master for a while had an approach that required the use of curved quotes for proper markup, and because I was using Electric Quote mode where it's easier to type curved than straight quotes, I converted some diagnostics and documentation source to use curved quotes. Most (though not all) of these curved quotes can now be converted back to grave quotes if someone who hates, Hates, HATES curved quotes wants to take the trouble to do that. However, I doubt whether it's worth the effort, as the curved quotes work fine in practice in the source, and really, why not give them a try? In practice they might not be as bad as all that.