bug#3125: 23.0.92; doc of load-library

bug#3125: 23.0.92; doc of load-library

[Drew Adams]

The doc string and Elisp manual entry for `load-library' could be more
helpful.
 
Doc string:
 
 Load the library named LIBRARY.
 
 LIBRARY should be a relative file name of the library, a string.
 It can omit the suffix (a.k.a. file-name extension).
 
 This is an interface to the function `load'.
 
Elisp entry:
 
 Command: load-library library
     This command loads the library named LIBRARY.  It is equivalent to
     `load', except in how it reads its argument interactively.
 
The explanation in the Emacs manual is good. It should be
cross-referenced from the Elisp manual. The Elisp manual says nothing
helpful; in particular, it says nothing about _how_ its reading of the
arg is different from that of `load'.
 
The doc string is inadequate on its own. The best solution would be
for it to cross-reference the Emacs manual (click a link), but that
feature was refused.  An alternative is to add some more explanation
to the doc string - about .elc, .el etc. 
 

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

bug#3125: 23.0.92; doc of load-library

[Stefan Monnier]

> The explanation in the Emacs manual is good. It should be
> cross-referenced from the Elisp manual. The Elisp manual says nothing
> helpful; in particular, it says nothing about _how_ its reading of the
> arg is different from that of `load'.

The Elisp manual should probably not bother talking about load-library,
actually.  It's just a user-level command, not a function to be called
from Elisp.
 
> The doc string is inadequate on its own.

Indeed, it's even somewhat misleading.  I'll try and rework it,
thank you.


        Stefan

bug#3125: 23.0.92; doc of load-library

[Stefan Monnier]

> The doc string and Elisp manual entry for `load-library' could be more

Please check the new docstring (but not the elisp manual yet).


        Stefan

bug#3125: 23.0.92; doc of load-library

[Drew Adams]

> > The doc string and Elisp manual entry for `load-library' 
> > could be more
> 
> Please check the new docstring (but not the elisp manual yet).

"actually loaded" -> "to be loaded"

"with or without" -> "with and without"

"the `load-suffixes' (as well as `load-file-rep-suffixes')" ->
"the suffixes from variables `load-suffixes' and `load-file-rep-suffixes'"

(Drop "variable", if that's too long.)

Do you really want to state here that there are two interfaces to `load'? If a
third is added later, then this will need to be updated. Why not just say that
`load-library' is an interface to `load'?

Or, better, just skip that altogether. The xref to the manual is sufficient. The
manual describes the relations among the various load functions. The doc string
need say only what `load-library' does/is.

bug#3125: marked as done (23.0.92; doc of load-library)

[Emacs bug Tracking System]

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


Your message dated Sat, 15 Aug 2009 14:00:16 -0400
with message-id <87zla10xfz.fsf@cyd.mit.edu>
and subject line Re: bug#3125: 23.0.92; doc of load-library
has caused the Emacs bug report #3125,
regarding 23.0.92; doc of load-library
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.)


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

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

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Subject: 23.0.92; doc of load-library
Date: Sun, 26 Apr 2009 21:12:58 -0700
Message-ID: <003a01c9c6ee$733d40c0$0200a8c0@us.oracle.com>

The doc string and Elisp manual entry for `load-library' could be more
helpful.
 
Doc string:
 
 Load the library named LIBRARY.
 
 LIBRARY should be a relative file name of the library, a string.
 It can omit the suffix (a.k.a. file-name extension).
 
 This is an interface to the function `load'.
 
Elisp entry:
 
 Command: load-library library
     This command loads the library named LIBRARY.  It is equivalent to
     `load', except in how it reads its argument interactively.
 
The explanation in the Emacs manual is good. It should be
cross-referenced from the Elisp manual. The Elisp manual says nothing
helpful; in particular, it says nothing about _how_ its reading of the
arg is different from that of `load'.
 
The doc string is inadequate on its own. The best solution would be
for it to cross-reference the Emacs manual (click a link), but that
feature was refused.  An alternative is to add some more explanation
to the doc string - about .elc, .el etc. 
 

In GNU Emacs 23.0.92.1 (i386-mingw-nt5.1.2600)
 of 2009-03-30 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: 1161 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: "Drew Adams" <drew.adams@oracle.com>
Cc: "'Stefan Monnier'" <monnier@IRO.UMontreal.CA>, <3125-done@emacsbugs.donarmstrong.com>
Subject: Re: bug#3125: 23.0.92; doc of load-library
Date: Sat, 15 Aug 2009 14:00:16 -0400
Message-ID: <87zla10xfz.fsf@cyd.mit.edu>

I've fixed the documentation accordingly.