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

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

[G. Branden Robinson]

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

[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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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/

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

[Dave Kemper]

On 5/16/21, G. Branden Robinson <g.branden.robinson@gmail.com> wrote:
> At 2021-05-16T20:29:30-0500, Dave Kemper wrote:
>> 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!

Maybe less's build system has a switch to compile in a different
default?  Maybe this is a recent change?  Maybe I'm completely wrong?
I haven't looked at the source or built it myself from github; I'm
going by the behavior on my systems, behavior I've observed on other
systems, and the wording of the man page (which documents "-i" to
invoke case-mostly-insensitive searches rather than an option to
switch to case-sensitive ones).