exporting patch:
# HG changeset patch
# User Daniel J Sebald <daniel.sebald@ieee.org>
# Date 1514775381 21600
#      Sun Dec 31 20:56:21 2017 -0600
# Node ID 88575904620377b89a3624110405e891389cb820
# Parent  0a567c6489ef7c59b47519aeda63c355056f768d
Add a help entry and documentation for @ character (bug #52771)

expr.txi: Add sub-node (sub-subsection) "Access via handle" to the "Calling
  Functions" node (section).  Don't indent an paragraph that refers to the
  previous example.  Provide the body for the "Access via handle" node and
  include an opindex entry.  Mention that '@' is also used for class methods
  and reference the "Object Oriented Programming" chapter.

oop.txi: Add an opindex reference to '@' so a quick index link is created.

op-kw-docs: Create an operator index entry for '@'.  Mention that '@' is also
  used for class methods and suggest seeing the "Object Oriented Programming"
  chapter of the manual.

diff --git a/doc/interpreter/expr.txi b/doc/interpreter/expr.txi
--- a/doc/interpreter/expr.txi
+++ b/doc/interpreter/expr.txi
@@ -388,6 +388,7 @@ expressions.  See also @ref{Index Expres
 @menu
 * Call by Value::
 * Recursion::
+* Access via handle::
 @end menu
 
 @node Call by Value
@@ -483,6 +484,7 @@ endfunction
 @end group
 @end example
 
+@noindent
 This function is recursive because it calls itself directly.  It
 eventually terminates because each time it calls itself, it uses an
 argument that is one less than was used for the previous call.  Once the
@@ -494,6 +496,53 @@ the recursion depth and prevents Octave 
 
 @DOCSTRING(max_recursion_depth)
 
+@node Access via handle
+@subsection Access via handle
+@cindex function handle
+@cindex indirect function call
+@opindex @@
+
+A function may be abstracted and referenced via a function handle acquired
+using the special operator @samp{@@}.  For example,
+
+@example
+@group
+a = @@sprintf;
+(a)("hello world")
+@end group
+@end example
+
+@noindent
+is equivalent to calling @code{sprintf("hello world")} directly.  Beyond
+abstraction for general programming, function handles find use in callback
+methods for figures and graphics by adding listeners to properties or
+assigning pre-existing actions, such as in the following example:
+
+@cindex figure deletefcn
+@example
+@group
+function mydelete (h, dummy, mystr)
+  printf(mystr);
+endfunction
+sombrero;
+set (gcf, "deletefcn", @{@@mydelete, "Bye!\n"@});
+close;
+@end group
+@end example
+
+@noindent
+The above will print "Bye!" to the terminal upon the closing (deleting) of
+the figure.  There are many graphics property actions for which a callback
+function may be assigned, including, @code{buttondownfcn},
+@code{windowscrollwheelfcn}, @code{createfcn}, @code{deletefcn},
+@code{keypressfcn}, etc.
+
+Note that the @samp{@@} character also plays a role in defining class
+functions, i.e., methods, but not as a syntactical element.  Rather it
+begins a directory name containing methods for a class that shares
+the directory name sans the @samp{@@} character.  See
+@ref{Object Oriented Programming}.
+
 @node Arithmetic Ops
 @section Arithmetic Operators
 @cindex arithmetic operators
diff --git a/doc/interpreter/oop.txi b/doc/interpreter/oop.txi
--- a/doc/interpreter/oop.txi
+++ b/doc/interpreter/oop.txi
@@ -81,6 +81,7 @@ Thus the polynomial can be represented b
 a = [a0, a1, a2, @dots{}, an];
 @end example
 
+@opindex @@
 This is a sufficient specification to begin writing the constructor for the
 polynomial class.  All object oriented classes in Octave must be located in a
 directory that is the name of the class prepended with the @samp{@@} symbol.
diff --git a/libinterp/op-kw-docs b/libinterp/op-kw-docs
--- a/libinterp/op-kw-docs
+++ b/libinterp/op-kw-docs
@@ -380,6 +380,25 @@ Element by element logical 'or' operator
 Logical 'or' (with short-circuit evaluation) operator.
 @seealso{|, or}
 @end deftypefn
+@
+@c libinterp/parse-tree/oct-parse.in.yy
+-*- texinfo -*-
+@deftypefn {} {} @@
+Acquire function handle.
+
+Example:
+
+@example
+@group
+a = @@sprintf;
+(a)("hello world")
+@end group
+@end example
+
+(Note: @@ also finds use in creating classes.  See manual chapter titled
+Object Oriented Programming for detailed description.)
+@seealso{function, functions, func2str, str2func, addlistener, dellistener}
+@end deftypefn
 break
 @c libinterp/parse-tree/oct-parse.in.yy
 -*- texinfo -*-
