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

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

[Arash Esbati]

Eli Zaretskii <eliz@gnu.org> writes:

> branch: emacs-29
> commit 889a550ca0847679bc96547c14622e239eb93f91
> Author: Eli Zaretskii <eliz@gnu.org>
> Commit: Eli Zaretskii <eliz@gnu.org>
>
>     ; Fix Texinfo warnings
>     
>     * doc/misc/wisent.texi (Grammar format):
>     * doc/misc/efaq.texi (Not writing files to the current directory):
>     * doc/misc/ede.texi:
>     * doc/lispref/errors.texi (Standard Errors): Fix warnings emitted
>     by makeinfo 7.1.

Thanks for fixing them.  I get other warnings as well (cc-mode.texi,
octave-mode.texi, org.texi, tramp.texi which will be adressed by the
package maintainers, I guess) but I think this one is in your hands:

  emacs-lisp-intro.texi:15802: warning: @noindent is useless inside of a
  paragraph

which is about this piece of input:

  @c colon in printed section title causes problem in Info cross reference
  This way, we avoid an error.
  @iftex
  @noindent
  (For information about @code{and}, see
  @ref{kill-new function, , The @code{kill-new} function}.)
  @end iftex
  @ifinfo
  @noindent
  (@xref{kill-new function, , The @code{kill-new} function}, for
  information about @code{and}.)
  @end ifinfo

This is with Emacs from master (ae33788410) and makeinfo 7.1.

Best, Arash

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

[Eli Zaretskii]

> From: Arash Esbati <arash@gnu.org>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Sun, 22 Oct 2023 12:30:43 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > branch: emacs-29
> > commit 889a550ca0847679bc96547c14622e239eb93f91
> > Author: Eli Zaretskii <eliz@gnu.org>
> > Commit: Eli Zaretskii <eliz@gnu.org>
> >
> >     ; Fix Texinfo warnings
> >     
> >     * doc/misc/wisent.texi (Grammar format):
> >     * doc/misc/efaq.texi (Not writing files to the current directory):
> >     * doc/misc/ede.texi:
> >     * doc/lispref/errors.texi (Standard Errors): Fix warnings emitted
> >     by makeinfo 7.1.
> 
> Thanks for fixing them.  I get other warnings as well (cc-mode.texi,
> octave-mode.texi, org.texi, tramp.texi which will be adressed by the
> package maintainers, I guess) but I think this one is in your hands:

I fixed octave-mode.texi as well, just didn't mention it in the log
message.  The rest are maintained outside Emacs, so the respective
maintainers will have to pick up the gauntlet (when they upgrade
Texinfo).

>   emacs-lisp-intro.texi:15802: warning: @noindent is useless inside of a
>   paragraph
> 
> which is about this piece of input:
> 
>   @c colon in printed section title causes problem in Info cross reference
>   This way, we avoid an error.
>   @iftex
>   @noindent
>   (For information about @code{and}, see
>   @ref{kill-new function, , The @code{kill-new} function}.)
>   @end iftex
>   @ifinfo
>   @noindent
>   (@xref{kill-new function, , The @code{kill-new} function}, for
>   information about @code{and}.)
>   @end ifinfo

Don't worry about this.  (I for now downgraded back to Texinfo 7.0.3
because 7.1 is abysmally slow on my system.)

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

[Arash Esbati]

Eli Zaretskii <eliz@gnu.org> writes:

> I fixed octave-mode.texi as well, just didn't mention it in the log
> message.

Ah, sorry, I missed that.

> Don't worry about this.  (I for now downgraded back to Texinfo 7.0.3
> because 7.1 is abysmally slow on my system.)

Last time I checked how long it takes to build Emacs on my system, it
was something more than 3 minutes; now it takes more than 4 minutes.  I
can't say if it's due to new Texinfo though; I didn't roll back to test.
This is on a MacBook Air M2.

