variable or function for list of known text properties?

variable or function for list of known text properties?

[Drew Adams]

Elisp manual node `Special Properties' lists text properties that "have
special built-in meanings", that is, text properties that are predefined.
Subsequent nodes `Format Properties' and `Links and Mouse-1' list a few more
such predefined text properties.

An Elisp function might want to use a list of such known text properties in
some way (e.g. as TABLE arg to `completing-read' or in a defcustom :type
expression). The list of predefined properties depends on the Emacs release
used.

Going forward, it might be useful to have a variable that holds a list of
such known text properties, or a function that would return such a list.
Then, code that makes use of this list could be release-independent
(starting with the release that provided the var or fn). This list could be
useful even if it is not exhaustive.

Better yet, how about having a macro that defines a new text property,
making it known as such - e.g. `define-text-property'? Then, the var or fn
suggested above would include newly defined properties.

FWIW, below is a list of text properties that I dug out of the Emacs Lisp
code. I don't claim it is exhaustive.

One thing that I see is that the Elisp manual documents some properties,
such as `fontified', that are used only in certain contexts (e.g. jit-lock),
but there are lots of other text properties that are used only in certain
contexts or modes and that are not documented in the manual (e.g.
`kbd-help'). What are the criteria for deciding whether a property (e.g.
`fontified' or `kbd-help') should be mentioned in the manual? I don't claim
that more properties should be documented, but I wonder how the choice is
made.

Another thing I notice is that some text properties that I suspect might
have different interpretations and uses in different libraries have the same
name - `comment', `buffer', `duplicable', `message', and `tags', for
instance. There is no problem, a priori, with the same name being reused for
something different in a different context, but there might be some risk of
interference.

Perhaps we might think about ways to deal with this potential problem (or
perhaps not, if it's not a real problem in practice) - a naming convention,
for example. And if we did have a list of known/defined text properties,
then code could check for membership before defining a new one. Of course,
even when the same property is used purposefully there is a risk of
interference (e.g. values). We might consider a defcustom-like definition
for `define-text-property' that would define not only a property name but
also its allowed values. (Of course, if we had namespaces...)

(After the release...)


----8<------------existing text properties-----------------

Text properties listed in the Elisp manual:
category face font-lock-face mouse-face fontified display
help-echo keymap local-map syntax-table read-only invisible
intangible field cursor pointer line-spacing line-height
modification-hooks insert-in-front-hooks insert-behind-hooks
point-entered point-left hard right-margin left-margin
justification follow-link

The rest of the properties listed here are not in the manual.

in directory lisp:
allout-was-hidden ansi-color buffer buffer-name column
button skip literal front-sticky rear-nonsticky composition
untranslated-utf-8 yank-handler dired-filename
read-face-name directory message debug font-lock-multiline
unknown insert-in-front-hooks kbd-help hilit-chg
ibuffer-filter-group-name ibuffer-properties ibuffer-title
ibuffer-summary ibuffer-title-header
inhibit-line-move-field-capture image-counter header-line
cvs-goal-column occur-target occur-match foreign-selection
before-string after-string ses smerge-force-highlighting
speedbar-function speedbar-token speedbar-text type
stroke-glyph data thumb-image-file original-file-name
associated-dired-buffer tags comment tumme-thumbnail
tutorial-remark vc-cvs-annotate-time end-name old-name
end-link old-link end-perm old-perm perm-changed widget-doc
secret real-field

in directory lisp/emacs-lisp:
elp-symname printed-value duplicable

in directory lisp/emulation: cursor

in directory lisp/erc:
erc-callback erc-data erc-identified erc-parsed erc-parsed
timestamp erc-prompt

in directory lisp/eshell:
comment arg-begin arg-end escaped history number test-func

in directory lisp/gnus:
earcon-data earcon-callback gnus-category gnus-part
article-type gnus-decoration dummy-invisible original-date
gnus-data gnus-callback gnus-prev gnus-next
gnus-mime-details gnus-line-format gnus-backlog
gnus-image-category gnus-image-text-deletable gnus-group
gnus-level gnus-indentation gnus-unread gnus-number articles
gnus-server gnus-named-server gnus-intangible gnus-topic
gnus-topic-level gnus-topic-unread gnus-topic-visible
gnus-active gnus-position gnus-time gnus-face
gnus-undeletable message-rank egg-end egg-lang egg-start
message-hidden message-deletable buffer from mm duplicable
script-name

in directory lisp/international:
kkc-conversion-index advice untranslated-utf-8 composition

in directory lisp/mail:
footnote-number rmail-fontified

in directory lisp/mh-e:
mh-data mh-mime-inserted mh-part mh-region mh-callback
mh-button-pressed mh-line-format mh-folder mh-children-p
mh-expanded mh-level mh-count

in directory lisp/net:
feed w3m-image nt-age nt-title nt-guid nt-desc
org-invisible nt-link nt-type nt-face

in directory lisp/progmodes:
c-type c-awk-NL-prop c-is-sws c-decl-arg-start c-decl-end
c-decl-id-start c-decl-type-start message REx-interpolated
in-pod here-doc-group syntax-type indentable REx-part2
first-format-line attrib-group cperl-postpone cpp-data
cpp-callback token ebrowse-tree ebrowse-member ebrowse-what
gdb-enabled gdb-bptno gdb-max-frames link fetch begin-glyph
begin-glyph-layout idlwave-class data source keyword find-args

in directory lisp/term: mac-ts-active-input-string

in directory lisp/textmodes:
fill-space priority test end-glyph begin-glyph org-cwidth
org-dwidth org-dwidth-n org-linked-text :org-clock-minutes
org-protected org-date-line org-today day org-agenda-type
time-of-day org-not-done-regexp prefix-length tags
org-marker org-agenda-diary-link org-hd-marker dotime
org-category undone-face done-face xr-alist table-cell
text-clones

Re: variable or function for list of known text properties?

[Richard Stallman]

    An Elisp function might want to use a list of such known text properties in
    some way (e.g. as TABLE arg to `completing-read' or in a defcustom :type
    expression). The list of predefined properties depends on the Emacs release
    used.

I do not see why this would be useful.  In any given place, each standard
property probably is or is not appropriate, so you need your own list anyway.

RE: variable or function for list of known text properties?

[Drew Adams]

>     An Elisp function might want to use a list of such known text
>     properties in some way (e.g. as TABLE arg to `completing-read'
>     or in a defcustom :type expression). The list of predefined
>     properties depends on the Emacs release used.
>
> I do not see why this would be useful.  In any given place, each standard
> property probably is or is not appropriate, so you need your own
> list anyway.

Short answer: be able to do general things with text areas that have some
text property - for example, search among and within such areas.

Longer answer:

1. If you think in terms only of the particular context where a property was
originally introduced, then you are right, at least for many properties: in
such a context, it is likely that only certain properties and certin
property values are appropriate.

Even in such a restricted context, however, it would be useful to be able
(able, not required) to declare the permitted values for a property. Hence,
the defcustom-like suggestion I made: define a property as having these
possible (i.e. known) values: x, y, z.


2. Other properties, such as `field', `face', `mouse-face',
`font-lock-face', `display', `invisible', `intangible', `category',
`keymap', and `syntax-table' are quite general - they can be used in many
different contexts.

Any program that lets users use text properties in a _general_ way could
make use of the suggested feature (list of defined properties). Consider a
command that lets a user apply any property to an area of text easily. We
already have commands (e.g. `C-u x =') that let a user check properties and
their values. And we have ways (e.g. facemenu) for users to interactively
set some properties (e.g. `face'). I can see a possible use for users to be
able to set other properties as well.


3. Here's how I currently use such a list of properties: I have a command
that lets you search a buffer (or buffers) for areas of text that have a
given property with a given value. That is, the search domain is effectively
limited to those areas. You can easily navigate among those areas, and you
can enter minibuffer text to filter the set of candidates (matching text
areas with the given property value). If you change your minibuffer text,
then the set of search areas is updated on the fly.

For example, you enter a) property `face' (using completion against the list
of properties) and then b) value `font-lock-function-name-face' (using
completion against the list of faces). The text areas that have that face
are then highlighted. You can navigate among those hits, or narrow the set
of candidate areas by typing some text - e.g. part of a function name. At
that point, the highlighted text areas are those with the given face value
that match your input (part of a function name). You navigate among the
search hits using various keys defined in the minibuffer completion maps and
`completion-list-mode-map'. One such key is `C-mouse-2' in *Completions*, to
move to that search hit.

You can do the same thing with any text property - navigate among fields,
invisible-text areas, links, whatever. Even just for debugging Emacs Lisp
that deals with text properties, this can be useful for any property and
values - it lets you "see" properties that normally have no visible effect.

I haven't yet done the same thing (search) for overlay text, but that too
would be useful.

If you want to try this, to get an idea of what is involved:
http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Search_Enhancements. The
particular search command for this is `icicle-search-text-property'. (Of
course, if you try, for instance, a font-lock face, then search candidates
will be limited to the portion of the buffer that has been fontified so
far.)


4. I'd like to perhaps do the same thing for other character properties,
besides text properties. That is, other kinds of information that you get
from `C-u C-x =' could perhaps be used in a similar way. I'm not very
familiar with that stuff, but a priori I imagine that character syntax,
charsets, and so on could be used similarly to define zones of text that you
might want to search for and search within.


5. Beyond my particular search tool, I don't have any other examples
ready-to-mind, but I'm convinced this would be useful generally. A text
property can be thought of as a particular kind of text. Whatever users do
to or with text, users might want to do to or with only text of a certain
kind (text with certain properties). There is quite a bit on the other side
of that door...

It thus would help to make properties and their permitted values (if those
are limited) "known" to Emacs, so that programs can, for example, check
"valid" properties and values before applying them. I'm not saying that it
would be _required_ to declare a new text property before it can be used,
but it would be useful to be able to see if a property has been so defined
(e.g. `text-property-p').

RE: variable or function for list of known text properties?

[Drew Adams]

Sorry for the immediate follow-up. I meant to also suggest that a
text-property search could be added to isearch or at least realized in a way
similar to isearch. You would first input the property and value, and then
isearch would be limited to the text areas that had that property and value.

IOW, there is nothing that limits this text-property search idea to the kind
of searching that Icicles provides. An isearch version would also be useful.

Re: variable or function for list of known text properties?

[Richard Stallman]

As people develop more general applications that work with text
properties, we will see what they need.  I am not convinced
that a list of standard property names _only_ is very useful.