Re: Playground pager lsp(1)

Hi Alex,

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

that's fine, thank you for taking the time give me feedback.

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

If you want to take a look at it: there is a branch "next" which you
might prefer as it closer resembles my current work.  There is a new
toggle "-V" that can be used to completely turn off validation.

I tried to assemble a Makefile that might work without a configure
script and attach it to the end.  A prefix /usr is the default value, if
your system prefers /usr/local you can use `make prefix=/usr/local
install`.  I hope I prepared some reasonable Makefile...

Concerning meson.build: I decided to have a look at meson as the
autobuild tool for lsp.  I am just gathering experiences with it and if
you have meson(1) installed you could use thes steps to (un)install lsp:

$ # cd to lsp directory
$ meson setup --prefix=/usr builddir ; cd builddir
$ ninja install # or uninstall

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

This is purely based on heuristics (regex) which is one reason for
validation of the found references.

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

exit(1) gets recognized as a possible reference but validation will fail.

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

No, broken references aren't marked.  Usually those unavailable
references make sense, e.g. if a manual page references some program
that not everyone uses.

One example that I couldn't resolve so far is a reference to
getconf(1) for example in fpatchconf(3).  Up to now I was not able to
find out which package contains getconf(1)...

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

Unfortunately, info(1) also doesn't do full resizes (on my system).

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

You get a pseudo-file from where you can reach any manual page on the
system.  Originally I thought this to help novice users but since lsp is
my system's PAGER I use it more often than expected.  I'm missing the
ability to give keywords to apropos but that's just a matter of time to
get fixed.

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

Yes, that is correct.  Only level 2 (0-based) does some additional
look-ahead.

Cheers,

Dirk