Best, Arash

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

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Thanks for fixing them.  I get other warnings as well (cc-mode.texi,
>> octave-mode.texi, org.texi, tramp.texi which will be adressed by the
>> package maintainers, I guess) but I think this one is in your hands:
>
> I fixed octave-mode.texi as well, just didn't mention it in the log
> message.  The rest are maintained outside Emacs, so the respective
> maintainers will have to pick up the gauntlet (when they upgrade
> Texinfo).

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?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: Arash Esbati <arash@gnu.org>, emacs-devel@gnu.org
> Date: Mon, 23 Oct 2023 12:35:21 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I fixed octave-mode.texi as well, just didn't mention it in the log
> > message.  The rest are maintained outside Emacs, so the respective
> > maintainers will have to pick up the gauntlet (when they upgrade
> > Texinfo).
> 
> 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.

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

[Ihor Radchenko]

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.

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

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.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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.

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

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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.

I was hoping that you know and can quickly explain the reason.

> 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.

Moving _before_ @item is not an option. For example, consider

- This is a long list item, and we want to put an anchor <<<here>>>, in the middle of the line.

The anchor does not belong to item itself, it is linking to a specific
place in the text.

>> 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.

AFAIU, it is not. See the above example.

>> 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.

Does it mean that something like

@item This is
@anchor{my-anchor}
a single paragraph inside item.

is always safe?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: arash@gnu.org, emacs-devel@gnu.org
> Date: Tue, 24 Oct 2023 09:11:08 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> 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.
> 
> I was hoping that you know and can quickly explain the reason.

I don't.  In any case, you will be much better off talking to the
Texinfo developers about these new warnings.

> > 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.
> 
> Moving _before_ @item is not an option. For example, consider
> 
> - This is a long list item, and we want to put an anchor <<<here>>>, in the middle of the line.
> 
> The anchor does not belong to item itself, it is linking to a specific
> place in the text.

IME, Texinfo doesn't support this usage.

> >> 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.
> 
> AFAIU, it is not. See the above example.

Well, your example doesn't work in all cases, where's my usage does.

But again, please talk to the Texinfo developers about this.

> >> 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.
> 
> Does it mean that something like
> 
> @item This is
> @anchor{my-anchor}
> a single paragraph inside item.
> 
> is always safe?

I don't know, and IMO @anchor should be before the @item, not after
it.

@anchor on @item line (was: emacs-29 889a550ca08: ; Fix Texinfo warnings)

[Ihor Radchenko]

Hi,

This is a question regarding a recent change in Texinfo.

AFAIU, @anchor in Texinfo can be used to refer to arbitrary place in the
document: https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#g_t_0040anchor
In some scenarios, this "arbitrary place" can be located _inside_ an
item.

However, there is a warning being produced when @anchor is found on the
same line with an item:

org.texi:15975: warning: @anchor should not appear on @item line

The problematic .texi source is

    @table @asis
    @item @samp{OrgOdtStyles.xml} @anchor{x-orgodtstyles-xml}
    This file contributes to the @samp{styles.xml} file of the final ODT
    document.  This file gets modified for the following purposes:

Here, the @anchor is referring to OrgOdtStyles.xml file and is not
necessarily linked to the @item itself.

May someone please explain the correct usage of @anchor in the above
example and why the warning is being thrown?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: @anchor on @item line (was: emacs-29 889a550ca08: ; Fix Texinfo warnings)

[Gavin Smith]

On Sun, Nov 05, 2023 at 11:30:42AM +0000, Ihor Radchenko wrote:
> However, there is a warning being produced when @anchor is found on the
> same line with an item:
> 
> org.texi:15975: warning: @anchor should not appear on @item line
> 
> The problematic .texi source is
> 
>     @table @asis
>     @item @samp{OrgOdtStyles.xml} @anchor{x-orgodtstyles-xml}
>     This file contributes to the @samp{styles.xml} file of the final ODT
>     document.  This file gets modified for the following purposes:
> 
> Here, the @anchor is referring to OrgOdtStyles.xml file and is not
> necessarily linked to the @item itself.
> 
> May someone please explain the correct usage of @anchor in the above
> example and why the warning is being thrown?

