On Wed, Sep 23, 2026 at 11:18:34AM +0200, Patrice Dumas wrote:
> Hello,
>
> I found out this with the emacs manuals, but it is more general.
> When there is both -o some/dir/ option to texi2any and a @setfilename
> with leading directories, like
> @setfilename ../../info/emacs-xtra.info
> texi2any uses both directories unless output is split HTML. So the final
> output file ends up being (for Info, HTML not split, DocBook):
>
> some/dir/../../info/emacs-xtra.XXX
>
> I think that ignoring the directory from @setfilename when the -o
> argument is determined to be a directory would be better, both more
> useful, simpler and more consistent with -o with a file name as
> argument.
I was unaware of what -o did with a directory argument when the output
was not a directory (i.e. split HTML output).
I question whether this behaviour is useful:
If FILE is a directory or ends with a ‘/’ the usual rules are used
to determine the output file name (namely, use ‘@setfilename’ or
the input file name) but the files are written to the FILE
directory. For example, ‘texi2any -o bar/ foo.texi’, with or
without ‘--no-split’, will write ‘bar/foo.info’, and possibly other
files, under ‘bar/’.
It seems that -o has two different modes, which would be easily confused
by users. The one which is the obvious mode is to give the name of the
output file, or if the output is a directory, to give the name of the output
directory. The other mode is to give the directory location if
the output is a file. (The rules for EPUB are different again and specific
to EPUB.)
Based on the description in the manual, the same invocation of texi2any
can switch from one mode to another based on what files exist in the
file system. For example:
texi2any foo.texi -o foo.info
This should output the file foo.info. But if foo.info already exists and
is a directory, the output file is placed inside the directory foo.info
instead. If the user creates such a directory by mistake they may
unintentionally produce their output file with texi2any in the wrong place.
Likewise if they want to place the output file inside that directory but
the directory doesn't exist, then the output file will not be in the user's
intended location.
I'd suggest making it an error if the output should be a single file and the
argument of -o exists and is a directory. (I'm not sure what -o would do
with split Info output, but presumably the most obvious behaviour would be
to use the argument as the stem to which "-1", "-2" suffixes etc. are
be added.)
I don't feel this would take away from the flexibility of the program any,
as the user can easily specify the base file name as part of the -o argument:
e.g. "texi2any -o dir/base".
> We should make sure that this does not break the emacs manual, but I
> think that it should not, as this use of @setfilename probably predates
> having -o recognize directories, which, I believe, started with Texinfo
> 5.0. Therefore I doubt that the emacs build system also uses -o DIR
> (except for split HTML). I had a look at emacs sources, and I found
> only non-split output with -o output_file being used that should be ok.
> It is very likely that there are other places where the emacs manuals
> are built, though, as the HTML manual linked to from the main emacs page
> is split.
>
> In the manuals tested that where downloaded in early 2025, mainly from
> https://www.gnu.org/manual/manual.html, emacs is the only project that
> uses leading paths in @setfilename. I did not manage to get all the
> manuals in thoses tests, including for GNU projects that have Texinfo
> manuals (lilypond, maxima, gnupg, octave...) and there aren't any
> non-GNU manual, so we still should be cautious and document any change.
If the current behaviour is broken or harmful and isn't much used, then
it would be better to change it now to reduce the chance that somebody
starts relying on it in the future.
> As a side note, having an (unused) @setfilename consistent with the output
> directory for emacs manuals is told in a comment in doc/emacs/Makefile.in:
> ## Where the output files go.
> ## Note that the setfilename command in the .texi files assumes this.
> I would still suggest using a simpler @setfilename, like
> @setfilename emacs-xtra.info
> in the emacs manuals, mainly for clarity.
Sorry, I can't follow what you are proposing here. What makes the @setfilename
unused, for example?
> A consequence would be that
> doing
> makeinfo emacs-xtra.texi
> would put the info file in the texinfo manuals directory and not in the
> ../../info directory, but I think that it would nevertheless be more
> expected.
>
> --
> Pat
>
