bug#2291: 23.0.90; finder-commentary

bug#2291: 23.0.90; finder-commentary

[Drew Adams]

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)'
 

bug#2291: 23.0.90; finder-commentary

[Drew Adams]

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.

bug#2291: 23.0.90; finder-commentary

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@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'.

bug#2291: marked as done (23.0.90; finder-commentary)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 838 bytes --]


Your message dated Sun, 08 Mar 2009 15:58:45 -0400
with message-id <87iqmjokga.fsf@cyd.mit.edu>
and subject line Re: 23.0.90; finder-commentary
has caused the Emacs bug report #2291,
regarding 23.0.90; finder-commentary
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
2291: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=2291
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3993 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Subject: 23.0.90; finder-commentary
Date: Wed, 11 Feb 2009 10:36:25 -0800
Message-ID: <004e01c98c77$a84e2420$c2b22382@us.oracle.com>

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)'
 




[-- Attachment #3: Type: message/rfc822, Size: 1462 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: "Drew Adams" <drew.adams@oracle.com>
Cc: 2291-done@emacsbugs.donarmstrong.com
Subject: Re: 23.0.90; finder-commentary
Date: Sun, 08 Mar 2009 15:58:45 -0400
Message-ID: <87iqmjokga.fsf@cyd.mit.edu>

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

bug#2291: 23.0.90; finder-commentary

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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

bug#2291: 23.0.90; finder-commentary

[Drew Adams]

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

bug#2291: 23.0.90; finder-commentary

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

bug#2291: 23.0.90; finder-commentary

[Drew Adams]

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