bug#14293: 23.4; Unclarity in documentation: flet replaced by cl-flet of cl-letf in 24.3 and up.

[Nikolaus Demmel]

This is a documentation bug that is not about my emacs version, but
about the documentation for a change in 24.3. flet has been made
obsolete. This is a follow up to my question on [7], where Drew Adams
suggested I file a bug. From that discussion:

-----
I'm referring to the documentation [1,2,3,4]. Together with the
notification

    `flet' is an obsolete macro (as of 24.3); use either `cl-flet' or
    `cl-letf'.

as reported here [5], this documentation does not really tell me what to
do if I want to keep relying on the dynamic scoping of flet. A brief
google search [6] leads me to believe that

    (cl-letf (((symbol-function 'foo) #'(lambda (...) ...))) ...)

is the suggested solution, however I wanted to make sure that is the
case.
-----

Stefan Monnier has confirmed the suggested solution, but also hinted
that using defadvice might be more appropriate. Maybe the information
about how to precisely replace flet (i.e. same call if using cl-flet,
different syntax if dynamic binding is desired using cl-letf, with an
hint that defadvice might be better) could be included somewhere in the
docs, maybe in [2]?

Thanks,
Niko



[1] 
http://www.gnu.org/software/emacs/manual/html_node/cl/Function-Bindings.html#index-cl_002dflet-24
[2] 
http://www.gnu.org/software/emacs/manual/html_node/cl/Obsolete-Macros.html#index-flet-173
[3] 
http://www.gnu.org/software/emacs/manual/html_node/cl/Obsolete-Macros.html#index-letf-175
[4] 
http://www.gnu.org/software/emacs/manual/html_node/cl/Modify-Macros.html#index-cl_002dletf-19
[5] https://github.com/moesenle/rosemacs-debs/issues/2
[6] 
https://groups.google.com/forum/#!msg/gnu.emacs.help/eaopyFH5hmY/emHfn-DYZZIJ 
[7] 
https://groups.google.com/forum/?fromgroups=#!topic/gnu.emacs.help/eXjBLqncchs



This bug report will be sent to the Free Software Foundation,
not to your local site managers!
Please write in English if possible, because the Emacs maintainers
usually do not have translators to read other languages for them.

Your report will be posted to the bug-gnu-emacs@gnu.org mailing list
and the gnu.emacs.bug news group, and at http://debbugs.gnu.org.

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug.  If you can, give
a recipe starting from `emacs -Q':



If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
For information about debugging Emacs, please read the file
/Applications/Emacs.app/Contents/Resources/etc/DEBUG.


In GNU Emacs 23.4.1 (x86_64-apple-darwin10.8.0, NS apple-appkit-1038.36)
 of 2012-05-21 on MBPdemmel.local
Windowing system distributor `Apple', version 10.3.1038
configured using `configure  '--with-ns' 'LDFLAGS=-L/opt/local/lib' 
'CPPFLAGS=-I/opt/local/include''

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: nil
  value of $XMODIFIERS: nil
  locale-coding-system: nil
  default enable-multibyte-characters: t

Major mode: Text

Minor modes in effect:
  nxhtml-menu-mode: t
  show-paren-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
M-x e m a c s ß r e <backspace> <backspace> <backspace> 
- r e <tab> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> b <tab> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> r e p o <tab> r <tab> <return>

