On Sun, Aug 25, 2024 at 10:54:31AM +0300, Eli Zaretskii wrote:
> > It should be possible to use an additional project-specific htmlxref.cnf
> > file that would take priority. See
> > <https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html>.
>
> This section of the Texinfo manual seems to imply that if a project
> has its own htmlxref.cnf file, that file must be present in every
> directory where HTML manuals are generated. IOW, there's no way of
> sharing the same file between different subdirectories of the same
> project tree. Is that conclusion correct?
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".
* 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.)
For example, if both "manual.texi" and "htmxref.cnf" are in "..", then
texi2any ../manual.texi --html --no-split
doesn't read htmlxref.cnf, whereas
texi2any ../manual.texi --html --no-split -c HTMLXREF_FILE=../htmlxref.cnf
does.
Unfortunately, the file specified by HTMLXREF_FILE is the *only* htmlxref.cnf
file that is read, so this variable should probably not be used. If
../manual.texi has
> @xref{,,,foo, The Foo Manual}.
>
> @xref{,,,bash, The Bash Manual}.
and ../htmlxref.cnf has
> foo node http://foo.example.com/
then the first of the commands above produces
<p>See <cite class="cite"><a data-manual="foo" href="foo.html#Top">The Foo
Manual</a></cite>.
</p>
<p>See <cite class="cite"><a data-manual="bash"
href="https://www.gnu.org/software/bash/manual/bash.html#Top";>The Bash
Manual</a></cite>.
</p>
with the location of the online bash manual being taken from system-installed
htmlxref.cnf.
<p>See <cite class="cite"><a data-manual="foo"
href="http://foo.example.com/index.html";>The Foo Manual</a></cite>.
</p>
<p>See <cite class="cite"><a data-manual="bash" href="bash.html#Top">The Bash
Manual</a></cite>.
</p>
The URL is used for 'foo' but 'bash' reverts to the default output.
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.
> 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.
> This is all quite annoying, to tell the truth. The only practical
> alternative seems to be to generate the HTML manuals using the
> system-wide htmlxref.cnf file, and then use our own script to edit all
> the instances of "MANUAL_html/" to say "MANUAL/" instead, which
> basically means we don't use any of the facilities provided by Texinfo
> for this purpose. Or am I missing something?
I don't know why you can't update the system-wide htmlxref.cnf file. I
imagine there can't be that many people building and uploading the
Emacs web manuals.
> That's a tough requirement when using a VCS to host the manuals, as
> the entire GNU project does. CVS doesn't support file renaming, so we
> lose all the history when renaming a directory. So renaming the
> existing directories is not an option for us.
I wasn't suggesting you renamed the existing directories. It appears
you are not uploading the directories with the "_html" suffix anyway
so there is no problem here.
>
> > What has caused the problem you are reporting is not actually the
> > output directory having the "_html" suffix, but this suffix appearing
> > in intermanual links.
>
> AFAIU, in order to work, the links and the directory structure must
> use the same conventions, otherwise there are significant
> complications (like redirection files etc.). So we must make sure the
> links use MANUAL, not MANUAL_html. Using the --output command-line
> option (which we do) does not solve this problem, as it only affects
> where the output files are being written, not the cross-reference
> links.
This was a suggestion for a change to texi2any but it could be confusing
so we probably won't do it.
