Accessibility options for gptel's Transient menus

[shindere]

(Cc @thierry-martinez who helped spotting the issue, thanks!!)

When emacs is run in -nw mode, after a prompt has been typed, doing the C-u M-x gptel-send sequence accurately displays the minibuffer with all its wonderful possibilities but, as the minibuffer does not get focused, it seems impossible to interact with it. In particular, point seems to remain where it was before C-u was pressed.

I do not know whether this issue is gptel-specific or not, as my Elisp-fu is not powerful enough to investigate further.

I am visually impaired and given that emacs run with a window system does not seem accessible at all, running it in -nw mode is my only way to use it so not being able to get that to work in this context is a rather problematic issue. However, the issue could be reproduced by @thierry-martinez who is sighted and does not use assistive technology at all so I do think that there definitely is a problem that can affect other, even sighted users.

[karthink]

Sorry, I don't follow the issue. The menu that opens when you run C-u M-x gptel-send is not the minibuffer, it is a transient menu in its own buffer. "Transient menus" are provided by the "Transient" package for Emacs, which gptel uses. Visually, the cursor remains where it was, but all your keystrokes should be captured by and applied to this menu.

This is how transient menus work in Emacs, it is not unique to gptel or to emacs -nw. What happens if you press a key or keys, like -m (that's minus followed by m) to change the gptel-model, or just RET to send the query? Does it work?

If you are looking more generally for accessibility features in transient menus, I suggest asking @tarsius as he is the maintainer of Transient. He has worked on making Transient menus more accessible in the past.

[shindere]

A huge bunch of thanks to you @karthing, (1) for your very prompt response and (2) for having narrowed down the problem so well.

I think you are absolutely correct that the difficulties I am encountering are with using transient. It's a concept I did encounter several times but did not take the time to explore until now, I apologize about that.

I think there are several issues.

One is that I have no clue that a transient menu appears, but this I think is really not a real issue either because I oculd install a hook to beep,, or because I will know, just out of habbit.

The second issue has more to do with interacting with the menu, I think. First, I am unable to make its buffer currnet. I tried C-x o to change window, but that didn't work. So my point is stuck in the buffer where I did invoke the transient menu from. In addition, I understand that I should be able to interact with the menu thanks to the arrow keys but, since I can't move point to the window where the menu is displayed, I have no clue on which option has the focus now. I guess the focused option is signaled to sighted suers through a specific color but, being totally blind, this information is super hard to access for me. Not impossible, as screen readers to have ways to convey the colors of what is displayed, but using that owuld be super painful.

I saw the accessibility option you were referring to @karthink, i.e. the way to display things in only one column. I think that is very useful, even when you read the screen through speech or braille because with such ways of reading it tables are not that great either. But I fear that is not really enough to allow a visually impaired person to use transient with the same degree of comfort than a sighted user, which is a pity because the feature seems absolutely great. I also understand know why I was not able to be comfortablewith Magit either.

Finally, I feat this issue is not the rightplace to keep the discussion going but I am unsure where to move it: does transient still have its own repository andthe discussion could continue there, or, since transent has now been integrated into Emacs, should the discussion proceed on Imacs' main issue tracker?

[karthink]

I think there are several issues.

One is that I have no clue that a transient menu appears, but this I think is really not a real issue either because I could install a hook to beep,, or because I will know, just out of habit.

There is transient-setup-buffer-hook, that might work.

The second issue has more to do with interacting with the menu, I think. First, I am unable to make its buffer current. I tried C-x o to change window, but that didn't work. So my point is stuck in the buffer where I did invoke the transient menu from.

Unfortunately Transient breaks some assumptions about how keyboard interactions work in Emacs. It uses a buffer but pretends that it doesn't, and sets the current-buffer to the buffer you are working in.

In addition, I understand that I should be able to interact with the menu thanks to the arrow keys but, since I can't move point to the window where the menu is displayed, I have no clue on which option has the focus now.

One Transient affordance is that you can still Isearch the Transient buffer with C-s, if that helps.

I guess the focused option is signaled to sighted users through a specific color but, being totally blind, this information is super hard to access for me. Not impossible, as screen readers to have ways to convey the colors of what is displayed, but using that would be super painful.

There is no concept of a "focused option" in Transient. All visible commands are simultaneously active/available, and you can press any of their keys to do things. IIUC, you need some way of getting a screen-reader to announce all the available commands. Essentially it activates a keymap with visual hints in a buffer, but the focus is on the keymap, and the visual hints are a bonus.

I saw the accessibility option you were referring to @karthink, i.e. the way to display things in only one column. I think that is very useful, even when you read the screen through speech or braille because with such ways of reading it tables are not that great either. But I fear that is not really enough to allow a visually impaired person to use transient with the same degree of comfort than a sighted user, which is a pity because the feature seems absolutely great. I also understand know why I was not able to be comfortable with Magit either.

Yes. I don't have any suggestions for you here since I'm not well-versed in accessibility features in Emacs. It is an interesting problem though. If there are, say, fifteen available commands in a Transient menu, what would be the ideal way to communicate them to you?

Finally, I feat this issue is not the rightplace to keep the discussion going but I am unsure where to move it: does transient still have its own repository andthe discussion could continue there, or, since transent has now been integrated into Emacs, should the discussion proceed on Imacs' main issue tracker?

I think the best place for this discussion is at https://github.com/magit/transient/issues. Tarsius actively monitors this tracker, and might be able to help with more accessibility information.

I am also interested in making gptel more accessible. To that end, I can provide some elisp code you can use to do the things gptel's transient menu does, but as regular Emacs commands. You can bind those to keys or use them however you do the rest of Emacs. What do you need to use gptel-menu for?

[tarsius]

I have worked with blind users before to increase accessibility, and usually prioritize dealing with their issues. This week I had too many balls in the air to get to this immediately.

We can continue the discussion here to avoid losing context. And yes, Transient's Github repository is still where the action is, so in the future please open discussions there.

There is no concept of a "focused option" in Transient.

That is not correct. You can use <up> and <down> to jump between commands (buttons) in the transient buffer. M-RET> invokes the "selected" command.

I believe Emacspeak reads the command descriptions to you, as select commands using these commands. If you don't use Emacspeak, you could advise transient-forward-button and transient-backward-button to do the same.

As @karthink mentioned, you should use (setq transient-force-single-column t), because otherwise commands are navigated in a weird order.

All visible commands are simultaneously active/available, and you can press any of their keys to do things.

That is true in much the same way as pressing C-x makes all the commands in ctl-x-map active/available. The difference is that C-x just says C-x - in the echo area, to remind you that you have pressed C-x and can now press other keys, provided you remember what you are.

One big advantage Transient prefix commands have over Emacs's regular prefix commands is that you don't have to remember the keys/commands you can subsequently use.

This is useful to both sighted and blind users, but blind users will need to have those commands read to them. Obviously always and immediately reading the description of all available command is not the way to go. But having some audible reminder that informs the user that they just entered a transient menu (prefix), as suggested, sounds like a good idea.

If you remember what key you have to press next (just as you remember that to open a file you to press C-f after you have typed C-x), then you can just do that. Otherwise you can move through the menu as mentioned before (using <up> and <down>, and then pressing M-RET). Or you can use isearch (C-s) to go to the command whose description matches what you expect to be available in the current menu.

[shindere]

Hello and a bunch of thanks for the feedback!

I apologize: I am responding through email because that is the most convenient to do for me, but I do know that the rendering of such responses in GitHub's web interface is not great. I'm really sorry about that and just wanted to make clear I actually am aware of the disturbance.

Jonas Bernoulli (2025/11/08 13:08 -0800):

I have worked with blind users before to increase accessibility, and usually prioritize dealing with their issues.

That in itself si already super lovely and I want to thank you a lot for that.

This week I had too many balls in the air to get to this immediately.

No worries al all, having your ears is already wonderful.

We can continue the discussion here to avoid losing context. And yes, Transient's Github repository is still where the action is, so in the future please open discussions there.

I will certainly make sure to do that.

There is no concept of a "focused option" in Transient.

That is not correct. You can use <up> and <down> to jump between commands (buttons) in the transient buffer. M-RET> invokes the "selected" command.

Ah. I did not realize that it was M-RET rather than plain RET which has to be used. I assume this is documented but I certainly missed it. May I ask why it's Meta-RET rather than plain RET though?

The other difficulty here is that I have no clue on which option is currently selected. One thing I realize I did not make explicit is that I am not mainly using speech synthesis, I rather use a refreshable braille display. Also and even if that may be of secondary importance, because graphical terminals are not yet as accessible as Linux virtual consoles, I use Emacs in full text-mode, that is with no X or Wayland server started. The software used to render the screen in braille in such a context is BRLTTY.

All that to say that, in such a setup, the most convenient way to convey where the focus is to a blind person is to put the cursor on the focused option. This is because BRLTTY is by default configured to track the cursor, which means that, by default, the part of the computer's screen that BRLTTY will render on the braille display is the part that contains the cursor.

I believe Emacspeak reads the command descriptions to you, as select commands using these commands. If you don't use Emacspeak, you could advise transient-forward-button and transient-backward-button to do the same.

I think this does not apply so well in the context I described above but please do not hesitate to correct me if you think I am wrong here.

As @karthink mentioned, you should use (setq transient-force-single-column t), because otherwise commands are navigated in a weird order.

Yes, I too think this will be an improvement and did change this setting. Not only because of the impact it has on navigation order, but also because, given that a braille display is more efficient in horizontal rendering than in reading tables, this will make not only navigating but also reading more easy and comfortable.

All visible commands are simultaneously active/available, and you can press any of their keys to do things.

That is true in much the same way as pressing C-x makes all the commands in ctl-x-map active/available. The difference is that C-x just says C-x - in the echo area, to remind you that you have pressed C-x and can now press other keys, provided you remember what you are.

Sure, all this makes perfect sense to me.

One big advantage Transient prefix commands have over Emacs's regular prefix commands is that you don't have to remember the keys/commands you can subsequently use.

Completely understood and found that great. I also understood why I had troubles using Magit, which I never completely understood before.

This applies to both sighted and blind users. Blind users will need to have those commands read to them. Obviously always and immediately reading the description of all available command is the way to go. But having some audible reminder that informs the user that they just entered a transient menu (prefix), as suggested, sounds like a good idea.

Well I think it's gonna be very user dependent and that there already is enough flexibility to let one implement what they need.

If you remember what key you have to press next (just as you remember that to open a file you to press C-f after you have typed C-x), then you can just do that. Otherwise you can move through the menu as mentioned before (using <up> and <down>, and then pressing M-RET).

And that's I think this possibility I am missing. Well maybe not so much the possibility of moving than the possibility to have a way to know what is actually selected, because the conjunction of the two (being able to move and knowing what is focused) gives you a wonderful way of discovering the available possibilities.

Or you can use isearch (C-s) to go to the command whose description matches what you expect to be available in this menu.

I suspect that here too the point would stay were it was when the menu was invoked, meaning that a braille user would have no clue on which item has been found.

I hope I managed to clarify the issue but am happy to provide more details and context if that helps and thank you all again for your interest and patience.

[tarsius]

I haven't forgotten about this, but still have quite a todo list I want to work through by the end of the year.

I'm considering to make it possibly to temporarily switch to the menu buffer. I'll be experimenting with that, but this will take a while because I don't want to publish the first thing that works and then be stuck with it.

Please explain a bit more what your output device feels like. The extremes I can think of, are on one hand something that outputs one line/sentence and on the other something that has enough rows and columns to display a sizable portion of a butter. I imaging that with a devise of the first kind you would have to "scroll" through a buffer, to have different lines appear under your fingers; while with the second kind you would move your hands around much more, to read something at the beginning/middle/end of buffer. I'm guessing both kinds of devices exist and that they have different tradeoffs.

In any case, it would be useful if you could describe how you work with Emacs buffers using such devices. Or point me towards description written by others. Other sighted maintainers of Emacs packages are in the same position as me, and could use some documentation and experience reports.

How do you for example deal with semantically relevant colors/faces? In Transient buffers we use different faces to indicate whether a command line switch is enabled or not. If I remember correctly Emacspeak deals with this by mapping the different faces to different spoken text such as "enabled argument" and we end up with something like "enabled argument --verbose" being spoken when moving to the --verbose argument in the menu (which sighted users know is enabled because it is green, not red).

If the braille device displays just a line or two and you have to "scroll" to move around, then I guess behavior similar to that of Emacspeak would make sense. But if it is more like an Emacs buffer that can be touched, then maybe not so much.

[shindere]

Cc-ing @sthibaul here who is in Charge of maintaining accessibility in Debian, among many, many other hats.

Although he is sighted, he knows the discussed topic very well and can help fill the gap between the two worlds, so to speak. He may also be able to provide good references.

Also, before responding, let me thank you, @tartius, for the depth of your interest in the topic.

I'm considering to make it possibly to temporarily switch to the menu buffer.

That would indeed look super helpful, thanks.

I was actually surprised that C-x o to switch to another window didn't work. I think that even M-x to enter a command is disabled as long as the transient menu is displayed, I assume these possiblilites are disabled because, if kept enabled, they would break something?

I'll be experimenting with that, but this will take a while because I don't want to publish the first thing that works and then be stuck with it.

Sure. If you wanted to share code, though, I'd be super happy to test it and provide feedback.

Please explain a bit more what your output device feels like. The extremes I can think of, are on one hand something that outputs one line/sentence and on the other something that has enough rows and columns to display a sizable portion of a butter.

Although we start to see braille displays with several lines around, most of them only have one. Mine, for instance, can display 40 characters simultaneously and is one of the largest among the portable models, which are the most frequent ones. The non-portable models can display up to 80 characters simultaneously I think. The smallest ones are round one line 16, 18, 20 or 32 cells (1 cell displays one character).

I imaging that with a devise of the first kind you would have to "scroll" through a buffer, to have different lines appear under your fingers; while with the second kind you would move your hands around much more, to read something at the beginning/middle/end of buffer. I'm guessing both kinds of devices exist and that they have different tradeoffs.

I think you are correct, mostly. Basically there are two ways for us (braille users) to read screen content. First, we can move the cursor around. Given that the software that renders the screen in braille (mainly BRLTTY) by default shows in braille the part of the computer screen where the cursor is, as soon as the cursor is moved to, say, a different line, the braille display will be refreshed for this line (or portion of line) to become the one that is displayed in braille. The second thing is that what is rendered in braille is not bound to the computer's screen. So braille display usually have a few function keys that let the user explore the screen to explore different parts of it, independently of where the cursor is. For instance you can ask to see the first line of the screen, the last one (convenient if you want to see what's going on in the minibuffer). You can move up or down one line, see the next/previous part of the screen, etc. etc.

