bug#4869: 23.1.50; weak documentation of prefer-coding-system

[Joseph Brenner]

The function prefer-coding-system does not explain if the CODING-SYSTEM
argument must be a symbol or a string (or either).

Without seeing a code example, a user might try using a quoted string:

   (prefer-coding-system "utf-8")

In which case, the error message is very confusing (this makes it sound
as though utf-8 is not supported):

   error: Invalid coding system `utf-8'

At a minimum, the documentation should be made more explicit, and I
would strongly suggest adding a code example:

   (prefer-coding-system 'utf-8)


In GNU Emacs 23.1.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 2.16.1)
 of 2009-10-22 on fineline
Windowing system distributor `The X.Org Foundation', version 11.0.10600000
configured using `configure  '--prefix' '/usr/local/emacs/cvs-102209''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Text

Minor modes in effect:
  shell-dirtrack-mode: t
  display-time-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
<return> g f C-x 1 s C-p C-p C-p C-p <return> SPC SPC
<return> C-p C-p o C-n C-n + P i c k <return> C-n R
P i r SPC <backspace> c SPC <return> <return> SPC <return>
C-p C-p f o <backspace> C-n C-x 2 C-x o M-x s h e l
l <return> k 3 b SPC & <return> C-x 0 C-x 2 ^ ^ ^ g
C-n f g f g C-n o C-p s C-n C-p C-p C-p C-p C-p C-p
C-p C-p C-p o g o C-n C-n C-n C-n C-n o <switch-frame>
<switch-frame> <switch-frame> <switch-frame> C-x o
g ^ g ^ g C-x 0 g C-x 5 0 C-x C-b C-x o C-n C-n C-n
C-n C-n C-n C-n C-n <escape> < C-s n o t e s - C-a
f <escape> > C-n C-n C-y C-a C-k C-y C-x C-x C-p C-o
C-o D r e w SPC A d m a <backspace> <backspace> a m
s SPC n u d g e s SPC m e SPC t o SPC d o SPC a SPC
b u f <backspace> g SPC r e p o r t : C-x C-s C-x C-p
M-x d o o m SPC r e v SPC <return> C-x o C-x C-g C-a
C-n C-x C-o C-x C-s C-n C-l C-n C-n C-n C-n C-k C-n
C-k C-k C-k C-x C-o C-x C-s C-n C-n C-n C-n C-n M-f
M-b M-h v <return> M-h f <return> C-SPC M-f M-f M-f
M-w C-x C-p M-h i u u u <return> s C-y <return> <prior>
u u u C-n C-n C-n C-n C-n C-n C-a <return> s <return>
s <return> s <return> C-x 0 C-a M-x r e p o r t SPC
e m SPC b SPC <return>

Recent messages:
Searching subfile elisp-2...
Searching subfile elisp-3...
Searching subfile elisp-4...
Searching subfile elisp-5...
Searching subfile elisp-6...
Searching subfile elisp-7...
Searching subfile elisp-8...
Searching subfile elisp-9...
Searching subfile elisp-10...
Searching subfile elisp-11...
Info-search: Search failed: "prefer-coding-system"

Load-path shadows:
/home/doom/End/Cave/DesktopAutosave/lib/emacs/desktop-recover-setup hides 
/home/doom/lib/emacs/Dots/desktop-recover-setup
/home/doom/End/Cave/DiredExternalApps/lib/emacs/image-dired hides 
/home/doom/lib/emacs/image-dired
/home/doom/End/Cave/DiredExternalApps/lib/emacs/dired-external-apps hides 
/home/doom/lib/emacs/dired-external-apps
/home/doom/lib/emacs/Dots/setup-colors-dark hides 
/home/doom/lib/emacs/setup-colors-dark
/usr/local/emacs/cedet-1.0pre6/speedbar/speedbar hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/speedbar
/home/doom/lib/emacs/Dots/strokes hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/strokes
/usr/local/emacs/cedet-1.0pre6/speedbar/sb-image hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/sb-image
/home/doom/End/Cave/DiredExternalApps/lib/emacs/image-dired hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/image-dired
/usr/local/emacs/cedet-1.0pre6/common/ezimage hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/ezimage
/usr/local/emacs/cedet-1.0pre6/speedbar/dframe hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/dframe
/home/doom/End/Cave/DesktopAutosave/lib/emacs/desktop hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/desktop
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-xface hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-xface
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-folder hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-folder
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-comp hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-comp
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-utils hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-utils
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-thread hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-thread
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-speed hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-speed
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-show hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-show
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-seq hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-seq
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-search hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-search
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-print hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-print
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-mime hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-mime
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-limit hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-limit
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-letter hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-letter
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-tool-bar hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-tool-bar
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-inc hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-inc
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-junk hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-junk
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-funcs hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-funcs
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-scan hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-scan
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-alias hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-alias
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-e hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-e
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-buffers hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-buffers
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-loaddefs hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-loaddefs
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-gnus hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-gnus
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-compat hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-compat
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-acros hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-acros
/usr/local/emacs/cvs-032909/share/emacs/23.0.91/lisp/mh-e/mh-identity hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/mh-e/mh-identity
/home/doom/lib/emacs/Dots/gnus-setup hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/gnus/gnus-setup
/usr/local/emacs/cedet-1.0pre6/eieio/eieio-base hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/eieio-base
/usr/local/emacs/cedet-1.0pre6/eieio/eieio-speedbar hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/eieio-speedbar
/usr/local/emacs/cedet-1.0pre6/eieio/eieio-opt hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/eieio-opt
/usr/local/emacs/cedet-1.0pre6/eieio/eieio-comp hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/eieio-comp
/usr/local/emacs/cedet-1.0pre6/eieio/eieio hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/eieio
/usr/local/emacs/cedet-1.0pre6/eieio/eieio-datadebug hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/eieio-datadebug
/usr/local/emacs/cedet-1.0pre6/eieio/chart hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/chart
/usr/local/emacs/cedet-1.0pre6/eieio/eieio-custom hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/emacs-lisp/eieio-custom
/usr/local/emacs/cedet-1.0pre6/srecode/srecode hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/srecode
/usr/local/emacs/cedet-1.0pre6/common/cedet-files hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/cedet-files
/usr/local/emacs/cedet-1.0pre6/common/cedet-cscope hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/cedet-cscope
/usr/local/emacs/cedet-1.0pre6/semantic/semantic hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/semantic
/usr/local/emacs/cedet-1.0pre6/common/pulse hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/pulse
/usr/local/emacs/cedet-1.0pre6/common/mode-local hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/mode-local
/usr/local/emacs/cedet-1.0pre6/common/inversion hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/inversion
/usr/local/emacs/cedet-1.0pre6/ede/ede hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/ede
/usr/local/emacs/cedet-1.0pre6/common/data-debug hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/data-debug
/usr/local/emacs/cedet-1.0pre6/common/cedet hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/cedet
/usr/local/emacs/cedet-1.0pre6/common/cedet-idutils hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/cedet-idutils
/usr/local/emacs/cedet-1.0pre6/common/cedet-global hides 
/usr/local/emacs/cvs-102209/share/emacs/23.1.50/lisp/cedet/cedet-global

Features:
(shadow mail-extr message ecomplete rfc822 nnheader gmm-utils mailheader
canlock sha1 hex-util hashcash mail-utils emacsbug eieio-opt help-mode
view image-mode vc vc-dispatcher ispell sh-script nroff-mode sb-info
info vc-rcs thingatpt desktop-recover newcomment rect mule-util
semantic-tag-file semantic-tag-write eldoc semanticdb-typecache
semanticdb-find semanticdb-ref executable semantic-c semantic-dep
semantic-gcc semantic-c-by semantic-lex-spp css-mode mmm-sample
mmm-mason mmm-mode mmm-univ mmm-class mmm-region mmm-utils semantic-html
html-mode jsp-html-helper-mode asp-html-helper-mode php-html-helper-mode
html-helper-mode tempo cc-mode cc-fonts cc-menus cc-cmds cc-styles
cc-align cc-engine cc-vars cc-defs semantic-decorate-mode
semantic-decorate pulse vc-git semanticdb-file semantic-edit semantic-el
semantic-bovine bovine-debug semantic-debug multi-isearch ede-dired
mh-utils mh-folder desktop doom-fineline ansi-color registers-defined
strokes macroman doom-filters find_and_replace doom-mh mh-comp sendmail
mh-scan mh-gnus mml mml-sec mm-view smime password-cache dig mm-decode
mm-bodies mm-encode mailcap mail-parse rfc2231 rfc2047 rfc2045
ietf-drums qp mm-util mail-prsvr gnus-util netrc time-date mh-e
mh-compat mailabbrev mh-acros mh-buffers mh-loaddefs mhe-setup
fugly-keystroke-macros dired-imagery-doomery-keystroke-macros
image-dired thinknow picture doomfile doomfiles-hacking-setup
caving-setup w3m-load mmm-auto mmm-vars mmm-compat generic-x mmm-setup
html-setup senator which-func semantic-imenu semantic-sb imenu
semantic-mru-bookmark semanticdb-mode semantic-idle ede-simple
cedet-files ede-linux ede-emacs ede-cpp-root cedet cedet-contrib-load
contrib-loaddefs cogre-load cogre-loaddefs speedbar-load
speedbar-loaddefs ede-load ede-loaddefs ede-speedbar ede-files ede
eieio-speedbar semantic-ia-sb semantic-analyze semantic-scope
semantic-analyze-fcn semantic-sort semanticdb-el semanticdb-search
semantic-find semanticdb semantic-ctxt semantic-format
semantic-util-modes semantic-util semantic semantic-lex semantic-tag
working fame speedbar sb-image ezimage dframe assoc eieio-custom
ede-source eieio-base srecode-load srecode srecode-loaddefs
semantic-load semantic-fw semantic-loaddefs mode-local eieio-load
eieio-loaddefs cedet-load cedet-compat cedet-loaddefs eieio inversion
apache-dev sgml-mode sepia edmacro kmacro sepia-cpan sepia-ido ido
sepia-tree tree-widget sepia-w3m w3m-perldoc w3m browse-url timezone
w3m-hist w3m-e22 wid-edit w3m-ccl ccl w3m-fsf w3m-favicon w3m-image
w3m-proc w3m-util gud easy-mmode cperl-mode perlnow easymenu template
perlnow-wrapper perl-setup elisp-hacking-setup doom-print printer-setup
shell-setup perlups derived byte-opt bytecomp byte-compile jka-compr
find-func timeclock-x timeclock timeclock-setup junk-o-doom text-setup
live-dangerously datestamps shell comint ring dired-external-apps
diredonsequences dired-setup info-to-registers basic-keymap-changes
paracide redroot simple-color-change setup-colors-dark dired-x dired-aux
dired regexp-opt paren uniquify advice help-fns advice-preload server
time emacs-setup cl cl-19 load-path-setup tooltip ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image fringe
lisp-mode register page menu-bar rfn-eshadow timer select scroll-bar
mldrag 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 loaddefs button minibuffer faces cus-face text-properties overlay
md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process dbusbind gtk
x-toolkit x multi-tty emacs)