From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: display-completion-list should not strip text properties Date: Sat, 1 Sep 2007 12:56:04 -0700 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="ISO-8859-15" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1188676596 27216 80.91.229.12 (1 Sep 2007 19:56:36 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 1 Sep 2007 19:56:36 +0000 (UTC) Cc: rms@gnu.org, =?ISO-8859-15?Q?Johan_=22Bockg=E5rd=22?= To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Sep 01 21:56:35 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1IRZ57-00034o-Dq for ged-emacs-devel@m.gmane.org; Sat, 01 Sep 2007 21:56:33 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IRZ56-000218-7x for ged-emacs-devel@m.gmane.org; Sat, 01 Sep 2007 15:56:32 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1IRZ51-00020F-Fz for emacs-devel@gnu.org; Sat, 01 Sep 2007 15:56:27 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1IRZ4z-0001yM-7V for emacs-devel@gnu.org; Sat, 01 Sep 2007 15:56:26 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IRZ4z-0001yJ-4d for emacs-devel@gnu.org; Sat, 01 Sep 2007 15:56:25 -0400 Original-Received: from agminet01.oracle.com ([141.146.126.228]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1IRZ4u-00013I-Js; Sat, 01 Sep 2007 15:56:20 -0400 Original-Received: from agmgw2.us.oracle.com (agmgw2.us.oracle.com [152.68.180.213]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id l81JuIgW002309; Sat, 1 Sep 2007 14:56:18 -0500 Original-Received: from acsmt350.oracle.com (acsmt350.oracle.com [141.146.40.150]) by agmgw2.us.oracle.com (Switch-3.2.0/Switch-3.2.0) with ESMTP id l81IbSbl022780; Sat, 1 Sep 2007 13:56:17 -0600 Original-Received: from dhcp-amer-whq-csvpn-gw3-141-144-80-148.vpn.oracle.com by acsmt350.oracle.com with ESMTP id 3176684461188676566; Sat, 01 Sep 2007 12:56:06 -0700 X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3138 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-Detected-Kernel: Linux 2.4-2.6 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:77554 Archived-At: This is from 2007-01-24: Johan>By putting text properties on doc strings you can insert > images and other fancy stuff in the *Help* buffer. This > change makes describe-variable preserve text properties > (describe-function already does so): > RMS> There is no clean and easy way to put text properties on a doc > string, so I think this is not very useful in the present > context. > If someone comes up with a clean way to do that, this would be > a useful part of the combination. We could think then about > installing it. I think this is a good idea. Can we make some progress on it? It seems that `defvar' and `defcustom' already let you pass a sexp to be evaled for the doc string, so you can already do things like this: (defvar foo 25 (propertize (make-string 5 ?P) 'face 'highlight)) With Johan's proposed fix to `describe-variable', this shows up fine in *Help* for `C-h v foo'. We should in any case implement his (one-line) enhancement - no reason not to, IMO. defun does not let you do something similar, however, presumably because it can't tell that the sexp is supposed to be a doc string instead of the first part of the body's implicit `progn' (with a missing doc string). This is perhaps part of what Richard had in mind when he wrote that there is no clean and easy way to put text properties on a doc string - in particular, defun doesn't facilitate doing so. Perhaps we could allow literal doc strings to contain special syntax that means "replace this sexp by its (string) value". This would be akin to \\[], \\<>, and \\{} for key bindings. Maybe use \\(...)? Then, you could write, for example: (defun foo () "mumble \\((propertize "toto" 'face 'highlight)) titi" whatever) As propertizing with a face would be a common use of \\(...), a convenience function `with-face' might be defined to abbreviate (propertize ... 'face ...). Then, you could write just: (defun foo () "mumble \\((with-face 'highlight "toto")) titi" whatever) As Johan mentioned, text properties could be used to insert images and do other things for *Help*, besides just adding faces. If it were thought that particular properties such as `face' would be used very often, then we might define syntax to abbreviate them. We might, for example, use \\#...# for \\(with-face...), with the convention that the face here would always be passed as a symbol that immediately follows \\#. You could then write, for instance: (defun foo () "mumble \\#highlight toto# titi" whatever) This syntax is not too inconvenient, and it doesn't interfere too much with source-code readability, IMO. Something similar might be done for image insertion using the `display' property. Such syntax might also prove useful in other contexts, besides doc strings - `substitute-command-keys', for instance. However, `substitute-command-keys' does not currently allow text properties, apparently. If `substitute-command-keys' didn't have this limitation, and if it had a shorter name (e.g. alias `doc'), then you could use it with these syntax enhancements as a shortcut for `format' or `concat' applications, in many cases. For example, instead of (concat "mumble " (propertize "toto" 'face 'highlight) "titi"), you could write (doc "mumble \\#highlight toto# titi"). In sum, I think we can find ways to make it convenient to add text properties to doc strings, and I think that could improve *Help* in some cases. In particular, it would be useful to have abbreviated syntax for inserting images and attaching faces to parts of doc strings. Anyway, I just wanted to open discussion on this - other ideas and implementations might be better. WDOT? Can we define a convenient way to let you use text properties in doc strings? Is it useful to do so?