Re: Playground pager lsp(1)

Alejandro Colomar
2023-04-04T23:46:00Z

[-- Attachment #1.1: Type: text/plain, Size: 9290 bytes --]

Hi Dirk.

On 3/25/23 21:47, Dirk Gouders wrote:
> 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.

No, I don't.

> 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.

If you had a Debian package, I might try it :)

Or maybe a Makefile to build from source... What is this meson.build?

>
> 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).

I'd say it does quite a lot more than paging... We could say this is some
info(1) equivalent for manual pages.

With the benefit that you don't need to implement such a system from scratch,
but just reusing the existing tools (apropos, man, whatis, ...). It seems
something like what I would have written if I had to implement info(1) from
scratch. I wish GNU guys had thought of this instead of developing their
own incompatible system.

>
> 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.

Out of curiosity, is this implemented with heuristics? Or do you rely on
semantic mdoc(7) macros?

If it's the first, how do you handle exit(1)? Is it a reference, or is it
just code (with the meaning exit(EXIT_FAILURE))?

If it's the second, I guess it doesn't support that in man(7), right? At
least until MR is released.

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

Do you mark these as broken references? It is interesting to know that
there's a reference which you don't have installed. It may prompt you to
install it and read it. When I see a broken reference, I usually find it
with `apt-file find man3/page.3`, and then install the relevant package.

>
> • 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.

Good. This I miss it in less(1) often. Not sure if they had any strong
reason to not support that.

>
> • 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.

What does it bring that `apropos * | less` can't do? If you're going the
of info(1) with full-blown system, it seems reasonable, but I never really
liked all that if it's just a new terminal and a command away from me.

>
> • 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.

Nice, and this an important feature missing feature in info(1), as I
reported recently. :) Maybe they are interested in something similar.

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

I guess the heuristics are just `^[^ ]` for SH and `^ [^ ]` for SS, right?
I tipically use something similar for searching for command flags, and as
you say, these just work.

Cheers,
Alex

>
> 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)

--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]