* Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual
@ 2019-10-13 15:49 Eli Zaretskii
2020-06-13 15:38 ` Basil L. Contovounesios
0 siblings, 1 reply; 7+ messages in thread
From: Eli Zaretskii @ 2019-10-13 15:49 UTC (permalink / raw)
To: Basil L. Contovounesios; +Cc: emacs-devel
This change loses information:
-@defmac with-coding-priority coding-systems &rest body@dots{}
-This macro execute @var{body}, like @code{progn} does
-(@pxref{Sequencing, progn}), with @var{coding-systems} at the front of
-the priority list for coding systems. @var{coding-systems} should be
-a list of coding systems to prefer during execution of @var{body}.
+@defmac with-coding-priority coding-systems &rest body
+This macro executes @var{body}, like @code{progn} does
+(@pxref{Sequencing}), with @var{coding-systems} at the front of the
+priority list for coding systems. @var{coding-systems} should be a
+list of coding systems to prefer during execution of @var{body}.
The 2nd argument of @pxref, as in @pxref{Sequencing, progn} above, is
not a no-op, and I see no reason to remove it in this case. Did I
miss something?
Thanks for improving our documentation.
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual
2019-10-13 15:49 [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual Eli Zaretskii
@ 2020-06-13 15:38 ` Basil L. Contovounesios
2020-06-13 15:49 ` Eli Zaretskii
0 siblings, 1 reply; 7+ messages in thread
From: Basil L. Contovounesios @ 2020-06-13 15:38 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: emacs-devel
Eli Zaretskii <eliz@gnu.org> writes:
> This change loses information:
>
> -@defmac with-coding-priority coding-systems &rest body@dots{}
> -This macro execute @var{body}, like @code{progn} does
> -(@pxref{Sequencing, progn}), with @var{coding-systems} at the front of
> -the priority list for coding systems. @var{coding-systems} should be
> -a list of coding systems to prefer during execution of @var{body}.
> +@defmac with-coding-priority coding-systems &rest body
> +This macro executes @var{body}, like @code{progn} does
> +(@pxref{Sequencing}), with @var{coding-systems} at the front of the
> +priority list for coding systems. @var{coding-systems} should be a
> +list of coding systems to prefer during execution of @var{body}.
>
> The 2nd argument of @pxref, as in @pxref{Sequencing, progn} above, is
> not a no-op, and I see no reason to remove it in this case. Did I
> miss something?
Sorry about the late reply. I think the reason I removed it is because
it produces the following Info:
This macro executes BODY, like ‘progn’ does (see progn
.), with CODING-SYSTEMS at the front of the priority list
for coding systems. CODING-SYSTEMS should be a list of coding
systems to prefer during execution of BODY.
Any ideas how to cajole it?
Thanks,
--
Basil
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual
2020-06-13 15:38 ` Basil L. Contovounesios
@ 2020-06-13 15:49 ` Eli Zaretskii
2020-06-13 16:35 ` Basil L. Contovounesios
0 siblings, 1 reply; 7+ messages in thread
From: Eli Zaretskii @ 2020-06-13 15:49 UTC (permalink / raw)
To: Basil L. Contovounesios; +Cc: emacs-devel
> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: emacs-devel@gnu.org
> Date: Sat, 13 Jun 2020 16:38:50 +0100
>
> > The 2nd argument of @pxref, as in @pxref{Sequencing, progn} above, is
> > not a no-op, and I see no reason to remove it in this case. Did I
> > miss something?
>
> Sorry about the late reply. I think the reason I removed it is because
> it produces the following Info:
>
> This macro executes BODY, like ‘progn’ does (see progn
> .), with CODING-SYSTEMS at the front of the priority list
> for coding systems. CODING-SYSTEMS should be a list of coding
> systems to prefer during execution of BODY.
>
> Any ideas how to cajole it?
What problem are you trying to avoid here?
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual
2020-06-13 15:49 ` Eli Zaretskii
@ 2020-06-13 16:35 ` Basil L. Contovounesios
2020-06-13 16:42 ` Eli Zaretskii
0 siblings, 1 reply; 7+ messages in thread
From: Basil L. Contovounesios @ 2020-06-13 16:35 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: emacs-devel
Eli Zaretskii <eliz@gnu.org> writes:
>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Cc: emacs-devel@gnu.org
>> Date: Sat, 13 Jun 2020 16:38:50 +0100
>>
>> > The 2nd argument of @pxref, as in @pxref{Sequencing, progn} above, is
>> > not a no-op, and I see no reason to remove it in this case. Did I
>> > miss something?
>>
>> Sorry about the late reply. I think the reason I removed it is because
>> it produces the following Info:
>>
>> This macro executes BODY, like ‘progn’ does (see progn
>> .), with CODING-SYSTEMS at the front of the priority list
>> for coding systems. CODING-SYSTEMS should be a list of coding
>> systems to prefer during execution of BODY.
>>
>> Any ideas how to cajole it?
>
> What problem are you trying to avoid here?
>> ...like ‘progn’ does (see progn.), with...
^^^
This
There shouldn't be a full stop there, right?
--
Basil
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual
2020-06-13 16:35 ` Basil L. Contovounesios
@ 2020-06-13 16:42 ` Eli Zaretskii
2020-06-13 17:03 ` Basil L. Contovounesios
0 siblings, 1 reply; 7+ messages in thread
From: Eli Zaretskii @ 2020-06-13 16:42 UTC (permalink / raw)
To: Basil L. Contovounesios; +Cc: emacs-devel
> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: emacs-devel@gnu.org
> Date: Sat, 13 Jun 2020 17:35:58 +0100
>
> > What problem are you trying to avoid here?
>
> >> ...like ‘progn’ does (see progn.), with...
> ^^^
> This
>
> There shouldn't be a full stop there, right?
Maybe not, but it's info.el which does that, not Texinfo. From the
Texinfo POV the result is perfectly correct, and provides a better
location to an Info reader (although ISTR the Emacs reader disregards
that).
IOW, the way info.el displays this is not a reason to avoid the 2nd
argument of a cross-reference. If we think the display is wrong, we
should fix info.el to yield a better one.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual
2020-06-13 16:42 ` Eli Zaretskii
@ 2020-06-13 17:03 ` Basil L. Contovounesios
2020-06-13 17:16 ` Eli Zaretskii
0 siblings, 1 reply; 7+ messages in thread
From: Basil L. Contovounesios @ 2020-06-13 17:03 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: emacs-devel
Eli Zaretskii <eliz@gnu.org> writes:
>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Cc: emacs-devel@gnu.org
>> Date: Sat, 13 Jun 2020 17:35:58 +0100
>>
>> > What problem are you trying to avoid here?
>>
>> >> ...like ‘progn’ does (see progn.), with...
>> ^^^
>> This
>>
>> There shouldn't be a full stop there, right?
>
> Maybe not, but it's info.el which does that, not Texinfo.
Ah, I didn't realise this was an info.el artefact.
I've now reverted the change:
Revert markup change in with-coding-priority docs
6cdecc2659 2020-06-13 17:54:51 +0100
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=6cdecc2659a290f4a9eddb498978e3b07d5cbc58
> From the Texinfo POV the result is perfectly correct, and provides a
> better location to an Info reader (although ISTR the Emacs reader
> disregards that).
Are you referring to the fact that following the xref doesn't take you
to the definition of progn? Because I would have guessed that's because
there's no @anchor{progn}. Or is Texinfo smarter about it?
> IOW, the way info.el displays this is not a reason to avoid the 2nd
> argument of a cross-reference. If we think the display is wrong, we
> should fix info.el to yield a better one.
I agree, thanks,
--
Basil
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual
2020-06-13 17:03 ` Basil L. Contovounesios
@ 2020-06-13 17:16 ` Eli Zaretskii
0 siblings, 0 replies; 7+ messages in thread
From: Eli Zaretskii @ 2020-06-13 17:16 UTC (permalink / raw)
To: Basil L. Contovounesios; +Cc: emacs-devel
> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: emacs-devel@gnu.org
> Date: Sat, 13 Jun 2020 18:03:25 +0100
>
> > From the Texinfo POV the result is perfectly correct, and provides a
> > better location to an Info reader (although ISTR the Emacs reader
> > disregards that).
>
> Are you referring to the fact that following the xref doesn't take you
> to the definition of progn?
Yes.
> Because I would have guessed that's because there's no
> @anchor{progn}.
The @anchor shouldn't be needed, the Info reader should just search
for the first occurrence of "progn" in the node. ISTR that at some
point the stand-alone Info reader did that, but I'm not sure, and the
latest version doesn't AFAICT. Maybe we should enhance info.el to do
that.
In any case, the printed manual produces a more targeted reference
from a 2-argument xref.
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2020-06-13 17:16 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-10-13 15:49 [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual Eli Zaretskii
2020-06-13 15:38 ` Basil L. Contovounesios
2020-06-13 15:49 ` Eli Zaretskii
2020-06-13 16:35 ` Basil L. Contovounesios
2020-06-13 16:42 ` Eli Zaretskii
2020-06-13 17:03 ` Basil L. Contovounesios
2020-06-13 17:16 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).