bug#60032: 30.0.50; [WISH] Customizing Info directories

bug#60032: 30.0.50; [WISH] Customizing Info directories

[Ihor Radchenko]

Hi,

I find the current customization of Info search path slightly awkward.

Emacs Info info page suggests to set INFOPATH environment variable.
Yet, it is not something I feel comfortable doing (it is outside the
nice warm Elisp VM).

There is also `Info-default-directory-list', but it only works for
special non-default value of INFOPATH.

Currently, the only way I found to force adding directories as Info
sources is the following:

(require 'info)
(info-initialize)
(add-to-list 'Info-directory-list "~/Git/org-mode/doc/")

which is awkward.

Would it be possible to introduce something like
`Info-overriding-directory-list' to be added in front of Info path in
Emacs? This will complement `Info-additional-directory-list'.

In GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 3.24.35, cairo version 1.17.6) of 2022-12-07 built on localhost
Repository revision: f0e118d3f676afe39df29663399d4bbe8f53f208
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101004
System Description: Gentoo Linux

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#60032: 30.0.50; [WISH] Customizing Info directories

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Tue, 13 Dec 2022 13:19:37 +0000
> 
> I find the current customization of Info search path slightly awkward.
> 
> Emacs Info info page suggests to set INFOPATH environment variable.
> Yet, it is not something I feel comfortable doing (it is outside the
> nice warm Elisp VM).
> 
> There is also `Info-default-directory-list', but it only works for
> special non-default value of INFOPATH.
> 
> Currently, the only way I found to force adding directories as Info
> sources is the following:
> 
> (require 'info)
> (info-initialize)
> (add-to-list 'Info-directory-list "~/Git/org-mode/doc/")
> 
> which is awkward.
> 
> Would it be possible to introduce something like
> `Info-overriding-directory-list' to be added in front of Info path in
> Emacs? This will complement `Info-additional-directory-list'.

Please describe your use case, because I don't think I see why another
variable would be needed.  I guess you have INFOPATH defined (by
someone who is not you?), but you don't like its value or something?
It's not clear which problems you are trying to solve.

In general, I can say 2 things, which I'm sure you already know:

  . environment variables can be set inside Emacs
  . you can hack Info-directory-list in any number of ways, and do
    whatever you want with it, in Lisp

While the above two methods are not exactly what I'd suggest to an
Emacs an Info newbie, I definitely can see you using them.  So again,
I'm unsure what kind of awkwardness is bothering you.  Please
elaborate.

bug#60032: 30.0.50; [WISH] Customizing Info directories

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

> Please describe your use case, because I don't think I see why another
> variable would be needed.  I guess you have INFOPATH defined (by
> someone who is not you?), but you don't like its value or something?
> It's not clear which problems you are trying to solve.

We had a user confused about how to force Emacs info command use Org
manual from git repo:
https://list.orgmode.org/87359jcuoi.fsf@localhost/T/#mde65bfe981036a6ff2e1faa750670d9af648bad8

The user attempted to customize `Info-default-directory-list' and got
surprised that it was ignored.

Upon my further investigation, `Info-default-directory-list' is indeed
ignored when INFOPATH is set by OS.

I also had a similar confusion and gave up customizing Info directories
at some point. Not because it is not documented, but because the setting
is so unusual that I do not think about finding it.

> In general, I can say 2 things, which I'm sure you already know:
>
>   . environment variables can be set inside Emacs
>   . you can hack Info-directory-list in any number of ways, and do
>     whatever you want with it, in Lisp
>
> While the above two methods are not exactly what I'd suggest to an
> Emacs an Info newbie, I definitely can see you using them.  So again,
> I'm unsure what kind of awkwardness is bothering you.  Please
> elaborate.

I do agree that it is possible to set Info directories to desired value.
However, `Info-default-directory-list' being ignored is rather
surprising, especially given that setting the other defcustom
(`Info-additional-directory-list') does not allow overriding system
settings.

Changing `Info-directory-list' is difficult because one needs to run
(info-initialize), which can only be found by reading the source code.

Changing environment variables is something I never ever needed to
customize Emacs' behaviour. Once I see it, my thinking goes: "Surely,
there should be some custom variable.", but no such variable exists.

Conclusion: Current customization state is not a game breaker, but
something I find confusing. That's why WISH.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#60032: 30.0.50; [WISH] Customizing Info directories

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: 60032@debbugs.gnu.org
> Date: Tue, 13 Dec 2022 13:43:50 +0000
> 
> The user attempted to customize `Info-default-directory-list' and got
> surprised that it was ignored.
> 
> Upon my further investigation, `Info-default-directory-list' is indeed
> ignored when INFOPATH is set by OS.

Yes.  But why didn't that user modify INFOPATH?

> However, `Info-default-directory-list' being ignored is rather
> surprising, especially given that setting the other defcustom
> (`Info-additional-directory-list') does not allow overriding system
> settings.

It is done for a good reason.  Setting up the list correctly is
difficult enough, what with the requirement that Emacs's own manuals
should sometimes be before the system-wide installation, and sometimes
after it (to support different use cases).  When INFOPATH is defined,
and used by the stand-alone Info reader, install-info, and other
stuff, it becomes impossible to DTRT.  So we punt, in effect saying:
if you have INFOPATH, you should already know what you are doing.

If you want the gory details (which I happily forgot), run "git log -L"
(or vc-region-history) on the area where Info-default-directory-list
is defined and used, and read the discussions related to the changes
and bugs reported against that.

> Changing environment variables is something I never ever needed to
> customize Emacs' behaviour. Once I see it, my thinking goes: "Surely,
> there should be some custom variable.", but no such variable exists.

Does this include PATH?  If not, why not?

IME, the *PATH variables are quite special: they should generally be
set from outside Emacs, and doing the same via customization options
is usually not a good idea.

bug#60032: 30.0.50; [WISH] Customizing Info directories

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> However, `Info-default-directory-list' being ignored is rather
>> surprising, especially given that setting the other defcustom
>> (`Info-additional-directory-list') does not allow overriding system
>> settings.
>
> It is done for a good reason.  Setting up the list correctly is
> difficult enough, what with the requirement that Emacs's own manuals
> should sometimes be before the system-wide installation, and sometimes
> after it (to support different use cases).  When INFOPATH is defined,
> and used by the stand-alone Info reader, install-info, and other
> stuff, it becomes impossible to DTRT.  So we punt, in effect saying:
> if you have INFOPATH, you should already know what you are doing.

INFOPATH may be set by OS, not by user. For example, it is the case for
me. I have never changed the default value of INFOPATH, which is
non-empty on Gentoo.

> If you want the gory details (which I happily forgot), run "git log -L"
> (or vc-region-history) on the area where Info-default-directory-list
> is defined and used, and read the discussions related to the changes
> and bugs reported against that.

I fail to see why a new variable, symmetric to
`Info-additional-directory-list' cannot be added. It will be prepended,
as opposed to `Info-additional-directory-list', to the Info path.

Also, searching through the commits I noticed the following entry in
Emacs FAQ:

3.5 How do I install a piece of Texinfo documentation?

   • You can create your own Info directory.  You can tell Emacs where
     that Info directory is by adding its pathname to the value of the
     variable ‘Info-default-directory-list’.  For example, to use a
     private Info directory which is a subdirectory of your home
     directory named ‘Info’, you could put this in your init file (*note
     Setting up a customization file::):

          (add-to-list 'Info-default-directory-list "~/Info/")

     You will need a top-level Info file named ‘dir’ in this directory
     which has everything the system ‘dir’ file has in it, except it
     should list only entries for Info files in that directory.  You
     might not need it if (fortuitously) all files in this directory
     were referenced by other ‘dir’ files.  The node lists from all
     ‘dir’ files in ‘Info-default-directory-list’ are merged by the Info
     system.

The above if not true when INFOPATH environment variable is set, AFAIU.

>> Changing environment variables is something I never ever needed to
>> customize Emacs' behaviour. Once I see it, my thinking goes: "Surely,
>> there should be some custom variable.", but no such variable exists.
>
> Does this include PATH?  If not, why not?
>
> IME, the *PATH variables are quite special: they should generally be
> set from outside Emacs, and doing the same via customization options
> is usually not a good idea.

I agree. However, I expect in-Emacs info reader to be more configurable.
It's not like info.el requires external system tools. I prefer Emacs to
be portable as much as sanely possible.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#60032: 30.0.50; [WISH] Customizing Info directories

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: 60032@debbugs.gnu.org
> Date: Wed, 14 Dec 2022 10:27:19 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Changing environment variables is something I never ever needed to
> >> customize Emacs' behaviour. Once I see it, my thinking goes: "Surely,
> >> there should be some custom variable.", but no such variable exists.
> >
> > Does this include PATH?  If not, why not?
> >
> > IME, the *PATH variables are quite special: they should generally be
> > set from outside Emacs, and doing the same via customization options
> > is usually not a good idea.
> 
> I agree. However, I expect in-Emacs info reader to be more configurable.
> It's not like info.el requires external system tools. I prefer Emacs to
> be portable as much as sanely possible.

Feel free to submit a patch for the master branch.  We will then have
enough time to see if it causes trouble for someone.

bug#60032: 30.0.50; [WISH] Customizing Info directories

[Michael Heerdegen]

Ihor Radchenko <yantar92@posteo.net> writes:

> Currently, the only way I found to force adding directories as Info
> sources is the following:
>
> (require 'info)
> (info-initialize)
> (add-to-list 'Info-directory-list "~/Git/org-mode/doc/")
>
> which is awkward.

Without judgment: Yes, it can be confusing, I remember the exact same
question had been raised just a few weeks ago at the emacs-helm repo
(thus the CC of Thierry as notification).

I struggled with myself about whether I should create a bug report, but
then saw that it's probably not easy to improve the end-user situation.

Michael.