Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

[Eli Zaretskii]

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.

Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

[Basil L. Contovounesios]

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

Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

[Eli Zaretskii]

> 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?

Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

[Basil L. Contovounesios]

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

Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

[Eli Zaretskii]

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

Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

[Basil L. Contovounesios]

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

Re: [Emacs-diffs] master fc759eb: Fix with-coding-priority markup in Elisp manual

[Eli Zaretskii]

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