In any case, it would be useful if you could describe how you work with Emacs buffers using such devices. Or point me towards description written by others. Other sighted maintainers of Emacs packages are in the same position as me, and could use some documentation and experience reports.

At this stage I find it hard to describe how I work with Emacs buffers because, exactly as you only know how a sighted person works with an Emacs buffer (whatever that means), I myself only know how a braille user works with an Emacs buffer (here again whatever that means, because the way to use Emacs in general and buffers in particular may be as diverse for braille users than for sighted users).

How do you for example deal with semantically relevant colors/faces?

As far as I know we simply do not use them. Because we do not have (easy) access to them. Perhaps we could, as brltty has the possibility to show character attributes, but I am really not sure how many of us actually use this feature and my guess is that, for those who use it, it's mostly when nothing else is available as, to use it, you have to switch between themode where it is the characters that are displayed and a mode where it is the attributes which are displayed ((you can't see both simultaneously), which means quite a lot of tinkering.

So yes, for what I know, blind people simplay cannot use syntax highlighting and the like.

In Transient buffers we use different faces to indicate whether a command line switch is enabled or not.

So, without entering in the details of braillle, speech etc., I think this way of doing is considered not so good practice for instance in the field of web accessibility. In this area of web accessibility, it's clearly stated that no information should be conveyed only in a visual way (by color, shape etc.). In other words, on the web, if you convey something visually, then if you want to be conform to the Web Content Accessibility Guidelines, you also have to convey that information in a non-visual way.

