Playground pager lsp(1)

[Dirk Gouders <dirk@gouders.net>]

Hi Alejandro,

first of all, chances are that you consider this post as spam, because
this list is about linux manual pages and not pagers.  In that case
please accept my apologies and ignore this post.

My reasoning was that readers here have some interest in manual pages
and therefore probably also in pagers that claim to "understand" manual
pages.  My hope is that even if you consider this post inappropriate you
will perhaps suggest some more appropriate place for such discussion.

Not long ago, I noticed a discussion [1] about what pagers can and
cannot do.  That was interesting to me, because I am currently playing
with a pager that claims to have a focus on manual pages.

I will try to not waste your time and attach the manual page and a link
to a short (3:50) demo video.  To me it is absolutely OK should you just
ignore this spam post, but perhaps you find lsp(1) interesting enough
for further discussion.

Best regards,

Dirk

[1] https://www.spinics.net/lists/linux-man/index.html#24494
[2] https://youtu.be/syGT4POgTAw

LSP(1)                           User commands                          LSP(1)

NAME
       lsp - list pages (or least significant pager)

SYNOPSIS
       lsp [options] [file_name]...

       lsp -h

       lsp -v

DESCRIPTION
       lsp is a terminal pager that assists in paging through data, usually
       text — no more(1), no less(1).

       The given files are opened if file names are given as options.
       Otherwise lsp assumes input from stdin and tries to read from there.

       In addition to it’s ability to aid in paging through text files lsp has
       limited knowledge about manual pages and offers some help in viewing
       them:

       •   Manual pages usually refer to other manual pages and lsp allows to
           navigate those references and to visit them as new files with the
           ability to also navigate through all opened manual pages or other
           files.

           Here, lsp tries to minimize frustration caused by unavailable
           references and verifies their existance before offering them as
           references that can be visited.

       •   In windowing environments lsp does complete resizes when windows
           get resized. This means it also reloads the manual page to fit the
           new window size.

       •   Search for manual pages using apropos(1); in the current most basic
           form it lists all known manual pages ready for text search and
           visiting referenced manual pages.

       •   lsp has an experimental TOC mode.

           This is a three-level folding mode trying to list only section and
           sub-section names for quick navigation in manual pages.

           The TOC is created using naive heuristics which works well to some
           extend, but it might be incomplete. Users should keep that in mind.

OPTIONS
       All options can be given on the command line or via the environment
       variable LSP_OPTIONS. The short version of toggles can also be used as
       commands, e.g. you can input -i while paging through a file to toggle
       case sensitivity for searches.

       -a, --load-apropos
           Create an apropos pseudo-file.

       -c, --chop-lines
           Toggle chopping of lines that do not fit the current screen width.

       -h, --help
           Output help and exit.

       -i, --no-case
           Toggle case sensitivity in searches.

       -I, --man-case
           Turn on case sensitivity for names of manual pages.

           This is used for example to verify references to other manual
           pages.

       -l, --log-file
           Specify a path to where write debugging output.

       -n, --line-numbers
           Toggle visible line numbers.

       -s, --search-string
           Specify an initial search string.

       -v, --version
           Output version information of lsp and exit.

       --no-color
           Disable colored output.

       --reload-command
           Specify command to load manual pages. Default is man.

       --verify-command
           Specify command to verify the existance of references. Default is
           man -w.

       --verify-with-apropos
           Use the entries of the apropos pseudo-file for validation of
           references.

COMMANDS
       Pg-Down / Pg-Up
           Forward/backward one page, respectively.

       Key-Down / Key-Up / Mouse-Wheel down/up
           Forward/backward one line, respectively.

       CTRL-l
           In search mode: bring current match to top of the page.

       ESC
           Turn off current highlighting of matches.

       TAB / S-TAB
           Navigate to next/previous reference respectively.

       ENTER

           •   If previous command was TAB or S-TAB:

               Open reference at point, i.e. call `man <reference>'.

           •   In TOC-mode:

               Go to currently selected position in file.

       /
           Start a forward search for regular expression.

       ?
           Start a backward search for regular expression.

       B
           Change buffer; choose from list.

       a
           Create a pseudo-file with the output of `apropos .'.

           That pseudo-file contains short descriptions for all manual pages
           known to the system; those manual pages can also be opened with TAB
           / S-TAB and ENTER commands.

       b
           Backward one page

       c
           Close file currently paged.

           Exits lsp if it was the only/last file being paged.

       f
           Forward one page

       h
           Show online help with command summary.

       m
           Open another manual page.

       n
           Find next match in search.

       p
           Find previous match in search.

       q

           •   Exit lsp.

           •   In TOC-mode: switch back to normal view.

           •   In help-mode: close help file.

ENVIRONMENT
       LSP_OPTIONS
           All command line options can also be specified using this variable.

       LSP_OPEN / LESSOPEN
           Analogical to less(1), lsp supports an input preprocessor but
           currently just the two basic forms:

           One that provides the path to a replacement file and the one that
           writes the content to be paged to a pipe.

SEE ALSO
       apropos(1), less(1), man(1), more(1), pg(1)

BUGS
       Report bugs at https://github.com/dgouders/lsp

alpha-1.0e-42                     03/25/2023                            LSP(1)