Re: Playground pager lsp(1)

[Alejandro Colomar]

Hi Eli!

On 4/5/23 07:35, Eli Zaretskii wrote:
>> 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.

"The manual was intended to be typeset; some detail is sacrificed on
terminals." (man(1), _Unix Time-Sharing System Programmer's Manual_,
Eighth Edition, Volume 1, February 1985)

You mean books like this one?  Courtesy of groff(1)'s Deri James =)
<https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/man-pages-6.04.01.pdf>

Or maybe you prefer HTML?
<https://man7.org/linux/man-pages/man1/intro.1.html>

As to efficiency, I'm not going to open that melon, because we're
both very biased to be efficient on the formats we each maintain.
I'll just say that I don't see an objective winner in those terms.

About variety of output formats, anything that can be produced by
groff(1), man(7) can be translated.  And groff(1) can do many formats.

> 
> Man pages have no means of specifying structure

.SH, .SS, .TP, .TQ, and very soon (hopefully weeks not months) .MR

Those can be used to produce very precise links such as this one
(one of my favourite references when reviewing man-pages patches):
<https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/man-pages-6.04.01.pdf#pdf%3Abm11886>

And there's still room for improvement over what you'll see in that
PDF, or what you can see in <man7.org>.

> 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?  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.

lsp(1) helps a little bit making the structure of man pages navigable,
and it's currently implemented using heuristics, but if it worked
together with groff(1) to get the real source of truth, it could get
precise data without needing heuristics.

> 
> 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).

This was discussed as a possible extension to '.MR'.  We're just not
sure that there's a real need for that in manual pages (although
there's not a consensus on that regard, and Branden, which I'm sure
is reading this, may jump in at any moment :).

>  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

You mean whatis(1) and apropos(1)?  lsp(1) makes use of those to be
able to navigate all pages in the system (I guess this is more or
less what info(1) does; with the obvious differences due to how
nodes are organized).

> accurately, even if the text of the index entry doesn't appear
> anywhere in the manual.

man pages have several ways:

-  Including keywords in the NAME section.
-  Link pages.
-  TH line.

Of course, this is for the terminal.  For PDF or HTML, you can
get hyperlinks to any subsection (and in the future maybe even
tagged paragraphs) within a page.

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

git is a huge program, yet its man pages are quite useful.
Just split your documentation at the right boundary, which
usually requires a good design for your software that allows
such division.

$ apt-file show git-man | wc -l
190

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

The fact that current man(1) implementations don't exploit
the whole power of man(7) doesn't mean you can't design a
software that does.

I'm sure you could build something similar to info(1) that
got man(7) pages as its input.

That PDF linked above is just a starter of what we want to
do in the not far future.  Hopefully we can also get some
time to work on HTML.

> 
>>>        •   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.

Hmm, now that I think, it's probably an issue of coordinating
man(1) and less(1).  I sometimes wish that when I resize a
window where I'm reading a man page, it would reformat the page
from source.  Of course, that might be a problem for keeping
track of where I was, since lines moved around.  Not sure how
good lsp(1) is at that.

> 
>>>        •   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.

Ahh, yes, this is true.  What I found missing is a kind of a map for
knowing what I have available for navigating (also the fact that I
don't usually run info(1) makes me be a bit fuzzy on detailing what
is it that I miss from it).  So, info(1) has a map of the sections
available in a page, and does it also have a map of all the pages
in the system (or whatever you call your pages, I don't yet really
understand the organization of info manuals).

> 
> 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).

It's nice to talk to you, even if we usually disagree in how we
find documentation more accessible :)

Cheers,
Alex

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

OpenPGP_signature
Description: OpenPGP digital signature