I don't think there's really much wrong with it.  We added more warnings
for nested commands, trying to define which commands should occur in
certain contexts.  We have given the @item command a class of
"contain_basic_inline", which excludes anchor commands, as well as
the cross-reference commands.

I don't remember, or never knew to start with, what the justification
was for giving @item this class.  It was the case for Texinfo 7.0 too,
as seen in tp/Texinfo/XS/parsetexi/command_data.txt in that release:

item_LINE               line,close_paragraph,contain_simple_text    LINE_line   

("contain_simple_text" has now been renamed "contain_basic_inline").

However, for whatever reason, this use of @anchor on an @item line
didn't trigger the warning in earlier releases.

It would be easy, I expect, to remove this warning:

diff --git a/tp/Texinfo/command_data.txt b/tp/Texinfo/command_data.txt
index 7d07b8bd54..df63c6ccd7 100644
--- a/tp/Texinfo/command_data.txt
+++ b/tp/Texinfo/command_data.txt
@@ -254,8 +254,8 @@ printindex              line,formattable_line,close_paragraph,global,contain_pla
 listoffloats            line,formattable_line,close_paragraph,global,contain_basic_inline   LINE_line
 exdent                  line,formatted_line,close_paragraph            LINE_line
 # or nobrace skipspace, depending on the context
-item_LINE               line,formatted_line,close_paragraph,contain_basic_inline    LINE_line
-itemx                   line,formatted_line,close_paragraph,contain_basic_inline    LINE_line
+item_LINE               line,formatted_line,close_paragraph    LINE_line
+itemx                   line,formatted_line,close_paragraph    LINE_line
 nodedescription         line,close_paragraph                               LINE_line
 # in index entries
 subentry                line,in_index,contain_basic_inline          LINE_line
0$ 

However, I would like to wait to see if anybody else has any comments first.

Re: @anchor on @item line (was: emacs-29 889a550ca08: ; Fix Texinfo warnings)

[Patrice Dumas]

On Mon, Nov 06, 2023 at 07:29:50PM +0000, Gavin Smith wrote:
> On Sun, Nov 05, 2023 at 11:30:42AM +0000, Ihor Radchenko wrote:
> > May someone please explain the correct usage of @anchor in the above
> > example and why the warning is being thrown?
> 
> I don't think there's really much wrong with it.  We added more warnings
> for nested commands, trying to define which commands should occur in
> certain contexts.  We have given the @item command a class of
> "contain_basic_inline", which excludes anchor commands, as well as
> the cross-reference commands.
> 
> I don't remember, or never knew to start with, what the justification
> was for giving @item this class.

I agree that accepting @anchor and @*ref on @item in @*table line would
be ok.

> However, for whatever reason, this use of @anchor on an @item line
> didn't trigger the warning in earlier releases.

My guess is that the code has been fixed to really use the 'flags' of
item_LINE and not the flags of @item that appears in @itemize,
@enumerate and @multitable which alreay has no restrictions in its content.

> It would be easy, I expect, to remove this warning:
> 
> diff --git a/tp/Texinfo/command_data.txt b/tp/Texinfo/command_data.txt
> index 7d07b8bd54..df63c6ccd7 100644
> --- a/tp/Texinfo/command_data.txt
> +++ b/tp/Texinfo/command_data.txt
> @@ -254,8 +254,8 @@ printindex              line,formattable_line,close_paragraph,global,contain_pla
>  listoffloats            line,formattable_line,close_paragraph,global,contain_basic_inline   LINE_line
>  exdent                  line,formatted_line,close_paragraph            LINE_line
>  # or nobrace skipspace, depending on the context
> -item_LINE               line,formatted_line,close_paragraph,contain_basic_inline    LINE_line
> -itemx                   line,formatted_line,close_paragraph,contain_basic_inline    LINE_line
> +item_LINE               line,formatted_line,close_paragraph    LINE_line
> +itemx                   line,formatted_line,close_paragraph    LINE_line
>  nodedescription         line,close_paragraph                               LINE_line
>  # in index entries
>  subentry                line,in_index,contain_basic_inline          LINE_line
> 0$ 
> 
> However, I would like to wait to see if anybody else has any comments first.

