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

[Alejandro Colomar]

Hi Eli, Colin,

On 4/8/23 09:05, Eli Zaretskii wrote:
>> Date: Sat, 8 Apr 2023 00:01:08 +0200
>> Cc: dirk@gouders.net, linux-man@vger.kernel.org, help-texinfo@gnu.org,
>>  наб <nabijaczleweli@nabijaczleweli.xyz>,
>>  "G. Branden Robinson" <g.branden.robinson@gmail.com>, groff <groff@gnu.org>,
>>  Colin Watson <cjwatson@debian.org>
>> From: Alejandro Colomar <alx.manpages@gmail.com>
>>
>>> How do you find the description of, say, "dereference symbolic link"
>>> (to take just a random example from the Emacs manual) when the actual
>>> text of the manual include neither this string nor matches for any
>>> related regular expressions, like "dereference.*link"?
>>
>> $ apropos link | grep sym | head -n5
>> readlink (2)         - read value of a symbolic link
>> readlinkat (2)       - read value of a symbolic link
>> sln (8)              - create symbolic links
>> symlink (2)          - make a new name for a file
>> symlink (7)          - symbolic link handling
>>
>> I bet you're looking for readlink(2) and symlink(7), aren't you?
> 
> I said "in the Emacs manual",

I wanted to show the man-pages equivalent.  Of course I know nothing
about the Emacs manual :)

> and I said "when the actual text of the
> manual doesn't include the phrase you are looking for".  So your
> example is not really up to its job: it uses text that is not the
> Emacs manual, and it finds only hits that literally appear in the
> title text of the man pages.

I thought you wanted to know about how dereferencing symlinks works
in general.

>  For example, the above doesn't find the
> man page of Find,

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.

$ man find | sed -n '/^       -L/,/^$/p;' | sed '/^$/,$d'
       -L     Follow symbolic links.  When find examines or prints information
              about  files, the information used shall be taken from the prop‐
              erties of the file to which the link points, not from  the  link
              itself (unless it is a broken symbolic link or find is unable to
              examine  the file to which the link points).  Use of this option
              implies -noleaf.  If you later use the -P option,  -noleaf  will
              still  be  in  effect.   If -L is in effect and find discovers a
              symbolic link to a subdirectory during its search, the subdirec‐
              tory pointed to by the symbolic link will be searched.

$ man find | sed -n '/^       -H/,/^$/p;' | sed '/^$/,$d'
       -H     Do not follow symbolic links, except while processing  the  com‐
              mand  line  arguments.  When find examines or prints information
              about files, the information used shall be taken from the  prop‐
              erties  of the symbolic link itself.  The only exception to this
              behaviour is when a file specified on the command line is a sym‐
              bolic link, and the link can be resolved.  For  that  situation,
              the  information  used is taken from whatever the link points to
              (that is, the link is followed).  The information about the link
              itself is used as a fallback if the file pointed to by the  sym‐
              bolic  link  cannot  be examined.  If -H is in effect and one of
              the paths specified on the command line is a symbolic link to  a
              directory,  the  contents  of  that  directory  will be examined
              (though of course -maxdepth 0 would prevent this).

$ man find | sed -n '/^       -P/,/^$/p;' | sed '/^$/,$d'
       -P     Never follow symbolic links.  This  is  the  default  behaviour.
              When  find  examines  or prints information about files, and the
              file is a symbolic link, the information  used  shall  be  taken
              from the properties of the symbolic link itself.

> nor the man pages of cp

If you want to know how symlinks are handled by cp(1), then:

$ man cp | grep sym.*link -B1

       -H     follow command-line symbolic links in SOURCE
--
       -L, --dereference
              always follow symbolic links in SOURCE
--
       -P, --no-dereference
              never follow symbolic links in SOURCE
--

       -s, --symbolic-link
              make symbolic links instead of copying

> and ls (and quite a few of

And similarly for ls(1):

$ man ls | grep sym.*link -C2

       -H, --dereference-command-line
              follow symbolic links listed on the command line

       --dereference-command-line-symlink-to-dir
              follow each command line symbolic link that points to  a  direc‐
              tory

--

       -L, --dereference
              when showing file information for a symbolic link, show informa‐
              tion  for  the file the link references rather than for the link
              itself


> others), all of which discuss what these utilities do with symbolic
> links.

If you want to know how other command handles symlinks, look at that
command's page, and try a few things with grep and sed.

>  By contrast, the Info manual of Coreutils has almost 40 index
> entries starting with "symbolic link", and they are all shown when the
> user types "i symbolic link TAB" ('i' being the letter that invokes
> index-searching command).
> 
>> diff --git a/man5/proc.5 b/man5/proc.5
>> index 521402fe8..233cc1c9d 100644
>> --- a/man5/proc.5
>> +++ b/man5/proc.5
>> @@ -36,7 +36,7 @@
>>  .\"
>>  .TH proc 5 (date) "Linux man-pages (unreleased)"
>>  .SH NAME
>> -proc \- process information pseudo-filesystem
>> +proc \- process information, system information, and sysctl 
>> pseudo-filesystem
>>  .SH DESCRIPTION
>>  The
>>  .B proc
>>
>>
>> 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).

>  By contrast,
> Texinfo lets you add any number of index entries that point to the
> same text.  A random example from the Emacs manual:
> 
>   @cindex arrow keys
>   @cindex moving point
>   @cindex movement
>   @cindex cursor motion
>   @cindex moving the cursor

