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

Previous Next

Full log

Message #31 received at control <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Marco Munari <mar21+dev.emacs.bugfix <at> allerta.it>
Cc: 46082 <at> debbugs.gnu.org
Subject: Re: bug#46082: acknowledged by developer (control message for bug
 #46082)
Date: Thu, 11 Mar 2021 16:26:30 +0200

tags 46082 notabug
thanks

> From: Marco Munari <mar21+dev.emacs.bugfix <at> allerta.it>
> Cc: 46082 <at> 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 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.