Re: Playground pager lsp(1)

[Eli Zaretskii]

> 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", 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.  For example, the above doesn't find the
man page of Find, nor the man pages of cp and ls (and quite a few of
others), all of which discuss what these utilities do with symbolic
links.  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.  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
    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".  So when you see them in
TOC or any similar navigation aid, you _know_, at least approximately,
what each section is about.

> >>> 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).
> >>
> >> I guess you mean searching from the command line by the name of the
> >> parameter to a function, or what?
> > 
> > No, I mean looking a specific subject of interest without having to
> > search/read through the entire document.
> 
> See symlink above.

Not relevant.

> >> I would be interested in a more detailed description of what you
> >> want to be able to search in current pages (hopefully ones that I
> >> maintain, so I can speak of them) that you can't find easily?  Maybe
> >> I can help making something more accessible.
> > 
> > See above, the example of using index-searching commands.
> 
> Yep.  I hope my answer about symlinks satisfied you.

No, it didn't.