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

[Michael Kerrisk (man-pages)]

Hi Branden,

On 5/17/21 2:50 PM, 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!
> 
>>> 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.

If any place, I think intro(1) would be most appropriate, or,
failing that, an initial sentence that points the reader at another
page (that could be added in man-pages). My guiding principle would
be that the guidance given should be simple (introductory and not
comprehensive), finishing with pointers to man(1) and/or less(1)
for further details.

The current intro(1) is an odd page though. Andries Brouwer made
some steps to turning into a general "intro to Linux" page, but that
was, to my mind, always going to be an impossibly huge scope. I'm
not a huge fan of what is there.

> I also wonder if the pager wars are basically over and less(1) won them.

That's certainly what I thought...

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

I actually saw someone use more(1) the other day. I was surprised!
(Okay, that person had been around UNIX for a _long_ time...)

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

man(7) predates my involvement in the project. It written by the first
maintainer, Rik Faith, and was part of the very first man-pages
release, back in 1993! I do not know the rationale for its creation.

Cheers,

Michael

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


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/