doc: improved documentation of optional #+call: line header arguments

* doc/org.texi (Evaluating code blocks):  Expanded discussion of
  #+call: line syntax.
  (Header arguments in function calls):  Expanded discussion of #+call:
  line syntax.

1 files changed, 32 insertions, 14 deletions

diff --git a/doc/org.texi b/doc/org.texi
index 409f94f..4d696ae 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11376,28 +11376,36 @@ blocks located in the current Org-mode buffer or in the ``Library of Babel''
 #+lob: <name>(<arguments>) <header arguments>
 @end example
 
-All variable (@code{:var}) header arguments can be placed in the
-@code{<arguments>} section using normal function call syntax. For example:
-
-@example
-#+source: double
-#+begin_src emacs-lisp :var n=2
-  (* n 2)
-#+end_src
-
-#+call: double(n=3)
-@end example
-
 @table @code
 @item <name>
 The name of the code block to be evaluated.
 @item <arguments>
-Arguments specified in this section will be passed to the code block.
+Arguments specified in this section will be passed to the code block.  These
+arguments should relate to @code{:var} header arguments in the called code
+block expressed using standard function call syntax.  For example if the
+original code block named @code{double} has the header argument @code{:var
+n=2}, then the call line passing the number four to that block would be
+written as @code{#+call: double(n=2)}.
 @item <header arguments>
 Header arguments can be placed after the function invocation.  See
 @ref{Header arguments} for more information on header arguments.
 @end table
 
+All header arguments placed in the @code{<header arguments>} section
+described above will be applied to the evaluation of the @code{#+call:} line,
+however it is sometimes desirable to specify header arguments to be passed to
+the code block being evaluated.
+
+This is possible through the use of the following optional extended syntax.
+
+@example
+#+call: <name>[<block header arguments>](<arguments>) <header arguments>
+@end example
+
+Any header argument placed between the square brackets in the @code{<block
+header arguments>} section will be applied to the evaluation of the named
+code block.  For more examples of passing header arguments to @code{#+call:}
+lines see @ref{Header arguments in function calls}.
 
 @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code
 @section Library of Babel
@@ -11656,12 +11664,22 @@ Multi-line header arguments on a named code block:
 @subsubheading Header arguments in function calls
 
 At the most specific level, header arguments for ``Library of Babel'' or
-function call lines can be set as shown below:
+function call lines can be set as shown in the two examples below.  For more
+information on the structure of @code{#+call:} lines see @ref{Evaluating code
+blocks}.
 
+The following will apply the @code{:exports results} header argument to the
+evaluation of the @code{#+call:} line.
 @example
 #+call: factorial(n=5) :exports results
 @end example
 
+The following will apply the @code{:session special} header argument to the
+evaluation of the @code{factorial} code block.
+@example
+#+call: factorial[:session special](n=5)
+@end example
+
 @node Specific header arguments,  , Using header arguments, Header arguments
 @subsection Specific header arguments
 The following header arguments are defined: