Does variable 'org-goto-interface' exist?

Does variable 'org-goto-interface' exist?

[Alain.Cochard]

At the end of section 2.3 (Motion) of the manual:

     See also the variable ‘org-goto-interface’.

But this variable does not seem to exist.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Does variable 'org-goto-interface' exist?

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> At the end of section 2.3 (Motion) of the manual:
>
>      See also the variable ‘org-goto-interface’.
>
> But this variable does not seem to exist.

It does, but you need to load org-goto library first.
(It is also auto-loaded when you call org-goto via key binding)

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

Re: Does variable 'org-goto-interface' exist?

[Alain.Cochard]

Ihor Radchenko writes on Tue 13 Dec 2022 09:33:
 > Alain.Cochard@unistra.fr writes:
 > 
 > > At the end of section 2.3 (Motion) of the manual:
 > >
 > >      See also the variable ‘org-goto-interface’.
 > >
 > > But this variable does not seem to exist.
 > 
 > It does, but you need to load org-goto library first.
 > (It is also auto-loaded when you call org-goto via key binding)

I see.  Thank you.  (I guess it wouldn't hurt to mention this in the
manual.)



-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Does variable 'org-goto-interface' exist?

[Ihor Radchenko]

[-- Attachment #1: Type: text/plain, Size: 296 bytes --]

Alain.Cochard@unistra.fr writes:

>  > It does, but you need to load org-goto library first.
>  > (It is also auto-loaded when you call org-goto via key binding)
>
> I see.  Thank you.  (I guess it wouldn't hurt to mention this in the
> manual.)

Does the attached patch help with understanding?

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-Document-that-org-goto.el-is-not-.patch --]
[-- Type: text/x-patch, Size: 1192 bytes --]

From ee19ca2493861947c9ef08acee74d5efc13449b8 Mon Sep 17 00:00:00 2001
Message-Id: <ee19ca2493861947c9ef08acee74d5efc13449b8.1670931772.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Tue, 13 Dec 2022 14:41:44 +0300
Subject: [PATCH] doc/org-manual.org: Document that org-goto.el is not loaded
 by default

* doc/org-manual.org (Motion): Mention that `org-goto-*' customization
are only available upon explicit `require' or auto-loading of
org-goto.el.

Reported-by: Alain.Cochard@unistra.fr
Link: https://orgmode.org/list/25496.19258.682537.503614@gargle.gargle.HOWL
---
 doc/org-manual.org | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 4fb017db8..e7f32d1da 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -693,6 +693,10 @@ ** Motion
   #+texinfo: @noindent
   See also the variable ~org-goto-interface~.
 
+  Note: ~org-goto-*~ variables are only accessible when =org-goto=
+  library is loaded using ~require~ statement in the config or
+  auto-loaded by calling ~org-goto~ interactively.
+
 ** Structure Editing
 :PROPERTIES:
 :DESCRIPTION: Changing sequence and level of headlines.
-- 
2.38.1


