Re: Accessibility of man pages (was: Playground pager lsp(1))

[Alejandro Colomar]

Hi Eli,

On 4/8/23 15:42, Eli Zaretskii wrote:
>> Date: Sat, 8 Apr 2023 15:02:59 +0200
>> Cc: dirk@gouders.net, linux-man@vger.kernel.org, help-texinfo@gnu.org,
>>  nabijaczleweli@nabijaczleweli.xyz, g.branden.robinson@gmail.com,
>>  groff@gnu.org
>> From: Alejandro Colomar <alx.manpages@gmail.com>
>>
>> If you want how symlinks are dereferenced by find(1):
>>
>> $ man find | grep sym.*link | head -n1
>>        The  -H,  -L  and  -P  options control the treatment of symbolic 
>> links.
> 
> That's because the text appears verbatim in the man page.  Suppose the
> person in question doesn't think about "symbolic links", but has
> something else in mind, for example, "dereference".  (Why? because
> he/she just happened to see that term in some article, and wanted to
> know what does Find do with that.  Or for some other reason.)  Then
> they will not find the description of symlink behavior of Find by
> searching for "dereference".

That's why using consistent language is important.  Searching just for
"dereference" will of course have slightly less quality, but that
should be expected.  Once you have a slightly related match, you can
find terms that will help refine your search.

$ man find | grep dereference -C1
       When  the  -H  or  -L options are in effect, any symbolic links
       listed as the argument of -newer will be dereferenced, and  the
       timestamp  will  be  taken  from the file to which the symbolic
--
       used but -follow is, any symbolic links appearing after -follow
       on  the  command line will be dereferenced, and those before it
       will not).
--
              haviour of the -newer predicate; any files listed as the
              argument of -newer will be dereferenced if they are sym‐
              bolic  links.   The  same consideration applies to -new‐
--
       -newer Supported.  If the file specified is a symbolic link, it
              is always dereferenced.  This is a change from  previous
              behaviour, which used to take the relevant time from the


This already shows "symbolic link" several times, so you probably want
to search for that.

If you want something that processes natural language, you can always
ask some AI engine to process man pages for you ;).

> 
> Do you see the crucial issue here?  Indexing can tag some text with
> topics which do not appear verbatim in the text, but instead
> anticipate what people could have in mind when they are searching for
> that text without knowing what it says, exactly.

I don't remember myself having had such issues so far.  I'd like to
see real reports of readers that struggle to find a certain search
term in a certain page.  There are, but few (the only one I remember
is this one we had recently about proc(5)).  If you ever have such a
real case with man pages, please report it, and I will try to make it
more accessible.  The intention is that a combination of man(1),
apropos(1), whatis(1), and then some grep(1) and sed(1) should be
enough 99% of the time, and we should fix the outliers.

> 
>>>> After this patch, if you apropos "system" or "sysctl", you'll see
>>>> proc(5) pop up in your list.
>>>
>>> This literally adds the text to what the reader will see.  It makes
>>> the text longer and thus more difficult to read and parse, and there's
>>> a limit to how many key phrases you can add like this.
>>
>> If a page has too many topics, consider splitting the page (I agree
>> that proc(5) is asking for that job).
> 
> Indexing can tag any paragraph of text, not just the entire page.  A
> page cannot usefully have too many keywords in its title, but it _can_
> benefit from different keywords for different paragraphs.

We can add source code comments, which would appear in `man -K`
searches, but so far I haven't seen the need in any specific page.


[...]

> 
>>>  So when you see them in
>>> TOC or any similar navigation aid, you _know_, at least approximately,
>>> what each section is about.
>>
>> I know a priori that if I'm reading sscanf(3)'s SYNOPSIS, I'll find
>> the function prototype for it.  Or if I read printf(3)'s ATTRIBUTES
>> I'll find the thread-safety of the function.
> 
> SYNOPSIS is at least approximately self-describing (although some
> non-native English speakers might stumble on it).  But how would a
> random reader know that ATTRIBUTES will describe thread-safety, for
> example?  I wouldn't.  Isn't it better to have a section named "Thread
> Safety" instead?

I don't know the origin of the name of ATTRIBUTES.  There's
attributes(7), which documents what you can find there.

> 
>> text search has false positives, like anything else.  But having good
>> tools for handling text is the key to solving the problem.  grep(1)
>> and sed(1) are your friends when reading man pages.
> 
> Modern documentation is not plain text (even if we ignore
> compression), so tools which just search the text have limitations,
> sometimes serious ones.

In some cases you need to search the man(7) source code to get
extra information that is difficult to search in formatted text,
but that's for rare cases.  So far, I find mostly everything I
need just with text tools.

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

OpenPGP_signature
Description: OpenPGP digital signature