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

From: Eli Zaretskii <[email-masked]>
Date: Mon, 09 Jan 2017 20:36:45 +0200

> Date: Mon, 9 Jan 2017 08:39:13 -0800 (PST)
> From: Drew Adams <[email-masked]>
> 
> 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.