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: Escaping quotes in docstrings, Was: A simple solution to "Upcoming loss of usability ..." Date: Mon, 06 Jul 2015 09:30:31 -0700 Organization: UCLA Computer Science Department Message-ID: <559AAD27.3000403@cs.ucla.edu> References: <87egkzg7gb.fsf@gmail.com> <558C2E25.10303@cs.ucla.edu> <558C492E.9000705@yandex.ru> <558C7DE1.4060507@cs.ucla.edu> <558C82D2.1070408@yandex.ru> <558CBA7E.7060900@cs.ucla.edu> <558D403D.303@yandex.ru> <558EDD4C.4040002@cs.ucla.edu> <558EE315.3080107@yandex.ru> <558F10FA.409@cs.ucla.edu> <558F4804.1020406@yandex.ru> <559010D6.5090905@cs.ucla.edu> <559058AD.5060504@yandex.ru> <55908355.3080407@yandex.ru> <559356D2.4000103@cs.ucla.edu> <5594813A.3000705@yandex.ru> <5594E0DB.1080702@cs.ucla.edu> <559A1C54.5030405@cs.ucla.edu> <559A6F86.2080809@yandex.ru> 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 1436202199 29861 80.91.229.3 (6 Jul 2015 17:03:19 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 6 Jul 2015 17:03:19 +0000 (UTC) To: Dmitry Gutov , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jul 06 19:03:12 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 1ZC9nT-0006ln-Uq for ged-emacs-devel@m.gmane.org; Mon, 06 Jul 2015 19:03:12 +0200 Original-Received: from localhost ([::1]:52029 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZC9KK-000401-S3 for ged-emacs-devel@m.gmane.org; Mon, 06 Jul 2015 12:33:04 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45499) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZC9I0-0001J3-Eh for emacs-devel@gnu.org; Mon, 06 Jul 2015 12:30:41 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZC9Hv-0005WR-AN for emacs-devel@gnu.org; Mon, 06 Jul 2015 12:30:40 -0400 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:38904) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZC9Hu-0005Vj-P3 for emacs-devel@gnu.org; Mon, 06 Jul 2015 12:30:34 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 3AB6A16019C; Mon, 6 Jul 2015 09:30:33 -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 JL-tuuFokSww; Mon, 6 Jul 2015 09:30:31 -0700 (PDT) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id DB3F4160888; Mon, 6 Jul 2015 09:30:31 -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 K_S1tvGKz3aI; Mon, 6 Jul 2015 09:30:31 -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 BD93616019C; Mon, 6 Jul 2015 09:30:31 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.7.0 In-Reply-To: <559A6F86.2080809@yandex.ru> 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:187744 Archived-At: Dmitry Gutov wrote: > Why not put `escaped' (or rename that `translated', maybe) on those generated > regions as well? Yes, in theory it could be done. But see below. >> Second, and more generally, the overall approach seems error prone. It >> asks programmers to mark every quote character that should not be >> transformed. But characters can come from many different sources, and >> it's hard to keep track of each place that can insert user data of some >> sort. > > So far I've only seen a few places of complication nearby: key translations, > keymap translations, and the escaping mechanism itself. I'm afraid this is because you've only started looking. Even if we limit ourselves to the regions you mention, the relevant code is scattered all over the place and it's hard to find exactly where to put 'escaped' or 'translated' into those regions. For example, one place might be the following code in keymap.c's single_key_description function: Lisp_Object result; char *buffer = SAFE_ALLOCA (sizeof "<>" + SBYTES (SYMBOL_NAME (key))); esprintf (buffer, "<%s>", SDATA (SYMBOL_NAME (key))); result = build_string (buffer); SAFE_FREE (); return result; Since KEY can be an arbitrary symbol, quite possibly its characters should be marked as 'escaped' or 'translated', which would mean adding this: put_text_property (1, 1 + SCHARS (SYMBOL_NAME (key)), Qescaped, Qt, result); before the return. Unfortunately it's not at all obvious whether this is needed unless one examines all the ways that C-h can put text into the *Help* buffer (which I haven't done). And one must do this potentially every time a string or symbol name is looked at. Plus, there are a lot of possibilities for off-by-one errors: for example, that '1 +' might easily be forgotten. Plus, even then there are opportunities for bugs: the above call to 'put_text_property' is not correct if the symbol name contains a NUL byte. Plus, there are other areas that will require this sort of complication, e.g., button labels, *Apropos* buffers. In contrast, it's much easier to look through the code for ` inside a string, and mark the exceptional characters that are intended to be quotes and that are not automatically translated already. > (we don't know all the possible sources the characters can > come from? that's not very good). No, actually, it's a good thing. It's nice that programs can put arbitrary text into *Help* buffers, and that that we don't need to worry about where the text came from: it just works. That's a simple interface, and simple interfaces are good. > By the way, when doing translation in Lisp, instead of using help-mode-finish, > we can instead examine all the functions that generate help buffers for Lisp > stuff, and translate only the docstrings, when they are being inserted. That's what the master branch is doing now, no?