Re: [ELPA] New package: transient

[Kévin Le Gouguec]

Richard Stallman <address@hidden> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Starting from minute 3:00 you will regularly see Transient buffers in
>   > use, popping up at the bottom of the frame, showing menus of commands
>   > and the key sequences which invoke them.
>
> Thanks, but I can't follow that.  Things flash on the screen, showing
> lots of text I can hardly see (it is small print), and I have no idea
> what it is doing or why.
>
> I can't learn the details of using a package that way.
>
> Anyway, the details are not what I need to learn.
> What I want to understand is the basic purpose and use of Transient.
>
> Would someone like to tell me in 10 lines
> whet job Transient does, and why it is useful?

In addition to Phil's summary, and tying in with the other thread on the
discoverability of outline-mode's bindings, here is a hastily made-up
hypothetical transient command for outline-mode:

(define-transient-command outline-menu ()
  "Show menu for selective display."
  [["Show"
    ("a" "all" outline-show-all)
    ("e" "entry" outline-show-entry)
    ("i" "children" outline-show-children)
    ("k" "branches" outline-show-branches)
    ("s" "subtree" outline-show-subtree)]
   ["Hide"
    ("c" "entry" outline-hide-entry)
    ("d" "subtree" outline-hide-subtree)
    ("l" "leaves" outline-hide-leaves)
    ("o" "other" outline-hide-other)
    ("q" "sublevels" outline-hide-sublevels)
    ("t" "body" outline-hide-body)]])

After evaluating this form, if I then visit e.g. NEWS and 

(local-set-key (kbd "C-c @") 'outline-menu)

Then "C-c @" spawns a menu at the bottom of the frame:

transient-ouline-example.png
Description: PNG image

>From there, I can run the command I am interested in with a single
keystroke, and the transient menu disappears.  Overall it's pretty
unobtrusive[1], so once the command makes it to muscle memory it's
virtually indistinguishable from just running "C-c @ <key>" without
pause.

This is a pretty trivial example; see Phil's answer for more interesting
features (e.g. providing arguments to commands).


[1] Unlike say C-h b or C-h m, which 1. takes a whole window, 2. I have
    to scroll through if the key I'm interested in isn't featured in
    what's initially displayed, 3. I must quit manually.