There are some doubts whether it is so good to use texi_macros_file as a template.

Yes, please do. Take a look at the doc for texi_macros_file for an example of another similar setting that has a default value that can be overridden but probably never should be.

And we already have bug #48654 if someone wants to look into adding support for java.opts to exist in more than one global directory, which I think is a good idea.

To clarify, when I said "no longer document it as something that the user should be changing", I am including the option of keeping it documented, but marking it as an expert feature. For example we also document the OCTAVE_TEXI_MACROS_FILE environment variable, but I honestly don't think a normal user has a need to set that variable.

The conflicting section in the documentation is:

https://hg.savannah.gnu.org/hgweb/octave/file/631076eab47b/doc/interpreter/external.txi#l2112

The description is really misleading: `OCTAVE_JAVA_DIR` must remain a constant path to `octave.jar`

$ export OCTAVE_JAVA_DIR=/tmp
$ octave-cli

>> javaaddpath("/home")
error: octave.jar does not exist: /tmp/octave.jar
error: called from
    javaaddpath at line 52 column 13

vs.

$ export OCTAVE_JAVA_DIR=
$ octave-cli
>> javaaddpath("/home") # no error

Therefore I agree, that `OCTAVE_JAVA_DIR` is an example of a useless environment variable.

I can imagine two solutions:

1. The location of `octave.jar` should not rely on reading the environment variable `OCTAVE_JAVA_DIR` and is determined at compile/install time.

2. Introduce two environment variables: `OCTAVE_JAVA_DIR` and `OCTAVE_JVM_OPTS`.  The latter one obtains the JVM parameters directly in favor of a separate file `java.ops`.

I favor the first solution, as it is not likely that the location of `octave.jar` will change after the installation.

In the documentation, it is only mentioned, that OCTAVE_JAVA_DIR,
if defined,
specifies the location of the java option file java.opts.
Nowhere is mentioned, that it also determines where octave.jar
and javaclasspath.txt is located.
If OCTAVE_JAVA_DIR is set and this is not taken into account,
octave.jar and javaclasspath.txt are no longer found.
As a consequence, part of the java classpath is missing.
In particular the java classes implementing the core of octave's java interface located in octave.jar are missing.
So the java interface does not work any longer.

THe documentation shall mention that besides java.opts also octave.jar and javaclasspath.txt shall be in the directory defined by OCTAVE_JAVA_DIR.