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: Mon, 6 Jul 2015 15:07:34 +0300 Message-ID: <559A6F86.2080809@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> 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 1436184505 20206 80.91.229.3 (6 Jul 2015 12:08:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 6 Jul 2015 12:08:25 +0000 (UTC) To: Paul Eggert , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jul 06 14:08:19 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 1ZC5C4-0001uK-24 for ged-emacs-devel@m.gmane.org; Mon, 06 Jul 2015 14:08:16 +0200 Original-Received: from localhost ([::1]:50535 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZC5C2-0001Kd-Va for ged-emacs-devel@m.gmane.org; Mon, 06 Jul 2015 08:08:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47218) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZC5Bd-0001EB-OV for emacs-devel@gnu.org; Mon, 06 Jul 2015 08:07:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZC5BY-00072T-ON for emacs-devel@gnu.org; Mon, 06 Jul 2015 08:07:49 -0400 Original-Received: from mail-wi0-x22b.google.com ([2a00:1450:400c:c05::22b]:38633) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZC5BY-000711-Gy for emacs-devel@gnu.org; Mon, 06 Jul 2015 08:07:44 -0400 Original-Received: by wibdq8 with SMTP id dq8so151180963wib.1 for ; Mon, 06 Jul 2015 05:07:41 -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=flxTSouYsdV1tHhRafqel4nhyS0EOoOkC8WSzNGxm/I=; b=nCO7XljhQAf3MdF+1T8j9IW5RzTHznHrhgv6oQZqbxYZCxazCJnYys+LFwSSyMYW9F YxdiDZ7XLzraX5bP2OH4w3DfJ8uv/2w3RFD9/KkcvvcyMk0JDakLAKun6jY65x5z5Gwv fvqq5tQO04J8Ju7+Yr+87GQHWkZsoRMV8U6+RL1HD6Bp36sz/mI05rcDbVIoM1DmN1mG a+hEF/fdvwiDbOfX8KJe2np6v/tRwiLmteX2/wz+d8iOqcSCbFZDPJfi7yF7FxqrHHEX PEEiu5quJ6o5I9a2JE8acJXTkMVd/tlrnbaecLLqXqhdOHzTXfjER0E95VvLu+iAby6/ ZHkQ== X-Received: by 10.181.13.241 with SMTP id fb17mr93497284wid.13.1436184461734; Mon, 06 Jul 2015 05:07:41 -0700 (PDT) Original-Received: from [192.168.1.2] ([185.105.173.135]) by mx.google.com with ESMTPSA id o6sm28248918wiz.16.2015.07.06.05.07.39 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 06 Jul 2015 05:07:40 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.0 In-Reply-To: <559A1C54.5030405@cs.ucla.edu> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:400c:c05::22b 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:187739 Archived-At: On 07/06/2015 09:12 AM, Paul Eggert wrote: > I've done that, and have discovered a couple of problems. Thank you. > First, a doc string that contains \[foo] is supposed to generate a key > description for 'foo', derived by calling (key-description 'foo). But > key-description can return a string that contains quote marks, and in > general some of them should be escaped and others should not be. It's > not clear to me whether both possibilities can occur in doc strings, but > the situation is worrisome. Why not put `escaped' (or rename that `translated', maybe) on those generated regions as well? > 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. The rest of them will likely have to be handled in substitute-command-keys anyway, somehow. > In contrast, it's easy to find grave accents in doc strings, to > fix the relative few that aren't already transformed automatically, and > to not worry about user data. If we find it hard to expose this data to Lisp, it will make the output presentation less flexible, and could indicate an overall problem in our docstring generation (we don't know all the possible sources the characters can come from? that's not very 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.