[-- Attachment #3: Type: text/plain, Size: 225 bytes --]



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

Re: Does variable 'org-goto-interface' exist?

[Alain.Cochard]

Ihor Radchenko writes on Tue 13 Dec 2022 11:43:

 > Does the attached patch help with understanding?

Yes, for me this is perfectly clear.

I have a practical question, though: in order to see the effect of
your patch in context, I applied it in my git repository and did

   make && make doc

I then can see the change in the org.pdf file, but not in the Info
manual, although I used

   emacs -Q -l .emacs.git

with .emacs.git containing

   (add-to-list 'load-path "~/Org/Coch-git/org-mode/lisp")

   (setq Info-default-directory-list 
	     (append '("/home/cochard/Org/Coch-git/org-mode/doc")
		     Info-default-directory-list))

What am I doing wrong?  Thank you.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Does variable 'org-goto-interface' exist?

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> I have a practical question, though: in order to see the effect of
> your patch in context, I applied it in my git repository and did
>
>    make && make doc
>
> I then can see the change in the org.pdf file, but not in the Info
> manual, although I used
>
>    emacs -Q -l .emacs.git
>
> with .emacs.git containing
>
>    (add-to-list 'load-path "~/Org/Coch-git/org-mode/lisp")
>
>    (setq Info-default-directory-list 
> 	     (append '("/home/cochard/Org/Coch-git/org-mode/doc")
> 		     Info-default-directory-list))
>
> What am I doing wrong?  Thank you.

Check out [[info:info#Emacs Info Variables]]

Basically, INFOPATH environment variable takes precedence.
You may also take a look at `Info-directory-list' docstring.

straight.el uses the following, slightly awkward approach:

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

Emacs info page suggests to set environment variable.

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

Re: Does variable 'org-goto-interface' exist?

[Max Nikulin]

On 13/12/2022 18:43, Ihor Radchenko wrote:
> +  Note: ~org-goto-*~ variables are only accessible when =org-goto=
> +  library is loaded using ~require~ statement in the config or
> +  auto-loaded by calling ~org-goto~ interactively.

Perhaps it is better to introduce some more concise notation to specify 
the package where a custom option or variable is defined like 
~org-goto-interface~ (=org-goto.el=).

Re: Does variable 'org-goto-interface' exist?

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> On 13/12/2022 18:43, Ihor Radchenko wrote:
>> +  Note: ~org-goto-*~ variables are only accessible when =org-goto=
>> +  library is loaded using ~require~ statement in the config or
>> +  auto-loaded by calling ~org-goto~ interactively.
>
> Perhaps it is better to introduce some more concise notation to specify 
> the package where a custom option or variable is defined like 
> ~org-goto-interface~ (=org-goto.el=).

I am not sure. This particular note is largely aiming at new users not
too familiar with Emacs system. Won't your suggestion be confusing?

For me ~org-goto-*~ should be naturally inside org-goto.el.

On the other hand, we may extend 1.5 Typesetting Conventions Used in
this Manual section of the manual describing what the proposed notation
refers to and then use it as needed.

Note, however, that org-goto is probably not the only place where we
refer to a customization that is not loaded by default. I am unsure how
many places like this exist and whether some presently auto-loaded
libraries will be still loaded in future as we try to make Org more
modular (and thus reduce the initial load time, many Emacs devs are
complaining about).

So, maintaining the proposed convention might not work well.

Or we may indicate the library with every variable we introduce from
that library for the first time + indicate that all the variables with
the same prefix will be from the same library.

WDYT?

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

Re: Does variable 'org-goto-interface' exist?

[Alain.Cochard]

Ihor Radchenko writes on Wed 14 Dec 2022 07:55:

 > This particular note is largely aiming at new users not too
 > familiar with Emacs system.

 > [...]
 
 > Note, however, that org-goto is probably not the only place where we
 > refer to a customization that is not loaded by default. I am unsure how
 > many places like this exist
 
I am not taking any side regarding the point Max brought up, but your
comment about new users surprises me.  I am a long time Emacs user,
but it is the 1st time (Org mode or otherwise) that 'C-h v' with the
cursor on a variable's name fails.  Reading again section 2.3, I
really don't see that I could have guessed about loading org-goto.

So if it is not the "only place", I bet it is relatively rare, and I
fear that I will have forgotten about it if the same thing happens
again to me in 3 years.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Does variable 'org-goto-interface' exist?

[Max Nikulin]

On 13/12/2022 15:54, Alain.Cochard wrote:
> At the end of section 2.3 (Motion) of the manual:
> 
>       See also the variable ‘org-goto-interface’.
> 
> But this variable does not seem to exist.

Alain, could you, please, clarify, what you was trying to do when you 
came to conclusion that `org-goto-interface' did not exist?

Interactive C-h v (`describe-variable') autoloads org-goto if TAB is 
pressed when "org-goto-" is typed into the prompt, so 
`org-goto-interface' becomes available for completion. However e.g. 
"org-go" is not enough for completion. A kind of pitfall is that 
non-interactive call
     M-: (describe-variable "org-goto-interface") RET
does not autoloads org-goto as well.

M-x customize-variable RET is not so clever (at least in Emacs-26) and 
it does not try autoloads.

If org-goto has not loaded yet and cursor is over `org-goto-interface' 
mention in the Info node "(org) Motion" then C-h v (`describe-variable') 
does not prefill the prompt. It is easier to jump to the help for this 
variable when org-goto is loaded.

My point is that maybe it is better to adjust Emacs behavior, not Org 
manual.

P.S. Sometimes I do not mind to have hyperlinks from HTML manuals to 
docstrings exported to HTML as well, but it is another story.

Re: Does variable 'org-goto-interface' exist?

[Alain.Cochard]

Max Nikulin writes on Wed 14 Dec 2022 17:01:
 > On 13/12/2022 15:54, Alain.Cochard wrote:
 > > At the end of section 2.3 (Motion) of the manual:
 > > 
 > >       See also the variable ‘org-goto-interface’.
 > > 
 > > But this variable does not seem to exist.
 > 
 > Alain, could you, please, clarify, what you was trying to do when you 
 > came to conclusion that `org-goto-interface' did not exist?
 > 
 > Interactive C-h v (`describe-variable') autoloads org-goto if TAB is 
 > pressed when "org-goto-" is typed into the prompt, so 
 > `org-goto-interface' becomes available for completion. However e.g. 
 > "org-go" is not enough for completion. A kind of pitfall is that 
 > non-interactive call
 >      M-: (describe-variable "org-goto-interface") RET
 > does not autoloads org-goto as well.

Like I said in another message that I sent just before receiving yours
my conclusion came from the fact that hitting 'C-h v' with the cursor
on 'org-goto-interface' provided nothing.  It was the first time this
ever happened to me.  I did try to explicitly enter the variable's
name by entering 'org-goto<TAB>', which (like 'org-go<TAB>') is not
enough: it is completed to 'org--goto'.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Does variable 'org-goto-interface' exist?

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

>  > Note, however, that org-goto is probably not the only place where we
>  > refer to a customization that is not loaded by default. I am unsure how
>  > many places like this exist
>  
> I am not taking any side regarding the point Max brought up, but your
> comment about new users surprises me.  I am a long time Emacs user,
> but it is the 1st time (Org mode or otherwise) that 'C-h v' with the
> cursor on a variable's name fails.  Reading again section 2.3, I
> really don't see that I could have guessed about loading org-goto.

Well. I guess my perception of "new user" is a bit biased :)
In any case, whatever we write in the manual should be understandable by
proper new users as well.

> So if it is not the "only place", I bet it is relatively rare, and I
> fear that I will have forgotten about it if the same thing happens
> again to me in 3 years.

There was at least one more bug report, similar to yours in the past.
Also, the majority of ob-*.el files and ol-*.el files are not loaded by
default. And I hope that even less files will be loaded by Org in future
to address "loading time" complaints.

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

Re: Does variable 'org-goto-interface' exist?

[Max Nikulin]

On 14/12/2022 17:20, Alain.Cochard wrote:
> 
> my conclusion came from the fact that hitting 'C-h v' with the cursor
> on 'org-goto-interface' provided nothing.  It was the first time this
> ever happened to me.  I did try to explicitly enter the variable's
> name by entering 'org-goto<TAB>', which (like 'org-go<TAB>') is not
> enough: it is completed to 'org--goto'.

I was confused by similar behavior as well, see
Maxim Nikulin to emacs-orgmode. Bug? C-h v in src block since org-9.4. 
Wed, 28 Apr 2021 19:19:13 +0700. 
https://list.orgmode.org/s6bjs2$b0$1@ciao.gmane.io

I think, help completion should include arguments of 
`register-definition-prefixes' from loaddefs files (till the related 
package is loaded), even if it may give some variants that has no 
functions or variables defined in a library. `customize-variable' should 
be consistent with describe-variable in respect to autoloading and 
completion option.

Alain, are you motivated enough to search in emacs bug tracker and in 
emacs-devel mailing list archives if such options were considered? From 
my point of view it is better to improve completion than to modify the 
Org Manual just for org-goto. Feel free to add me as X-Debbugs-CC if you 
decide to create a feature request or a bug.

Re: Does variable 'org-goto-interface' exist?

[Max Nikulin]

On 14/12/2022 14:55, Ihor Radchenko wrote:
> Max Nikulin writes:
>> Perhaps it is better to introduce some more concise notation to specify
>> the package where a custom option or variable is defined like
>> ~org-goto-interface~ (=org-goto.el=).

...

> Note, however, that org-goto is probably not the only place where we
> refer to a customization that is not loaded by default.

This the exact reason why I decided to consider some general convention.

> So, maintaining the proposed convention might not work well.

I agree. In addition, I do not see a way to make such convention 
semi-active to help users to access docs easier.

So I suggest to leave the Org manual as is and perhaps to improve C-h 
completion instead. Actually I am surprised that symbols are not 
transformed to help links in info buffers.

Re: Does variable 'org-goto-interface' exist?

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> Alain, are you motivated enough to search in emacs bug tracker and in 
> emacs-devel mailing list archives if such options were considered? From 
> my point of view it is better to improve completion than to modify the 
> Org Manual just for org-goto. Feel free to add me as X-Debbugs-CC if you 
> decide to create a feature request or a bug.

I agree. It is better if Emacs fixes this issue.
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=60085

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

Re: Does variable 'org-goto-interface' exist?

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> Actually I am surprised that symbols are not 
> transformed to help links in info buffers.

Well. https://yhetil.org/emacs-devel/86lfm3k05m.fsf@duenenhof-wilhelm.de

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

[Info path] Re: Does variable 'org-goto-interface' exist?

[Alain.Cochard]

Ihor Radchenko writes on Tue 13 Dec 2022 13:14:
 > Alain.Cochard@unistra.fr writes:
 > 
 > > I have a practical question, though: in order to see the effect of
 > > your patch in context, I applied it in my git repository and did
 > >
 > >    make && make doc
 > >
 > > I then can see the change in the org.pdf file, but not in the Info
 > > manual, although I used
 > >
 > >    emacs -Q -l .emacs.git
 > >
 > > with .emacs.git containing
 > >
 > >    (add-to-list 'load-path "~/Org/Coch-git/org-mode/lisp")
 > >
 > >    (setq Info-default-directory-list 
 > > 	     (append '("/home/cochard/Org/Coch-git/org-mode/doc")
 > > 		     Info-default-directory-list))
 > >
 > > What am I doing wrong?  Thank you.
 > 
 > Check out [[info:info#Emacs Info Variables]]
 > 
 > Basically, INFOPATH environment variable takes precedence.
 > You may also take a look at `Info-directory-list' docstring.

Thanks a lot.  I now see it is not a good idea to customize
Info-default-directory-list.

Still, with the setup indicated above, Info-directory-list is
   
   ("/home/cochard/Org/Coch-git/org-mode/doc"
    "/usr/local/share/info/" "/usr/share/info/" "/usr/share/info/")

and the 1st line of the Info Org manual is

   This manual is for Org version 9.6.

So, somehow, setq Info-default-directory-list is taken into account
(if I don't to it, I get "Org version 9.4", the native one for emacs
27.2) and I still don't understand why I don't see the effect of the
patch in the Info Org manual (I do see the effect in org.pdf).


-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]