[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#46082: acknowledged by developer (control message for bug #46082)
From: |
Eli Zaretskii |
Subject: |
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@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.