On Thu, Feb 20, 2025 at 12:07:44AM +0100, Sebastian Meyer wrote:
> For a collection of Texinfo manuals that reference each other but no other
> manuals, `-c HTMLXREF_MODE=none` could be used for `texi2any --html` to
> force links in the generated HTML manuals to point to the local---thus
> same-version---HTML files rather than to a (canonical) website from a
> (built-in) htmlxref.cnf (that possibly serves a different version of the
> manuals).
>
> Using this approach, Texinfo >= 7.2 now shows warnings of the form
>
> warning: no HTML cross-references entry found for `...'
>
> which I can mute by an additional `-c CHECK_HTMLXREF=0`.
> Should that be the default for `HTMLXREF_MODE=none` ?
Yes, I think that would make sense to make this the default. Thanks for
the suggestion.
> Now for --epub output, cross-references cannot be to local files so do need
> URLs from a htmlxref.cnf. Is there a recommended approach for generating
> both HTML and EPUB versions of a collection of manuals, where the former
> points to local files and the latter uses full URLs? Is the approach
> described above (using the customization variables for the --html case)
> reasonable and stable?
I'm not aware of a recommended approach for this, but I assume you
would run texi2any twice, each time with different flags and options.
> Obviously HTMLXREF_MODE=none wouldn't work if the manuals also contained
> truly external cross-references (e.g., to other GNU manuals). How to proceed
> in that case? Create and switch (as needed) two htmlxref.cnf files for the
> within-project manuals such as
>
> manualA mono ${BASEURL}/manualA.html
> manualB mono ${BASEURL}/manualB.html
>
> and set `BASEURL = .` for the --html run or is there a more elegant
> solution?
>
> Thanks!
Well it seems that you would need to use two different htmlxref.cnf
files for the two runs.
It is an interesting question how to specify in htmlxref.cnf that a
local manual should be used. Your approach of using a URL beginning with
"." appears to work and I don't know of a better one.
Of course, it is possible to use HTMLXREF_MODE=file (the default) along
with CHECK_HTMLXREF=0. (Some of these variables may change in
the next release where htmlxref.d directories can be used
instead.) If you didn't provide your own htmlxref entries for "manualA"
and "manualB" then defaults would be used instead, which may or may
not be appropriate.
The downside would be that you would not get other warnings
for missing htmlxref data, and that there is a small chance that your
manuals could have incorrect definitions in installed locations.
Incidentally, I could not find a way to completely nullify an
htmlxref entry. For example, if I have "@xref{Top,,,bash}" in a
manual, then by default this is output as 'See <a data-manual="bash"
href="https://www.gnu.org/software/bash/manual/bash.html#Top";>(bash)Top</a>',
using the system htmlxref.cnf. I can override this by adding an entry
"bash mono ./bash.html" to a local 'htmlxref.cnf' file, yielding
'See <a data-manual="bash" href="./bash.html#Top">(bash)Top</a>' instead.
However, there is no way to completely remove the entry, so that
a warning like
test.texi:10: warning: no htmlxref.cnf entry found for `bash'
would be printed, and the link output as the default
"See <a data-manual="bash" href="bash.html#Top">(bash)Top</a>"
or
"See <a data-manual="bash" href="../bash_html/index.html#Top">(bash)Top".
This may not matter very much as the user could easily provide these
locations in htmlxref.cnf if they wanted the default output:
bash mono bash.html
bash node ../bash_html
There would be no point to having a warning in that case as these locations
have been explicitly requested by the user.
"
