bug#5068: 23.1; doc of load-history

bug#5068: 23.1; doc of load-history

[Drew Adams]

Oddly enough, neither the doc string nor the Elisp manual mentions
that `load-history' is in fact a load history. They do not say that
what is in the list is a record of what has _already been_ loaded.
 
If you read the doc, there is no way to know that the files listed in
the variable's list value have already been loaded. It reads like a
declarative statement of the mappings between files and their
contents, without any indication that the files listed have in fact
been loaded.
 
No, that fact is not obvious. Look at the doc string:
 
 "Alist mapping file names to symbols and features."
 
And then it describes the format of the alist. But it doesn't say that
each of the files has actually been loaded. The closest it comes is
this:
 
 "The file name is absolute and is the true file name (i.e. it
  doesn't contain symbolic links) of the loaded file."

This is the closest it comes, because this is the only place where
"loaded" is used.
 
But that statement can be read as meaning that this is the name of
a file that contains the definitions that follow, if and when this
file is ever loaded. The real import of that statement concerns
the nature of the file-name entry (absolute, no symlink).
 
Likewise, the Elisp manual:
 
 "This variable's value is an alist connecting library file names
  with the names of functions and variables they define, the
  features they provide, and the features they require."
 
This is even less correct/complete. It should not be phrased in terms
of "features", "provide", and "require". Many of the entries in
`load-history' are for files that are not `require'd, and have no
features that are `provide'd - buff-menu.elc, for example.
 
Please state explicitly that this variable records the files that have
already been loaded (including preloaded), and the functions etc. that
were defined when they were loaded.
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

bug#5068: marked as done (23.1; doc of load-history)

[Emacs bug Tracking System]

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

Your message dated Fri, 01 Jan 2010 13:15:15 -0500
with message-id <87fx6pr8ss.fsf@stupidchicken.com>
and subject line Re: 23.1; doc of load-history
has caused the Emacs bug report #5068,
regarding 23.1; doc of load-history
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 bug-gnu-emacs@gnu.org
immediately.)


-- 
5068: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=5068
Emacs Bug Tracking System
Contact bug-gnu-emacs@gnu.org with problems

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

From: "Drew Adams" <drew.adams@oracle.com>
To: <bug-gnu-emacs@gnu.org>
Subject: 23.1; doc of load-history
Date: Sat, 28 Nov 2009 08:47:23 -0800
Message-ID: <E75800ACA57242C192EB76C80BE93EC4@us.oracle.com>

Oddly enough, neither the doc string nor the Elisp manual mentions
that `load-history' is in fact a load history. They do not say that
what is in the list is a record of what has _already been_ loaded.
 
If you read the doc, there is no way to know that the files listed in
the variable's list value have already been loaded. It reads like a
declarative statement of the mappings between files and their
contents, without any indication that the files listed have in fact
been loaded.
 
No, that fact is not obvious. Look at the doc string:
 
 "Alist mapping file names to symbols and features."
 
And then it describes the format of the alist. But it doesn't say that
each of the files has actually been loaded. The closest it comes is
this:
 
 "The file name is absolute and is the true file name (i.e. it
  doesn't contain symbolic links) of the loaded file."

This is the closest it comes, because this is the only place where
"loaded" is used.
 
But that statement can be read as meaning that this is the name of
a file that contains the definitions that follow, if and when this
file is ever loaded. The real import of that statement concerns
the nature of the file-name entry (absolute, no symlink).
 
Likewise, the Elisp manual:
 
 "This variable's value is an alist connecting library file names
  with the names of functions and variables they define, the
  features they provide, and the features they require."
 
This is even less correct/complete. It should not be phrased in terms
of "features", "provide", and "require". Many of the entries in
`load-history' are for files that are not `require'd, and have no
features that are `provide'd - buff-menu.elc, for example.
 
Please state explicitly that this variable records the files that have
already been loaded (including preloaded), and the functions etc. that
were defined when they were loaded.
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 




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

From: Chong Yidong <cyd@stupidchicken.com>
To: "Drew Adams" <drew.adams@oracle.com>
Cc: 5068-done@debbugs.gnu.org
Subject: Re: 23.1; doc of load-history
Date: Fri, 01 Jan 2010 13:15:15 -0500
Message-ID: <87fx6pr8ss.fsf@stupidchicken.com>

> Oddly enough, neither the doc string nor the Elisp manual mentions
> that `load-history' is in fact a load history. They do not say that
> what is in the list is a record of what has _already been_ loaded.

Thanks, I've changed the docstring and manual to make this clearer.

bug#5288: 23.1; doc of load-history

[Drew Adams]

> Thanks, I've changed the docstring and manual to make this clearer.

Thanks.

FYI - These open bugs are also doc or message bugs.

1144 - No doc string for `symbol-at-point' and other, similar functions
1375 - Elisp manual node Special Properties
1749 - Emacs manual, node Mode Line
2792 - doc string of switch-to-buffer
2946 - output of describe-font-internal and doc string of font-info
2974 - Documentation incomplete for mode-line variables
3042 - display-visual class doc
3052 - please add doc strings for printing.el commands
3135 - doc of custom-variable-documentation
3137 - doc of compilation-get-file-structure
3138 - doc of ediff-patch-file
3227 - doc strings too wide
3249 - doc of transpose-subr and transpose-regions
3313 - Use Lisp strings for syntax descriptor examples
3320 - Rename `mini-' options
3371 - doc of `comment-style'
3393 - Document lisp-indent-function in Elisp manual
3503 - Emacs manual, main menu typo
3509 - improper quoting in (org)Special agenda views
3519 - (emacs)Init Examples: Rumsfeld is yesterday's news
3523 - "inferiors" -> "subnodes" in Detailed Node Listing
3524 - Use `emacs-lisp-mode-syntax-table' for NEWS
3525 - document `list-character-sets' in Emacs manual, node Charsets
3527 - Setting the default font using `menu-set-font'
3549 - Remove empty custom group `refill'
3564 - compose-region doc string
3566 - explain why not to use group defined by define-minor-mode
3575 - doc string of text-scale-increase should mention
       text-scale-decrease
3598 - doc string of frame-root-window
3599 - (elisp)Window Tree: Need to define root window
3615 - (elisp)Local Variables: xrefs to nodes for buffer-local
       and frame-local vars
3801 - Emacs manual: add index entry for "notation, keys"
       or "key notation"
3849 - Eshell manual - mostly empty etc.
3856 - doc string of `widget-complete'
3934 - Document `minibuffer-history-variable'
4162 - common doc strings that are too wide
4562 - Customize State button problems
4668 - two common doc strings too wide
       - shows up in most uses of `C-h m'