bug#17709: 24.3; `tool-bar-map' seems inadaquately documented

[Samuel Bronson]

So, we have this:
,----[ C-h v tool-bar-map RET ]
| tool-bar-map is a variable defined in `tool-bar.el'.
[...]
| Documentation:
| Keymap for the tool bar.
| Define this locally to override the global tool bar.
[...]
`----

But we also have this:
,----[ C-h f tool-bar-make-keymap RET ]
| tool-bar-make-keymap is a compiled Lisp function in `tool-bar.el'.
| 
| (tool-bar-make-keymap &optional IGNORE)
| 
| Generate an actual keymap from `tool-bar-map'.
| Its main job is to figure out which images to use based on the display's
| color capability and based on the available image libraries.
`----

It seems that the docs for the variable `tool-bar-map' are, at best,
completely glossing over the fact that, while perhaps technically a
keymap according to the defition in (info "(elisp) Format of Keymaps"),
the value of this variable is not actually directly usable, which
(presumably) has some special extra conditional stuff in it that the
`tool-bar-make-keymap' function filters out.

It seems like it would be good to at least MENTION the existance of such
deviations; if you'd rather not document their exact form, you could
just say what fields to expect differences in and reference the
functions `tool-bar-add-item'/`tool-bar-local-item' and
`tool-bar-add-item-from-menu'/`tool-bar-local-item-from-menu' used to
make such "keymaps".