If I remember correctly Emacspeak deals with this by mapping the different faces to different spoken text such as "enabled argument" and we end up with something like "enabled argument --verbose" being spoken when moving to the --verbose argument in the menu (which sighted users know is enabled because it is green, not red).

But what about the color-blind persons? Is there a way to change which color is associated with "enabled" and which color is associated with "disabled"? And if this setting is changed, will the screen rendering technology be aware of it, or is the green->enabled red->disabled association hard-coded in emacspeak?

If the braille device displays just a line or two and you have to "scroll" to move around, then I guess behavior similar to that of Emacspeak would make sense.

Yes and (maybe) no. Yes, in the sense that having a textual indication that the menu is enabled or disabled would be very helpful. Maybe no, in the sense that, given the low number of available cells one may want to look for a more concise represnetation of enabled/disabled. Maybe enabled could simply not be represented, so normal text, and disabled could be represented by prefixing the item with an exclamation mark, or something like that?

I'll share the link to this issue with the users on the BRLTTY mailing-list. Not all of them use Emacs (blinds are like others, they may prefer different editors), but I know there are at least a few quite involved Emacs users there who may want to participate to the current discussion.

Thanks again for your interest!

[shindere]

One more question: the discussion has become very accessibilit-focused, which in itself is never a bad thing. In the present situation, though, I wonder whether the issue actually is (only) accessibility-related, or not.

Am I correct that the problem I reported will be encountered also by a sighted user who would run Emacs with -nw or on a Linux console?

[tarsius]

Sorry for the silence. I was meaning to work on this next, ever since your last post, but people keep opening new issues, which means if I take the deep dive necessary here, then other things will pile up. This does cause me some anxiety -- I was going for TODO list zero by the end of the year, and I was going strong until about two weeks ago when stuff started raining down on me. So far I have managed to not let the list grow too much, but it certainly isn't getting smaller and I haven't checked of any of the big items.

Or in other words, this is still a priority but I also have heed the warning signs to avoid burning out, which means I am unlikely to produce anything, that you could test, before Christmas. Or -- let's be honest -- next year.

[shindere]

No worries. There is no emergency about this issue so just put it aside and let it come back when the circumstances make it possible without damaging your health.

Take care and many thanks for the heads-up!

[karthink]

No worries. There is no emergency about this issue so just put it aside and let it come back when the circumstances make it possible without damaging your health.

Indeed. Please take care of yourself, Jonas! Despite the name, I'm sure Transient will stick around while you recharge.