RE: display-completion-list should not strip text properties

["Drew Adams" <drew.adams@oracle.com>]

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?