From 234b4879c24b548f85a0eff05507f4130d89f0e4 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 1 Nov 2024 06:53:31 -1000 Subject: [PATCH] imp: less pager will use HLEDGER_LESS instead, if defined When using `less` as pager, if HLEDGER_LESS is defined, it will provide the options (instead of LESS + hledger's extra options). You can set your own preferred options here, or you can set it equal to LESS to use exactly those options. [#2272]-related --- hledger-lib/Hledger/Utils/IO.hs | 15 +++++++++---- hledger/hledger.m4.md | 40 +++++++++++++++++++++++---------- 2 files changed, 39 insertions(+), 16 deletions(-) diff --git a/hledger-lib/Hledger/Utils/IO.hs b/hledger-lib/Hledger/Utils/IO.hs index 65c35bf69dc..e31a2c6f8d0 100644 --- a/hledger-lib/Hledger/Utils/IO.hs +++ b/hledger-lib/Hledger/Utils/IO.hs @@ -213,6 +213,11 @@ getTerminalWidth = fmap snd <$> getTerminalHeightWidth -- --use-backslash -- --use-color -- +-- You can choose different options by setting the HLEDGER_LESS variable; +-- if set, its value will be used instead of LESS. +-- Or you can force hledger to use your exact LESS settings, +-- by setting HLEDGER_LESS equal to LESS. +-- setupPager :: IO () setupPager = do let @@ -231,11 +236,13 @@ setupPager = do ,"--use-backslash" ,"--use-color" ] - mless <- lookupEnv "LESS" + mhledgerless <- lookupEnv "HLEDGER_LESS" + mless <- lookupEnv "LESS" setEnv "LESS" $ - case mless of - Just less -> unwords [less, deflessopts] - _ -> deflessopts + case (mhledgerless, mless) of + (Just hledgerless, _) -> hledgerless + (_, Just less) -> unwords [less, deflessopts] + _ -> deflessopts -- | Display the given text on the terminal, trying to use a pager ($PAGER, less, or more) -- when appropriate, otherwise printing to standard output. Uses maybePagerFor. diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 271aeb46a02..7e8107d5dd7 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -760,22 +760,34 @@ with a `y`/`yes` or `n`/`no` value to force it on or off. #### Paging -In unix-like environments, when displaying large output in the terminal, +In unix-like environments, when displaying large output (in any output format) in the terminal, hledger tries to use a pager when appropriate. -(Actually it does this for any output format displayed in the terminal, not just text.) -You can prevent this with the `--pager=no` option, perhaps in your config file. - -It will use the pager specified by the `PAGER` environment variable, -otherwise `less` if available, otherwise `more` if available. - The pager shows one page of text at a time, and lets you scroll around to see more. -While it is active, usually `SPACE` shows the next page, `q` quits, and `?` shows more features. -(And in `less`, `G` jumps to the end, which is useful when you are viewing register output.) +While it is active, usually `SPACE` shows the next page, `h` shows help, and `q` quits. +The home/end/page up/page down/cursor keys, and mouse scrolling, may also work. +hledger will use the pager specified by the `PAGER` environment variable, otherwise `less` if available, otherwise `more` if available. The pager is expected to display hledger's ANSI colour and text styling. -hledger adds `R` to the `LESS` and `MORE` environment variables to enable this for `less` and its `more` compatibility mode. -If you use a different pager, you might need to configure it similarly, to avoid seeing junk on screen. -(Or you can disable colour, as described above.) +(If you use a pager other than `less`, you might need to configure it to handle this. +Or you could disable colour as described above.) + +If you are using the `less` pager, hledger automatically appends a number of options to +the `LESS` variable to enable ANSI colour and a number of other conveniences. +(At the time of writing: +--chop-long-lines +--hilite-unread +--ignore-case +--mouse +--no-init +--quit-at-eof +--quit-if-one-screen +--RAW-CONTROL-CHARS +--shift=8 +--squeeze-blank-lines +--use-backslash +--use-color +). +If these don't work well, you can set your preferred options in the `HLEDGER_LESS` variable, which will be used instead. ### HTML output @@ -959,6 +971,10 @@ This is normally set by your terminal; some hledger commands (`register`) will format their output to this width. If not set, they will try to use the available terminal width. +**HLEDGER_LESS** +If `less` is your [pager](#paging), this variable specifies the `less` options hledger should use. +(Otherwise, `LESS` + custom options are used.) + **LEDGER_FILE** The main journal file to use when not specified with `-f/--file`. Default: `$HOME/.hledger.journal`.