GNU bug report logs - #2291
23.0.90; finder-commentary

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 2291 in the body.
You can then email your comments to 2291 AT debbugs.gnu.org in the normal way.

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

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.90; finder-commentary
Date: Wed, 11 Feb 2009 10:36:25 -0800

1. This sexp in finder-commentary is inappropriate:
(delete-other-windows).  The original buffer is current when this is
called, and it makes no sense to delete the other windows.  And the
call is immediately followed by pop-to-buffer to display and select
the Finder commentary buffer.
 
2. The Commentary buffer name should not be "*Finder-package*".  That
prohibits you from having more than one such buffer. Also, the name
should reflect the content: this is the Commentary section of a
particular Lisp file.  Please use something like this:
 
(pop-to-buffer
 (concat "*Commentary, " (file-name-sans-extension file) "*"))
 
instead of this:
(pop-to-buffer "*Finder-package*")
 
The result will then be a name like this: *Commentary, buff-menu*
 
Among other things, being able to have more than one Finder commentary
buffer lets you use the Commentary section of Lisp files for
documentation that refers to other Lisp file Commentary sections.
With a simple link facility (e.g. `linkd.el' or Org mode), this doc
becomes hypertext among Commentary sections, each in Finder mode, with
the comment characters removed etc.
 

In GNU Emacs 23.0.90.1 (i386-mingw-nt5.1.2600)
 of 2009-02-01 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

Message #10 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <2291 <at> debbugs.gnu.org>, <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#2291: 23.0.90; finder-commentary
Date: Wed, 11 Feb 2009 15:35:44 -0800

I forgot to mention this:

3. The doc string of `finder-commentary' does not describe argument LIBRARY. The
doc string:

"Display FILE's commentary section.
FILE should be in a form suitable for passing to `locate-library'."

But the doc string of `locate-library' also does not say what is suitable for
its LIBRARY argument:

"Show the precise file name of Emacs library LIBRARY.
This command searches the directories in `load-path' like `M-x load-library'
to find the file that `M-x load-library RET LIBRARY RET' would load.
Optional second arg NOSUFFIX non-nil means don't add suffixes `load-suffixes'
to the specified name LIBRARY.

If the optional third arg PATH is specified, that list of directories
is used instead of `load-path'.

When called from a program, the file name is normally returned as a
string.  When run interactively, the argument INTERACTIVE-CALL is t,
and the file name is displayed in the echo area."

That says absolutely nothing about argument LIBRARY, except that it is a
library. However, it refers you to `load-library'. But the doc string of
`load-library' also says absolutely nothing about argument LIBRARY. It refers
you to `load'...

The user should be told, somewhere along the line (preferably everywhere, if
short), just which Lisp objects are acceptable as values of argument LIBRARY.

Message #20 received at 2291 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>, 2291 <at> debbugs.gnu.org
Subject: Re: bug#2291: 23.0.90; finder-commentary
Date: Fri, 13 Feb 2009 17:19:55 +0200

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Date: Wed, 11 Feb 2009 15:35:44 -0800
> Cc: 
> 
> I forgot to mention this:
> 
> 3. The doc string of `finder-commentary' does not describe argument LIBRARY. The
> doc string:
> 
> "Display FILE's commentary section.
> FILE should be in a form suitable for passing to `locate-library'."
> 
> But the doc string of `locate-library' also does not say what is suitable for
> its LIBRARY argument:
> 
> "Show the precise file name of Emacs library LIBRARY.
> This command searches the directories in `load-path' like `M-x load-library'
> to find the file that `M-x load-library RET LIBRARY RET' would load.
> Optional second arg NOSUFFIX non-nil means don't add suffixes `load-suffixes'
> to the specified name LIBRARY.
> 
> If the optional third arg PATH is specified, that list of directories
> is used instead of `load-path'.
> 
> When called from a program, the file name is normally returned as a
> string.  When run interactively, the argument INTERACTIVE-CALL is t,
> and the file name is displayed in the echo area."
> 
> That says absolutely nothing about argument LIBRARY, except that it is a
> library. However, it refers you to `load-library'. But the doc string of
> `load-library' also says absolutely nothing about argument LIBRARY. It refers
> you to `load'...
> 
> The user should be told, somewhere along the line (preferably everywhere, if
> short), just which Lisp objects are acceptable as values of argument LIBRARY.

I fixed the doc strings of `load-library' and `locate-library'.

Message #25 received at 2291-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 2291-done <at> debbugs.gnu.org
Subject: Re: 23.0.90; finder-commentary
Date: Sun, 08 Mar 2009 15:58:45 -0400

> 1. This sexp in finder-commentary is inappropriate:
> (delete-other-windows).

I've removed it.  Thanks for pointing this out.
 
> 2. The Commentary buffer name should not be "*Finder-package*".  That
> prohibits you from having more than one such buffer.

That would be problematic, as it leaves a trail of finder-commentary
buffers that you have to delete manually.  That's the same reason we
don't uniquify *Help* buffers.

Message #26 received at 2291-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> stupidchicken.com>
Cc: <2291-done <at> debbugs.gnu.org>
Subject: RE: 23.0.90; finder-commentary
Date: Sun, 8 Mar 2009 13:08:00 -0700

> > 2. The Commentary buffer name should not be 
> >    "*Finder-package*".  That prohibits you from having
> >    more than one such buffer.
> 
> That would be problematic, as it leaves a trail of finder-commentary
> buffers that you have to delete manually.  That's the same reason we
> don't uniquify *Help* buffers.

There is no relation between this and *Help*. There is a good reason for having
multiple commentary buffers, which I mentioned:

> being able to have more than one Finder commentary buffer
> lets you use the Commentary section of Lisp files for
> documentation that refers to other Lisp file Commentary sections.
>
> With a simple link facility (e.g. `linkd.el' or Org mode),
> this doc becomes hypertext among Commentary sections, each in
> Finder mode, with the comment characters removed etc.

It is not difficult to delete a buffer you no longer want. But without the
requested change there is no easy way for a user to view the commentaries of
more than one library. 

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 2291 <at> debbugs.gnu.org
Subject: Re: bug#2291: 23.0.90; finder-commentary
Date: Wed, 27 Apr 2016 19:43:07 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 1. This sexp in finder-commentary is inappropriate:
> (delete-other-windows).  The original buffer is current when this is
> called, and it makes no sense to delete the other windows.  And the
> call is immediately followed by pop-to-buffer to display and select
> the Finder commentary buffer.

This looks like it's fixed now?

> 2. The Commentary buffer name should not be "*Finder-package*".  That
> prohibits you from having more than one such buffer. Also, the name
> should reflect the content: this is the Commentary section of a
> particular Lisp file.  Please use something like this:
>
> (pop-to-buffer
>  (concat "*Commentary, " (file-name-sans-extension file) "*"))
>
> instead of this:
> (pop-to-buffer "*Finder-package*")
>
> The result will then be a name like this: *Commentary, buff-menu*

Wouldn't it make more sense just to use the *Help* buffer?  It has a
nice history and stuff...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 2291 <at> debbugs.gnu.org
Subject: RE: bug#2291: 23.0.90; finder-commentary
Date: Wed, 27 Apr 2016 10:53:30 -0700 (PDT)

> > 1. This sexp in finder-commentary is inappropriate:
> > (delete-other-windows).  The original buffer is current when this is
> > called, and it makes no sense to delete the other windows.  And the
> > call is immediately followed by pop-to-buffer to display and select
> > the Finder commentary buffer.
> 
> This looks like it's fixed now?

Yes, I guess so - it seems to have been removed in Emacs 23.
Dunno whether the bad effect is gone, but I'll assume so.

> > 2. The Commentary buffer name should not be "*Finder-package*".  That
> > prohibits you from having more than one such buffer. Also, the name
> > should reflect the content: this is the Commentary section of a
> > particular Lisp file.  Please use something like this:
> >
> > (pop-to-buffer
> >  (concat "*Commentary, " (file-name-sans-extension file) "*"))
> >
> > instead of this:
> > (pop-to-buffer "*Finder-package*")
> >
> > The result will then be a name like this: *Commentary, buff-menu*
> 
> Wouldn't it make more sense just to use the *Help* buffer?  It has a
> nice history and stuff...

No, certainly not.  It should be commentary-specific, and file-specific,
as described in the bug report.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 2291 <at> debbugs.gnu.org
Subject: Re: bug#2291: 23.0.90; finder-commentary
Date: Wed, 27 Apr 2016 19:58:45 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

>> > 2. The Commentary buffer name should not be "*Finder-package*".  That
>> > prohibits you from having more than one such buffer. Also, the name
>> > should reflect the content: this is the Commentary section of a
>> > particular Lisp file.  Please use something like this:
>> >
>> > (pop-to-buffer
>> >  (concat "*Commentary, " (file-name-sans-extension file) "*"))
>> >
>> > instead of this:
>> > (pop-to-buffer "*Finder-package*")
>> >
>> > The result will then be a name like this: *Commentary, buff-menu*
>> 
>> Wouldn't it make more sense just to use the *Help* buffer?  It has a
>> nice history and stuff...
>
> No, certainly not.  It should be commentary-specific, and file-specific,
> as described in the bug report.

It would be unusual.  Most of these help-ish commands reuse the same
buffer, and if you want to keep several of them around, you just rename
the buffer yourself.

So I don't think there's anything more to be done on this report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 2291 <at> debbugs.gnu.org
Subject: RE: bug#2291: 23.0.90; finder-commentary
Date: Wed, 27 Apr 2016 11:05:16 -0700 (PDT)

> >> Wouldn't it make more sense just to use the *Help* buffer?  It has a
> >> nice history and stuff...
> >
> > No, certainly not.  It should be commentary-specific, and file-specific,
> > as described in the bug report.
> 
> It would be unusual.  Most of these help-ish commands reuse the same
> buffer, and if you want to keep several of them around, you just rename
> the buffer yourself.
> 
> So I don't think there's anything more to be done on this report.

This is nuts.  `finder-commentary' is file-specific.  Anyone
who uses it (and admittedly it is underused - most users know
nothing about its existence) uses it on multiple files.

You might have noticed recently a bunch of mails about having
multiple grep buffers etc.  Well this is even more important
than that - and simpler, as this is just file-specific.  Each
file should get its own finder-commentary buffer, named after it.

Previous Next

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