Re: Playground pager lsp(1)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 5 Apr 2023 01:45:46 +0200
> Cc: help-texinfo@gnu.org
> From: Alejandro Colomar <alx.manpages@gmail.com>
> 
> With the benefit that you don't need to implement such a system from scratch,
> but just reusing the existing tools (apropos, man, whatis, ...).  It seems
> something like what I would have written if I had to implement info(1) from
> scratch.  I wish GNU guys had thought of this instead of developing their
> own incompatible system.

This last sentence is a misunderstanding.  The goal of Texinfo is not
to improve the man pages.  Texinfo is a completely different approach
to software documentation, which allows to write large books and then
produce various on-line and off-line formats to read and efficiently
search those books.

Man pages have no means of specifying structure 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).

By contrast, Texinfo documents have sectioning structure, have
cross-references that can appear where you need them and point
anywhere else in the document (or into another document).  They also
have indexing and commands that allow the reader to use the index in
order to find the subject he/she is interested in very quickly and
accurately, even if the text of the index entry doesn't appear
anywhere in the manual.

How can you document a large and flexible software package, such as
GDB or Texinfo or Emacs, in man pages?

It is a mistake to even compare these two documentation systems,
certainly in this way.

> >        •   In windowing environments lsp does complete resizes when windows
> >            get resized. This means it also reloads the manual page to fit the
> >            new window size.
> 
> Good.  This I miss it in less(1) often.  Not sure if they had any strong
> reason to not support that.

??? Why do you say 'less' doesn't support window resizing?  It does
here.

> >        •   lsp has an experimental TOC mode.
> > 
> >            This is a three-level folding mode trying to list only section and
> >            sub-section names for quick navigation in manual pages.
> 
> Nice, and this an important feature missing feature in info(1), as I
> reported recently.  :)

It isn't missing.  The TOC is presented as top-level menu in each
manual, and large manuals have also the "detailed menu" with all the
sub-nodes spelled out.  In addition, the Emacs Info reader has the
Info-toc command, which presents a structured menu with all the
sectioning levels of a manual even if the manual didn't produce it.

There are also more focused commands which present TOC-like lists
across all the manuals, which you can then navigate to read what you
deem appropriate.  See the description of "--all" command-line option
of the stand-alone Info reader.  For example, try this command:

  $ info --all e --index-search "init file"

There's also the index-apropos command from inside the stand-alone
reader (and the matching info-apropos in the Emacs Info reader).