From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: Escaping quotes in docstrings, Was: A simple solution to "Upcoming loss of usability ..." Date: Tue, 7 Jul 2015 01:10:11 +0300 Message-ID: <559AFCC3.3070409@yandex.ru> 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> <559AAD27.3000403@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 1436220647 31333 80.91.229.3 (6 Jul 2015 22:10:47 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 6 Jul 2015 22:10:47 +0000 (UTC) To: Paul Eggert , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jul 07 00:10:47 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 1ZCEb8-0003oY-Sq for ged-emacs-devel@m.gmane.org; Tue, 07 Jul 2015 00:10:47 +0200 Original-Received: from localhost ([::1]:53088 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZCEb7-0007qo-F5 for ged-emacs-devel@m.gmane.org; Mon, 06 Jul 2015 18:10:45 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36722) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZCEaj-0007qM-Mc for emacs-devel@gnu.org; Mon, 06 Jul 2015 18:10:22 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZCEae-0001dv-Hm for emacs-devel@gnu.org; Mon, 06 Jul 2015 18:10:21 -0400 Original-Received: from mail-wg0-x230.google.com ([2a00:1450:400c:c00::230]:36715) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZCEae-0001de-78 for emacs-devel@gnu.org; Mon, 06 Jul 2015 18:10:16 -0400 Original-Received: by wguu7 with SMTP id u7so152268858wgu.3 for ; Mon, 06 Jul 2015 15:10:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-type:content-transfer-encoding; bh=W37YEdB+qz8bnJx+Jh/2SkrZ/acQRRJxkmUy56ombRo=; b=RdRWgY+dTNWR6Nt8kGgDTkgyNcD8Cm9QqSrLIwF5+JUo90EFN/gkemr5sj8Nu1YlAq gH3E5qoq5Vo163EUc7ViBwK1SGsrMbWd9m583P+SVOtEJMApyuqb+DI/1IzXfatWxC6N DWEw+uuOawriUJGE06aNwidBMQgNSgY5NYo1L6h82iaichO77goI4VK0Ta+M8RjbgLNF vhvtTaT3hOKgCiTjr0fcDhpLMzbFOd0QjWjNjxPb4TD22cD2Wb2O3Xil4ZoSHgeFp9/9 a2BZcUmgzbCEyO1SD8dsbha0lHFDcVYMqxMEUkwDUxNLvaMMv+mvn+XWtwnwVTEs6kaT vFyA== X-Received: by 10.194.187.170 with SMTP id ft10mr2020889wjc.26.1436220615673; Mon, 06 Jul 2015 15:10:15 -0700 (PDT) Original-Received: from [192.168.1.2] ([185.105.175.24]) by mx.google.com with ESMTPSA id ho10sm30221445wjb.39.2015.07.06.15.10.13 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 06 Jul 2015 15:10:13 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.0 In-Reply-To: <559AAD27.3000403@cs.ucla.edu> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:400c:c00::230 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:187751 Archived-At: On 07/06/2015 07:30 PM, Paul Eggert wrote: > 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. I meant complications related to `substitute-command-keys'. That function should know exactly where to put them, because it expands \\[command] and similar syntax. But if you were looking for consumers of `key-description' in help-fns.el, these are concentrated in `help-fns--key-bindings'. And it's only used in one place: `describe-function-1'. Putting `help-value' on it is trivial. > For example, one place > might be the following code in keymap.c's single_key_description function: That doesn't sound right to me. `key-description' should continue returning a plain string. > Since KEY can be an arbitrary symbol, quite possibly its characters > should be marked as 'escaped' or 'translated', which would mean adding > this: I never was proposing a "dirty" string tagging throughout all functions that deal with them. Only in functions that output to Help buffers (and know about it), that deal with `' markup. > 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. I'm afraid I don't understand you here. > Plus, > there are a lot of possibilities for off-by-one errors: for example, > that '1 +' might easily be forgotten. That's one of the reasons to implement as little as possible in C. > 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. Apropos buffers - maybe. But since when do button labels have quotes in them? > 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. Sorry, I don't understand this either. Mark? Automatically translated? >> (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. Well, it's one way of looking at it. >> 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? That would be closer, but the current master implements more in C, which means fewer people who can change or maintain the code. And it complicates the API of a low-level function (substitute-command-keys), in a way that seems incompatible with radically changing the output later.