Re: Texinfo 7.0 changed the name of HTML output directory

[Patrice Dumas]

On Sun, Aug 25, 2024 at 11:32:01AM +0100, Gavin Smith wrote:
> It's actually worse.  It's not just a matter of placing the htmlxref.cnf
> file in the same directory as the Texinfo source.  It has to be present
> in the working directory (.) where texi2any runs.  (I just tested
> this with current git 'master'.)  
> 
> So I can see a few ways to use the same htmlxref.cnf file:
> 
> * In the build process for the web manuals, copy the project-specific
> htmlxref.cnf file to the current working directory.  How this is done
> would depend on the project.
> 
> * texi2any checks in ~/.texinfo/ where ~ is the "current user's home
> directory" according to the manual.  This is the value of the HOME
> environment variable.  Hence, you could override HOME.  If I have the
> files "subdir/.texinfo/htmlxref.cnf" and "manual/manual.texi", then
> I can run:
> 
> HOME=subdir texi2any manual/manual.texi --html --no-split
> 
> This is a hack but may be the best way at the moment.  I think we
> should have a better way of supporting this if there isn't one already.
> We should at least support the "XDG Base Directory Specification".

Agreed.

> * Use HTMLXREF_FILE.  Below I explain why this variable is probably not
> what you want to use.
> 
> (HTMLXREF_FILE should possibly be used along with HTMLXREF_MODE=file although
> this seemed not to be necessary when I tested it.)

If HTMLXREF_MODE is not file, then HTMLXREF_FILE is used instead of
htmxref.cnf as the base file name.

> For example, if both "manual.texi" and "htmxref.cnf" are in "..", then
> 
>   texi2any ../manual.texi --html --no-split

This could be changed, we could add the manual source directory to the
htmlxref.cnf search path (actually the @language_config_dirs, see below),
for example, although only after the input file name directory has been
determined, so right before parsing (as we do for include files). 

> doesn't read htmlxref.cnf, whereas
> 
>   texi2any ../manual.texi --html --no-split -c HTMLXREF_FILE=../htmlxref.cnf
> 
> does.

This is not how HTMLXREF_FILE is supposed to be used/to work with
default HTMLXREF_MODE.  Normally (and according to my reading of the
code), HTMLXREF_FILE will be prepended to the directories, so the
files tried should be:

../htmlxref.cnf
./.texinfo/../htmlxref.cnf
$HOME/../htmlxref.cnf
SYSCONFDIR/texinfo/../htmlxref.cnf
DATADIR/texinfo/../htmlxref.cnf

> Unfortunately, the file specified by HTMLXREF_FILE is the *only* htmlxref.cnf
> file that is read, so this variable should probably not be used.

I do not think that it is true, however the directories searched are not
the expected ones, so I think that it is wrong to have HTMLXREF_FILE
specified with a relative path to lead to that list of files to be
looked at.  I think that this should be changed.  I see two
possibilities, either disallow completly relative paths, or if there is
a relative path only try it and not any other path, which is already
what is done with an absolute path, which actually has my preference
(and we already do something like that in another setting).  In any case,
this is not the way to go for this use case for the reasons you say, it
only works to find one file.

> I suggest that we should add a warning to texi2any any time an htmlxref.cnf
> entry is missing for a manual and we revert to the default "../MANUAL_html/"
> link.  That way manual authors would be aware of such problems.  We
> could add an option to turn the warning off for special uses.

This is already possible, it is CHECK_HTMLXREF (which is set to 1 in the
default case for EPUB as relative paths in EPUB are not possible).

> > There is the HTMLXREF_FILE variable we could use to point to a single
> > htmlxref.cnf file, but was this variable supported starting from the
> > same Texinfo version which introduced htmlxref.cnf?  It doesn't sound
> > that way: htmlxref.cnf is mentioned in NEWS under Texinfo 5.0, whereas
> > HTMLXREF_FILE is mentioned only under Texinfo 7.0.  So using this
> > variable would mean we'd need to restrict HTML generation to Texinfo
> > 7.0 and newer, right?
> 
> Yes.

Also, I think that there is no situation in which it would solve this use
case.

We should probably implement the two changes proposed above, to me they
are improvements.  But I do not think that they will solve this use case
either, if I understood well.

To me, to solve this use case, a natural solution would be the
possibility to prepend a directory to the list of directories searched
for htmlxref.cnf, such that all the manuals in a project can use the
same htmlxref.cnf to override or add to the default htmlxref.cnf.
However, this is not possible for now.  For other directory lists, we
have this possibility, with -I (and we even have -P) for @include and
images and for init files there is --conf-dir.

htmlxref.cnf is searched for in a list of directories that I called
@language_config_dirs in texi2any, with the idea that this list of
directory could be (at least partly) implementation independent.  For
example, if texi2html was still developped, it could use the same search
path for htmlxref.cnf files.  For now, this @language_config_dirs list
is used for two purposes:
1) to set some paths in the default directories list used for init files,
  with init subdirectory prepended.  This corresponds to the path 6 to 9
  in 
https://www.gnu.org/software/texinfo/manual/texi2any_api/html_node/Loading-Init-Files.html
2) for htmlxref files

We could make this list of directories a customization option, like we
currently do with INCLUDE_DIRECTORIES, which is influenced by -P and -I,
for example named TEXINFO_LANGUAGE_DIRECTORIES, and add a command line
option to prepend to this list?

-- 
Pat