Design goals

[sharkdp]

Advantages of a "pager" as a library:

• Make everything easily configurable: custom header and footer messages, keybindings
• Bidirectional communication: send events like "terminal resize" or key presses back to the application to trigger a redraw or other actions.

A few advantages if we would use a builtin pager in bat:

• Have one consistent pager experience across all operating systems. No need to call external programs that might not be available. No special handling / bug fixing for different versions of less. Consistent "quit if one screen" handling (#860, #1000, #717, #710, #681, #520, #415, #312, #271, #519, #376, #887, #943, #838, …)
• Handling of terminal resize events (#294, #322, #921, #1009)
• Open editor with a key press (#358, #464, #528, #697)
• Possibility to always draw the header at the top of the screen, even when scrolling down (#908)
• Builtin --follow support (#457, #808)
• Special handling for multiple files? (press 'n' to go to the next file)
• Error handling: we could print errors/warnings in the footer of the pager, instead of in the background (#946)
• Better 'tab' handling (#980, #894)
• Handling of ANSI hyperlinks (#961)
• Disable style components via keypress. For example: switch off the side bar with a keypress - for easy copy&paste.

[stdedos]

Links added; feel free to use my text and remove the comment

Let's use this ticket to discuss some ideas and possible upsides/downsides of writing our own custom pager library that we could use instead of calling an external $PAGER process (or, essentially, less).

A few advantages if we would use a builtin pager in bat:

• Have one consistent pager experience across all operating systems. No need to call external programs that might not be available. No special handling / bug fixing for different versions of less. Consistent "quit if one screen" handling, and much more (Default pager breaks colours in Windows Terminal #860, Garbage unicode chars on wide screen display #1000, Can't open Dockerfile or .dockerfile  #717, Bat does not work as file viewer for Midnight Commander for small files #710, pager="less -RF" breaks on macOS for single-page, but default pager breaks pgup/pgdn #681, File content not printed #520, Bat quickly exits #415, Bat with BAT_PAGER set doesn't work on small files #312, Always displays escape characters #271, Horizontal line wraps if less --status-column is used as pager #519, Width is wrong when using less as pager with -J option #376, Since recent update, short files that do not require paging are displayed and then lost #887, Bat opens a file and close it itself in a second on Windows #943, Can't view some files #838, …)
• Handling of terminal resize events. This would be my personal main motivation. (iTerm2 issue with fullscreen #294, Support terminal resize. #322, bat doesn't redraw content when size of terminal changes when using i3 #921, SIGWINCH support #1009)
• Open editor with a key press (could you add edit mode? #358, editor mode #464, v command does not work with a file as arg #528, Cannot edit standard input (Press RETURN) #697, Have the ability to open a vim session from bat (like less) #1051, Open file with v, like with less #1607)
• Possibility to always draw the header at the top of the screen, even when scrolling down (Option to add header to every page #908)
• Builtin --follow support (Add follow option #457, Pass in "Ctrl-C" to pager? #808)
• Special handling for multiple files? (press 'n' to go to the next file)
• Error handling: we could print errors/warnings in the footer of the pager, instead of in the background (Error message printed in the middle of the output for another file #946)
• Better 'tab' handling (--tabs should be 0 by default instead of 4 #980, --tabs 0 is realy 8 #894)
• Handling of ANSI hyperlinks (bat breaks hyperlinks in command output #961)
• Reload the displayed file with a keypress.
• Disable style components via keypress. For example: switch off the side bar with a keypress - for easy copy&paste.
• Properly handle search with wrapping enabled. Search is currently broken for words being wrapped (Bat search is slow and not accurate sometime #1475)

General advantages of a "pager" as a library (not just for bat):

• Make everything easily configurable: custom header and footer messages, keybindings
• Bidirectional communication: send events like "terminal resize" or key presses back to the main application to trigger a redraw or other actions.

The obvious downsides are:

• this will be a lot of work 😄
• I'm sure there will be TONS of bug reports regarding obscure terminal emulators and operating systems where things are not working as expected - which results in even more work. less comes with 36 years(!!) of experience.

One way to circumvent the second point would be to make this an opt-in feature, at least in the beginning.

I have actually started to implement a really simple cross-platform pager-as-a-library like this in a private repository. The first results look promising 😄

I'd be happy to hear about your thoughts and ideas!