Re: scratch/tzz/auth-source-reveal-mode 4a7c98d 3/3: Create and document auth-source-reveal-mode

[Ted Zlatanov <tzz@lifelogs.com>]

On Wed, 24 Jun 2020 18:13:21 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

EZ> First, the branch seems to include changes that fall into two classes:
EZ> a feature that allows to hide passwords in auth-related commands, and
EZ> a "library of text prettification".  Is this correct?  If so, why are
EZ> two almost unrelated features being developed on the same branch?

(For reference, the branch is scratch/tzz/prettify-text-mode)

Hi Eli.

The two features will be separate commits so their coexistence in the
branch is just to make reviews and testing easier. But they are very
much related: the prettification functions are in prettify-text-* and
then `auth-source-reveal-mode' uses those functions.

EZ> Next, how is the "text prettification library" different from the
EZ> prettify-symbols-mode we already have, and what is the purpose of
EZ> introducing such a library?  It sounds like "text prettification"
EZ> actually is about the same job as prettify-symbols-mode, but if so,
EZ> why do we need the additional code?  Perhaps the intent is to let
EZ> other features use the same technique as prettify-symbols-mode for
EZ> purposes other than prettifying identifiers in programming-language
EZ> buffers?

Earlier in scratch/tzz/auth-source-reveal-mode I implemented
`auth-source-reveal-mode' on top of `prettify-symbols-mode' but Stefan
commented and I agreed that it would be better refactored as a library.
So as of now, the prettify-text-* functions are a way to implement text
prettifications that works like `prettify-symbols-mode' but doesn't
interfere with it.

The prettify-text-* functions also support regular expressions, unlike
`prettify-symbols-mode'. That's the major new feature because without
it, `auth-source-reveal-mode' could not work. In addition,
prettifications based on regular expressions have been requested many
times in external forums, so I think this is a valid use case beyond
`auth-source-reveal-mode'.

EZ> But then why is, for example, prettify-text-alist talking
EZ> about "identifiers"?

The identifiers in `prettify-text-alist' are symbols that identify each
entry's origin. For `auth-source-reveal-mode' the identifier is
'auth-source-reveal-regexp. That allows the prettify-text-* functions to
list and remove related prettifications instead of anonymously mashing
them together like `prettify-symbols-mode' does.

EZ> And this actually brings me to the most important point: the use of
EZ> static compositions.  That feature is semi-deprecated: its
EZ> implementation in the display engine and its Lisp APIs are not very
EZ> clean, and in particular it doesn't support bidirectional text.

Let's separate the library functions named prettify-text-* from the
underlying implementation.

1) The library functions. Currently prettify-text-* functions can add or
remove prettifications of a regexp to a single character or a
composition list. That prettification can be hidden or revealed when
point is inside or on the right edge of the prettification. (That's the
functionality of `prettify-symbols-mode' as well, except it doesn't
support regular expressions and users manipulate the alist directly.)

The major problem you raise here is the limitation to a single character
or a composition list, which in the prettify-text-* functions gets
exposed in exactly one place: the docstring of `prettify-text-alist',
which should not be directly manipulated by library users anyway.

file:lisp/progmodes/prog-mode.el::95
 In ~prettify-text-alist~:
 #+BEGIN_SRC emacs-lisp
 (defvar-local prettify-text-alist nil
  "Alist of text regexp prettifications.
Each element must look like (IDENTIFIER REGEXP CHARACTER)
...
CHARACTER can be a character, or it can be a list or vector, in
which case it will be used to compose the new symbol as per the
third argument of `compose-region'.
 #+END_SRC

So I think we can easily move away from static compositions in the
prettify-text-* library functions.

2) The underlying implementation. This is almost exactly like
`prettify-symbols-mode' in its dependence on static compositions. I
agree we should change it, the question is when (before merge or in a
followup code fix) and to what, so the behavior is preserved.

EZ> Alternatively, if the purpose is to display some text as something
EZ> else, we already have display properties and overlays that can be (and
EZ> are) used for implementing such features; why not use them instead?

I would welcome help in implementing the prettify-text-* internals
better (supporting bidirectional script and anything else you would
consider required) and asked for help with it earlier. I'll need a hand
from someone knowledgeable, or at least a pointer to code that provides
the same functionality as `prettify-symbols-mode' in a way that's
acceptable. I listed the functionality in (1) above.

Ted