[ANN] TerminalPager.jl: REPL inline help added

Package Announcements
1

TL;DR

TerminalPager.jl v0.6.5 adds an inline help viewer to the REPL, activated by hitting <alt>+<h>. Hitting <q> brings you back to the line where you were.

Credit

@Ronis_BR is the author of the TerminalPager.jl package. As we both collaborated on this new feature and we think it will be useful for many (if not most) REPL users, we agreed that I’ll write an announcement.

Motivation

While Julia’s help mode is very useful, in my opinion it has two usability problems:

  1. If you find you need help after you started typing, you need to
    1. jump back to the beginning of the line with <home>
    2. hit <?>
    3. hit <enter>
    4. get your input back with <arrow up>
    5. jump back again to the beginning of the line with <home>
    6. remove the ? with <delete>
    7. hit <end> to return to the end of the line
    8. finally continue where you left off
    9. This gets even more complicated if the function you need help with is in the middle of a complex expression.
  2. It clutters the REPL output. While sometimes it is useful to see the help output permanently while typing the current line, this is often only needed because getting help again is tedious (see above). And even then you only see the last part of the help output, although the call syntax is most often what you need when typing a new command. Quite often it is at least as useful to see the output of the previous commands without needing to scroll there.

The new inline help mode of TerminalPager.jl solves both of these issues.

Usage

Load the package with using TerminalPager (and install it if necessary). I also recommend adding it to your startup file.

The following is a quick tutorial for users which are not familiar with the workings of a pager. You do not need all this functionality to use the help mode, but it might be nice to learn some useful shortcuts. You can follow along with this example in your REPL.

  1. startswith( – which argument came first, was it the start or the whole string?
  2. <alt> + <h> – help: read the documentation
  3. <q> – quit: Back at the normal REPL containing startswith(
  4. startswith("1 haystack", – continuing the input, but can the second argument be a regular expression?
  5. <alt> + <h> – help: read the documentation
  6. /Regex – search for “Regex” and jump there
  7. <j> (repeatedly) – scroll down (and possibly up again with <k>) to look at the documentation of the correct method
  8. <q> – quit: Back at the normal REPL containing startswith("1 haystack",
  9. startswith("1 haystack", r"[0-9]") – finish command

The cursor never needed to jump between the start of the line and the end of the line. The fingers never needed to leave their regular position.

Have fun with using this functionality and retraining your muscle memory.

20 Likes
2

Nice! This is the sort of functionality I’d like to see make its way into REPL one day.

2 Likes
3

If maintainers wish to have this included into the REPL, we can work towards this goal. However, my current feeling is, at least for the moment, that this is more a package topic.

That being said, the main feature which is currently missing in Base for such a help functionality is the pager.

4

Thanks @PatrickHaecker ! The work you are doing in TerminalPager.jl is amazing!

2 Likes
5

Thanks @Ronis_BR! However, this is only possible because of your support and because I can build on your amazing work in TerminalPager.jl!

2 Likes
6

By the way, if you need the extended help (which is very useful in PrettyTables.jl), you can type <alt> + <shift> + <h>.

2 Likes
7

It looks like a neat idea.

The example above does not work on my machine. Win 11 with Julia 1.11.7.

At least the first examples in the documentation work. I can get into pager mode okay.

8

Is no pager/help opening at all although you hit <alt> + <h> and your cursor is inside a function name? Can you try <F1>?

I could imagine, that the key codes are different on the different operating systems. It works on my Linux system with Julia 1.11.7.

9

I am following the USAGE example above.

  1. startswith(
  2. <alt> + <h> or <alt> + <Shift> + <h> or F1

And nothing happens

| (the pipe symbol) gives me the pager prompt.

10

Hum, unfortunately I have no Windows machine to try debugging the problem :frowning:

If you type @help startswith, does it work?

11

@help startswith works

rand(100, 100) |> pager also works

12

Hum, so it maybe something related to key identification (alt +h or F1).

13

I also currently lack a Windows test environment where I could reproduce this. Do the regular <alt> sequences work in your setup like <alt> + <b> or <alt> + <f> to move a word forward or backward?

Could you change your terminal, i.e. use cmd, PowerShell, WSL or VS Code’s terminal?

14

Starting Julia in the CMD window or Powershell or VSCode makes no difference. I don’t have Julia loaded in WSL so did not check there.

I didn’t know about <alt> + <b> or <alt> + <f> before today but they work within Julia.

15

Thanks, this is strange.

I do not see a relevant difference.

Probably a dumb question, but could it be that Pkg hasn’t updated TerminalPager.jl to v0.6.5 or v0.6.6 due to some compatibility constraints? That would explain why the pager works, but not the inline help.

16

It was version 0.6.4. I downloaded it just before posting.
I just did an update and it is now 0.6.6.
It is working now.

1 Like
17

Great that you could solve it. Thanks for your patience.

18

I have freshly installed TerminalPager.jl v0.6.6 under Julia v1.12.0 on a M4 Mac 15.7.1 (the same however on an old macOS on Intel Mac), Julia running in Terminal, or in VSCode.

The behavior is similar to reported by Jake above: <alt> + <h> produces ª (superscript a), <alt> + <Shift> + <h> produces Ó, F1 has no visible effect. | (the pipe symbol) gives the pager prompt, @help startswith works.

19

Can you please also check whether <alt> + <b> and <alt> + <f> work for you to move a word backward and forward?

If these do not work correctly, I think you need to configure your terminal to send escape sequences instead of Unicode characters. I am not a Mac user, but this is what Claude says:

  • Terminal.app: Enable “Use Option as Meta key” in Preferences → Profiles → Keyboard
  • iTerm2: Set Left Option Key to “Esc+” in Preferences → Profiles → Keys
20

This is great! Any chance you’ll make shift+F1 work like alt+shift+h, to provide a way to access the extended help for those of us who can’t use the alt-based shortcuts for whatever reason?

1 Like