On Sun, Oct 11, 2026 at 08:05:18PM +0100, Gavin Smith wrote: > ffmpeg's use of Texinfo is idiosyncratic, as far as I remember. I don't > know exactly how they use Texinfo: on their website, they have single-page > HTML documentation generated from Texinfo. I also remember they were one > of the few projects making use of the Perl customization API of texi2any. > If they aren't using Info or split HTML output the ugly node names may > not be a major problem (although there may be other implications for > adding nodes such as changes to navigation headers).
Indeed, they do not generate Info, each manual is a kind of article/book/report, and they generate a man page through POD for each of the manual. It is not like the typical GNU documentation, which tend to integrate the subjects and commands together, but I also think that it is well within the model of Texinfo. > When AUTO_SECTION_NODE=0, we don't need to give warnings unless the > shadow targets are referenced. That should resolve this problem with > processing this manual. That's how I implemented it in texinfo.tex, > because of this possible problem. In this input, it is the @xref that > gives the warning, rather than the @chapter: This is also like that in texi2any if AUTO_SECTION_NODE=1: $ ./texi2any.pl ambiguous_ref_to_section_without_node.texi ambiguous_ref_to_section_without_node.texi:14: @xref reference to nonexistent node `Options' For formats for which AUTO_SECTION_NODE=1 means that nodes are added, there would be no way to have warnings about duplicate "shadow" targets, like: $ ./texi2any.pl -c AUTO_SECTION_NODE=0 ambiguous_ref_to_section_without_node.texi ambiguous_ref_to_section_without_node.texi:10: warning: @chapter `Options' already added target ambiguous_ref_to_section_without_node.texi:6: warning: added for @chapter Therefore another customization variable could be needed. Another possibility would be to use a string instead a boolean for AUTO_SECTION_NODE, with 3 possibilities * AUTO_SECTION_NODE=add: add nodes in Info and HTML only if not ambiguous (otherwise add nodes with postpended [+1+] and [+2+]), and for other formats add targets only if not ambiguous. The default. * AUTO_SECTION_NODE=warn: always add a target and warn if there are duplicate * AUTO_SECTION_NODE=silent: always add a target if there are duplicate and do not warn > If we add an option to control the warnings for duplicates, we could > still warn (or error) if an attempt is made to reference one of them. If I understand well, I do not think that it is needed, to me there should only be a warning or error if there is no target added. -- Pat
