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

[Mike]

On 17 May 12:50, G. Branden Robinson wrote:
> [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!

man(1) from the man-db package execs less(1) (or other configured pager)
with the LESS environment variable populated with "-ix8RmPm%s$PM%s$".

The %s escapes are replaced by the prompt string.

See include/manconfig.h:

#define LESS_OPTS   "-ix8RmPm%s$PM%s$"

Any existing $LESS is appended to this string prior to exec, allowing
these options to be overridden.

This is on debian buster.

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