Recent messages:
majmodpri-apply-priorities running ... (done)
Loading /Users/demmeln/.emacs.d/site/nxhtml/nxhtml/nxhtml-autoload...done
... nXhtml loading 0.6 seconds elapsed ...
=== Loaded at nxhtml/autostart.el end:
(feature 'nxhtml-menu)=t
Nxml/Nxhtml Autostart.el loaded in 0.7 seconds
trace: loading flymake-files
Loading /Users/demmeln/.emacs.d/site/nxhtml/autostart.el (source)...done
For information about GNU Emacs and the GNU system, type C-h C-a.
Making completion list...

Load-path shadows:
/Users/demmeln/.emacs.d/site/nxhtml/util/org-panel hides 
~/.emacs.d/site/org-mode/contrib/lisp/org-panel
/Users/demmeln/.emacs.d/site/nxhtml/util/org-odt hides 
~/.emacs.d/site/org-mode/lisp/org-odt
~/.emacs.d/site/python/python hides 
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/python
~/.emacs.d/site/prolog hides 
/Applications/Emacs.app/Contents/Resources/lisp/progmodes/prolog
~/.emacs.d/site/org-mode/lisp/org hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org
~/.emacs.d/site/org-mode/lisp/org-xoxo hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-xoxo
~/.emacs.d/site/org-mode/lisp/org-wl hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-wl
~/.emacs.d/site/org-mode/lisp/org-w3m hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-w3m
~/.emacs.d/site/org-mode/lisp/org-vm hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-vm
~/.emacs.d/site/org-mode/lisp/org-timer hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-timer
~/.emacs.d/site/org-mode/lisp/org-table hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-table
~/.emacs.d/site/org-mode/lisp/org-src hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-src
~/.emacs.d/site/org-mode/lisp/org-rmail hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-rmail
~/.emacs.d/site/org-mode/lisp/org-remember hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-remember
~/.emacs.d/site/org-mode/lisp/org-publish hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-publish
~/.emacs.d/site/org-mode/lisp/org-protocol hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-protocol
~/.emacs.d/site/org-mode/lisp/org-plot hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-plot
~/.emacs.d/site/org-mode/lisp/org-mouse hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-mouse
~/.emacs.d/site/org-mode/lisp/org-mobile hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-mobile
~/.emacs.d/site/org-mode/lisp/org-mhe hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-mhe
~/.emacs.d/site/org-mode/lisp/org-mew hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-mew
~/.emacs.d/site/org-mode/lisp/org-macs hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-macs
~/.emacs.d/site/org-mode/lisp/org-mac-message hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-mac-message
~/.emacs.d/site/org-mode/lisp/org-list hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-list
~/.emacs.d/site/org-mode/lisp/org-latex hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-latex
~/.emacs.d/site/org-mode/lisp/org-jsinfo hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-jsinfo
~/.emacs.d/site/org-mode/lisp/org-irc hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-irc
~/.emacs.d/site/org-mode/lisp/org-install hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-install
~/.emacs.d/site/org-mode/lisp/org-inlinetask hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-inlinetask
~/.emacs.d/site/org-mode/lisp/org-info hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-info
~/.emacs.d/site/org-mode/lisp/org-indent hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-indent
~/.emacs.d/site/org-mode/lisp/org-id hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-id
~/.emacs.d/site/org-mode/lisp/org-icalendar hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-icalendar
~/.emacs.d/site/org-mode/lisp/org-html hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-html
~/.emacs.d/site/org-mode/lisp/org-habit hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-habit
~/.emacs.d/site/org-mode/lisp/org-gnus hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-gnus
~/.emacs.d/site/org-mode/lisp/org-freemind hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-freemind
~/.emacs.d/site/org-mode/lisp/org-footnote hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-footnote
~/.emacs.d/site/org-mode/lisp/org-feed hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-feed
~/.emacs.d/site/org-mode/lisp/org-faces hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-faces
~/.emacs.d/site/org-mode/lisp/org-exp hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-exp
~/.emacs.d/site/org-mode/lisp/org-exp-blocks hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-exp-blocks
~/.emacs.d/site/org-mode/lisp/org-docbook hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-docbook
~/.emacs.d/site/org-mode/lisp/org-datetree hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-datetree
~/.emacs.d/site/org-mode/lisp/org-crypt hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-crypt
~/.emacs.d/site/org-mode/lisp/org-compat hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-compat
~/.emacs.d/site/org-mode/lisp/org-colview hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-colview
~/.emacs.d/site/org-mode/lisp/org-clock hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-clock
~/.emacs.d/site/org-mode/lisp/org-bibtex hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-bibtex
~/.emacs.d/site/org-mode/lisp/org-bbdb hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-bbdb
~/.emacs.d/site/org-mode/lisp/org-attach hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-attach
~/.emacs.d/site/org-mode/lisp/org-ascii hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-ascii
~/.emacs.d/site/org-mode/lisp/org-archive hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-archive
~/.emacs.d/site/org-mode/lisp/org-agenda hides 
/Applications/Emacs.app/Contents/Resources/lisp/org/org-agenda
~/.emacs.d/site/python/sym-comp hides 
/Applications/Emacs.app/Contents/Resources/lisp/obsolete/sym-comp

Features:
(shadow sort mail-extr message ecomplete rfc822 mml mml-sec
password-cache mm-decode mm-bodies mm-encode mailcap mail-parse rfc2231
rfc2047 rfc2045 qp ietf-drums mailabbrev nnheader gnus-util netrc
mm-util mail-prsvr gmm-utils wid-edit mailheader canlock hashcash
mail-utils emacsbug help-mode view flymake-files flymakemsg
nxhtml-autostart nxhtml-autoload majmodpri vc-bzr sha1 hex-util
nxhtml-menu web-autoload nxhtml-base paredit-zoink paredit
slime-autoloads cc-mode cc-fonts cc-menus cc-cmds cc-styles cc-align
cc-engine cc-vars cc-defs hs-lint tex-site auto-loads ido ielm pp
edmacro kmacro ob-dot ob-ditaa ob-R org-latex org-export-latex
org-beamer org-exp ob-exp org-exp-blocks org-agenda org byte-opt
warnings bytecomp byte-compile advice help-fns advice-preload
ob-emacs-lisp ob-tangle ob-ref ob-lob ob-table org-footnote org-src
ob-comint ob-keys ob ob-eval org-pcomplete pcomplete org-list org-faces
org-compat org-entities org-macs time-date noutline outline cal-menu
calendar cal-loaddefs footnote org-install flymake python-21 python
skeleton info derived regexp-opt rx sym-comp hippie-exp
fill-column-indicator easy-mmode grep compile comint ring paren tooltip
ediff-hook vc-hooks lisp-float-type mwheel ns-win easymenu 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 files text-properties overlay md5 base64 format env code-pages
mule custom widget hashtable-print-readable backquote
make-network-process dbusbind ns multi-tty emacs)