From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-devel@gnu.org>
Cc: rms@gnu.org, "Johan \"Bockgård\"" <bojohan+news@dd.chalmers.se>
Subject: RE: display-completion-list should not strip text properties
Date: Sat, 1 Sep 2007 12:56:04 -0700 [thread overview]
Message-ID: <EIENLHALHGIMHGDOLMIMOEBNDDAA.drew.adams@oracle.com> (raw)
In-Reply-To: <E1HA2EU-0003Po-FK@fencepost.gnu.org>
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?
next prev parent reply other threads:[~2007-09-01 19:56 UTC|newest]
Thread overview: 83+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-01-22 17:23 display-completion-list should not strip text properties Drew Adams
2007-01-22 18:56 ` Stefan Monnier
2007-01-23 2:07 ` Richard Stallman
2007-01-23 5:10 ` Drew Adams
2007-01-23 21:32 ` Drew Adams
2007-01-24 8:22 ` Richard Stallman
2007-01-24 23:43 ` Johan Bockgård
2007-01-25 10:53 ` Richard Stallman
2007-01-26 13:17 ` Vinicius Jose Latorre
2007-01-27 0:46 ` Richard Stallman
2007-09-01 19:56 ` Drew Adams [this message]
2007-09-02 18:52 ` Juri Linkov
2007-09-03 18:25 ` Richard Stallman
2007-09-03 23:48 ` Juri Linkov
2007-09-04 5:59 ` David Kastrup
2007-09-04 9:52 ` Juri Linkov
2007-09-04 8:49 ` tomas
2007-09-04 9:54 ` Juri Linkov
2007-09-04 10:56 ` Johan Bockgård
2007-09-04 22:58 ` Richard Stallman
2007-09-04 16:45 ` Richard Stallman
2007-09-04 18:51 ` Drew Adams
2007-09-04 22:46 ` Davis Herring
2007-09-05 6:16 ` Richard Stallman
2007-09-05 14:21 ` Drew Adams
2007-09-06 4:59 ` Richard Stallman
2007-09-06 16:35 ` Drew Adams
2007-09-06 20:04 ` Edward O'Connor
2007-09-06 20:16 ` Drew Adams
2007-09-06 23:08 ` Robert J. Chassell
2007-09-06 23:42 ` Davis Herring
2007-09-07 12:30 ` Robert J. Chassell
2007-09-08 7:00 ` Richard Stallman
2007-09-07 19:53 ` Richard Stallman
2007-09-07 22:07 ` Drew Adams
2007-09-06 20:06 ` David Kastrup
2007-09-06 20:22 ` Drew Adams
2007-09-07 6:31 ` Richard Stallman
2007-09-05 6:16 ` Richard Stallman
2007-03-20 22:36 ` Drew Adams
2007-04-02 16:55 ` Drew Adams
2007-04-02 18:51 ` Kim F. Storm
2007-04-03 21:40 ` Richard Stallman
2007-04-03 21:53 ` Juanma Barranquero
2007-04-04 14:03 ` Richard Stallman
2007-04-03 22:03 ` Nick Roberts
2007-04-04 14:03 ` Richard Stallman
2007-04-04 14:59 ` Chong Yidong
2007-04-05 23:11 ` Richard Stallman
2007-04-05 23:20 ` Chong Yidong
2007-04-06 19:47 ` Richard Stallman
2007-04-05 23:45 ` Nick Roberts
2007-04-06 1:15 ` Glenn Morris
2007-04-06 1:59 ` Chong Yidong
2007-04-06 2:22 ` David Kastrup
2007-04-06 4:18 ` Glenn Morris
2007-04-06 8:41 ` Eli Zaretskii
2007-04-06 14:47 ` Chong Yidong
2007-04-06 16:26 ` Kim F. Storm
2007-04-06 17:34 ` Eli Zaretskii
2007-04-07 12:40 ` Richard Stallman
2007-04-06 17:06 ` Kim F. Storm
2007-04-06 19:23 ` Kevin Rodgers changes Chong Yidong
2007-04-07 7:32 ` martin rudalics
2007-04-07 12:40 ` Richard Stallman
2007-04-07 16:57 ` Chong Yidong
2007-04-07 17:34 ` Eli Zaretskii
2007-04-08 12:28 ` Richard Stallman
2007-04-08 21:07 ` Eli Zaretskii
2007-04-09 14:33 ` Daniel Brockman
2007-04-09 15:42 ` Richard Stallman
2007-04-08 21:30 ` Chong Yidong
2007-04-09 15:42 ` Richard Stallman
2007-04-11 16:38 ` display-completion-list should not strip text properties Markus Triska
2007-04-11 17:13 ` Chong Yidong
2007-04-06 19:47 ` Richard Stallman
2007-04-06 8:42 ` Eli Zaretskii
2007-04-06 19:47 ` Richard Stallman
2007-04-04 17:45 ` Edward O'Connor
2007-04-05 14:36 ` Chong Yidong
2007-04-05 15:02 ` Juanma Barranquero
2007-04-05 23:11 ` Richard Stallman
2007-01-24 7:07 ` Kevin Rodgers
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=EIENLHALHGIMHGDOLMIMOEBNDDAA.drew.adams@oracle.com \
--to=drew.adams@oracle.com \
--cc=bojohan+news@dd.chalmers.se \
--cc=emacs-devel@gnu.org \
--cc=rms@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.