Re: Playground pager lsp(1)

[Patrice Dumas]

On Wed, Apr 05, 2023 at 11:03:36AM +0200, tomas@tuxteam.de wrote:
> 
> I was dreaming of a world where both doc systems converge
> in a way their respective users don't notice, and we end
> up with a Grand Unified Documentation (GUD) for all things
> free.

Because of the differences in design, as Eli described, I do not think
that it is really possible to have something really well unified, nor to
have users not noticing.  That being said, it may be possible to have
cross-manual links better handled accross different documentation
systems.

For HTML, we have in Texinfo a way to specify other manuals as described
here:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Link-Basics.html
Maybe it could be considered for a similar scheme for man pages, such
that the man pages can be specified as a Texinfo @xref (as documented at
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-References.html
) and could be used to link from/to man pages when both man pages and
Texinfo manuals are rendered as HTML.

Doing something with the Info format and the Info reader, especially the
standalone infor reader (maybe it could be easier with the Emacs Info
reader) is likely to be much more challenging if not impossible in my
opinion.  I cannot really imagine a way to have something really
integrated given the limitations of the Info format.  The standalone
Info reader already shows a man page when an info manual is not found,
but this is not true integration.

The Info format is described here, it is quite simple:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Info-Format-Specification.html

All that should probably be thought with other documentation systems,
for instance, it would make sense to include something like Mallard
(http://projectmallard.org/) in the reflexion, as the Mallard design is
again something else that Texinfo or man pages in term of design.

As a side note, we have a POD to Texinfo converter, POD explicitly
considers man pages (and POD design is clearly based on man pages), when
converting to Texinfo, I reused the Pod::Simple::HTML way of doing 
by having a link to 'ls (1)' becomes an url like
@uref{http://man.he.net/man1/ls}.  But again it is not very satisfying
as it is very specific of man pages.

If a discussion on cross formats links is started, I would be ok to be
in it, but I am not aware of such endeavour.

-- 
Pat