GNU bug report logs - #31574
27.0; Doc string for `with-help-window'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 31574 in the body.
You can then email your comments to 31574 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0; Doc string for `with-help-window'
Date: Wed, 23 May 2018 12:45:12 -0700 (PDT)

The doc string ends with this sentence: 

  See 'help-window-setup' for more options.

But that link takes you to this text, which tells you nothing at all
about "more options":

  Set up help window WINDOW for 'with-help-window'.
  WINDOW is the window used for displaying the help buffer.
  Return VALUE.



In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
 of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''

Message #8 received at 31574 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, 31574 <at> debbugs.gnu.org, 
 Nick Helm <nick <at> tenpoint.co.nz>
Subject: Re: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 09:20:48 +0200

> The doc string ends with this sentence:
>
>    See 'help-window-setup' for more options.
>
> But that link takes you to this text, which tells you nothing at all
> about "more options":

Indeed.  This was part of the fix for Bug#30792.  Nick, could you
please have a look ?

martin

Message #13 received at 31574-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 31574-done <at> debbugs.gnu.org
Subject: Re: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 19:31:36 +0300

> Date: Wed, 23 May 2018 12:45:12 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc string ends with this sentence: 
> 
>   See 'help-window-setup' for more options.
> 
> But that link takes you to this text, which tells you nothing at all
> about "more options":

"Options" was not the best word here, so I rephrased the last sentence
of the doc string.

Thanks.

Message #16 received at 31574-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 31574-done <at> debbugs.gnu.org
Subject: RE: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 10:17:49 -0700 (PDT)

> > The doc string ends with this sentence:
> >
> >   See 'help-window-setup' for more options.
> >
> > But that link takes you to this text, which tells you nothing at all
> > about "more options":
> 
> "Options" was not the best word here, so I rephrased the last sentence
> of the doc string.

I see that the bug was closed.  Not sure what the fix was,
but if it was just to change "options" then it might not
really be fixed.

The real problem is that after you follow the link there
is NOTHING about `with-help-window', AFAICT.

And I should have been clear that the doc string of
`help-window-setup' is even more problematic.  It doesn't
say anything helpful at all, AFAICT.  What does setting
up that window even mean?  The only thing this doc string
tells you, that you might not guess, is that VALUE is
returned from the function.

Did you fix the doc string of `help-window-setup', or can
you please do so as part of this bug?  Or do you need a
separate bug filed for that?

Message #19 received at 31574 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 31574 <at> debbugs.gnu.org
Subject: Re: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 21:09:30 +0300

> Date: Thu, 24 May 2018 10:17:49 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 31574-done <at> debbugs.gnu.org
> 
> > "Options" was not the best word here, so I rephrased the last sentence
> > of the doc string.
> 
> I see that the bug was closed.  Not sure what the fix was,
> but if it was just to change "options" then it might not
> really be fixed.

I told yesterday in response to another message of yours how can you
see the changes in the repository using  Web browser.  Please take a
look, then we can discuss the fix.

> The real problem is that after you follow the link there
> is NOTHING about `with-help-window', AFAICT.

No, the real problem is that the reference to help-window-setup gave
you wrong expectations regarding what information that function should
add.  My change tried to make those expectations match the original
intent.

> And I should have been clear that the doc string of
> `help-window-setup' is even more problematic.  It doesn't
> say anything helpful at all, AFAICT.

That's a subroutine, so I don't necessarily see its doc string as
something we need to invest an effort in.

Message #22 received at 31574 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 31574 <at> debbugs.gnu.org
Subject: RE: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 11:26:22 -0700 (PDT)

> I told yesterday in response to another message of yours how can you
> see the changes in the repository using  Web browser.  Please take a
> look, then we can discuss the fix.

I looked at your mention of this, which was apparently in a bug
#31311 message.  After jumping through some hoops, yes, one can
see the texinfo source code.

But even trying that for this bug, I don't see it.  I don't see
anything about 31574 here, which is presumably the latest and
right place to look for it (?):

http://git.savannah.gnu.org/cgit/emacs.git/log/

> > The real problem is that after you follow the link there
> > is NOTHING about `with-help-window', AFAICT.
> 
> No, the real problem is that the reference to help-window-setup gave
> you wrong expectations regarding what information that function should
> add.  My change tried to make those expectations match the original
> intent.

Which was what?

> > And I should have been clear that the doc string of
> > `help-window-setup' is even more problematic.  It doesn't
> > say anything helpful at all, AFAICT.
> 
> That's a subroutine, so I don't necessarily see its doc string as
> something we need to invest an effort in.

We disagree.  A doc string that says only that WINDOW is the
windo for displaying the help buffer (obvious), plus just
"Return VALUE" might as well not even exist (and the optional
arg should be called RETURN-VALUE).

This is a non-trivial function.  Some explanation of what the
window "setup" entails is appropriate.

Message #25 received at 31574 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 31574 <at> debbugs.gnu.org
Subject: Re: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 22:09:50 +0300

> Date: Thu, 24 May 2018 11:26:22 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 31574 <at> debbugs.gnu.org
> 
> But even trying that for this bug, I don't see it.  I don't see
> anything about 31574 here, which is presumably the latest and
> right place to look for it (?):
> 
> http://git.savannah.gnu.org/cgit/emacs.git/log/

That's the master branch.  You need to look at emacs-26, which is
where I fixed this.  There's a dialog box on the top right corner of
the window, which should say "master"; click the arrow, and select
"emacs-26".

> > No, the real problem is that the reference to help-window-setup gave
> > you wrong expectations regarding what information that function should
> > add.  My change tried to make those expectations match the original
> > intent.
> 
> Which was what?

That the doc string of help-window-setup says something that sheds
light on with-help-window.

Message #28 received at 31574 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31574 <at> debbugs.gnu.org
Subject: RE: bug#31574: 27.0; Doc string for `with-help-window'
Date: Thu, 24 May 2018 12:26:35 -0700 (PDT)

> That's the master branch.  You need to look at emacs-26, which is
> where I fixed this.  There's a dialog box on the top right corner of
> the window, which should say "master"; click the arrow, and select
> "emacs-26".

Thanks for this info.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.