bug#15226: 24.3; frame-background-mode docstring on not setq

[Kevin Ryde]

The docstring of frame-background-mode says

    Don't set this variable with `setq'; this won't have the expected
    effect.

but doesn't say what you should in fact do.  Perhaps something like
below.  Unless frame-set-background-mode is meant to be internals ...

2013-08-31  Kevin Ryde  <user42@zip.com.au>

        * frame.el (frame-background-mode): Docstring describe
        frame-set-background-mode after setting and suggest
        custom-set-variables from .emacs.

diff -c /down/emacs-bzr/lisp/frame.el.orig /down/emacs-bzr/lisp/frame.el
*** /down/emacs-bzr/lisp/frame.el.orig  2013-08-31 10:01:50.000000000 +1000
--- /down/emacs-bzr/lisp/frame.el       2013-08-31 10:23:16.000000000 +1000
***************
*** 872,879 ****
    "The brightness of the background.
  Set this to the symbol `dark' if your background color is dark,
  `light' if your background is light, or nil (automatic by default)
! if you want Emacs to examine the brightness for you.  Don't set this
! variable with `setq'; this won't have the expected effect."
    :group 'faces
    :set #'(lambda (var value)
           (set-default var value)
--- 872,886 ----
    "The brightness of the background.
  Set this to the symbol `dark' if your background color is dark,
  `light' if your background is light, or nil (automatic by default)
! if you want Emacs to examine the brightness for you.
! 
! If this variable is changed with `setq' then call
! `frame-set-background-mode' on each frame to update existing
! faces.  The customize interface updates after setting and that
! can be used from .emacs or similar with for example
! 
!     (custom-set-variables '(frame-background-mode 'dark))"
! 
    :group 'faces
    :set #'(lambda (var value)
           (set-default var value)

Diff finished.  Sat Aug 31 10:23:38 2013



In GNU Emacs 24.3.1 (i486-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2013-05-29 on blah.blah, modified by Debian
System Description:     Debian GNU/Linux unstable (sid)

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'
 'build_alias=i486-linux-gnu' 'CFLAGS=-g -O2 -fstack-protector
 --param=ssp-buffer-size=4 -Wformat -Werror=format-security -Wall'
 'LDFLAGS=-Wl,-z,relro -Wl,-znocombreloc'
 'CPPFLAGS=-D_FORTIFY_SOURCE=2''

Important settings:
  value of $LANG: en_AU
  locale-coding-system: iso-latin-1-unix
  default enable-multibyte-characters: t