Re: Texinfo 7.0 changed the name of HTML output directory

[Gavin Smith]

On Sun, Aug 25, 2024 at 01:29:22PM +0200, Patrice Dumas wrote:
> > 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

I see, only the first file actually existed so that is the only
one which was read.

> 
> > 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 think it makes sense to treat relative paths in a similar way to
absolute paths.  The only question is whehther the path should be
relative to current working directory or the source file directory
(or possibly both).  The current behaviour is to be relative to cwd
and so that should be kept.


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

Good point.  I think we should make CHECK_HTMLXREF=1 the default for
HTML as otherwise various web manuals will have broken links that nobody
knows about (we already found a broken link for "eglot", and the link
for "smtpmail" would have been broken if a newer version of Texinfo had
been used).


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

If we implemented the XDG specification then the user could use or
append to XDG_CONFIG_DIRS, which is a colon-separated list of
directories to search.  However, I am not sure if this is an appropriate
use of this variable as this is for user- or system-specific configuration,
but not necessarily for project-specific configuration.

https://specifications.freedesktop.org/basedir-spec/latest/index.html

So I suppose we need to devise some other mechanism for this.

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

One possiblility is to use --conf-dir to look for htmlxref.cnf files as
well, although I haven't thought about this deeply.