In GNU Emacs 24.3.1 (i486-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2013-12-22 on binet, modified by Debian
Windowing system distributor `Colin Harrison', version 11.0.60900031
System Description:     Debian GNU/Linux testing (jessie)

Configured using:
 `configure '--build' 'i486-linux-gnu' '--build' 'i486-linux-gnu'
 '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib'
 '--localstatedir=/var/lib' '--infodir=/usr/share/info'
 '--mandir=/usr/share/man' '--with-pop=yes'
 
'--enable-locallisppath=/etc/emacs24:/etc/emacs:/usr/local/share/emacs/24.3/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.3/site-lisp:/usr/share/emacs/site-lisp'
 '--with-crt-dir=/usr/lib/i386-linux-gnu' '--with-x=yes'
 '--with-x-toolkit=lucid' '--with-toolkit-scroll-bars' '--without-gconf'
 '--without-gsettings' 'build_alias=i486-linux-gnu' 'CFLAGS=-g -O2
 -fstack-protector --param=ssp-buffer-size=4 -Wformat
 -Werror=format-security -Wall' 'LDFLAGS=-Wl,-z,relro'
 'CPPFLAGS=-D_FORTIFY_SOURCE=2''

Important settings:
  value of $LC_COLLATE: C
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  diff-auto-refine-mode: t
  dir-locals-mode: t
  shell-dirtrack-mode: t
  xterm-mouse-mode: t
  show-paren-mode: t
  recentf-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
f a <tab> q <backspace> <return> C-g M-x <up> <up> 
<return> <return> <down> <down> <down> <down> <down> 
<down> <down> <down> <end> <down> <end> <down> <end> 
<down> C-x C-f C-g C-x C-f e <tab> <tab> C-g C-x k 
<return> C-s a u t o l o a d s C-s C-s C-s C-s C-s 
C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s 
C-s C-s <C-home> <next> <next> <next> <next> <C-end> 
<C-home> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <end> <down> <end> <down> <down> 
<down> <up> <up> <up> <up> <up> <backspace> , , <backspace> 
<backspace> <home> <end> <home> C-k S o h u l <backspace> 
<backspace> <backspace> <backspace> h o u l d n ' t 
SPC t h e r e SPC b e SPC a SPC c o n v e n i e n c 
e SPC a l i a s SPC f o r SPC t h i s ? <return> <up> 
<down> <down> - - <up> <up> <end> <down> <down> SPC 
S y s t e m SPC I n f r o m a t <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> f o 
r m a t i o n SPC = - - <backspace> <backspace> <backspace> 
- - <home> <end> <home> <end> <home> <end> <next> <prior> 
<C-home> <C-end> <C-home> <down> <down> <down> <down> 
<down> <down> <down> <down> <next> <next> <next> <next> 
<next> <next> <next> <next> <next> <C-home> <C-home> 
<down> <down> <down> <down> <down> <down> <end> <down> 
<down> <down> <down> <up> <end> <up> <end> C-c C-c 
y s e <backspace> <backspace> e s <return> <down-mouse-1> 
<mouse-movement> <mouse-1> <down-mouse-1> <mouse-1> 
<down-mouse-1> <mouse-1> <help-echo> <down-mouse-1> 
<mouse-2> <help-echo> <down-mouse-1> <mouse-1> <down-mouse-1> 
<mouse-1> <down-mouse-1> <mouse-1> <down-mouse-1> <mouse-1> 
<down-mouse-1> <mouse-1> <down-mouse-1> <mouse-1> <right> 
<end> <home> <C-right> <right> M-x <up> <up> <up> <up> 
<return>

Recent messages:
Making completion list...
Quit
Mark saved where search started
Mark set [9 times]
Sending...
Mark set [2 times]
Sending via mail...
Sending...done
Checking spelling of INADAQUATELY...
byte-code: Window #<window 952 on  *Minibuf-1*> too small for splitting

Load-path shadows:
/home/naesten/system/emacs/dist/elpa/w3-4.0.46/ssl hides 
/usr/share/emacs24/site-lisp/wl/ssl
/usr/share/emacs24/site-lisp/css-mode/css-mode hides 
/usr/share/emacs/site-lisp/css-mode/css-mode
/usr/local/share/emacs/site-lisp/coq hides 
/usr/share/emacs/24.3/site-lisp/proofgeneral/coq/coq
/usr/share/emacs/site-lisp/autoconf/autotest-mode hides 
/usr/share/emacs/site-lisp/autotest-mode
/usr/share/emacs/24.3/site-lisp/cscope/xcscope hides 
/usr/share/emacs/site-lisp/xcscope
/usr/share/emacs/24.3/site-lisp/debian-startup hides 
/usr/share/emacs/site-lisp/debian-startup
/usr/share/emacs24/site-lisp/cmake-data/cmake-mode hides 
/usr/share/emacs/site-lisp/cmake-mode
/usr/share/emacs24/site-lisp/flim/md4 hides /usr/share/emacs/24.3/lisp/md4
/home/naesten/system/emacs/dist/elisp/loaddefs hides 
/usr/share/emacs/24.3/lisp/loaddefs
/usr/share/emacs24/site-lisp/flim/hex-util hides 
/usr/share/emacs/24.3/lisp/hex-util
/home/naesten/system/emacs/dist/elpa/json-1.2/json hides 
/usr/share/emacs/24.3/lisp/json
/home/naesten/system/emacs/dist/elisp/t-mouse hides 
/usr/share/emacs/24.3/lisp/t-mouse
/usr/share/emacs24/site-lisp/html-helper-mode/tempo hides 
/usr/share/emacs/24.3/lisp/tempo
/usr/share/emacs24/site-lisp/css-mode/css-mode hides 
/usr/share/emacs/24.3/lisp/textmodes/css-mode
/usr/share/emacs/site-lisp/rst hides /usr/share/emacs/24.3/lisp/textmodes/rst
/usr/share/emacs24/site-lisp/dictionaries-common/ispell hides 
/usr/share/emacs/24.3/lisp/textmodes/ispell
/usr/share/emacs24/site-lisp/dictionaries-common/flyspell hides 
/usr/share/emacs/24.3/lisp/textmodes/flyspell
/usr/share/emacs24/site-lisp/flim/sasl-digest hides 
/usr/share/emacs/24.3/lisp/net/sasl-digest
/usr/share/emacs24/site-lisp/flim/sasl-cram hides 
/usr/share/emacs/24.3/lisp/net/sasl-cram
/usr/share/emacs24/site-lisp/flim/hmac-md5 hides 
/usr/share/emacs/24.3/lisp/net/hmac-md5
/usr/share/emacs24/site-lisp/flim/hmac-def hides 
/usr/share/emacs/24.3/lisp/net/hmac-def
/usr/share/emacs24/site-lisp/flim/sasl-ntlm hides 
/usr/share/emacs/24.3/lisp/net/sasl-ntlm
/usr/share/emacs24/site-lisp/flim/ntlm hides /usr/share/emacs/24.3/lisp/net/ntlm
/usr/share/emacs24/site-lisp/flim/sasl hides /usr/share/emacs/24.3/lisp/net/sasl
/usr/share/emacs24/site-lisp/wl/rfc2368 hides 
/usr/share/emacs/24.3/lisp/mail/rfc2368
/home/naesten/system/emacs/dist/elisp/package hides 
/usr/share/emacs/24.3/lisp/emacs-lisp/package
/home/naesten/system/emacs/dist/elpa/tabulated-list-0/tabulated-list hides 
/usr/share/emacs/24.3/lisp/emacs-lisp/tabulated-list
/usr/share/emacs24/site-lisp/auctex/toolbar-x hides 
/usr/share/emacs/site-lisp/auctex/toolbar-x
/usr/share/emacs24/site-lisp/auctex/tex-style hides 
/usr/share/emacs/site-lisp/auctex/tex-style
/usr/share/emacs24/site-lisp/auctex/tex-bar hides 
/usr/share/emacs/site-lisp/auctex/tex-bar
/usr/share/emacs24/site-lisp/auctex/tex-fold hides 
/usr/share/emacs/site-lisp/auctex/tex-fold
/usr/share/emacs24/site-lisp/auctex/preview hides 
/usr/share/emacs/site-lisp/auctex/preview
/usr/share/emacs24/site-lisp/auctex/context hides 
/usr/share/emacs/site-lisp/auctex/context
/usr/share/emacs24/site-lisp/auctex/context-nl hides 
/usr/share/emacs/site-lisp/auctex/context-nl
/usr/share/emacs24/site-lisp/auctex/prv-emacs hides 
/usr/share/emacs/site-lisp/auctex/prv-emacs
/usr/share/emacs24/site-lisp/auctex/context-en hides 
/usr/share/emacs/site-lisp/auctex/context-en
/usr/share/emacs24/site-lisp/auctex/tex-jp hides 
/usr/share/emacs/site-lisp/auctex/tex-jp
/usr/share/emacs24/site-lisp/auctex/plain-tex hides 
/usr/share/emacs/site-lisp/auctex/plain-tex
/usr/share/emacs24/site-lisp/auctex/bib-cite hides 
/usr/share/emacs/site-lisp/auctex/bib-cite
/usr/share/emacs24/site-lisp/auctex/tex-font hides 
/usr/share/emacs/site-lisp/auctex/tex-font
/usr/share/emacs24/site-lisp/auctex/tex-mik hides 
/usr/share/emacs/site-lisp/auctex/tex-mik
/usr/share/emacs24/site-lisp/auctex/font-latex hides 
/usr/share/emacs/site-lisp/auctex/font-latex
/usr/share/emacs24/site-lisp/auctex/texmathp hides 
/usr/share/emacs/site-lisp/auctex/texmathp
/usr/share/emacs24/site-lisp/auctex/tex-info hides 
/usr/share/emacs/site-lisp/auctex/tex-info
/usr/share/emacs24/site-lisp/auctex/latex hides 
/usr/share/emacs/site-lisp/auctex/latex
/usr/share/emacs24/site-lisp/auctex/multi-prompt hides 
/usr/share/emacs/site-lisp/auctex/multi-prompt
/usr/share/emacs24/site-lisp/auctex/tex hides 
/usr/share/emacs/site-lisp/auctex/tex
/usr/share/emacs24/site-lisp/auctex/tex-buf hides 
/usr/share/emacs/site-lisp/auctex/tex-buf
/usr/share/emacs24/site-lisp/debian-el/preseed hides 
/usr/share/emacs/site-lisp/debian-el/preseed
/usr/share/emacs24/site-lisp/debian-el/gnus-BTS hides 
/usr/share/emacs/site-lisp/debian-el/gnus-BTS
/usr/share/emacs24/site-lisp/debian-el/debian-el hides 
/usr/share/emacs/site-lisp/debian-el/debian-el
/usr/share/emacs24/site-lisp/debian-el/debian-bug hides 
/usr/share/emacs/site-lisp/debian-el/debian-bug
/usr/share/emacs24/site-lisp/debian-el/deb-view hides 
/usr/share/emacs/site-lisp/debian-el/deb-view
/usr/share/emacs24/site-lisp/debian-el/apt-utils hides 
/usr/share/emacs/site-lisp/debian-el/apt-utils
/usr/share/emacs24/site-lisp/debian-el/apt-sources hides 
/usr/share/emacs/site-lisp/debian-el/apt-sources
/usr/share/emacs24/site-lisp/debian-el/debian-el-loaddefs hides 
/usr/share/emacs/site-lisp/debian-el/debian-el-loaddefs
/usr/share/emacs24/site-lisp/html-helper-mode/hhm-config hides 
/usr/share/emacs/site-lisp/html-helper-mode/hhm-config
/usr/share/emacs24/site-lisp/html-helper-mode/visual-basic-mode hides 
/usr/share/emacs/site-lisp/html-helper-mode/visual-basic-mode
/usr/share/emacs24/site-lisp/html-helper-mode/tempo hides 
/usr/share/emacs/site-lisp/html-helper-mode/tempo
/usr/share/emacs24/site-lisp/html-helper-mode/html-helper-mode hides 
/usr/share/emacs/site-lisp/html-helper-mode/html-helper-mode
/usr/share/emacs24/site-lisp/mailcrypt/mc-toplev hides 
/usr/share/emacs/site-lisp/mailcrypt/mc-toplev
/usr/share/emacs24/site-lisp/mailcrypt/mc-remail hides 
/usr/share/emacs/site-lisp/mailcrypt/mc-remail
/usr/share/emacs24/site-lisp/mailcrypt/mc-pgp6 hides 
/usr/share/emacs/site-lisp/mailcrypt/mc-pgp6
/usr/share/emacs24/site-lisp/mailcrypt/mc-pgp5 hides 
/usr/share/emacs/site-lisp/mailcrypt/mc-pgp5
/usr/share/emacs24/site-lisp/mailcrypt/mc-pgp hides 
/usr/share/emacs/site-lisp/mailcrypt/mc-pgp
/usr/share/emacs24/site-lisp/mailcrypt/mc-gpg hides 
/usr/share/emacs/site-lisp/mailcrypt/mc-gpg
/usr/share/emacs24/site-lisp/mailcrypt/mailcrypt hides 
/usr/share/emacs/site-lisp/mailcrypt/mailcrypt
/usr/share/emacs24/site-lisp/mailcrypt/expect hides 
/usr/share/emacs/site-lisp/mailcrypt/expect
/usr/share/emacs24/site-lisp/mailcrypt/mc-setversion hides 
/usr/share/emacs/site-lisp/mailcrypt/mc-setversion
/usr/share/emacs24/site-lisp/psgml/psgml-edit hides 
/usr/share/emacs/site-lisp/psgml/psgml-edit
/usr/share/emacs24/site-lisp/psgml/psgml-charent hides 
/usr/share/emacs/site-lisp/psgml/psgml-charent
/usr/share/emacs24/site-lisp/psgml/psgml hides 
/usr/share/emacs/site-lisp/psgml/psgml
/usr/share/emacs24/site-lisp/psgml/psgml-other hides 
/usr/share/emacs/site-lisp/psgml/psgml-other
/usr/share/emacs24/site-lisp/psgml/psgml-api hides 
/usr/share/emacs/site-lisp/psgml/psgml-api
/usr/share/emacs24/site-lisp/psgml/psgml-sysdep hides 
/usr/share/emacs/site-lisp/psgml/psgml-sysdep
/usr/share/emacs24/site-lisp/psgml/psgml-init hides 
/usr/share/emacs/site-lisp/psgml/psgml-init
/usr/share/emacs24/site-lisp/psgml/psgml-parse hides 
/usr/share/emacs/site-lisp/psgml/psgml-parse
/usr/share/emacs24/site-lisp/psgml/psgml-info hides 
/usr/share/emacs/site-lisp/psgml/psgml-info
/usr/share/emacs24/site-lisp/psgml/psgml-ids hides 
/usr/share/emacs/site-lisp/psgml/psgml-ids
/usr/share/emacs24/site-lisp/psgml/psgml-dtd hides 
/usr/share/emacs/site-lisp/psgml/psgml-dtd
/usr/share/emacs/24.3/lisp/gnus/.dir-locals hides 
/home/naesten/system/emacs/dist/elisp/magit/.dir-locals
/usr/share/emacs24/site-lisp/emacs-goodies-el/markdown-mode hides 
/home/naesten/system/emacs/dist/elisp/markdown-mode/markdown-mode

Features:
(shadow emacsbug etags debug dired-aux mule-diag crm trace reporter
rmailmm rmail winner windmove follow bbdb-hooks bbdb-gnus bbdb-snarf
bbdb-gui tex-info texinfo tex nnweb nnregistry nnnil nnmairix nnir
mm-url gnus-sync json gnus-sieve deuglify gnus-notifications gnus-fun
notifications dbus xml gnus-eform gnus-dup gnus-diary nndiary gnus-demon
gnus-delay gnus-draft gnus-bookmark gnus-salt cus-theme eieio-custom
wid-browse descr-text uudecode info-look gnus-registry registry
eieio-base tmm goto-addr tabify man tramp-cmds noutline outline gnus-cus
boxquote disass gnus-topic canlock two-column iso-transl thingatpt
gnus-kill url-queue shr-color color shr browse-url flow-fill mule-util
sort smiley gnus-cite mail-extr gnus-async gnus-bcklg utf-7 qp gnus-ml
mailcrypt nndoc mm-archive url-http url-gw url-cache url-auth
url-handlers nndraft nnmh parse-time netrc gnutls nnfolder nnagent nnml
network-stream starttls tls gnus-agent gnus-srvr gnus-score score-mode
nnvirtual nntp gnus-cache spam-report spam spam-stat bbdb-com bbdb
timezone gnus-uu yenc gnus-msg gnus-art mm-uu mml2015 epg-config mm-view
mml-smime smime dig gnus-sum nnoo gnus-group gnus-undo nnmail
mail-source gnus-start gnus-spec gnus-int gnus-range message rfc822 mml
mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev
gmm-utils mailheader gnus-win gnus gnus-ems nnheader cperl-mode hideif
cpp cmacexp files-x time-stamp face-remap apropos filladapt cc-langs
inform-mode term disp-table ehelp electric ispell find-dired rst
pcmpl-unix pcmpl-gnu python conf-mode imenu debian-bug
debian-changelog-mode sh-script smie executable vc-sccs vc-svn vc-cvs
vc-rcs vc-dir vc-bzr bzr-dvc bzr tla smerge-mode dvc-state dvc-config
diff sendmail rfc2047 rfc2045 ietf-drums mail-utils tla-gnus dvc-gnus
dvc-cmenu dvc-about dvc-version debian-control-mode help-mode misearch
multi-isearch vc-git xgit-dvc xgit cus-edit xgit-annotate rect
dvc-annotate xgit-log dvc-revlist dvc-diff uniquify dvc-fileinfo
bzr-core tla-core pp tla-autoconf tla-defs dvc-log dvc-unified dvc-tips
dired-x ffap ediff-merg ediff-diff ediff-wind ediff-help ediff-util
ediff-mult ediff-init ediff xdarcs-core xgit-core xhg-core xmtn-minimal
make-mode unsafep dired view magit-bisect magit-key-mode magit
commit-patch-buffer vc vc-dispatcher diff-mode log-edit pcvs-util
add-log server xcscope arc-mode archive-mode asm-mode my-asm
slime-autoloads dvc-autoloads dvc-core dvc-lisp dvc-buffers dvc-ui
dvc-register dvc-utils dvc-emacs ewoc dvc-defs dvc-site jka-compr
dir-locals cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align
cc-engine cc-vars cc-defs eproject esh-var esh-io esh-cmd esh-opt
esh-ext esh-proc esh-arg eldoc esh-groups eshell esh-module esh-mode
esh-util elisp-depend rx ps-print-bg-fixup warnings wgrep grep compile
edebug tramp-cache tramp-sh tramp tramp-compat tramp-loaddefs shell
pcomplete comint ansi-color ring format-spec xt-mouse paren recentf
tree-widget wid-edit diminish cus-start cus-load eldoc-eval-autoloads
elisp-cache-autoloads erc-hl-nicks-autoloads
fill-column-indicator-autoloads find-file-in-git-repo-autoloads
mo-git-blame-autoloads synonyms-autoloads tabulated-list-autoloads info
wgrep-autoloads yagist-autoloads json-autoloads
yasnippet-bundle-autoloads yasnippet-bundle dropdown-list yasnippet
easymenu assoc package derived find-func cl-macs gv w3m-load psgml-init
proof-site proof-autoloads pg-vars mmm-auto mmm-vars mmm-compat cl
mailcrypt-init haskell-mode-autoloads edmacro kmacro emacs-goodies-el
emacs-goodies-custom emacs-goodies-loaddefs easy-mmode dpkg-dev-el
dpkg-dev-el-loaddefs tempo url url-proxy url-privacy url-expand
url-methods url-history url-cookie url-domsuf url-util url-parse
auth-source eieio byte-opt bytecomp byte-compile cconv gnus-util
time-date mm-util mail-prsvr password-cache url-vars mailcap xml-parse
doxymacs develock advice help-fns cl-lib advice-preload debian-el
debian-el-loaddefs bbdb-autoloads preview-latex tex-site auto-loads
tooltip ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar
dnd fontset image regexp-opt fringe tabulated-list newcomment lisp-mode
register page menu-bar rfn-eshadow timer select scroll-bar mouse
jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
minibuffer loaddefs button faces cus-face macroexp files text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process dbusbind
dynamic-setting font-render-setting x-toolkit x multi-tty emacs)

-- 
Hi! I'm a .signature virus! Copy me into your ~/.signature to help me spread!