Using consistent language across pages helps for these things.

>     To do more than insert characters, you have to know how to move
>   point (@pxref{Point}).  The keyboard commands @kbd{C-f}, @kbd{C-b},
>   @kbd{C-n}, and @kbd{C-p} move point to the right, left, down, and up,
>   respectively.  You can also move point using the @dfn{arrow keys}
>   present on most keyboards: @key{RIGHT}, @key{LEFT},
>   @key{DOWN}, and @key{UP}; however, many Emacs users find
>   that it is slower to use the arrow keys than the control keys, because
>   you need to move your hand to the area of the keyboard where those
>   keys are located.
> 
> This paragraph has 5 index entries with different key phrases, all
> pointing to it.  Different people will have different phrases in their
> minds when they think about "cursor movement", thus the need for
> several entries.  One of the phrases appears in the text literally,
> the other don't; moreover, one of them, "movement" is a very frequent
> word, so searching for it with Grep is likely to bring a lot of false
> hits, whereas index-searching commands will not.
> 
>>> The corresponding index-searching commands of Info readers are a
>>> primary means for finding information quickly and efficiently,
>>> avoiding too many false positives and also avoiding frustrating
>>> misses, i.e., searches that fail to find anything pertinent.
>>
>> That's no different than apropos(1).
> 
> See above: it is very different.
> 
>>>>> Man pages have no means of specifying structure
>>>>
>>>> .SH, .SS, .TP, .TQ, and very soon (hopefully weeks not months) .MR
>>>
>>> These provide just one level.
>>
>> We have many levels:
>>
>> book:                /opt/local/foobar/man/
>> volume:              man2/, man3/, ...
>> chapter:     man3/, man3type/, ...
>> page:                sscanf(3)
>> section:     sscanf(3)/DESCRIPTION
>> subsection:  sscanf(3)/DESCRIPTION/Conversions
>> tags:                sscanf(3)/DESCRIPTION/Conversions/n
> 
> Texinfo has:
> 
>   - chapters
>   - sections
>   - subsections
>   - subsubsections
>   - unnumbered variants of the above (unnumberedsubsec etc.)
>   - appendices (appendix, appendixsubsec etc.)
>   - headings (majorheading, chapheading, subheading, etc.)
> 
> More importantly, all those have meaningful names, not just standard
> labels like "DESCRIPTION" or "Conversions".

"Conversions" is not a standard subsection.  It's about conversion
specifiers; something exclusive of sscanf(3).  However, sections and
above do be standardized, and I believe that's good, so that you can
have some a-priori expectations of the organization of a 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.  So much, that I have
functions for reading a specific section of a certain page:


$ man_section man3/sscanf.3 SYNOPSIS
sscanf(3)               Library Functions Manual               sscanf(3)

SYNOPSIS
       #include <stdio.h>

       int sscanf(const char *restrict str,
                  const char *restrict format, ...);

       #include <stdarg.h>

       int vsscanf(const char *restrict str,
                  const char *restrict format, va_list ap);

   Feature    Test    Macro    Requirements    for   glibc   (see   fea‐
   ture_test_macros(7)):

       vsscanf():
           _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

Linux man‐pages (unreleased)     (date)                        sscanf(3)



$ man_section man3/printf.3 ATTRIBUTES
printf(3)               Library Functions Manual               printf(3)

ATTRIBUTES
       For an explanation of the terms used in this section, see attrib‐
       utes(7).
       ┌──────────────────────────────┬───────────────┬────────────────┐
       │ Interface                    │ Attribute     │ Value          │
       ├──────────────────────────────┼───────────────┼────────────────┤
       │ printf(), fprintf(),         │ Thread safety │ MT‐Safe locale │
       │ sprintf(), snprintf(),       │               │                │
       │ vprintf(), vfprintf(),       │               │                │
       │ vsprintf(), vsnprintf()      │               │                │
       └──────────────────────────────┴───────────────┴────────────────┘


Linux man‐pages (unreleased)     (date)                        printf(3)


> 
>>>>> and hyper-links except
>>>>> by loosely-coupling pages via "SEE ALSO" cross-references at the end;
>>>>> they have no means of quickly and efficiently finding some specific
>>>>> subject except by text search (which usually produces a lot of false
>>>>> positives).

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.

Colin, I've had a feeling for a long time that compressed pages are
not very useful.  These days, storage is cheap.  How would you feel
about having the man pages installed uncompressed in Debian?  That
would allow running text tools directly in /usr/share/man/.  I've had
to do that several times, and lucky me that I have the source code of
the Linux man-pages checked out in my computers, but other users don't
and they might have trouble finding for example which pages talk about
RLIMIT_NOFILE.  The only way I know of is:

$ grep -rl RLIMIT_NOFILE man*
man2/dup.2
man2/pidfd_getfd.2
man2/open.2
man2/fcntl.2
man2/poll.2
man2/pidfd_open.2
man2/getrlimit.2
man2/select.2
man2/seccomp_unotify.2
man3/getdtablesize.3
man3/mq_open.3
man3/errno.3
man3/sysconf.3
man5/proc.5
man7/unix.7
man7/fanotify.7
man7/capabilities.7


I'd like to enable this ability for everyone by not compressing
system man pages.  I guess we should talk to the Debian policy
mailing list?


Cheers,
Alex

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

OpenPGP_signature
Description: OpenPGP digital signature