From: Eli Zaretskii <eliz@gnu.org>
To: Marco Munari <mar21+dev.emacs.bugfix@allerta.it>
Cc: 46082@debbugs.gnu.org
Subject: bug#46082: acknowledged by developer (control message for bug #46082)
Date: Thu, 11 Mar 2021 16:26:30 +0200 [thread overview]
Message-ID: <83k0qdn4vd.fsf@gnu.org> (raw)
In-Reply-To: <ywmsg56up5e.fsf@nb.mm.homeunix.org.valid> (message from Marco Munari on Mon, 08 Mar 2021 07:37:33 +0100)
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.
next prev parent reply other threads:[~2021-03-11 14:26 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <87eegy6gtv.fsf@gnus.org>
2021-01-24 16:26 ` bug#46082: (texinfo) @ref says something lisp/info.el do not respect by default Marco Munari
2021-01-27 2:56 ` Lars Ingebrigtsen
2021-03-01 15:20 ` Lars Ingebrigtsen
[not found] ` <handler.46082.C.161461205518066.notifdonectrl.0@debbugs.gnu.org>
2021-03-01 19:22 ` bug#46082: acknowledged by developer (control message for bug #46082) Marco Munari
2021-03-01 20:10 ` Eli Zaretskii
2021-03-08 6:37 ` Marco Munari
2021-03-11 14:26 ` Eli Zaretskii [this message]
2021-04-09 16:59 ` bug#46082: (texinfo) @ref says something lisp/info.el do not respect by default Stefan Kangas
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83k0qdn4vd.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=46082@debbugs.gnu.org \
--cc=mar21+dev.emacs.bugfix@allerta.it \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.