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

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

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


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