Subject: bug#75638: [PATCH] Include various GNU manuals in info-url-alist

From: Eli Zaretskii <[email-masked]>
Date: Sun, 19 Jan 2025 07:32:25 +0200

> From: Björn Bidar <[email-masked]>
> Cc: [email-masked],  [email-masked],  [email-masked],
>   [email-masked]
> Date: Sat, 18 Jan 2025 22:40:40 +0200
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> >> From: Björn Bidar <[email-masked]>
> >> Cc: Stefan Kangas <[email-masked]>,  Andrea Corallo
> >>  <[email-masked]>,  Juri Linkov <[email-masked]>,  [email-masked]
> >> Date: Sat, 18 Jan 2025 16:23:33 +0200
> >> 
> >> Eli Zaretskii <[email-masked]> writes:
> >> 
> >> > The canonical place that associates Texinfo manuals with the URLs of
> >> > their Web pages is the file util/htmlxref.cnf in the Texinfo source
> >> > tree.
> >> 
> >> If this file exists why do we not use it then?
> >
> > It was never needed before.  The current code supports only the Emacs
> > manuals, and for those we always know where they are kept, because we
> > upload them there.
> >
> 
> I understand that it was never needed before but from the way you
> explained it using htmlxef.cnf was from my point of view clearly the
> correct approach. 

"Correct" in what sense?  Supporting only Emacs manuals doesn't need
it, so depending on it is an extra dependency (and/or extra code to
process it) when the result is known in advance.  So with the current
code, use of that file is not justified: it has disadvantages, but no
advantages.

> >> To link to documentation for example. For example a project I'm working
> >> on uses Autoconf. To explain a change I've made I linked to the manual
> >> on the GNU website. Linking to HTML version of the manual is the most
> >> accessible in a editor neutral context.
> >
> > First, we have in Emacs a format for linking to Info documentation.
> > The command 'w' in Info copies the link to the kill-ring, so you can
> > later yank it into a different place.  The link is in the form
> > "(FILENAME) NODENAME", and the Info reader can interpret it.
> 
> Sure that is nice but most people don't consume manuals this way. If I
> want to link to a manual using a link is natural linking a manual in the
> Info form isn't natural to people who don't frequently use it, i.e.
> Emacs- or generally GNU-users. 

These links are more natural to Emacs and Info users than the links to
HTML docs, because the node is explicitly named in exactly the same
words as you'd type at the prompt of the 'g' command (as opposed to a
URL, where the node's name can be modified due to HTML requirements).
As for people who do not use Info, why is it not enough to tell them
the name of the manual and the node?

> Regarding the maintenance burden: is there already code to parse a file
> like htmlxref.cnf?

Not that I know of, no.

> The maintenace burden of using this format which
> seems to be the intentional file to read for this should be very low.

That's true, but then this command will not work if the file is not
installed on the user's machine.  Alternatively, the Emacs maintainers
will have to remember to run some command from time to time and update
the database from its results, which is also an additional burden.

> >> I would like to link to Info manuals so they can be opened with Info but
> >> there is no such a thing.
> >
> > When using Info for accessing the linked manual, there is: see above.
> 
> That is not a link. A link wouldb be an uri that can be recognized by
> the OS and then handled. Yes most Emacs modes can understand the the
> syntax e.g. when I write (info "(emacs) Entering Emacs") then Gnus
> understands the format and will follow the reference correctly.

So you agree that, as long as the user stays in Emacs, these links do
work.

> The function isn't called Info-goto-node-web-emacs yes the default
> setting is to open manuals on the gnu.org server but it doesn't have to be.

The name of a command isn't supposed (and cannot, in practice) to say
everything about what the command does and doesn't do.  That's what
the doc string is for.  Having command names that are not too long is
also an advantage.

Anyway, it's clear that we disagree about this, so let's wait for
others to chime in and state their opinions.