On Sun, Oct 11, 2026 at 07:33:26PM +0200, Patrice Dumas wrote:
> Hello,
>
> The ffmpeg manual does not use @node, uses @anchor for cross-references
> and has a lot of duplicate section names, all that on purpose.
>
> The automatic nodes addition is not good, all the sections get a [+X+]
> prependend, which leads to ugly hrefs. There are no warnings.
>
> With AUTO_SECTION_NODE=0, the output is as before, however, there are
> many warnings, more than 1000, like:
>
> doc/decoders.texi:32: warning: @subsection `Options' already added target
> doc/ffmpeg.texi:772: warning: added for @chapter
> doc/decoders.texi:55: warning: @subsection `Options' already added target
> doc/ffmpeg.texi:772: warning: added for @chapter
> ....
>
> We should give the possibility to either not add shadow anchors, or
> remove the warnings for duplicate shadow anchors.
Recommending the authors of this manual to use AUTO_SECTION_NODE=0 is
the best option in my opinion.
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).
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:
\input texinfo
@node Top
@top Top
@xref{Options}.
@chapter Options
PPPPPPP.
@chapter Options
QQQQQQQQQ.
@bye
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.
(I appreciate this may take some work to do to record that the added
targets were added as "shadow targets" so this can be checked when
such an attempt is made.)
