On Thu, Sep 24, 2026 at 07:52:49AM +0300, Eli Zaretskii wrote: > > From: Gavin Smith <[email protected]> > > Date: Wed, 23 Sep 2026 18:24:18 +0100 > > > > 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. > > The same happens with 'cp', no? So why do you think this logic is so > outlandish or confusing?
It's not the main purpose of the -o option and seems like an unnecessary feature. In the original proposal from Patrice, he was suggesting possible behaviour for a combination of @setfilename and -o, where the argument to -o was a directory. My point was that the use of this directory argument was itself a bad idea (arguably). I don't see the point of changing the behaviour of the program for the benefit of a questionable feature like this. I don't see why we'd be encouraging people to use a directory as the argument to -o for the location of the output file. If we were going to make (incompatible) changes, I think that it should be in the direction of making the -o option simpler and more consistent, not in the direction of deciding what obscure combinations of dubious usages should mean. Another problem with -o DIR, other than being affected about whether the output is a directory or not, is that the behaviour depends on the output format. This could have very bad results if the user is trying out different output formats with an -o DIR option: $ texi2any --info test.texi -o my-docs If my-docs is a directory, this should output test.info or test.info-* in the my-docs directory. $ texi2any --latex test.texi -o my-docs This adds test.tex to my-docs. $ texi2any --docbook test.texi -o my-docs Now my-docs also contains test.xml. $ texi2any --epub3 test.texi -o my-docs This doesn't seem to work: test.epub is created in the current directory. (The manual discusses EPUB as a special case - I'm guessing files were placed in my-docs but then deleted before texi2any finished running.) Now let's try HTML: $ texi2any --html test.texi -o my-docs This creates a mess: the my-docs directory still contains all of its previous contents, but contains all the files from the split HTML output as well. This suggests that split HTML output doesn't remove stale files from the output directory, either: the directory listing can end up looking like this: -rw-rw-r-- 1 g g 771 Sep 24 17:16 A-Chapter.html -rw-rw-r-- 1 g g 771 Sep 24 17:28 B-Chapter.html -rw-rw-r-- 1 g g 1.2k Sep 24 17:28 index.html -rw-rw-r-- 1 g g 712 Sep 24 17:28 Test.html - where "A chapter" was the name of a removed node from a previous run of texi2any. > > 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. > > That's a backward-incompatible change, so my recommendation would be > not to do it, as it runs the risk of breaking someone's setup. At the least we should make it a warning. And I think we should seriously consider whether the output directory should be wiped for split HTML output. Another option could be warning about stale files in the output directory for split HTML output. > > > 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. > > I respectfully disagree. IME, what is "broken" in your eyes might be > a useful feature in someone else's. Backward-incompatible changes > should only be done when the current behavior is utterly broken, IMO. There is a trade-off to be made and as we don't have evidence of anyone using or relying on the current behaviour of the -o option, it moves the trade-off away from maintaining the status quo.
