bug#25406: 24.5; doc string of `Info-history'

bug#25406: 24.5; doc string of `Info-history'

[Drew Adams]

The doc string of `Info-find-emacs-command-nodes' refers you to variable
`Info-history' for the format of the locations.

But the doc for `Info-history' says nothing about FILENAME, NODENAME,
and BUFFERPOS.

Instead, those are described in `Info-find-emacs-command-nodes'.

Something is backwards here, and/or missing.  Why refer to "the format
used in the variable `Info-history' if consulting that variable tells
you less about the format that what you are told before sending you
there?

Also, the language in the last sentence of the doc string for
`Info-find-emacs-command-nodes' is not so good.  I'm guessing that
this might be what is really meant:

 ", where BUFFERPOS is the line number
 of the first element of the returned list (which is treated specially
 in `Info-goto-emacs-command-node'), and 0 for the other elements of
 the list."

But why the parenthetical remark, and what it really means, I have
no idea.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#25406: 24.5; doc string of `Info-history'

[Eli Zaretskii]

> Date: Mon, 9 Jan 2017 08:39:13 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> The doc string of `Info-find-emacs-command-nodes' refers you to variable
> `Info-history' for the format of the locations.
> 
> But the doc for `Info-history' says nothing about FILENAME, NODENAME,
> and BUFFERPOS.
> 
> Instead, those are described in `Info-find-emacs-command-nodes'.

Yes, and that is consistent with the text of the doc string.

> Something is backwards here, and/or missing.  Why refer to "the format
> used in the variable `Info-history' if consulting that variable tells
> you less about the format that what you are told before sending you
> there?

While the reference to Info-history might be redundant to some degree,
I see nothing wrong with it -- or the rest of the text.

>  ", where BUFFERPOS is the line number
>  of the first element of the returned list (which is treated specially
>  in `Info-goto-emacs-command-node'), and 0 for the other elements of
>  the list."
> 
> But why the parenthetical remark, and what it really means, I have
> no idea.

It is a hint for why BUFFERPOS is non-zero only in that first element.
That hint is only important to someone who wants to understand how the
code works.

bug#25406: 24.5; doc string of `Info-history'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Mon, 9 Jan 2017 08:39:13 -0800 (PST)
>> From: Drew Adams <drew.adams@oracle.com>
>>
>> The doc string of `Info-find-emacs-command-nodes' refers you to variable
>> `Info-history' for the format of the locations.
>>
>> But the doc for `Info-history' says nothing about FILENAME, NODENAME,
>> and BUFFERPOS.
>>
>> Instead, those are described in `Info-find-emacs-command-nodes'.
>
> Yes, and that is consistent with the text of the doc string.
>
>> Something is backwards here, and/or missing.  Why refer to "the format
>> used in the variable `Info-history' if consulting that variable tells
>> you less about the format that what you are told before sending you
>> there?
>
> While the reference to Info-history might be redundant to some degree,
> I see nothing wrong with it -- or the rest of the text.
>
>>  ", where BUFFERPOS is the line number
>>  of the first element of the returned list (which is treated specially
>>  in `Info-goto-emacs-command-node'), and 0 for the other elements of
>>  the list."
>>
>> But why the parenthetical remark, and what it really means, I have
>> no idea.
>
> It is a hint for why BUFFERPOS is non-zero only in that first element.
> That hint is only important to someone who wants to understand how the
> code works.

It seems to me that the conclusion here is to do nothing.  Can we close
this bug report or am I missing something?

Best regards,
Stefan Kangas

bug#25406: 24.5; doc string of `Info-history'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 5 Jul 2019 14:17:39 +0200
> Cc: Drew Adams <drew.adams@oracle.com>, 25406@debbugs.gnu.org
> 
> It seems to me that the conclusion here is to do nothing.  Can we close
> this bug report or am I missing something?

I'm fine with closing it.

bug#25406: 24.5; doc string of `Info-history'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > From: Stefan Kangas <stefan@marxist.se>
> > Date: Fri, 5 Jul 2019 14:17:39 +0200
> > Cc: Drew Adams <drew.adams@oracle.com>, 25406@debbugs.gnu.org
> >
> > It seems to me that the conclusion here is to do nothing.  Can we close
> > this bug report or am I missing something?
>
> I'm fine with closing it.

OK, closed.

Thanks,
Stefan Kangas