bug#46082: (texinfo) @ref says something lisp/info.el do not respect by default

bug#46082: (texinfo) @ref says something lisp/info.el do not respect by default

[Marco Munari]

[-- Attachment #1: Type: text/plain, Size: 2187 bytes --]

Hi Kim,

I'm writing in relation to  defcustom Info-hide-note-references t  in  lisp/info.el
a9efebd0ba1 (Kim 2002-11-01 306) (defcustom Info-hide-note-references t

because it's a bad default to proper info documentation

as said in  (texinfo) @ref  documentation

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040ref.html
   ,---------------------------------------------------------------------------
   | 6.6 @ref
   | @ref is nearly the same as @xref except that it does not generate a ‘See’
   | in the printed output, just the reference itself.
   | This makes it useful as the last part of a sentence.
   |
   | For example,
   | 
   | For more information, @pxref{This}, and @ref{That}.
   | produces in Info:
   | 
(*)| For more information, *note This::, and *note That::.
   | and in printed output:
   | 
   | For more information, see Section 1.1 [This], page 1, and Section 1.2 [That], page 2.
   `---------------------------------------------------------------------------

but with current  info.el  default in emacs shows

(*)| For more information, see [This]., and see [That].


(
A part that with only two examples (texinfo) @ref it's not very clear that
there are three cases:
@ref
@xref
@pxref
)


As I intended it, the second "see" should absolutely not be present,
Info-hide-note-references is already customize-able to nil(=compliant)
or hide(my preference), but the current default of  t  is(seem to me)
not at all as designed in texinfo,

for example python info documentation was plenty of misplaced
``See`` ... ``.`` (which is the reason I looked into the origin of the
problem) and found it: @ref should have not a processing for info that
add "See" as should while processing @xref, than the pxref is to
distinguish printed rendering.

I will not insist over this trivial change,
if ever you disagree you can also ignore the request

Cheers,
Marco Munari
-- 
x(t),y(t) = th(3t-34.5)*e^[-(3t-34.5)^2]/2-4.3+e^(-1.8/t^2)/(.8*atg(t-
3)+2)(t-1.8)-.3th(5t-42.5),(1.4e^[-(3t-34.5)^2]+1-sgn[|t-8.5|-.5]*1.5*
|sin(pi*t)|^[2e^(-(t-11.5)^2)+.5+e^(-(.6t-3.3)^2)])/(.5+t)+1  ; 0<t<14

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Adjust default to respect (texinfo) @ref documentation (as long as @xref was not used in the interactive mode who write the documentation correctly did not thought to have a "See" added in front of the node) --]
[-- Type: text/x-patch, Size: 784 bytes --]

diff --git a/lisp/info.el b/lisp/info.el
index 13c57bdcd1..dc663bf761 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -1,6 +1,6 @@
 ;; info.el --- Info package for Emacs  -*- lexical-binding:t -*-
 
-;; Copyright (C) 1985-1986, 1992-2020 Free Software Foundation, Inc.
+;; Copyright (C) 1985-1986, 1992-2021 Free Software Foundation, Inc.
 
 ;; Maintainer: emacs-devel@gnu.org
 ;; Keywords: help
@@ -303,7 +303,7 @@ Info-scroll-prefer-subnodes
   :type 'boolean
   :group 'info)
 
-(defcustom Info-hide-note-references t
+(defcustom Info-hide-note-references nil
   "If non-nil, hide the tag and section reference in *note and * menu items.
 If the value is t, the default, replace \"*note\" with \"see\".
 If the value is `hide', remove \"*note\" without replacing it with anything.

bug#46082: (texinfo) @ref says something lisp/info.el do not respect by default

[Lars Ingebrigtsen]

Marco Munari <mar21+dev.emacs.bugfix@allerta.it> writes:

> for example python info documentation was plenty of misplaced
> ``See`` ... ``.`` (which is the reason I looked into the origin of the
> problem) and found it: @ref should have not a processing for info that
> add "See" as should while processing @xref, than the pxref is to
> distinguish printed rendering.

Do you have an example of how Emacs displays this Python documentation?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#46082: (texinfo) @ref says something lisp/info.el do not respect by default

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Marco Munari <mar21+dev.emacs.bugfix@allerta.it> writes:
>
>> for example python info documentation was plenty of misplaced
>> ``See`` ... ``.`` (which is the reason I looked into the origin of the
>> problem) and found it: @ref should have not a processing for info that
>> add "See" as should while processing @xref, than the pxref is to
>> distinguish printed rendering.
>
> Do you have an example of how Emacs displays this Python documentation?

More information was requested, but no response was given within a
month, so I'm closing this bug report.  If the problem still exists,
please respond to this email and we'll reopen the bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#46082: acknowledged by developer (control message for bug #46082)

[Marco Munari]

I noticed only the bug close notification now,
the mention of python info example was secondary,
the rendering difform to specification emerges precisely
with (texinfo) manual itself

Repro steps:

1. launch emacs info	C-h i
2. go to node		g (texinfo)@ref

read the rendered manual page with attention
(I described at the beginning of the initial bug report
 the problem in the line marked with (*))

python and even perl info manuals uses a lot of @ref (according
to the way texinfo does and describe its functionality)
resulting a lot of inappropriate  See  making the references surrounded
by nonsense "see ... dot(.)", but the problem emerges in the exact page
of texinfo describing how @ref should work, showing that it doesnt.

Anyway as required an example on how python manual looks,
here there is a random section (Note the "see" are simply misleading.
My fix removes the default misbehaviour for "see",
but the dot(.) after the node description remains):
========================================================================
File: python.info,  Node: Expression input,  Prev: Interactive input,  Up: Top-level components

4.9.4 Expression input
----------------------

*note eval(). is used for expression input.  It ignores leading
whitespace.  The string argument to *note eval(). must have the
following form:

     eval_input ::= expression_list NEWLINE*
========================================================================


And here is an extract of `perlfunc` info manual:


========================================================================
File: perlfunc.info,  Node: Top,  Up: (dir)

1 NAME
******

perlfunc - Perl builtin functions

2 DESCRIPTION
*************

...

2.1 Perl Functions by Category
==============================

Here are Perl’s functions (including things that look like functions,
like some keywords and named operators) arranged by category.  Some
functions appear in more than one place.  Any warnings, including those
produced by keywords, are described in *note (perldiag):: and *note
(warnings)::.

Functions for SCALARs or strings

     *note ‘chomp’, *note ‘chop’, *note
     ‘chr’, *note ‘crypt’ *note ‘fc’, *note ‘hex’, *note ‘index’,
     *note ‘lc’, *note ‘lcfirst’, *note ‘length’, *note ‘oct’, *note
     ‘ord’, *note ‘pack’, *note ‘q//’, *note ‘qq//’, *note ‘reverse’,
     *note ‘rindex’, *note ‘sprintf’, *note ‘substr’, *note ‘tr///’,
     *note ‘uc’, *note ‘ucfirst’, *note ‘y///’.

     *note ‘fc’: fc EXPR. is available only if the *note ‘"fc"’ feature:
     (feature)The 'fc' feature. is enabled or if it is prefixed with
     ‘CORE::’.  The *note ‘"fc"’ feature: (feature)The 'fc' feature. is
     enabled automatically with a ‘use v5.16’ (or higher) declaration in
     the current scope.

Regular expressions and pattern matching

     *note ‘m//’: m//, *note ‘pos’: pos SCALAR, *note ‘qr//’:
     qr/STRING/, *note ‘quotemeta’: quotemeta EXPR, *note ‘s///’: s///,
     *note ‘split’: split /PATTERN/,EXPR,LIMIT, *note ‘study’: study
     SCALAR.
...

break

     Break out of a ‘given’ block.

     *note ‘break’. is available only if the *note ‘"switch"’
     feature(feature). is enabled or if it is
     prefixed with ‘CORE::’.  The *note ‘"switch"’ feature(feature).
     . is enabled automatically with a ‘use v5.10’ (or
     higher) declaration in the current scope.
...
========================================================================

bug#46082: acknowledged by developer (control message for bug #46082)

[Eli Zaretskii]

> From: Marco Munari <mar21@allerta.it>
> Date: Mon, 01 Mar 2021 20:22:58 +0100
> 
> read the rendered manual page with attention
> (I described at the beginning of the initial bug report
>  the problem in the line marked with (*))
> 
> python and even perl info manuals uses a lot of @ref (according
> to the way texinfo does and describe its functionality)
> resulting a lot of inappropriate  See  making the references surrounded
> by nonsense "see ... dot(.)", but the problem emerges in the exact page
> of texinfo describing how @ref should work, showing that it doesnt.
> 
> Anyway as required an example on how python manual looks,
> here there is a random section (Note the "see" are simply misleading.
> My fix removes the default misbehaviour for "see",
> but the dot(.) after the node description remains):

I have difficulty understanding the problem, and thus the proposed
solution.  I think the difficulty stems from the fact that you didn't
show the Texinfo source of the Info output which you posted.  Without
that, it's hard to decide whether the problem is with Emacs, or with
Texinfo's 'makeinfo', or with the original Texinfo source as authored
by whoever wrote those manuals (which are not Emacs manuals).

So please show the Texinfo sources of these snippets.

Thanks.

bug#46082: acknowledged by developer (control message for bug #46082)

[Marco Munari]

On Mon, 01 Mar 2021 22:10:03 +0200, Eli Zaretskii <eliz@gnu.org> said:

>>From: Marco Munari <mar21@allerta.it>
>>Date: Mon, 01 Mar 2021 20:22:58 +0100
>>
>>read the rendered manual page with attention
>>(I described at the beginning of the initial bug report
>>the problem in the line marked with (*))
>>
>>python and even perl info manuals uses a lot of @ref (according
>>to the way texinfo does and describe its functionality)
>>resulting a lot of inappropriate  See  making the references surrounded
>>by nonsense "see ... dot(.)", but the problem emerges in the exact page
>>of texinfo describing how @ref should work, showing that it doesnt.
>>
>>Anyway as required an example on how python manual looks,
>>here there is a random section (Note the "see" are simply misleading.
>>My fix removes the default misbehaviour for "see",
>>but the dot(.) after the node description remains):

>I have difficulty understanding the problem, and thus the proposed
>solution.  I think the difficulty stems from the fact that you didn't
>show the Texinfo source of the Info output which you posted.  Without
>that, it's hard to decide whether the problem is with Emacs, or with
>Texinfo's 'makeinfo', or with the original Texinfo source as authored
>by whoever wrote those manuals (which are not Emacs manuals).

>So please show the Texinfo sources of these snippets.

>Thanks.

I noticed that when I copy and yank from an info buffer to gnus
it keept showing what the info buffers shown, but it didn't remain
the same on sending the email, so I didn't send previously the intended
info rendering (which renders worse than what I sent out).
Instead of "*note" (sent in the previous email) info shows "see" and adds
a dot

So for example (python)Expression input is rendered with info.el
in user reading phase as:
| See eval(). is used for expression input.  It ignores leading
| whitespace.  The string argument to see eval(). must have the
| following form:

from the python.info source

| *note eval(): ca8. is used for expression input.  It ignores leading
| whitespace.  The string argument to *note eval(): ca8. must have the
| following form:

which is from the texi input from texinfo

| @ref{ca8,,eval()} is used for expression input.  It ignores leading whitespace. The
| string argument to @ref{ca8,,eval()} must have the following form:

produced in cpython git source with the command
sphinx-build -b texinfo -d build/doctrees . build/texinfo
more details in
https://www.emacswiki.org/emacs/ExternalDocumentation

to see the source of texinfo add two repro steps (3 and 4)
1. info			C-h i
2. got to node		g (texinfo)@ref
(now with the cursor in the buffer rendered by info of texinfo CWD is good)
3. open file from CWD	C-x f
4. the texinfo source	textinfo.info-1.gz
                                     (use tab, I had it here in (arch)linux)
5. search a piece	C-s is nearly the same as

and there are other source chunks for example, repored after my signature

Cheers,
MARco
-- 
x(t),y(t) = th(3t-34.5)*e^[-(3t-34.5)^2]/2-4.3+e^(-1.8/t^2)/(.8*atg(t-
3)+2)(t-1.8)-.3th(5t-42.5),(1.4e^[-(3t-34.5)^2]+1-sgn[|t-8.5|-.5]*1.5*
|sin(pi*t)|^[2e^(-(t-11.5)^2)+.5+e^(-(.6t-3.3)^2)])/(.5+t)+1  ; 0<t<14

==============================================================================
...
\x1f
File: texinfo.info,  Node: @ref,  Next: @pxref,  Prev: Referring to a Manual as a Whole,  Up: Cross References

6.6 '@ref'
==========

'@ref' is nearly the same as '@xref' except that it does not generate a
'See' in the printed output, just the reference itself.  This makes it
useful as the last part of a sentence.

For example,

     For more information, @pxref{This}, and @ref{That}.

produces in Info:

     For more information, *note This::, and *note That::.

and in printed output:

     For more information, see Section 1.1 [This], page 1, and Section
     1.2 [That], page 2.

   The '@ref' command can tempt writers to express themselves in a
manner that is suitable for a printed manual but looks awkward in the
Info format.  Bear in mind that your audience could be using both the
printed and the Info format.  For example:

     Sea surges are described in @ref{Hurricanes}.

looks ok in the printed output:

     Sea surges are described in Section 6.7 [Hurricanes], page 72.

but is awkward to read in Info, "note" being a verb:

     Sea surges are described in *note Hurricanes::.

\x1f
File: texinfo.info,  Node: @pxref,  Next: @anchor,  Prev: @ref,  Up: Cross References

...
==============================================================================

which  is output of makeinfo from somehow the following (but the info
says discursively that @ref should not gegerate a 'see', and the
makeinfo output has @ref (right as intended), emacs info.el show a "see")
(I don't see in this case necesseray the following deeper texinfo source
 describing ref from git.savannah.gnu.org/git/texinfo.git file doc/texinfo.texi):

==============================================================================
...
@node @code{@@ref}
@section @code{@@ref}

@anchor{ref}@c old name
@findex ref
@cindex Cross-references using @code{@@ref}
@cindex References using @code{@@ref}

@code{@@ref} is nearly the same as @code{@@xref} except that it does
not generate a `See' in the printed output, just the reference itself.
This makes it useful as the last part of a sentence.

@noindent For example,

@cindex Hurricanes
@example
For more information, @@pxref@{This@}, and @@ref@{That@}.
@end example

@noindent
produces in Info:

@example
For more information, *note This::, and *note That::.
@end example

@noindent
and in printed output:

@quotation
For more information, see Section 1.1 [This], page 1,
and Section 1.2 [That], page 2.
@end quotation

The @code{@@ref} command can tempt writers to express themselves in a
manner that is suitable for a printed manual but looks awkward in the
Info format.  Bear in mind that your audience could be using both the
printed and the Info format.  For example:

@cindex Sea surges
@example
Sea surges are described in @@ref@{Hurricanes@}.
@end example

@noindent
looks ok in the printed output:

@quotation
Sea surges are described in Section 6.7 [Hurricanes], page 72.
@end quotation

@noindent
but is awkward to read in Info, ``note'' being a verb:

@example
Sea surges are described in *note Hurricanes::.
@end example

...
==============================================================================
==============================================================================


==============================================================================

Then the following correct use of @ref

==============================================================================
@node perlfunc Perl Functions by Category
@section Perl Functions by Category
@cindex function

Here are Perl's functions (including things that look like
functions, like some keywords and named operators)
arranged by category.  Some functions appear in more
than one place.  Any warnings, including those produced by
keywords, are described in @ref{perldiag NAME} and @ref{,,, warnings}.

@table @asis
@item Functions for SCALARs or strings
@anchor{perlfunc Functions for SCALARs or strings}
@cindex scalar
@cindex string
@cindex character

@ref{perlfunc chomp VARIABLE, @code{chomp}, @code{chomp}}, @ref{perlfunc chop VARIABLE, @code{chop}, @code{chop}},
@ref{perlfunc chr NUMBER, @code{chr}, @code{chr}}, @ref{perlfunc crypt PLAINTEXT@comma{}SALT, @code{crypt}, @code{crypt}},
@ref{perlfunc fc EXPR, @code{fc}, @code{fc}}, @ref{perlfunc hex EXPR, @code{hex}, @code{hex}},
@ref{perlfunc index STR@comma{}SUBSTR@comma{}POSITION, @code{index}, @code{index}}, @ref{perlfunc lc EXPR, @code{lc}, @code{lc}},
@ref{perlfunc lcfirst EXPR, @code{lcfirst}, @code{lcfirst}}, @ref{perlfunc length EXPR, @code{length}, @code{length}},
@ref{perlfunc oct EXPR, @code{oct}, @code{oct}}, @ref{perlfunc ord EXPR, @code{ord}, @code{ord}},
@ref{perlfunc pack TEMPLATE@comma{}LIST, @code{pack}, @code{pack}},
@ref{perlfunc q/STRING/, @code{q//}, @code{q//}},
@ref{perlfunc qq/STRING/, @code{qq//}, @code{qq//}}, @ref{perlfunc reverse LIST, @code{reverse}, @code{reverse}},
@ref{perlfunc rindex STR@comma{}SUBSTR@comma{}POSITION, @code{rindex}, @code{rindex}},
@ref{perlfunc sprintf FORMAT@comma{} LIST, @code{sprintf}, @code{sprintf}},
@ref{perlfunc substr EXPR@comma{}OFFSET@comma{}LENGTH@comma{}REPLACEMENT, @code{substr}, @code{substr}},
@ref{perlfunc tr///, @code{tr///}, @code{tr///}}, @ref{perlfunc uc EXPR, @code{uc}, @code{uc}},
@ref{perlfunc ucfirst EXPR, @code{ucfirst}, @code{ucfirst}},
@ref{perlfunc y///, @code{y///}, @code{y///}}

@ref{perlfunc fc EXPR, @code{fc}, @code{fc}} is available only if the
@ref{The 'fc' feature, @code{"fc"} feature,, feature} is enabled or if it is
prefixed with @code{CORE::}.  The
@ref{The 'fc' feature, @code{"fc"} feature,, feature} is enabled automatically
with a @code{use v5.16} (or higher) declaration in the current scope.
...
==============================================================================

produces with `makeinfo` the .info:
...
| Functions for SCALARs or strings
| 
|     *note ‘chomp’: chomp VARIABLE, *note ‘chop’: chop VARIABLE, *note
|     ‘chr’: chr NUMBER, *note ‘crypt’: crypt PLAINTEXT,SALT, *note ‘fc’:
|     fc EXPR, *note ‘hex’: hex EXPR, *note ‘index’: index
|     STR,SUBSTR,POSITION, *note ‘lc’: lc EXPR, *note ‘lcfirst’: lcfirst
|     EXPR, *note ‘length’: length EXPR, *note ‘oct’: oct EXPR, *note
|     ‘ord’: ord EXPR, *note ‘pack’: pack TEMPLATE,LIST, *note ‘q//’:
|     q/STRING/, *note ‘qq//’: qq/STRING/, *note ‘reverse’: reverse LIST,
|     *note ‘rindex’: rindex STR,SUBSTR,POSITION, *note ‘sprintf’:
|     sprintf FORMAT, LIST, *note ‘substr’: substr
|     EXPR,OFFSET,LENGTH,REPLACEMENT, *note ‘tr///’: tr///, *note ‘uc’:
|     uc EXPR, *note ‘ucfirst’: ucfirst EXPR, *note ‘y///’: y///.
|
|     *note ‘fc’: fc EXPR. is available only if the *note ‘"fc"’ feature:
|     (feature)The 'fc' feature. is enabled or if it is prefixed with
|     ‘CORE::’.  The *note ‘"fc"’ feature: (feature)The 'fc' feature. is
|     enabled automatically with a ‘use v5.16’ (or higher) declaration in
|     the current scope.


which end up by default (before my change) being rendered in emacs as:

| Here are Perl’s functions (including things that look like functions,
| like some keywords and named operators) arranged by category.  Some
| functions appear in more than one place.  Any warnings, including those
| produced by keywords, are described in see (perldiag) and see
| (warnings).
|
| Functions for SCALARs or strings
|
|     See ‘chomp’ see ‘chop’ see
|     ‘chr’ see ‘crypt’ see ‘fc’
|      see ‘hex’, see ‘index’
|     SUBSTR,POSIT, see ‘lc’ see ‘lcfirst’
|      see ‘length’ see ‘oct’ see
|     ‘ord’, see ‘pack’ see ‘q//’
|      see ‘qq//’ see ‘reverse’
|     see ‘rindex’ see ‘sprintf’
|      see ‘substr’
|     OFFSET,LENGTH,REPLACEMENT, see ‘tr///’ see ‘uc’
|      see ‘ucfirst’ see ‘y///’.
|
|     See ‘fc’. is available only if the see ‘"fc"’ feature
|     (feature). is enabled or if it is prefixed with
|     ‘CORE::’.  The see ‘"fc"’ feature(feature). is
|     enabled automatically with a ‘use v5.16’ (or higher) declaration in
|     the current scope.

the principal reference is in (texinfo)@ref
Where emerge that the .info
	*note 'reference': commaSeparedDetails
produced with makeinfo of textinfo package with input
	@ref{reference,commaSeparedDetails}
should be rendered in a documented way which result not to be the final
one (with the intermediate step of "rerendering" .info
with a syntesis ``See reference .'' even in the middle of a sentence
that is not expected

bug#46082: acknowledged by developer (control message for bug #46082)

[Eli Zaretskii]

tags 46082 notabug
thanks

> From: Marco Munari <mar21+dev.emacs.bugfix@allerta.it>
> Cc: 46082@debbugs.gnu.org
> Date: Mon, 08 Mar 2021 07:37:33 +0100
> 
> I noticed that when I copy and yank from an info buffer to gnus
> it keept showing what the info buffers shown, but it didn't remain
> the same on sending the email, so I didn't send previously the intended
> info rendering (which renders worse than what I sent out).
> Instead of "*note" (sent in the previous email) info shows "see" and adds
> a dot
> 
> So for example (python)Expression input is rendered with info.el
> in user reading phase as:
> | See eval(). is used for expression input.  It ignores leading
> | whitespace.  The string argument to see eval(). must have the
> | following form:
> 
> from the python.info source
> 
> | *note eval(): ca8. is used for expression input.  It ignores leading
> | whitespace.  The string argument to *note eval(): ca8. must have the
> | following form:

That's normal: info.el hides some of the text of the buffer or even
displays replacement text instead of some of the text in the buffer,
but when you copy/paste the text into another buffer, the hidden text
and the replacements are undone, and you see what is actually in
buffer text.

> which is from the texi input from texinfo
> 
> | @ref{ca8,,eval()} is used for expression input.  It ignores leading whitespace. The
> | string argument to @ref{ca8,,eval()} must have the following form:

Btw, these two instances of @ref are invalid use of @ref, as I explain
below.  And that incorrect use of @ref is actually at the heart of the
problem which bothers you.  IOW, it isn't an Emacs problem, it's a
problem with how the original Texinfo was written (or produced from
some other markup, if that's its prodigy).  More details below.

> which  is output of makeinfo from somehow the following (but the info
> says discursively that @ref should not gegerate a 'see', and the
> makeinfo output has @ref (right as intended), emacs info.el show a "see")
> (I don't see in this case necesseray the following deeper texinfo source
>  describing ref from git.savannah.gnu.org/git/texinfo.git file doc/texinfo.texi):

This is a partial misunderstanding.  The "see" which the Texinfo
manual says isn't generated is not the one you see in Emacs in Info
mode.  What the Texinfo manual alludes to is this: when you use @xref
or @pxref in Texinfo, they produce "see *note REFERENCE" (@xref
produces a capitalized "See" instead).  By contrast, @ref produces
just *note REFERENCE".  That is the "see" which Texinfo alludes to
when it says that @ref doesn't produce it.

The "see" which you see in the Info buffers in Emacs is the
replacement for "*note".  So it's a different kind of "see".

> Then the following correct use of @ref
> 
> ==============================================================================
> @node perlfunc Perl Functions by Category
> @section Perl Functions by Category
> @cindex function
> 
> Here are Perl's functions (including things that look like
> functions, like some keywords and named operators)
> arranged by category.  Some functions appear in more
> than one place.  Any warnings, including those produced by
> keywords, are described in @ref{perldiag NAME} and @ref{,,, warnings}.
> 
> @table @asis
> @item Functions for SCALARs or strings
> @anchor{perlfunc Functions for SCALARs or strings}
> @cindex scalar
> @cindex string
> @cindex character
> 
> @ref{perlfunc chomp VARIABLE, @code{chomp}, @code{chomp}}, @ref{perlfunc chop VARIABLE, @code{chop}, @code{chop}},
> @ref{perlfunc chr NUMBER, @code{chr}, @code{chr}}, @ref{perlfunc crypt PLAINTEXT@comma{}SALT, @code{crypt}, @code{crypt}},
> @ref{perlfunc fc EXPR, @code{fc}, @code{fc}}, @ref{perlfunc hex EXPR, @code{hex}, @code{hex}},

That isn't a correct use of @ref.  @ref was never meant to be used
like an HTML "<a href = ..." hyperlink, it is subtly different.  The
subtlety is that for good results @ref should be preceded by some text
which provides context for it, and it should be followed by a
punctuation character, usually a period or a comma.

The Texinfo source you show violates these principles, so the result
looks ugly and barely legible.

> produces with `makeinfo` the .info:
> ...
> | Functions for SCALARs or strings
> | 
> |     *note ‘chomp’: chomp VARIABLE, *note ‘chop’: chop VARIABLE, *note
> |     ‘chr’: chr NUMBER, *note ‘crypt’: crypt PLAINTEXT,SALT, *note ‘fc’:
> |     fc EXPR, *note ‘hex’: hex EXPR, *note ‘index’: index
> |     STR,SUBSTR,POSITION, *note ‘lc’: lc EXPR, *note ‘lcfirst’: lcfirst
> |     EXPR, *note ‘length’: length EXPR, *note ‘oct’: oct EXPR, *note
> |     ‘ord’: ord EXPR, *note ‘pack’: pack TEMPLATE,LIST, *note ‘q//’:
> |     q/STRING/, *note ‘qq//’: qq/STRING/, *note ‘reverse’: reverse LIST,
> |     *note ‘rindex’: rindex STR,SUBSTR,POSITION, *note ‘sprintf’:
> |     sprintf FORMAT, LIST, *note ‘substr’: substr
> |     EXPR,OFFSET,LENGTH,REPLACEMENT, *note ‘tr///’: tr///, *note ‘uc’:
> |     uc EXPR, *note ‘ucfirst’: ucfirst EXPR, *note ‘y///’: y///.
> |
> |     *note ‘fc’: fc EXPR. is available only if the *note ‘"fc"’ feature:
> |     (feature)The 'fc' feature. is enabled or if it is prefixed with
> |     ‘CORE::’.  The *note ‘"fc"’ feature: (feature)The 'fc' feature. is
> |     enabled automatically with a ‘use v5.16’ (or higher) declaration in
> |     the current scope.
> 
> 
> which end up by default (before my change) being rendered in emacs as:
> 
> | Here are Perl’s functions (including things that look like functions,
> | like some keywords and named operators) arranged by category.  Some
> | functions appear in more than one place.  Any warnings, including those
> | produced by keywords, are described in see (perldiag) and see
> | (warnings).
> |
> | Functions for SCALARs or strings
> |
> |     See ‘chomp’ see ‘chop’ see
> |     ‘chr’ see ‘crypt’ see ‘fc’
> |      see ‘hex’, see ‘index’
> |     SUBSTR,POSIT, see ‘lc’ see ‘lcfirst’
> |      see ‘length’ see ‘oct’ see
> |     ‘ord’, see ‘pack’ see ‘q//’
> |      see ‘qq//’ see ‘reverse’
> |     see ‘rindex’ see ‘sprintf’
> |      see ‘substr’
> |     OFFSET,LENGTH,REPLACEMENT, see ‘tr///’ see ‘uc’
> |      see ‘ucfirst’ see ‘y///’.
> |
> |     See ‘fc’. is available only if the see ‘"fc"’ feature
> |     (feature). is enabled or if it is prefixed with
> |     ‘CORE::’.  The see ‘"fc"’ feature(feature). is
> |     enabled automatically with a ‘use v5.16’ (or higher) declaration in
> |     the current scope.

That's expected.  The problem is that whoever wrote that Texinfo
expected to see just the names of the functions, displayed in a
typeface suitable for hyperlinks.  But that's not how @ref works.

This is not a bug, not an Emacs bug, anyway.

bug#46082: (texinfo) @ref says something lisp/info.el do not respect by default

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> tags 46082 notabug
> thanks
[...]
> This is not a bug, not an Emacs bug, anyway.

I'm therefore closing this bug report.