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

From: Björn Bidar <[email-masked]>
Date: Sun, 19 Jan 2025 15:54:59 +0200

Eli Zaretskii <[email-masked]> writes:

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

Correct in that would be the technically intended way of referring to the
HTML version of a node in an Info manual.
Since the references have to be maintained in that file anyway
duplication would be reduce in any case that way.

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

It is possible that a user opens a terminal and calls info but
most users who dont use terminals or know of a graphical info viewer
such as Emacs or KDE Help Center/KHelpCenter likely gloss over such
instructions. Using a web link reduces the barrier of entry to read the
referenced node. 

Web links are just the norm outside of Emacs.

As for Emacs users or Info users who use Emacs too: It should be
possible to install a browse-url handler to reverse the mapping using
htmlxref.cnf. Emacs users who use something else than Emacs can't use
Emacs to follow Info links in general unless the do so by themselves.
However that is offtopic.

>> Regarding the maintenance burden: is there already code to parse a file
>> like htmlxref.cnf?
>
> Not that I know of, no.

OK that's to bad but the file doesn't look to difficult to parse. 

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

Maybe the Texinfo people know what is the best option for this. There is
also the option to keep a copy of the file as the fallback but that
brings other issues I know.

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

Yes I do, at least most of the time. However Emacs users not only stay
in Emacs and even if staying in Emacs the link part doesn't work
everywhere as the linkification (don't know the right work) is only done
in some modes by themselves e.g. in Gnus articles. However that's a
different topic I think. 

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

Sure it can't say everything, which is why I think it should be generic
to cover the general functionality and not only the default setting.

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

No problem, no offense taken. Just replying to your comments, not
arguing to try to not disagree on this.