Looks good to me.

-- 
Pat

Re: @anchor on @item line

[Gavin Smith]

On Tue, Nov 07, 2023 at 11:29:24AM +0100, Patrice Dumas wrote:
> On Mon, Nov 06, 2023 at 07:29:50PM +0000, Gavin Smith wrote:
> > On Sun, Nov 05, 2023 at 11:30:42AM +0000, Ihor Radchenko wrote:
> > > May someone please explain the correct usage of @anchor in the above
> > > example and why the warning is being thrown?
> > 
> > I don't think there's really much wrong with it.  We added more warnings
> > for nested commands, trying to define which commands should occur in
> > certain contexts.  We have given the @item command a class of
> > "contain_basic_inline", which excludes anchor commands, as well as
> > the cross-reference commands.
> > 
> > I don't remember, or never knew to start with, what the justification
> > was for giving @item this class.
> 
> I agree that accepting @anchor and @*ref on @item in @*table line would
> be ok.

There is actually a problem with @ftable and @vtable.  If you put an
@anchor on an @item line there, then it is the text of an index entry,
which is a real problem.


@node Top

@ftable @asis
@item AA @anchor{xy}
one

@item BB
two

@end ftable

@node Index

@printindex fn

@bye 

This gives the warnings:

test.texi:4: warning: @anchor should not appear on @item line
test.texi:4: @anchor output more than once: xy

The anchor is processed a second time when the index is output.  Adding
further @printindex commands results in the same error being output again.

A warning is also given for @anchor in other index commands, like @cindex,
so this is consistent.

When I have time, I will look at how the warning could be given for
@ftable and @vtable only.

Re: @anchor on @item line

[Gavin Smith]

On Sun, Nov 12, 2023 at 07:23:41PM +0000, Gavin Smith wrote:
> There is actually a problem with @ftable and @vtable.  If you put an
> @anchor on an @item line there, then it is the text of an index entry,
> which is a real problem.

Further to this, if @anchor should be allowed inside @item as long as the
@item is not creaing an index entry, it should also be allowed inside
@defline and @deftypeline (these are new commands), as these do not create
index entries.

I have made a commit today to allow @anchor in @item and also these
other commands, and will also add this change to the release branch so
that if there is ever a 7.1.1 release, this fix will be included.

We may still not want to allow other "non-basic inline" commands
(e.g. @xref) inside @item/@defline/@deftypeline as inappropriate for
one reason or another, but at the moment it seems the easiest way forward
is to allow these.

@anchor used inside @item inside @ftable/@vtable still leads to a warning
if the index is output, just the warning is slightly obscure.

I thought of allowing @anchor as basic inline content, but we would have
to come up with some other mechanism for detecting and warning about
@anchor inside index entries, and there are too many other commands where
we truly should not have @anchors (e.g. @node names, as cross-references
to those nodes would have to have the @anchor in them).  @anchor should
not appear in any context where it does not correspond to a single
position in the output file.

Re: @anchor on @item line

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Tue, 14 Nov 2023 21:58:01 +0000
> 
> @anchor should not appear in any context where it does not
> correspond to a single position in the output file.

Good luck with documenting this restriction in a way that Texinfo
users can use in practice without a very deep understanding how the
converters work.

MO is that @anchor should always be on a line of its own.  I suggest
to say that in the Texinfo manual, and that using it inline is
discouraged.  There are no good reasons for such inline use in Texinfo
documents, IME.