Re: Playground pager lsp(1)

Dirk Gouders
2023-04-05T10:02:40Z

[-- Attachment #1: Type: text/plain, Size: 5054 bytes --]

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

[-- Attachment #2: Makefile --]
[-- Type: application/octet-stream, Size: 576 bytes --]

version=\"$(shell cat .version)\"
CFLAGS := $(shell pkg-config --cflags ncursesw)
CFLAGS += -DLSP_VERSION=$(version)
LDFLAGS := $(shell pkg-config --libs ncursesw)

ifeq ($(prefix),)
prefix := /usr
endif

lsp: lsp.c
gcc $(CFLAGS) $(LDFLAGS) -o $@ $<

doc/lsp.1: doc/lsp.adoc
a2x --doctype manpage --format manpage -a lsp-version=$(version) $<

.PHONY: uninstall install

install: lsp doc/lsp.1 doc/lsp-help.1
install lsp $(prefix)/bin
install doc/lsp.1 doc/lsp-help.1 $(prefix)/share/man/man1/

uninstall:
rm $(prefix)/bin/lsp
rm $(prefix)/share/man/man1/lsp{,-help}.1