getting more out of man pages with less(1) (was: [bug #59962] soelim(1) man page uses pic diagram--should it?)

[G. Branden Robinson]

[looping in linux-man@ because issues of user education and topics that
fall between project/man page stools come up below]

At 2021-05-16T20:29:30-0500, Dave Kemper wrote:
> This stuff about less(1) is only tangential to groff, but it did come
> up in the context of viewing man pages, so I'm keeping the groff list
> in the cc.

Good idea.  I've further changed the Subject: to reflect the flow of the
discussion.

> On 5/12/21, G. Branden Robinson <g.branden.robinson@gmail.com> wrote:
> > One thing I would mention is that less(1) supports regex searches
> > within its buffer.  On my system, the searches are even
> > case-insensitive by default if the search pattern is all lowercase,
> > and not otherwise.
> 
> less's default is for searches to be case-sensitive.  Its -i option
> (which can be given on the command line or while less is running) is
> what activates the behavior described above.  A user or a distro might
> make -i the default in their environment (I do) through the $LESS
> environment variable or an alias, but that isn't less's out-of-the-box
> behavior.

On my Debian buster-based system, less(1) behaves that way, but $LESS is
not defined in my environment and I don't have a shell alias or function
set up.  Checking the source package, I don't see patches to turn -i on
by default.  Baffling!

> > In fact, to leap among sections you can do
> >
> > /^[a-z]
> >
> > regardless of the lettercase convention, and after doing the above
> > once you can type simply
> >
> > /
> >
> > to repeat the search or
> >
> > ?
> >
> > to repeat it in the backwards direction.
> 
> Or to save yourself a keypress (since those methods require a "Return"
> after the "/" or "?") you can use "n" and "N" respectively.  Longtime
> vi users will do this without even thinking about it.

Yup, you caught me.  :D

I don't think it's ever too soon to teach a user who has seen man pages
how to get more out of them, and that includes the pager interface.
It's frustrating because man(1), less(1), and man(7), formally
considered, can all disclaim responsibility for communicating this
knowledge.  less(1) can page all sorts of text files, not just man
pages, and its own man page is huge and talks about all kinds of stuff.
man(1) is also big, and that program definitely is not the pager.
man(7) documents the macro package[1], which is a man page _writer's_
interface, not primarily one for the reader.

I find myself wishing that intro(1) from the Linux man-pages project
said more about this, either directly in that page or maybe in the
man(7) they provide, with a conspicuous pointer there from the former.

Maybe Michael or Alejandro can advise regarding where they think a good
place for a man page utilization tutorial would be.

I also wonder if the pager wars are basically over and less(1) won them.
I haven't heard anyone mention most(1) in a long time[2], and the, uh,
simple elegance of more(1)'s inability to seek its stream (meaning: no
backwards searching) seems to have driven many people to less(1) even if
they have reservations about the length of its feature list.

Regards,
Branden

[1] Michael Kerrisk can correct me, I hope, but as far as I know the
    Linux man-pages man(7) page arose because, back in the '90s, the GNU
    roff project refused to supply one, in keeping with the GNU "no
    documentation at all if not Texinfo" philosophy--Susan G.  Kleinmann
    of Debian had to write one, which I guess escaped the notice of the
    (Red Hat-using?) man-pages maintainer(s) of the time.  By 1999, the
    rigor of groff's fealty to that principle had slackened, and,
    judging by groff's CVS-to-Git history, it looks like I can credit
    Werner Lemberg with adopting and revising her work as groff_man(7).

[2] a fate that seems to have inexorably claimed any project that
    hitched its horses to S-Lang's wagon

signature.asc
Description: PGP signature