Index: doc/apl.texi
===================================================================
--- doc/apl.texi	(revision 519)
+++ doc/apl.texi	(working copy)
@@ -48,7 +48,7 @@
 in ISO standard 13751, aka. "Programming Language APL, Extended".
 
 This manual for GNU APL can be distributed under the terms of the
- GNU Free Documentation License, *Note Chapter 6::.
+ GNU Free Documentation License, *Note Chapter 7::.
 
 This manual does NOT describe APL itself; there exist a number of good books
 and texts about APL. We would like to refer the reader to the following:
@@ -63,11 +63,12 @@
 
 @menu
 * Chapter 1::    Installing and Starting APL
-* Chapter 2::    Non-standard Features
-* Chapter 3::    Limitations and Missing Features
-* Chapter 4::    Internationalization
-* Chapter 5::    Libraries Contributed by GNU APL Users
-* Chapter 6::    Licenses for GNU APL and this Manual
+* Chapter 2::    Implementation Choices
+* Chapter 3::    Non-standard Features
+* Chapter 4::    Limitations and Missing Features
+* Chapter 5::    Internationalization
+* Chapter 6::    Libraries Contributed by GNU APL Users
+* Chapter 7::    Licenses for GNU APL and this Manual
 @end menu
 
 @c ============================================================================
@@ -561,6 +562,39 @@
 
 @c ----------------------------------------------------------------------------
 @node Chapter 2
+@chapter Implementation Choices
+
+@section Function / Operator Symbols
+
+A few standard APL symbols have historically come to denote both functions and
+operators. These are:
+
+@itemize
+@item `/' and `⌿' denote both the function Replicate and the operator Reduction;
+@item `\' and `⍀' denote both the function Expand and the operator Scan.
+@end itemize
+
+Neither ISO standard 13751 nor the original APL2 manual provide enough
+information to cleanly resolve these border cases.
+
+In order to avoid lengthy and complicated run-time lookaheads of the left
+argument of these symbols, GNU APL tries to resolve this ambiguity at ⎕FX time.
+This works well except if the left argument is a user-defined symbol. In that
+case the rule in GNU APL is that an expression in parentheses is assumed to be
+a value, while a user-defined symbol is assumed to be a function.
+
+This has the practical consequence that in some cases, for example when one
+wishes to use the Replicate or Expand functions with a user-defined symbol as
+the left argument and with an operator applied to its right, then the left
+argument needs to be enclosed in parentheses:
+
+@verbatim
+      A/¨B       ⍝ A is assumed to be a function and / means Reduction
+      (A)/¨B     ⍝ A is forced to be a value, so that / means Replicate
+@end verbatim
+
+@c ----------------------------------------------------------------------------
+@node Chapter 3
 @chapter Non-standard Features
 
 There are a few possibly useful features in GNU APL:
@@ -1423,7 +1457,7 @@
     function or variable name.
 
 @c ----------------------------------------------------------------------------
-@node Chapter 3
+@node Chapter 4
 @chapter Limitations and Missing Features
 
 APL is an almost full implementation of the ISO standard 13751.
@@ -1466,7 +1500,7 @@
 APL interpreter rather that adding auxiliary processors.
 
 @c ----------------------------------------------------------------------------
-@node Chapter 4
+@node Chapter 5
 @chapter Internationalization
 
 GNU APL used to be internationalized by means of GNU gettext, but is not
@@ -1493,7 +1527,7 @@
 --en might solve problems related to the terminal.
 
 @c ----------------------------------------------------------------------------
-@node Chapter 5
+@node Chapter 6
 @chapter Libraries Contributed by GNU APL Users
 
 Since the first release of GNU APL, a number of libraries, but also other
@@ -1501,11 +1535,11 @@
 contributions.
 
 @menu
-* Section 5.1::  The GNU APL Community Webpage
-* Section 5.2::  Core Libraries
+* Section 6.1::  The GNU APL Community Webpage
+* Section 6.2::  Core Libraries
 @end menu
 
-@node Section 5.1
+@node Section 6.1
 @section The GNU APL Community Webpage
 
 The GNU APL project maintains a web page that lists contibutions made by
@@ -1523,7 +1557,7 @@
 to fix that.
 
 
-@node Section 5.2
+@node Section 6.2
 @section Core Libraries
 
 There is a small number of libraries that are considered "core" APL because,
@@ -1547,21 +1581,21 @@
 SQL
 
 @c ----------------------------------------------------------------------------
-@node Chapter 6
+@node Chapter 7
 @chapter Licenses for this GNU APL Manual and for GNU APL
 
 This manual for GNU APL is licensed under the GNU Free Documentation
-License, *Note Section 4.1:: below.
+License, *Note Section 7.1:: below.
 
 GNU APL itself is licensed under the GNU Public License version 3 or later
-(aka GPLv3+), *Note Section 4.2:: below.
+(aka GPLv3+), *Note Section 7.2:: below.
 
 @menu
-* Section 6.1::  The GNU Free Documentation License
-* Section 6.2::  The GNU General Public License
+* Section 7.1::  The GNU Free Documentation License
+* Section 7.2::  The GNU General Public License
 @end menu
 
-@node Section 6.1
+@node Section 7.1
 @section The GNU Free Documentation License
 
 @c The GNU Free Documentation License.
@@ -2063,7 +2097,7 @@
 free software license, such as the GNU General Public License,
 to permit their use in free software.
 
-@node Section 6.2
+@node Section 7.2
 @section The GNU GENERAL PUBLIC LICENSE
 
                     GNU GENERAL PUBLIC LICENSE