Re: emacs-29 889a550ca08: ; Fix Texinfo warnings

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: arash@gnu.org, emacs-devel@gnu.org
> Date: Mon, 23 Oct 2023 13:24:21 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> What we are getting in org.texi is
> >> org.texi:15975: warning: @anchor should not appear on @item line
> >> 
> >> May someone familiar with Texinfo explain what is the problem?
> >
> > What is unclear in the warning's text?  I think it speaks for itself.
> 
> According to Texinfo manual:
> 
>     An anchor is a position in your document, labelled so that
>     cross-references can refer to it, just as they can to nodes. You
>     create an anchor with the @anchor command, and give the label as a
>     normal brace-delimited argument. For example:
>     
>     This marks the @anchor{x-spot}spot.
>     ...
>     @xref{x-spot,,the spot}.
> 
>     ...
> 
>     It is best to put @anchor commands just before the position you wish
>     to refer to; that way, the reader’s eye is led on to the correct
>     text when they jump to the anchor. You can put the @anchor command
>     on a line by itself if that helps readability of the source.
>     Whitespace (including newlines) is ignored after @anchor.
> 
> I do not see any clear reason why one may not put @anchor at the same
> line with @item.

I don't understand what you are saying here.  Are you saying that the
warning is bogus and should not be emitted in this case?  Or that the
Texinfo manual should explain better why @anchor should not appear on
an @item line?  If so, please take this up with the Texinfo
maintainers, and ask them either to change the code or to fix the
manual.

Me, I would simply move the @anchor line before the @item, where it
belongs.  It will shut up the warning and also make the manual cleaner
from the Texinfo POV.  (Thet's what I did in other cases where this
warning was emitted by makeinfo 7.1.)  But that's me.

> In Org mode, we add @anchor at the same place where the corresponding
> Org markup (<<<radio target>>>) is placed.

That's a mistake, IMO.  @anchor is basically the same as @node.

> I guess we might try to put @anchor on a separate line just for the sake
> of avoiding this warning, but I am not confident that it is always safe
> and won't break Texinfo markup.

It won't, since that's how @anchor is supposed to be used.