Commit 122ff675 authored by Stefan Monnier's avatar Stefan Monnier

* doc/lispref/functions.texi (Advising Functions): New section.

* doc/lispref/modes.texi (Running Hooks): Don't document with-wrapper-hook and
run-hook-wrapped any more.
(Hooks): Link to the new Advising Functions node.
* doc/lispref/elisp.texi (Top): Don't include advice.texi.
* doc/lispref/advice.texi: Remove.
* doc/lispref/makefile.w32-in (srcs):
* doc/lispref/Makefile.in (srcs): Adjust accordingly.
* doc/misc/cl.texi (Function Bindings): Fix incorrect description of cl-let.
parent cd6d07ec
......@@ -218,7 +218,6 @@ xresources.texi cyd
** Check the Lisp manual.
abbrevs.texi rgm
advice.texi cyd
anti.texi rgm
back.texi rgm
backups.texi cyd
......
2014-01-10 Stefan Monnier <monnier@iro.umontreal.ca>
* functions.texi (Advising Functions): New section.
* modes.texi (Running Hooks): Don't document with-wrapper-hook and
run-hook-wrapped any more.
(Hooks): Link to the new Advising Functions node.
* elisp.texi (Top): Don't include advice.texi.
* advice.texi: Remove.
* makefile.w32-in (srcs):
* Makefile.in (srcs): Adjust accordingly.
2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de>
* text.texi (Parsing HTML/XML): Document `shr-insert-document'.
......
......@@ -76,7 +76,6 @@ srcs = \
$(srcdir)/elisp.texi \
$(emacsdir)/emacsver.texi \
$(srcdir)/abbrevs.texi \
$(srcdir)/advice.texi \
$(srcdir)/anti.texi \
$(srcdir)/backups.texi \
$(srcdir)/buffers.texi \
......
This diff is collapsed.
......@@ -194,7 +194,6 @@ To view this manual in other formats, click
* Loading:: Reading files of Lisp code into Lisp.
* Byte Compilation:: Compilation makes programs run faster.
* Advising Functions:: Adding to the definition of a function.
* Debugging:: Tools and tips for debugging Lisp programs.
* Read and Print:: Converting Lisp objects to text and back.
......@@ -614,19 +613,6 @@ Byte Compilation
* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
Advising Emacs Lisp Functions
* Simple Advice:: A simple example to explain the basics of advice.
* Defining Advice:: Detailed description of @code{defadvice}.
* Around-Advice:: Wrapping advice around a function's definition.
* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
* Activation of Advice:: Advice doesn't do anything until you activate it.
* Enabling Advice:: You can enable or disable each piece of advice.
* Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments.
* Combined Definition:: How advice is implemented.
Debugging Lisp Programs
* Debugger:: A debugger for the Emacs Lisp evaluator.
......@@ -1561,7 +1547,6 @@ Object Internals
@include customize.texi
@include loading.texi
@include compile.texi
@include advice.texi
@c This includes edebug.texi.
@include debugging.texi
......
This diff is collapsed.
......@@ -49,7 +49,6 @@ texinputdir = $(srcdir)\..\..\nt\envadd.bat \
srcs = \
$(emacsdir)/emacsver.texi \
$(srcdir)/abbrevs.texi \
$(srcdir)/advice.texi \
$(srcdir)/anti.texi \
$(srcdir)/backups.texi \
$(srcdir)/buffers.texi \
......
......@@ -69,11 +69,13 @@ functions are called with arguments, or their return values are used
in some way. The hook's documentation says how the functions are
called. You can use @code{add-hook} to add a function to an abnormal
hook, but you must write the function to follow the hook's calling
convention.
convention. By convention, abnormal hook names end in @samp{-functions}.
By convention, abnormal hook names end in @samp{-functions}. If the
variable's name ends in @samp{-function}, then its value is just a single
function, not a list of functions.
@cindex single-function hook
If the variable's name ends in @samp{-function}, then its value is
just a single function, not a list of functions. @code{add-hook} cannot be
used to modify such a @emph{single function hook}, and you have to use
@code{add-function} instead (@pxref{Advising Functions}).
@menu
* Running Hooks:: How to run a hook.
......@@ -129,47 +131,6 @@ non-@code{nil} value, it returns that value; otherwise it returns
@code{nil}.
@end defun
@defmac with-wrapper-hook hook args &rest body
This macro runs the abnormal hook @code{hook} as a series of nested
``wrapper functions'' around the @var{body} forms. The effect is
similar to nested @code{around} advices (@pxref{Around-Advice}).
Each hook function should accept an argument list consisting of a function
@var{fun}, followed by the additional arguments listed in @var{args}.
The first hook function is passed a function @var{fun} that, if it is
called with arguments @var{args}, performs @var{body} (i.e., the default
operation). The @var{fun} passed to each successive hook function is
constructed from all the preceding hook functions (and @var{body}); if
this @var{fun} is called with arguments @var{args}, it does what the
@code{with-wrapper-hook} call would if the preceding hook functions were
the only ones in @var{hook}.
Each hook function may call its @var{fun} argument as many times as it
wishes, including never. In that case, such a hook function acts to
replace the default definition altogether, and any preceding hook
functions. Of course, a subsequent hook function may do the same thing.
Each hook function definition is used to construct the @var{fun} passed
to the next hook function in @var{hook}, if any. The last or
``outermost'' @var{fun} is called once to produce the overall effect.
When might you want to use a wrapper hook? The function
@code{filter-buffer-substring} illustrates a common case. There is a
basic functionality, performed by @var{body}---in this case, to extract
a buffer-substring. Then any number of hook functions can act in
sequence to modify that string, before returning the final result.
A wrapper-hook also allows for a hook function to completely replace the
default definition (by not calling @var{fun}).
@end defmac
@defun run-hook-wrapped hook wrap-function &rest args
This function is similar to @code{run-hook-with-args-until-success}.
Like that function, it runs the functions on the abnormal hook
@code{hook}, stopping at the first one that returns non-@code{nil}.
Instead of calling the hook functions directly, though, it actually
calls @code{wrap-function} with arguments @code{fun} and @code{args}.
@end defun
@node Setting Hooks
@subsection Setting Hooks
......
2014-01-10 Stefan Monnier <monnier@iro.umontreal.ca>
* cl.texi (Function Bindings): Fix incorrect description of cl-let.
2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de>
* Makefile.in: Add eww.texi.
......@@ -18,8 +22,8 @@
(Advanced configuration)
(Header arguments in Org mode properties): Spelling fixes.
(Special blocks): Add #+BEGIN_ABSTRACT as another example.
(@LaTeX{} specific attributes): New index entries. Use
#+BEGIN_ABSTRACT in the example.
(@LaTeX{} specific attributes): New index entries.
Use #+BEGIN_ABSTRACT in the example.
2013-01-07 Nicolas Goaziou <n.goaziou@gmail.com>
......@@ -80,7 +84,7 @@
2014-01-02 Aidan Gauland <aidalgol@amuri.net>
* eshell.texi (Command Basics): Removed `Command basics' chapter.
* eshell.texi (Command Basics): Remove `Command basics' chapter.
2014-01-02 Aidan Gauland <aidalgol@amuri.net>
......@@ -200,8 +204,8 @@
* org.texi (Orgstruct mode): Fix suggested setting of
`orgstruct-heading-prefix-regexp'.
* org.texi (Export settings): Document
`org-export-allow-bind-keywords'.
* org.texi (Export settings):
Document `org-export-allow-bind-keywords'.
* org.texi (History and Acknowledgments): Small rephrasing.
......@@ -209,8 +213,8 @@
in a year datetree.
* org.texi (Beamer export, @LaTeX{} and PDF export)
(Header and sectioning, @LaTeX{} specific attributes): Enhance
style.
(Header and sectioning, @LaTeX{} specific attributes):
Enhance style.
* org.texi (Agenda commands): Add a footnote about dragging agenda
lines: it does not persist and it does not change the .org files.
......@@ -229,15 +233,15 @@
* org.texi (Other built-in back-ends): New section.
* org.texi (Editing source code): Document
`org-edit-src-auto-save-idle-delay' and
* org.texi (Editing source code):
Document `org-edit-src-auto-save-idle-delay' and
`org-edit-src-turn-on-auto-save'.
* org.texi (External links): Document contributed link types
separately.
* org.texi (Closing items): Document
`org-closed-keep-when-no-todo'.
* org.texi (Closing items):
Document `org-closed-keep-when-no-todo'.
* org.texi (Export back-ends): Rename from "Export formats".
(The Export Dispatcher): Remove reference to
......@@ -273,8 +277,8 @@
(Agenda commands): Move details about filtering commands to
the new section, only include a summary here.
(Customizing tables in ODT export)
(System-wide header arguments, Conflicts, Dynamic blocks): Use
spaces for indentation.
(System-wide header arguments, Conflicts, Dynamic blocks):
Use spaces for indentation.
* org.texi (Emphasis and monospace): Mention `org-emphasis-alist'.
......@@ -331,8 +335,8 @@
(In-buffer settings): Update to reflect changes from the new
export engine.
* org.texi (Matching tags and properties): More examples. Explain
group tags expansion as regular expressions.
* org.texi (Matching tags and properties): More examples.
Explain group tags expansion as regular expressions.
* org.texi (Tag groups): New section.
......@@ -357,8 +361,8 @@
* org.texi (Org syntax): New section.
* org.texi (Orgstruct mode): Document
`orgstruct-heading-prefix-regexp'.
* org.texi (Orgstruct mode):
Document `orgstruct-heading-prefix-regexp'.
* org.texi (Speeding up your agendas): New section.
......@@ -382,8 +386,8 @@
* org.texi: Update the list contributions.
* org.texi (Agenda commands): Exporting the agenda to an .org file
will not copy the subtrees and the inherited tags. Document
`org-agenda-filter-by-regexp'.
will not copy the subtrees and the inherited tags.
Document `org-agenda-filter-by-regexp'.
* org.texi (Publishing action, Complex example): Fix names of
publishing functions.
......@@ -397,8 +401,8 @@
* org.texi (Capture): Mention that org-remember.el is not
supported anymore.
* org.texi (Top, Exporting, Beamer class export): Delete
references to the TaskJuggler export.
* org.texi (Top, Exporting, Beamer class export):
Delete references to the TaskJuggler export.
(History and Acknowledgments): Mention that the TaskJuggler has
been rewritten by Nicolas and now lives in the contrib/ directory
of Org's distribution. Mention that Jambunathan rewrote the HTML
......@@ -415,16 +419,16 @@
(@LaTeX{} and PDF export, Header and sectioning)
(Publishing options): Fix LaTeX options names.
* org.texi (Export options, CSS support, In-buffer settings): Fix
references to HTML_LINK_* and HTML_STYLE keywords.
* org.texi (Export options, CSS support, In-buffer settings):
Fix references to HTML_LINK_* and HTML_STYLE keywords.
* org.texi (Export options, In-buffer settings): Fix references to
#+SELECT_TAGS and #+EXCLUDE_TAGS and remove reference to #+XSLT.
* org.texi (Top, Markup, Initial text, Images and tables)
(@LaTeX{} fragments, @LaTeX{} fragments, Exporting)
(Export options, JavaScript support, Beamer class export): Remove
references to the DocBook export, which has been deleted.
(Export options, JavaScript support, Beamer class export):
Remove references to the DocBook export, which has been deleted.
(History and Acknowledgments): Mention that DocBook has been
deleted, suggest to use the Texinfo exporter instead, then to
convert the .texi to DocBook with makeinfo.
......@@ -433,8 +437,8 @@
* org.texi (Deadlines and scheduling): Add a variable to the
index. Add documentation about delays for scheduled tasks.
* org.texi (Emphasis and monospace): Mention
`org-fontify-emphasized-text' and
* org.texi (Emphasis and monospace):
Mention `org-fontify-emphasized-text' and
`org-emphasis-regexp-components'.
* org.texi (References): Small enhancement.
......@@ -491,7 +495,7 @@
* org.texi (Extracting source code): Mention the prefix argument
to org-babel-tangle.
(noweb): Removed erroneous negative.
(noweb): Remove erroneous negative.
(Specific header arguments): Document new header arguments.
Documentation for new tangle-mode header argument.
(Top): Documentation for new tangle-mode header argument.
......@@ -595,8 +599,8 @@
* org.texi (Header and sectioning): Add a footnote about the
different between LATEX_HEADER_EXTRA and LATEX_HEADER.
* org.texi (The Export Dispatcher): Document
`org-export-in-background'.
* org.texi (The Export Dispatcher):
Document `org-export-in-background'.
* org.texi (Footnotes): Export back-ends do not use
`org-footnote-normalize' anymore.
......@@ -618,19 +622,19 @@
* org.texi (Include files): Remove reference to :prefix1
and :prefix. Give more details for :minlevel.
* org.texi (Macro replacement): Fix macro name. Update
documentation about possible locations and escaping mechanism.
* org.texi (Macro replacement): Fix macro name.
Update documentation about possible locations and escaping mechanism.
* org.texi (Table of contents): Update documentation. Document
lists of listings and lists of tables. Add documentation for
* org.texi (Table of contents): Update documentation.
Document lists of listings and lists of tables. Add documentation for
optional title and #+TOC: keyword.
2013-11-12 Rick Frankel <rick@rickster.com>
* org.texi (results): Add Format section, broken out of Type
section to match code.
(hlines, colnames): Remove incorrect Emacs Lisp exception. Note
that the actual default handling (at least for python and
(hlines, colnames): Remove incorrect Emacs Lisp exception.
Note that the actual default handling (at least for python and
emacs-lisp) does not seem to match the description.
2013-11-12 Sacha Chua <sacha@sachachua.com> (tiny change)
......@@ -640,8 +644,8 @@
2013-11-12 Yasushi Shoji <yashi@atmark-techno.com>
* org.texi (Resolving idle time): Document
`org-clock-x11idle-program-name'.
* org.texi (Resolving idle time):
Document `org-clock-x11idle-program-name'.
2013-10-24 Michael Albinus <michael.albinus@gmx.de>
......@@ -882,8 +886,8 @@
2013-07-29 Michael Albinus <michael.albinus@gmx.de>
* tramp.texi (Frequently Asked Questions): Mention
`tramp-use-ssh-controlmaster-options'.
* tramp.texi (Frequently Asked Questions):
Mention `tramp-use-ssh-controlmaster-options'.
2013-07-26 Tassilo Horn <tsdh@gnu.org>
......@@ -927,8 +931,8 @@
2013-07-08 Tassilo Horn <tsdh@gnu.org>
* gnus.texi (lines): Correct description of
`gnus-registry-track-extra's default value. Mention
`gnus-registry-remove-extra-data'.
`gnus-registry-track-extra's default value.
Mention `gnus-registry-remove-extra-data'.
2013-07-06 Lars Ingebrigtsen <larsi@gnus.org>
......
......@@ -1282,13 +1282,8 @@ cells of symbols rather than on the value cells. Each @var{binding}
must be a list of the form @samp{(@var{name} @var{arglist}
@var{forms}@dots{})}, which defines a function exactly as if
it were a @code{cl-defun} form. The function @var{name} is defined
accordingly for the duration of the body of the @code{cl-flet}; then
the old function definition, or lack thereof, is restored.
You can use @code{cl-flet} to disable or modify the behavior of
functions (including Emacs primitives) in a temporary, localized fashion.
(Compare this with the idea of advising functions.
@xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.)
accordingly but only within the body of the @code{cl-flet}, hiding any external
definition if applicable.
The bindings are lexical in scope. This means that all references to
the named functions must appear physically within the body of the
......
......@@ -905,6 +905,7 @@ It is only available if Emacs is compiled with libxml2 support.
symbol_words as a single word, similar to what `subword-mode' does and
using the same internal functions.
+++
** New package nadvice.el offers lighter-weight advice facilities.
It is layered as:
- add-function/remove-function which can be used to add/remove code on any
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment